/* ************************************************************************
#
# DivConq
#
# http://divconq.com/
#
# Copyright:
# Copyright 2014 eTimeline, LLC. All rights reserved.
#
# License:
# See the license.txt file in the project's top-level directory for details.
#
# Authors:
# * Andy White
#
************************************************************************ */
/*
* Path.java February 2001
*
* Copyright (C) 2001, Niall Gallagher <niallg@users.sf.net>
*
* 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 divconq.www.http;
/**
* The <code>Path</code> 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.
* <p>
* If the path that this represents is <code>/usr/bin/../etc/./README</code>
* then the actual path, normalized, is <code>/usr/etc/README</code>. 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 <code>file.en_US.extension</code>
* will produce an extension of <code>extension</code>. 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 <code>/usr/README</code> the name is <code>README</code>.
* 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 <code>/usr/../etc/./</code> the
* path is <code>/etc/</code>. 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
* <code>../</code> or <code>./</code>
*/
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 <code>substring</code> 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
* <code>../</code> or <code>./</code>
*/
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 <code>substring</code> 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
* <code>../</code> or <code>./</code>
*/
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 <code>/usr/bin/../etc</code> then the segments
* returned would be <code>usr</code> and <code>etc</code> 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 <code>/pub/./bin/README</code> would be to return
* the highest directory path <code>/pub/bin/</code>. 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 <code>getDirectory</code>. 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
* <code>/usr/share/rfc/rfc2396.txt</code> and the issued
* path was <code>/usr/share/text.txt</code> then this will
* return the path string <code>/rfc/rfc2396.txt</code>.
*
* @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 <code>/usr/../etc/./</code> the
* path is <code>/etc/</code>. 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
* <code>../</code> or <code>./</code>
*/
String toString();
}