net.sf.javaprinciples.resource.ResourceIdentifier Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of resource-handling-api Show documentation

There is a newer version: 3.0.3

Show newest version

package net.sf.javaprinciples.resource;

import java.util.List;
import java.util.Map;

/**
 * Interface encapsulating the Identifier for a Resource.
 * Identifiers are typically richer than a plain String, and are considered immutable.
 * @author rvl
 */
public interface ResourceIdentifier
{
    /**
     * Get the path elements from the ResourceIdentifier.
     * In the case of a URL, these are the elements separated by "/", with the
     * additional restriction that the base URL has been removed first.
     *
     * That is, given a URL of http://example.com/resources/example/animals/dogs,
     * and a base URL of http://example.com/resources/example, the path would contain
     * elements "animals" and "dogs" in that order.
     *
     * @return A list of the path elements of the ResourceIdentifier that do not include
     *   the base URL elements, and will never be null.
     */
    List getPathElements();

    /**
     * Gets the query parameters associated with the ResourceIdentifier.
     * Query parameters are primarily used for passing parameters to algorithmic
     * resources.
     *
     * For example, http://example.com/resources/example/animals/dogs?size=medium&fur=short
     * could be interpreted as a request for a list of all medium-sized dogs with short fur,
     * made of an algorithmic resource. The query parameters are size = medium and fur = short.
     *
     * @return The query parameters if any. The returned Map is never null.
     */
    Map getQueryParameters();

    /**
     * Gets the Identifier component of the ResourceIdentifier.
     * This is not to be confused with the ResourceIdentifier itself, which is the
     * complete URL. The Identifier in this case is by convention the last path element
     * in the ResourceIdentifier, and is an identifier of some "thing" as understood by
     * the system.
     *
     * @return The Identifier.
     */
    String getIdentifier();
}