org.simpleframework.http.Path Maven / Gradle / Ivy
/*
* Path.java February 2001
*
* Copyright (C) 2001, Niall Gallagher
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
* Public License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307 USA
*/
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
*/
public 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
*/
public 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 ./
*/
public 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 ./
*/
public 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 ./
*/
public 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
*/
public 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
*/
public 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
*/
public 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 ./
*/
public String toString();
}