Package org.simpleframework.http.parse

## Class PathParser

- java.lang.Object
- - org.simpleframework.util.parse.Parser
  - - org.simpleframework.http.parse.PathParser

- All Implemented Interfaces:
    `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 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.

  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 `AddressParser` should be used.

  Author:
    Niall Gallagher

- - ### Field Summary

    - ### Fields inherited from class org.simpleframework.util.parse.Parser

      `buf, count, off`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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` | `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` | `getPath​(int from)` | This will return the normalized path from the specified path segment.
    `java.lang.String` | `getPath​(int from, int count)` | This will return the normalized path from the specified path segment.
    `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 org.simpleframework.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`

    - #### 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 `./`

    - #### getPath

          public java.lang.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.
      Specified by:
        `getPath` in interface `Path`
      Parameters:
        `from` - this is the segment offset to get the path for
      Returns:
        this returns the normalize path without `../` or `./`

    - #### getPath

          public java.lang.String getPath​(int from,
                                          int count)

      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.
      Specified by:
        `getPath` in interface `Path`
      Parameters:
        `from` - this is the segment offset to get the path for
        `count` - this is the number of path segments to include
      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 `./`