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}