org.simpleframework.http.Path Maven / Gradle / Ivy
Show all versions of simple Show documentation
/*
* Path.java February 2001
*
* Copyright (C) 2001, Niall Gallagher
*
* 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.simpleframework.http;
/**
* The Path represents the path part of a URI. This provides
* the various components of the URI path to the user. The normalization
* of the path is the conversion of the path given into it's actual path by
* removing the references to the parent directories and to the current dir.
*
* If the path that this represents is /usr/bin/../etc/./README
* then the actual path, normalized, is /usr/etc/README. Once
* the path has been normalized it is possible to acquire the segments as
* an array of strings, which allows simple manipulation of the path.
*
* @author Niall Gallagher
*
* @see org.simpleframework.http.parse.PathParser
*/
public interface Path {
/**
* This will return the extension that the file name contains.
* For example a file name file.en_US.extension
* will produce an extension of extension. This
* will return null if the path contains no file extension.
*
* @return this will return the extension this path contains
*/
String getExtension();
/**
* This will return the full name of the file without the path.
* As regargs the definition of the path in RFC 2396 the name
* would be considered the last path segment. So if the path
* was /usr/README the name is README.
* Also for directorys the name of the directory in the last
* path segment is returned. This returns the name without any
* of the path parameters. As RFC 2396 defines the path to have
* path parameters after the path segments.
*
* @return this will return the name of the file in the path
*/
String getName();
/**
* This will return the normalized path. The normalized path is
* the path without any references to its parent or itself. So
* if the path to be parsed is /usr/../etc/./ the
* path is /etc/. If the path that this represents
* is a path with an immediate back reference then this will
* return null. This is the path with all its information even
* the parameter information if it was defined in the path.
*
* @return this returns the normalize path without
* ../ or ./
*/
String getPath();
/**
* This will return the normalized path from the specified path
* segment. This allows various path parts to be acquired in an
* efficient means what does not require copy operations of the
* use of substring invocations. Of particular
* interest is the extraction of context based paths. This is
* the path with all its information even the parameter
* information if it was defined in the path.
*
* @param from this is the segment offset to get the path for
*
* @return this returns the normalize path without
* ../ or ./
*/
String getPath(int from);
/**
* This will return the normalized path from the specified path
* segment. This allows various path parts to be acquired in an
* efficient means what does not require copy operations of the
* use of substring invocations. Of particular
* interest is the extraction of context based paths. This is
* the path with all its information even the parameter
* information if it was defined in the path.
*
* @param from this is the segment offset to get the path for
* @param count this is the number of path segments to include
*
* @return this returns the normalize path without
* ../ or ./
*/
String getPath(int from, int count);
/**
* This method is used to break the path into individual parts
* called segments, see RFC 2396. This can be used as an easy
* way to compare paths and to examine the directory tree that
* the path points to. For example, if an path was broken from
* the string /usr/bin/../etc then the segments
* returned would be usr and etc as
* the path is normalized before the segments are extracted.
*
* @return return all the path segments within the directory
*/
String[] getSegments();
/**
* This will return the highest directory that exists within
* the path. This is used to that files within the same path
* can be acquired. An example of that this would do given
* the path /pub/./bin/README would be to return
* the highest directory path /pub/bin/. The "/"
* character will allways be the last character in the path.
*
* @return this method will return the highest directory
*/
String getDirectory();
/**
* This will return the path as it is relative to the issued
* path. This in effect will chop the start of this path if
* it's start matches the highest directory of the given path
* as of getDirectory. This is useful if paths
* that are relative to a specific location are required. To
* illustrate what this method will do the following example
* is provided. If this object represented the path string
* /usr/share/rfc/rfc2396.txt and the issued
* path was /usr/share/text.txt then this will
* return the path string /rfc/rfc2396.txt.
*
* @param path the path prefix to acquire a relative path
*
* @return returns a path relative to the one it is given
* otherwize this method will return null
*/
String getRelative(String path);
/**
* This will return the normalized path. The normalized path is
* the path without any references to its parent or itself. So
* if the path to be parsed is /usr/../etc/./ the
* path is /etc/. If the path that this represents
* is a path with an immediate back reference then this will
* return null. This is the path with all its information even
* the parameter information if it was defined in the path.
*
* @return this returns the normalize path without
* ../ or ./
*/
String toString();
}