simple.util.parse
Class PathParser

java.lang.Object
  extended by simple.util.parse.Parser
      extended by simple.util.parse.PathParser
All Implemented Interfaces:
java.io.Serializable, Path

public class PathParser
extends Parser
implements Path

This is used to parse a path given as part of a URI. This will read the path, normalize it, and break it up into its components. The normalization of the path is the conversion of the path given into it's actual path by removing the references to the parent directorys and to the current dir.

So if the path that was given was /usr/bin/../etc/./README then the actual path, normalized, is /usr/etc/README. This will also extract a localization from the path given. A localization is extracted if there is a second extension given in the path name, for example file.ext.ext. The second extension will be parsed so that all the characters before the first underscore character, '_', will define the language and all the characters after the first underscore will define the country, for example index.en_US.html will have the language en and the country would be US. Currently this only supports two character codes for both language and country. These are defined from the java.util.Locale using the getISOCountries and getISOLanguages methods.

Although RFC 2396 defines the path within a URI to have parameters this does not extract those parameters this will simply normalize the path and include the path parameters in the path. If the path is to be converted into a OS specific file system path that has the parameters extracted then the URIParser should be used. Also the inclusion of the locale attributes in this parser is not defined in RFC 2396. This is because this is a feature of the parser to extract a locale from a file if you choose to do so, if however you do not this does not effect the parsing or results of this parser.

Author:
Niall Gallagher
See Also:
Serialized Form

Field Summary
 
Fields inherited from class simple.util.parse.Parser
buf, count, off
 
Constructor Summary
PathParser()
          The default constructor will create a PathParser that contains no specifics.
PathParser(java.lang.String path)
          This is primarily a convineance constructor.
 
Method Summary
 java.lang.String getCountry()
          This will return the country that this path has taken from the locale of the path.
 java.lang.String getDirectory()
          This will return the highest directory that exists within the path.
 java.lang.String getExtension()
          This will return the extension that the file name contains.
 java.lang.String getLanguage()
          This will return the language that this path has taken from the locale of the path.
 java.lang.String getName()
          This will return the full name of the file without the path.
 java.lang.String getPath()
          This will return the normalized path.
 java.lang.String getRelative(java.lang.String path)
          This will return the path as it is relative to the issued path.
 java.lang.String[] getSegments()
          This method is used to break the path into individual parts called segments, see RFC 2396.
protected  void init()
          This will initialize the parser so that it is in a ready state.
protected  void parse()
          This will parse the path in such a way that it ensures that at no stage there are trailing back references, using path normalization.
 java.lang.String toString()
          This will return the normalized path.
 
Methods inherited from class simple.util.parse.Parser
digit, ensureCapacity, parse, skip, space, toLower
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PathParser

public PathParser()
The default constructor will create a PathParser that contains no specifics. The instance will return null for all the get methods. The PathParser's get methods may be populated by using the parse method.


PathParser

public PathParser(java.lang.String path)
This is primarily a convineance constructor. This will parse the String given to extract the specifics. This could be achived by calling the default no-arg constructor and then using the instance to invoke the parse method on that String to extract the parts.

Parameters:
path - a String containing a path value
Method Detail

parse

protected void parse()
This will parse the path in such a way that it ensures that at no stage there are trailing back references, using path normalization. The need to remove the back references is so that this PathParser will create the same String path given a set of paths that have different back references. For example the paths /path/../path and /path are the same path but different String's.

This will NOT parse an immediate back reference as this signifies a path that cannot exist. So a path such as /../ will result in a null for all methods. Paths such as ../bin will not be allowed.

Specified by:
parse in class Parser

init

protected void init()
This will initialize the parser so that it is in a ready state. This allows the parser to be used to parse many paths. This will clear the parse buffer objects and reset the offset to point to the start of the char buffer. The count variable is reset by the Parser.parse method.

Specified by:
init in class Parser

getLanguage

public java.lang.String getLanguage()
This will return the language that this path has taken from the locale of the path. For example a file name of file.en_US.extension produces a language of en. This will return null if there was no language information within the path.

Specified by:
getLanguage in interface Path
Returns:
returns the locale language this path contains

getCountry

public java.lang.String getCountry()
This will return the country that this path has taken from the locale of the path. For example a file name of file.en_US.extension produces a country of US. This will return null if there was no country information within the path.

Specified by:
getCountry in interface Path
Returns:
returns the locale country this path contains

getExtension

public java.lang.String getExtension()
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.

Specified by:
getExtension in interface Path
Returns:
this will return the extension this path contains

getName

public java.lang.String getName()
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.

Specified by:
getName in interface Path
Returns:
this will return the name of the file in the path

getPath

public java.lang.String getPath()
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.

Specified by:
getPath in interface Path
Returns:
this returns the normalize path without ../ or ./

getDirectory

public java.lang.String getDirectory()
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.

Specified by:
getDirectory in interface Path
Returns:
this method will return the highest directory

getSegments

public java.lang.String[] getSegments()
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.

Specified by:
getSegments in interface Path
Returns:
return all the path segments within the directory

getRelative

public java.lang.String getRelative(java.lang.String path)
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.

Specified by:
getRelative in interface Path
Parameters:
path - the path prefix to acquire a relative path
Returns:
returns a path relative to the one it is given otherwize this method will return null

toString

public java.lang.String toString()
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.

Specified by:
toString in interface Path
Overrides:
toString in class java.lang.Object
Returns:
this returns the normalize path without ../ or ./