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.net.URI;
019import java.net.URL;
020import java.nio.file.Path;
021import org.apiguardian.api.API;
022import org.apiguardian.api.API.Status;
023import org.jspecify.annotations.Nullable;
024
025/**
026 * A path-like object that can provide a {@link Path Java NIO Path}.
027 *
028 * <p>This enables wrapping various implementations and providers of {@link Path} objects
029 * in a translucent façade that enables representing paths in a hierarchical format.
030 *
031 * @author Ashley Scopes
032 * @since 0.0.1
033 */
034@API(since = "0.0.1", status = Status.STABLE)
035public interface PathRoot {
036
037  /**
038   * Determine if two path roots are equivalent. If the provided object is {@code null} or not an
039   * instance of a {@link PathRoot}, then this will return {@code false} unless otherwise
040   * specified.
041   *
042   * @param other the object to compare with.
043   * @return {@code true} if semantically equal, or {@code false} otherwise.
044   */
045  @Override
046  boolean equals(@Nullable Object other);
047
048  /**
049   * Determine the hash-code for the object.
050   *
051   * @return the hash code.
052   */
053  @Override
054  int hashCode();
055
056  /**
057   * Get the {@link Path Java NIO Path} for this path-like object.
058   *
059   * @return the path.
060   * @see #getUri()
061   * @see #getUrl()
062   */
063  Path getPath();
064
065  /**
066   * Get a URI representation of this path-like object.
067   *
068   * @return the URI.
069   * @see #getUrl()
070   * @see #getPath()
071   */
072  URI getUri();
073
074  /**
075   * Get a URL representation of this path-like object.
076   *
077   * @return the URL.
078   * @see #getUri()
079   * @see #getPath()
080   */
081  URL getUrl();
082
083  /**
084   * Get the parent path root, if there is one.
085   *
086   * @return the parent path root, or {@code null} if no parent root exists.
087   */
088  PathRoot getParent();
089}