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.jspecify.annotations.Nullable;
023
024/**
025 * A path-like object that can provide a {@link Path Java NIO Path}.
026 *
027 * <p>This enables wrapping various implementations and providers of {@link Path} objects
028 * in a translucent façade that enables representing paths in a hierarchical format.
029 *
030 * @author Ashley Scopes
031 * @since 0.0.1
032 */
033@SuppressWarnings("unused")
034public interface PathRoot {
035
036  /**
037   * Convert the given path root into a JAR and return the byte contents of the JAR.
038   *
039   * <p>You can use this to create JAR files from existing path roots, if you want to package
040   * some compiled outputs into a JAR to use them as inputs to another build.
041   *
042   * @return the byte contents of the JAR.
043   * @throws UncheckedIOException          if the JAR cannot be created.
044   * @throws UnsupportedOperationException if the operation is not supported.
045   * @since 0.4.0
046   */
047  byte[] asJar();
048
049  /**
050   * Determine if two path roots are equivalent. If the provided object is {@code null} or not an
051   * instance of a {@link PathRoot}, then this will return {@code false} unless otherwise
052   * specified.
053   *
054   * @param other the object to compare with.
055   * @return {@code true} if semantically equal, or {@code false} otherwise.
056   */
057  @Override
058  boolean equals(@Nullable Object other);
059
060  /**
061   * Determine the hash-code for the object.
062   *
063   * @return the hash code.
064   */
065  @Override
066  int hashCode();
067
068  /**
069   * Get the {@link Path Java NIO Path} for this path-like object.
070   *
071   * @return the path.
072   * @see #getUri()
073   * @see #getUrl()
074   */
075  Path getPath();
076
077  /**
078   * Get a URI representation of this path-like object.
079   *
080   * @return the URI.
081   * @see #getUrl()
082   * @see #getPath()
083   */
084  URI getUri();
085
086  /**
087   * Get a URL representation of this path-like object.
088   *
089   * @return the URL.
090   * @see #getUri()
091   * @see #getPath()
092   */
093  URL getUrl();
094
095  /**
096   * Get the parent path root, if there is one.
097   *
098   * @return the parent path root, or {@code null} if no parent root exists.
099   */
100  @Nullable
101  PathRoot getParent();
102}