org.restlet.ext.jaxrs

Class ExtendedUriBuilder

java.lang.Object

javax.ws.rs.core.UriBuilder

org.restlet.ext.jaxrs.AbstractUriBuilder

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

Constructors

Constructor and Description
ExtendedUriBuilder()

Method Summary

Methods

Modifier and Type	Method and Description
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

build

public URI build(Object... values)
          throws IllegalArgumentException,
                 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.

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,
                            UriBuilderException

Overrides:

buildFromEncoded in class AbstractUriBuilder

Throws:

IllegalArgumentException

UriBuilderException

See Also:

UriBuilder.buildFromEncoded(java.lang.Object[])

buildFromEncodedMap

public URI buildFromEncodedMap(Map<String,? extends Object> values)
                        throws IllegalArgumentException,
                               UriBuilderException

Overrides:

buildFromEncodedMap in class AbstractUriBuilder

Throws:

IllegalArgumentException

UriBuilderException

See Also:

UriBuilder.buildFromEncodedMap(java.util.Map)

buildFromMap

public URI buildFromMap(Map<String,? extends Object> values)
                 throws IllegalArgumentException,
                        UriBuilderException

Overrides:

buildFromMap in class AbstractUriBuilder

Throws:

IllegalArgumentException

UriBuilderException

See Also:

UriBuilder.buildFromMap(java.util.Map)

clone

public ExtendedUriBuilder clone()

Overrides:

clone in class 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[])

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)

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)