001/*
002 * Copyright (C) 2022 - 2023, 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@API(since = "0.0.1", status = Status.STABLE)
036public interface PathRoot {
037
038  /**
039   * Convert the given path root into a JAR and return the byte contents of the JAR.
040   *
041   * <p>You can use this to create JAR files from existing path roots, if you want to package
042   * some compiled outputs into a JAR to use them as inputs to another build.
043   *
044   * @return the byte contents of the JAR.
045   * @throws UncheckedIOException          if the JAR cannot be created.
046   * @throws UnsupportedOperationException if the operation is not supported.
047   * @since 0.4.0
048   */
049  @API(since = "0.4.0", status = Status.STABLE)
050  byte[] asJar();
051
052  /**
053   * Determine if two path roots are equivalent. If the provided object is {@code null} or not an
054   * instance of a {@link PathRoot}, then this will return {@code false} unless otherwise
055   * specified.
056   *
057   * @param other the object to compare with.
058   * @return {@code true} if semantically equal, or {@code false} otherwise.
059   */
060  @Override
061  boolean equals(@Nullable Object other);
062
063  /**
064   * Determine the hash-code for the object.
065   *
066   * @return the hash code.
067   */
068  @Override
069  int hashCode();
070
071  /**
072   * Get the {@link Path Java NIO Path} for this path-like object.
073   *
074   * @return the path.
075   * @see #getUri()
076   * @see #getUrl()
077   */
078  Path getPath();
079
080  /**
081   * Get a URI representation of this path-like object.
082   *
083   * @return the URI.
084   * @see #getUrl()
085   * @see #getPath()
086   */
087  URI getUri();
088
089  /**
090   * Get a URL representation of this path-like object.
091   *
092   * @return the URL.
093   * @see #getUri()
094   * @see #getPath()
095   */
096  URL getUrl();
097
098  /**
099   * Get the parent path root, if there is one.
100   *
101   * @return the parent path root, or {@code null} if no parent root exists.
102   */
103  @Nullable
104  PathRoot getParent();
105}