001/* 002 * Copyright (C) 2022 - 2024, the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package io.github.ascopes.jct.workspaces; 017 018import java.io.UncheckedIOException; 019import java.net.URI; 020import java.net.URL; 021import java.nio.file.Path; 022import org.apiguardian.api.API; 023import org.apiguardian.api.API.Status; 024import org.jspecify.annotations.Nullable; 025 026/** 027 * A path-like object that can provide a {@link Path Java NIO Path}. 028 * 029 * <p>This enables wrapping various implementations and providers of {@link Path} objects 030 * in a translucent façade that enables representing paths in a hierarchical format. 031 * 032 * @author Ashley Scopes 033 * @since 0.0.1 034 */ 035@SuppressWarnings("unused") 036@API(since = "0.0.1", status = Status.STABLE) 037public interface PathRoot { 038 039 /** 040 * Convert the given path root into a JAR and return the byte contents of the JAR. 041 * 042 * <p>You can use this to create JAR files from existing path roots, if you want to package 043 * some compiled outputs into a JAR to use them as inputs to another build. 044 * 045 * @return the byte contents of the JAR. 046 * @throws UncheckedIOException if the JAR cannot be created. 047 * @throws UnsupportedOperationException if the operation is not supported. 048 * @since 0.4.0 049 */ 050 @API(since = "0.4.0", status = Status.STABLE) 051 byte[] asJar(); 052 053 /** 054 * Determine if two path roots are equivalent. If the provided object is {@code null} or not an 055 * instance of a {@link PathRoot}, then this will return {@code false} unless otherwise 056 * specified. 057 * 058 * @param other the object to compare with. 059 * @return {@code true} if semantically equal, or {@code false} otherwise. 060 */ 061 @Override 062 boolean equals(@Nullable Object other); 063 064 /** 065 * Determine the hash-code for the object. 066 * 067 * @return the hash code. 068 */ 069 @Override 070 int hashCode(); 071 072 /** 073 * Get the {@link Path Java NIO Path} for this path-like object. 074 * 075 * @return the path. 076 * @see #getUri() 077 * @see #getUrl() 078 */ 079 Path getPath(); 080 081 /** 082 * Get a URI representation of this path-like object. 083 * 084 * @return the URI. 085 * @see #getUrl() 086 * @see #getPath() 087 */ 088 URI getUri(); 089 090 /** 091 * Get a URL representation of this path-like object. 092 * 093 * @return the URL. 094 * @see #getUri() 095 * @see #getPath() 096 */ 097 URL getUrl(); 098 099 /** 100 * Get the parent path root, if there is one. 101 * 102 * @return the parent path root, or {@code null} if no parent root exists. 103 */ 104 @Nullable 105 PathRoot getParent(); 106}