org.dmfs.rfc3986.Uri Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of rfc3986-uri Show documentation
RFC 3986 compliant URI implementation.
There is a newer version: 0.8.1
/*
 * Copyright 2017 dmfs GmbH
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.dmfs.rfc3986;

import org.dmfs.optional.Optional;


/**
 * A URI as specified in RFC 3986.
 * 
 * For convenience this represents a URI-reference as specified in RFC 3986, Section 4.1. For
 * brevity and as per common usage it's still called just {@code Uri} instead of {@code UriReference}.
 * 

 * As a consequence, {@link #scheme()} returns an {@link Optional}, because in contrast to a URI, a relative reference doesn't have a scheme.
 * 
 * {@link #isAbsolute()} may be used to distinguish between real URIs that have a scheme ({@link #isAbsolute()} returns {@code true}) and relative references
 * ({@link #isAbsolute()} returns {@code false}).
 *
 * @author Marten Gajda
 */
public interface Uri
{
    /**
     * Returns the {@link Optional} {@link Scheme} of the URI reference.
     *
     * @return An {@link Optional} {@link Scheme}.
     */
    Optional scheme();

    /**
     * Returns the {@link Optional} {@link Authority} of the URI reference.
     *
     * @return An {@link Optional} {@link Authority}.
     */
    Optional authority();

    /**
     * Returns the {@link Path} of this URI reference.
     *
     * @return A {@link Path}. The path is always present, but may be empty.
     */
    Path path();

    /**
     * Returns the {@link Optional} {@link Query} of the URI reference.
     *
     * @return An {@link Optional} {@link Query}.
     */
    Optional query();

    /**
     * Returns the {@link Optional} {@link Fragment} of the URI reference.
     *
     * @return An {@link Optional} {@link Fragment}.
     */
    Optional fragment();

    /**
     * Returns whether this URI reference is hierarchical.
     *
     * @return {@code true} if the URI is hierarchical, {@code false} otherwise.
     */
    boolean isHierarchical();

    /**
     * Returns whether this URI reference is absolute, i.e. a URI. A URI reference is absolute if it has a scheme, otherwise it's a relative reference as per RFC 3986, Section 4.2
     *
     * @return {@code true} if the URI is absolute, {@code false} otherwise.
     */
    boolean isAbsolute();
}