org.simpleframework.http.parse

## Class AddressParser

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

All Implemented Interfaces:
  Address

    public class AddressParser
    extends Parser
    implements Address

This parser is used to parse uniform resource identifiers. The uniform resource identifier syntax is given in RFC 2396. This parser can parse relative and absolute URI's. The uniform resource identifier syntax that this parser will parse are based on the generic web based URL similar to the syntax represented in RFC 2616 section 3.2.2. The syntax used to parse this URI is a modified version of RFC 2396

        URI         = (absoluteURI | relativeURI)
        absoluteURI = scheme ":" ("//" netpath | relativeURI)
        relativeURI = path ["?" querypart]
        netpath     = domain [":" port] relativeURI
        path        = *("/" segment)
        segment     = *pchar *( ";" param )

This implements the `Address` interface and provides methods that access the various parts of the URI. The parameters in the path segments of the uniform resource identifier are stored in name value pairs. If parameter names are not unique across the path segments then only the deepest parameter will be stored from the path segment. For example if the URI represented was `http://domain/path1;x=y/path2;x=z` the value for the parameter named `x` would be `z`.

This will normalize the path part of the uniform resource identifier. A normalized path is one that contains no back references like "./" and "../". The normalized path will not contain the path parameters.

The `setPath` method is used to reset the path this uniform resource identifier has, it also resets the parameters. The parameters are extracted from the new path given.

Author:
  Niall Gallagher

### Field Summary

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

`buf, count, off`

### Constructor Summary

Constructors
Constructor and Description
`AddressParser()` Default constructor will create a `AddressParser` that contains no specifics.
`AddressParser(java.lang.String text)` This is primarily a convenience constructor.

### Method Summary

Methods
`java.lang.String` `getDomain()` This is used to retrive the domain of this URI.
`KeyMap<java.lang.String>` `getParameters()` This extracts the parameter values from the uniform resource identifier represented by this object.
`Path` `getPath()` This is used to retrive the path of this URI.
`int` `getPort()` This is used to retrive the port of the uniform resource identifier.
`Query` `getQuery()` This is used to retrieve the query of this URI.
`java.lang.String` `getScheme()` This allows the scheme of the URL given to be returned.
`protected void` `init()` This will empty each tokens cache.
`protected void` `parse()` This will check to see what type of URI this is if it is an `absoluteURI` or a `relativeURI`.
`void` `setDomain(java.lang.String value)` This will set the domain to whatever value is in the string parameter.
`void` `setPath(Path path)` This will set the path to whatever value it is given.
`void` `setPath(java.lang.String text)` This will set the path to whatever value it is given.
`void` `setPort(int port)` This will set the port to whatever value it is given.
`void` `setQuery(Query query)` This will set the query to whatever value it is given.
`void` `setQuery(java.lang.String value)` This will set the query to whatever value it is given.
`void` `setScheme(java.lang.String value)` This allows the scheme for the URI to be specified.
`java.lang.String` `toString()` This is used to convert this URI object into a `String` object.

### 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

#### AddressParser

    public AddressParser()

Default constructor will create a `AddressParser` that contains no specifics. The instance will return `null` for all the get methods. The parsers get methods are populated by using the `parse` method.

#### AddressParser

    public AddressParser(java.lang.String text)

This is primarily a convenience constructor. This will parse the `String` given to extract the specifics. This could be achieved 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:
  `text` - a `String` containing a URI value

### Method Detail

#### getScheme

    public java.lang.String getScheme()

This allows the scheme of the URL given to be returned. If the URI does not contain a scheme then this will return null. The scheme of the URI is the part that specifies the type of protocol that the URI is used for, an example `gopher://domain/path` is a URI that is intended for the gopher protocol. The scheme is the string `gopher`.

Specified by:
  `getScheme` in interface `Address`
Returns:
  this returns the scheme tag for the URI if there is one specified for it

#### getDomain

    public java.lang.String getDomain()

This is used to retrive the domain of this URI. The domain part in the URI is an optional part, an example `http://domain/path?querypart`. This will return the value of the domain part. If there is no domain part then this will return null otherwise the domain value found in the uniform resource identifier.

Specified by:
  `getDomain` in interface `Address`
Returns:
  the domain part of this uniform resource identifier this represents

#### getPath

    public Path getPath()

This is used to retrive the path of this URI. The path part is the most fundemental part of the URI. This will return the value of the path. If there is no path part then this will return `/` to indicate the root.

The `Path` object returned by this will contain no path parameters. The path parameters are available using the `Address` methods. The reason that this does not contain any of the path parameters is so that if the path is needed to be converted into ab OS specific path then the path parameters will not need to be separately parsed out.

Specified by:
  `getPath` in interface `Address`
Returns:
  the path that this URI contains, this value will not contain any back references such as "./" and "../" or any path parameters

#### getQuery

    public Query getQuery()

This is used to retrieve the query of this URI. The query part in the URI is an optional part. This will return the value of the query part. If there is no query part then this will return an empty `Query` object. The query is an optional member of a URI and comes after the path part, it is preceded by a question mark, `?` character. For example the following URI contains `query` for its query part, `http://host:port/path?query`.

This returns a `org.simpleframework.http.Query` object that can be used to interact directly with the query values. The `Query` object is a read-only interface to the query parameters, and so will not affect the URI.

Specified by:
  `getQuery` in interface `Address`
Returns:
  a `Query` object for the query part

#### getPort

    public int getPort()

This is used to retrive the port of the uniform resource identifier. The port part in this is an optional part, an example `http://host:port/path?querypart`. This will return the value of the port. If there is no port then this will return `-1` because this represents an impossible uniform resource identifier port. The port is an optional part.

Specified by:
  `getPort` in interface `Address`
Returns:
  this returns the port of the uniform resource identifier

#### getParameters

    public KeyMap<java.lang.String> getParameters()

This extracts the parameter values from the uniform resource identifier represented by this object. The parameters that a uniform resource identifier contains are embedded in the path part of the URI. If the path contains no parameters then this will return an empty `Map` instance.

This will produce unique name and value parameters. Thus if the URI contains several path segments with similar parameter names this will return the deepest parameter. For example if the URI represented was `http://domain/path1;x=y/path2;x=z` the value for the parameter named `x` would be `z`.

Specified by:
  `getParameters` in interface `Address`
Returns:
  this will return the parameter names found in the URI

#### setScheme

    public void setScheme(java.lang.String value)

This allows the scheme for the URI to be specified. If the URI does not contain a scheme then this will attach the scheme and the `://` identifier to ensure that the `Address.toString` will produce the correct syntax.

Caution must be taken to ensure that the port and the scheme are consistent. So if the original URI was `http://domain:80/path` and the scheme was changed to `ftp` the port number that remains is the standard HTTP port not the FTP port.

Parameters:
  `value` - this specifies the protocol this URI is intended for

#### setDomain

    public void setDomain(java.lang.String value)

This will set the domain to whatever value is in the string parameter. If the string is null then this URI objects `toString` method will not contain the domain. The result of the `toString` method will be `/path/path?query`. If the path is non-null this URI will contain the path.

Parameters:
  `value` - this will be the new domain of this uniform resource identifier, if it is not null

#### setPort

    public void setPort(int port)

This will set the port to whatever value it is given. If the value is 0 or less then the `toString` will will not contain the optional port. If port number is above 0 then the `toString` method will produce a URI like `http://host:123/path` but only if there is a valid domain.

Parameters:
  `port` - the port value that this URI is to have

#### setPath

    public void setPath(java.lang.String text)

This will set the path to whatever value it is given. If the value is null then this `Address.toString` method will not contain the path, that is if path is null then it will be interpreted as `/`.

This will reset the parameters this URI has. If the value given to this method has embedded parameters these will form the parameters of this URI. The value given may not be the same value that the `getPath` produces. The path will have all back references and parameters stripped.

Parameters:
  `text` - the path that this URI is to be set with

#### setPath

    public void setPath(Path path)

This will set the path to whatever value it is given. If the value is null then this `Address.toString` method will not contain the path, that is if path is null then it will be interpreted as `/`.

This will reset the parameters this URI has. If the value given to this method has embedded parameters these will form the parameters of this URI. The value given may not be the same value that the `getPath` produces. The path will have all back references and parameters stripped.

Parameters:
  `path` - the path that this URI is to be set with

#### setQuery

    public void setQuery(java.lang.String value)

This will set the query to whatever value it is given. If the value is null then this `Address.toString` method will not contain the query. If the query was `abc` then the `toString` method would produca a string like `http://host:port/path?abc`. If the query is null this URI would have no query part. The query must not contain the `?` character.

Parameters:
  `value` - the query that this uniform resource identifier is to be set to if it is non-null

#### setQuery

    public void setQuery(Query query)

This will set the query to whatever value it is given. If the value is null then this `Address.toString` method will not contain the query. If the `Query.toString` returns null then the query will be empty. This is basically the `setQuery(String)` method with the string value from the issued `Query.toString` method.

Parameters:
  `query` - a `Query` object that contains the name value parameters for the query

#### parse

    protected void parse()

This will check to see what type of URI this is if it is an `absoluteURI` or a `relativeURI`. To see the definition of a URI see RFC 2616 for the definition of a URL and for more specifics see RFC 2396 for the expressions.

Specified by:
  `parse` in class `Parser`

#### init

    protected void init()

This will empty each tokens cache. A tokens cache is used to represent a token once the token's `toString` method has been called. Thus when the `toString` method is called then the token depends on the value of the cache alone in further calls to `toString`. However if a URI has just been parsed and that method has not been invoked then the cache is created from the buf if its length is greater than zero.

Specified by:
  `init` in class `Parser`

#### toString

    public java.lang.String toString()

This is used to convert this URI object into a `String` object. This will only convert the parts of the URI that exist, so the URI may not contain the domain or the query part and it will not contain the path parameters. If the URI contains all these parts then it will return somthing like

     scheme://host:port/path/path?querypart

It can return `/path/path?querypart` style relative URI's. If any of the parts are set to null then that part will be missing, for example if `setDomain` method is invoked with a null parameter then the domain and port will be missing from the resulting URI. If the path part is set to null using the `setPath` then the path will be `/`. An example URI with the path part of null would be

     scheme://host:port/?querypart

Specified by:
  `toString` in interface `Address`
Overrides:
  `toString` in class `java.lang.Object`
Returns:
  the URI with only the path part and the non-null optional parts of the uniform resource identifier