org.restlet.ext.jaxrs
Class ExtendedUriBuilder

java.lang.Object
  extended by javax.ws.rs.core.UriBuilder
      extended by org.restlet.ext.jaxrs.AbstractUriBuilder
          extended by org.restlet.ext.jaxrs.ExtendedUriBuilder

public class ExtendedUriBuilder
extends AbstractUriBuilder

This UriBuilder extension provides special help for "file" extensions. They will not be removed, if path will be changed (e.g. replaced, removed or matrix parameters added). For further information see extension(String), extensionLanguage(String) and extensionMedia(String). You could get an instance with an ExtendedUriInfo.

Author:
Stephan Koops

Constructor Summary
ExtendedUriBuilder()
           
 
Method Summary
 URI build(Object... values)
          Build a URI, using the supplied values in order to replace any URI template parameters.
 URI buildFromEncoded(Object... values)
          
 URI buildFromEncodedMap(Map<String,? extends Object> values)
          
 URI buildFromMap(Map<String,? extends Object> values)
           
 ExtendedUriBuilder clone()
          
 ExtendedUriBuilder extension(String extensions)
          Set the extension that will be appended to the final path segment at build time.
 ExtendedUriBuilder extensionLanguage(String language)
          Appends an extension for the language ("de", "en", "fr" or whatever).
 ExtendedUriBuilder extensionMedia(String mediaExtension)
          Appends an extension for the media type ("html", "pdf", "gif" or whatever).
 ExtendedUriBuilder fragment(String fragment)
          Set the URI fragment using an unencoded value.
static ExtendedUriBuilder fromPath(String path)
          Create a new instance representing a relative URI initialized from a URI path.
static ExtendedUriBuilder fromResource(Class<?> resource)
          Create a new instance representing a relative URI initialized from a root resource class.
static ExtendedUriBuilder fromUri(String uri)
          Create a new instance initialized from an existing URI.
static ExtendedUriBuilder fromUri(URI uri)
          Create a new instance initialized from an existing URI.
 String getExtension()
          Returns the extension of the current uri, if available.
 ExtendedUriBuilder host(String host)
          Set the URI host.
 ExtendedUriBuilder matrixParam(String name, Object... values)
          Append a matrix parameter to the existing set of matrix parameters of the current final segment of the URI path.
static ExtendedUriBuilder newInstance()
          Creates a new instance of UriBuilder.
 ExtendedUriBuilder path(Class resource)
          Append path segments from a Path-annotated class to the existing list of segments.
 ExtendedUriBuilder path(Class resource, String methodName)
          Append path segments from a Path-annotated method to the existing list of segments.
 ExtendedUriBuilder path(Method method)
          Append the path from a Path-annotated method to the existing path.
 ExtendedUriBuilder path(String pathToAppend)
          Append path to the existing path.
 ExtendedUriBuilder port(int port)
          Set the URI port.
 ExtendedUriBuilder port(String port)
          Set the URI port.
 ExtendedUriBuilder queryParam(String name, Object... values)
          Append a query parameter to the existing set of query parameters.
 ExtendedUriBuilder replaceMatrix(String matrix)
          Set the matrix parameters of the current final segment of the current URI path.
 ExtendedUriBuilder replaceMatrixParam(String name, Object... values)
          
 ExtendedUriBuilder replacePath(String newPath)
          Set the URI path.
 ExtendedUriBuilder replaceQuery(String query)
          Set the URI query string.
 ExtendedUriBuilder replaceQueryParam(String name, Object... values)
          
 ExtendedUriBuilder scheme(String scheme)
          Set the URI scheme.
 ExtendedUriBuilder schemeSpecificPart(String ssp)
          Set the URI scheme-specific-part (see URI).
 ExtendedUriBuilder segment(String... segments)
          Append path segments to the existing path.
 String toString()
          Returns the actual URI as String.
 ExtendedUriBuilder uri(URI uri)
          Copies the non-null components of the supplied URI to the UriBuilder replacing any existing values for those components.
 ExtendedUriBuilder userInfo(String ui)
          Set the URI user-info.
 
Methods inherited from class org.restlet.ext.jaxrs.AbstractUriBuilder
copyInto, path, replacePath
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ExtendedUriBuilder

public ExtendedUriBuilder()
Method Detail

fromPath

public static ExtendedUriBuilder fromPath(String path)
                                   throws IllegalArgumentException
Create a new instance representing a relative URI initialized from a URI path.

Parameters:
path - a URI path that will be used to initialize the UriBuilder, may contain URI template parameters.
Returns:
a new UriBuilder
Throws:
IllegalArgumentException - if path is null

fromResource

public static ExtendedUriBuilder fromResource(Class<?> resource)
                                       throws IllegalArgumentException
Create a new instance representing a relative URI initialized from a root resource class.

Parameters:
resource - a root resource whose Path value will be used to initialize the UriBuilder.
Returns:
a new UriBuilder
Throws:
IllegalArgumentException - if resource is not annotated with Path or resource is null.

fromUri

public static ExtendedUriBuilder fromUri(String uri)
                                  throws IllegalArgumentException
Create a new instance initialized from an existing URI.

Parameters:
uri - a URI that will be used to initialize the UriBuilder, may not contain URI parameters.
Returns:
a new UriBuilder
Throws:
IllegalArgumentException - if uri is not a valid URI or is null

fromUri

public static ExtendedUriBuilder fromUri(URI uri)
                                  throws IllegalArgumentException
Create a new instance initialized from an existing URI.

Parameters:
uri - a URI that will be used to initialize the UriBuilder.
Returns:
a new UriBuilder
Throws:
IllegalArgumentException - if uri is null

newInstance

public static ExtendedUriBuilder newInstance()
Creates a new instance of UriBuilder.

Returns:
a new instance of UriBuilder

clone

public ExtendedUriBuilder clone()

Overrides:
clone in class javax.ws.rs.core.UriBuilder

extension

public ExtendedUriBuilder extension(String extensions)
Set the extension that will be appended to the final path segment at build time. An initial "." will be appended if necessary. If the final path segment already contains an extension, it will be retained and the supplied extension will be used as a new extension.

Note that the extension will be appended to the path component, matrix and query parameters will follow any appended extension.

Parameters:
extensions - the extensions to append at build time, a null value will result in no extension being appended.
Returns:
the updated UriBuilder

extensionLanguage

public ExtendedUriBuilder extensionLanguage(String language)
Appends an extension for the language ("de", "en", "fr" or whatever). null resets the language extension.

Parameters:
language -
Returns:
this ExtendedUriBuilder

extensionMedia

public ExtendedUriBuilder extensionMedia(String mediaExtension)
Appends an extension for the media type ("html", "pdf", "gif" or whatever). null resets the media type extension.

Parameters:
mediaExtension -
Returns:
this ExtendedUriBuilder

fragment

public ExtendedUriBuilder fragment(String fragment)
Set the URI fragment using an unencoded value.

Overrides:
fragment in class AbstractUriBuilder
Parameters:
fragment - the URI fragment, may contain URI template parameters
Returns:
the updated UriBuilder
See Also:
UriBuilder.fragment(java.lang.String)

getExtension

public String getExtension()
Returns the extension of the current uri, if available.

Overrides:
getExtension in class AbstractUriBuilder
Returns:
the extension for content negotiation, including a "." at the start, or null if no extension is available. Never returns "" or ".".

host

public ExtendedUriBuilder host(String host)
                        throws IllegalArgumentException
Set the URI host.

Overrides:
host in class AbstractUriBuilder
Parameters:
host - the URI host, may contain URI template parameters
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if host is invalid or is null
See Also:
UriBuilder.host(java.lang.String)

matrixParam

public ExtendedUriBuilder matrixParam(String name,
                                      Object... values)
                               throws IllegalArgumentException
Append a matrix parameter to the existing set of matrix parameters of the current final segment of the URI path. If multiple values are supplied the parameter will be added once per value. Note that the matrix parameters are tied to a particular path segment; subsequent addition of path segments will not affect their position in the URI path.

Overrides:
matrixParam in class AbstractUriBuilder
Parameters:
name - the matrix parameter name, may contain URI template parameters
values - the matrix parameter value(s), each object will be converted to a String using its toString() method. Stringified values may contain URI template parameters.
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if name or value is null, or if automatic encoding is disabled and the name or any stringified value contains illegal characters
See Also:
Matrix URIs, UriBuilder.matrixParam(String, Object...)

path

public ExtendedUriBuilder path(Class resource)
                        throws IllegalArgumentException
Append path segments from a Path-annotated class to the existing list of segments. When constructing the final path, each segment will be separated by '/' if necessary. The value of the encode property of the Path annotation will be used when processing the value of the @Path but it will not be used to modify the state of automatic encoding for the builder.

Overrides:
path in class AbstractUriBuilder
Parameters:
resource - a resource whose @Path value will be used to obtain the path segment.
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if resource is null, or if resource.encode is false and resource.value contains illegal characters, or if resource is not annotated with UrPath
See Also:
UriBuilder.path(java.lang.Class)

path

public ExtendedUriBuilder path(Class resource,
                               String methodName)
                        throws IllegalArgumentException
Append path segments from a Path-annotated method to the existing list of segments. When constructing the final path, each segment will be separated by '/' if necessary. This method is a convenience shortcut to path(Method), it can only be used in cases where there is a single method with the specified name that is annotated with @ Path.

Overrides:
path in class AbstractUriBuilder
Parameters:
resource - the root resource class containing the method.
methodName - the name of the method whose @Path value will be used to obtain the path segment.
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if resource or method is null, or if the specified method does not exist, or there is more than or less than one variant of the method annotated with UriPath
See Also:
UriBuilder.path(java.lang.Class, java.lang.String)

path

public ExtendedUriBuilder path(Method method)
                        throws IllegalArgumentException
Append the path from a Path-annotated method to the existing path. When constructing the final path, a '/' separator will be inserted between the existing path and the supplied path if necessary.

Overrides:
path in class AbstractUriBuilder
Parameters:
method - a method whose Path value will be used to obtain the path to append to the existing path
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if any element of methods is null or is not annotated with a Path
See Also:
UriBuilder.path(java.lang.reflect.Method)

path

public ExtendedUriBuilder path(String pathToAppend)
                        throws IllegalArgumentException
Append path to the existing path. When constructing the final path, a '/' separator will be inserted between the existing path and the supplied path if necessary. Existing '/' characters are preserved thus a single value can represent multiple URI path segments.

Overrides:
path in class AbstractUriBuilder
Parameters:
pathToAppend - the path to append to the current path, may contain URI template parameters
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if path is null
See Also:
UriBuilder.path(java.lang.String)

port

public ExtendedUriBuilder port(int port)
                        throws IllegalArgumentException
Set the URI port.

Overrides:
port in class AbstractUriBuilder
Parameters:
port - the URI port, a value of -1 will unset an explicit port.
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if port is invalid
See Also:
UriBuilder.port(int)

port

public ExtendedUriBuilder port(String port)
                        throws IllegalArgumentException
Set the URI port. Only integers or a variable template is allowed

Overrides:
port in class AbstractUriBuilder
Parameters:
port - the URI port (null will unset an explicit port) or a template variable.
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if given value is invalid
See Also:
AbstractUriBuilder.port(int)

queryParam

public ExtendedUriBuilder queryParam(String name,
                                     Object... values)
                              throws IllegalArgumentException
Append a query parameter to the existing set of query parameters. If multiple values are supplied the parameter will be added once per value.

Overrides:
queryParam in class AbstractUriBuilder
Parameters:
name - the query parameter name, may contain URI template parameters
values - the query parameter value(s), each object will be converted to a String using its toString() method. Stringified values may contain URI template parameters.
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if name or value is null, or if automatic encoding is disabled and name or value contains illegal characters
See Also:
UriBuilder.queryParam(String, Object...)

replaceMatrix

public ExtendedUriBuilder replaceMatrix(String matrix)
                                 throws IllegalArgumentException
Set the matrix parameters of the current final segment of the current URI path. This method will overwrite any existing matrix parameters on the current final segment of the current URI path. Note that the matrix parameters are tied to a particular path segment; subsequent addition of path segments will not affect their position in the URI path.

Overrides:
replaceMatrix in class AbstractUriBuilder
Parameters:
matrix - the matrix parameters, may contain URI template parameters. A null value will remove all matrix parameters of the current final segment of the current URI path.
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if matrix cannot be parsed, or if automatic encoding is disabled and any matrix parameter name or value contains illegal characters
See Also:
UriBuilder.replaceMatrix(String)

replaceMatrixParam

public ExtendedUriBuilder replaceMatrixParam(String name,
                                             Object... values)
                                      throws IllegalArgumentException

Overrides:
replaceMatrixParam in class AbstractUriBuilder
Throws:
IllegalArgumentException
See Also:
UriBuilder.replaceMatrixParam(java.lang.String, java.lang.Object[])

replacePath

public ExtendedUriBuilder replacePath(String newPath)
Set the URI path. This method will overwrite any existing path and associated matrix parameters. Existing '/' characters are preserved thus a single value can represent multiple URI path segments.

Overrides:
replacePath in class AbstractUriBuilder
Parameters:
newPath - the path to replace the old path with, may contain URI template parameters. A null value will unset the path component of the URI.
Returns:
the updated UriBuilder
See Also:
UriBuilder.replacePath(java.lang.String)

replaceQuery

public ExtendedUriBuilder replaceQuery(String query)
                                throws IllegalArgumentException
Set the URI query string. This method will overwrite any existing query parameters.

Overrides:
replaceQuery in class AbstractUriBuilder
Parameters:
query - the URI query string, may contain URI template parameters. A null value will remove all query parameters.
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if query cannot be parsed
See Also:
UriBuilder.replaceQuery(java.lang.String)

replaceQueryParam

public ExtendedUriBuilder replaceQueryParam(String name,
                                            Object... values)
                                     throws IllegalArgumentException

Overrides:
replaceQueryParam in class AbstractUriBuilder
Throws:
IllegalArgumentException
See Also:
UriBuilder.replaceQueryParam(String, Object[])

scheme

public ExtendedUriBuilder scheme(String scheme)
                          throws IllegalArgumentException
Set the URI scheme.

Overrides:
scheme in class AbstractUriBuilder
Parameters:
scheme - the URI scheme, may contain URI template parameters
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if scheme is invalid or is null
See Also:
UriBuilder.scheme(java.lang.String)

schemeSpecificPart

public ExtendedUriBuilder schemeSpecificPart(String ssp)
                                      throws IllegalArgumentException
Set the URI scheme-specific-part (see URI). This method will overwrite any existing values for authority, user-info, host, port and path.

Overrides:
schemeSpecificPart in class AbstractUriBuilder
Parameters:
ssp - the URI scheme-specific-part, may contain URI template parameters
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if ssp cannot be parsed or is null
See Also:
UriBuilder.schemeSpecificPart(java.lang.String)

segment

public ExtendedUriBuilder segment(String... segments)
                           throws IllegalArgumentException
Append path segments to the existing path. When constructing the final path, a '/' separator will be inserted between the existing path and the first path segment if necessary and each supplied segment will also be separated by '/'. Existing '/' characters are encoded thus a single value can only represent a single URI path segment.

Overrides:
segment in class AbstractUriBuilder
Parameters:
segments - the path segment values, each may contain URI template parameters
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if segments or any element of segments is null
See Also:
UriBuilder.segment(java.lang.String[])

uri

public ExtendedUriBuilder uri(URI uri)
                       throws IllegalArgumentException
Copies the non-null components of the supplied URI to the UriBuilder replacing any existing values for those components.

Overrides:
uri in class AbstractUriBuilder
Parameters:
uri - the URI to copy components from
Returns:
the updated UriBuilder
Throws:
IllegalArgumentException - if uri is null
See Also:
UriBuilder.uri(java.net.URI)

userInfo

public ExtendedUriBuilder userInfo(String ui)
Set the URI user-info.

Overrides:
userInfo in class AbstractUriBuilder
Parameters:
ui - the URI user-info, may contain URI template parameters
Returns:
the updated UriBuilder
See Also:
UriBuilder.userInfo(java.lang.String)

build

public URI build(Object... values)
          throws IllegalArgumentException,
                 javax.ws.rs.core.UriBuilderException
Build a URI, using the supplied values in order to replace any URI template parameters. Values are converted to String using their toString method and are then encoded to match the rules of the URI component to which they pertain. All '%' characters in the stringified values will be encoded. The state of the builder is unaffected; this method may be called multiple times on the same builder instance.

All instances of the same template parameter will be replaced by the same value that corresponds to the position of the first instance of the template parameter. e.g. the template "{a}/{b}/{a}" with values {"x", "y", "z"} will result in the the URI "x/y/x", not "x/y/z".

Overrides:
build in class AbstractUriBuilder
Parameters:
values - a list of URI template parameter values
Returns:
the URI built from the UriBuilder
Throws:
IllegalArgumentException - if there are any URI template parameters without a supplied value, or if a value is null.
javax.ws.rs.core.UriBuilderException - if a URI cannot be constructed based on the current state of the builder.
See Also:
UriBuilder.build(java.lang.Object[])

buildFromEncoded

public URI buildFromEncoded(Object... values)
                     throws IllegalArgumentException,
                            javax.ws.rs.core.UriBuilderException

Overrides:
buildFromEncoded in class AbstractUriBuilder
Throws:
IllegalArgumentException
javax.ws.rs.core.UriBuilderException
See Also:
UriBuilder.buildFromEncoded(java.lang.Object[])

buildFromEncodedMap

public URI buildFromEncodedMap(Map<String,? extends Object> values)
                        throws IllegalArgumentException,
                               javax.ws.rs.core.UriBuilderException

Overrides:
buildFromEncodedMap in class AbstractUriBuilder
Throws:
IllegalArgumentException
javax.ws.rs.core.UriBuilderException
See Also:
UriBuilder.buildFromEncodedMap(java.util.Map)

buildFromMap

public URI buildFromMap(Map<String,? extends Object> values)
                 throws IllegalArgumentException,
                        javax.ws.rs.core.UriBuilderException
Overrides:
buildFromMap in class AbstractUriBuilder
Throws:
IllegalArgumentException
javax.ws.rs.core.UriBuilderException
See Also:
UriBuilder.buildFromMap(java.util.Map)

toString

public String toString()
Returns the actual URI as String.

Overrides:
toString in class AbstractUriBuilder
Returns:
the actual URI as String.
See Also:
AbstractUriBuilder.toStringWithCheck(boolean)


Copyright © 2005-2013 Restlet.