javax.ws.rs.core
Class UriBuilder

java.lang.Object
  javax.ws.rs.core.UriBuilder

@Contract
public abstract class UriBuilder
extends java.lang.Object

URI template aware utility class for building URIs from their components. See UriTemplate.value() for an explanation of URI templates.

See Also:

URI, UriTemplate

Constructor Summary

UriBuilder()

Method Summary

abstract UriBuilder	authority(java.lang.String authority) Set the URI authority.
abstract java.net.URI	build() Build a URI, any URI template parameters will be replaced by the empty string.
abstract java.net.URI	build(java.util.Map<java.lang.String,java.lang.String> values) Build a URI, any URI template parameters will be replaced by the value in the supplied map.
abstract java.net.URI	build(java.lang.String... values) Build a URI, using the supplied values in order to replace any URI template parameters.
UriBuilder	fragment(java.lang.String fragment) Set the URI fragment using an unencoded value, equivalent to fragment(fragment, true).
abstract UriBuilder	fragment(java.lang.String fragment, boolean encode) Set the URI fragment.
static UriBuilder	fromPath(java.lang.String path) Create a new instance initialized from an unencoded URI path, equivalent to fromPath(path, true).
static UriBuilder	fromPath(java.lang.String path, boolean encode) Create a new instance initialized from a URI path.
static UriBuilder	fromResource(java.lang.Class resource) Create a new instance initialized from a root resource class.
static UriBuilder	fromUri(java.net.URI uri) Create a new instance initialized from an existing URI.
abstract UriBuilder	host(java.lang.String host) Set the URI host.
UriBuilder	matrixParam(java.lang.String name, java.lang.String value) Append a matrix parameter to the existing set of matrix parameters of the final segment of the current URI path, equivalent to matrixParam(name, value, true).
abstract UriBuilder	matrixParam(java.lang.String name, java.lang.String value, boolean encode) Append a matrix parameter to the existing set of matrix parameters of the final segment of the current URI path.
protected static UriBuilder	newInstance() Creates a new instance of UriBuilder
abstract UriBuilder	path(boolean encode, java.lang.String... segments) Append path segments to the existing list of segments.
abstract UriBuilder	path(java.lang.Class resource) Append path segments to the existing list of segments.
UriBuilder	path(java.lang.String... segments) Append unencoded path segments to the existing list of segments, equivalent to path(true, segments).
abstract UriBuilder	port(int port) Set the URI port.
UriBuilder	queryParam(java.lang.String name, java.lang.String value) Append a query parameter to the existing set of query parameters, equivalent to queryParam(name, value, true).
abstract UriBuilder	queryParam(java.lang.String name, java.lang.String value, boolean encode) Append a query parameter to the existing set of query parameters.
UriBuilder	replaceMatrixParams(java.lang.String matrix) Set the matrix parameters of the final segment of the current URI path using an unencoded value, equivalent to replaceMatrixParams(matrix, true).
abstract UriBuilder	replaceMatrixParams(java.lang.String matrix, boolean encode) Set the matrix parameters of the final segment of the current URI path.
UriBuilder	replacePath(java.lang.String path) Set the URI path using an unencoded value, equivalent to replacePath(path, true).
abstract UriBuilder	replacePath(java.lang.String path, boolean encode) Set the URI path.
UriBuilder	replaceQueryParams(java.lang.String query) Set the URI query string using an unencoded value, equivalent to replaceQueryParams(query, true).
abstract UriBuilder	replaceQueryParams(java.lang.String query, boolean encode) Set the URI query string.
abstract UriBuilder	scheme(java.lang.String scheme) Set the URI scheme.
abstract UriBuilder	schemeSpecificPart(java.lang.String ssp) Set the URI scheme-specific-part.
abstract UriBuilder	uri(java.net.URI uri) Copies the non-null components of the supplied URI to the UriBuilder.
UriBuilder	userInfo(java.lang.String ui) Set the URI user-info using an unencoded value.
abstract UriBuilder	userInfo(java.lang.String ui, boolean encode) Set the URI user-info.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UriBuilder

public UriBuilder()

Method Detail

newInstance

protected static UriBuilder newInstance()

Creates a new instance of UriBuilder

Returns:

a new instance of UriBuilder

fromUri

public static UriBuilder fromUri(java.net.URI uri)

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

fromPath

public static UriBuilder fromPath(java.lang.String path)

Create a new instance initialized from an unencoded URI path, equivalent to fromPath(path, true).

Parameters:

path - a URI path that will be used to initialize the UriBuilder.

Returns:

a new UriBuilder

fromPath

public static UriBuilder fromPath(java.lang.String path,
                                  boolean encode)

Create a new instance initialized from a URI path.

Parameters:

path - a URI path that will be used to initialize the UriBuilder.

encode - controls whether the supplied value is automatically encoded (true) or not (false). If false, the value must be valid with all illegal characters already escaped.

Returns:

a new UriBuilder

fromResource

public static UriBuilder fromResource(java.lang.Class resource)

Create a new instance initialized from a root resource class.

Parameters:

resource - a root resource whose @UriTemplate value will be used to initialize the UriBuilder.

Returns:

a new UriBuilder

uri

public abstract UriBuilder uri(java.net.URI uri)

Copies the non-null components of the supplied URI to the UriBuilder.

Parameters:

uri - the URI to copy components from

Returns:

the updated UriBuilder

scheme

public abstract UriBuilder scheme(java.lang.String scheme)

Set the URI scheme.

Parameters:

scheme - the URI scheme

Returns:

the updated UriBuilder

schemeSpecificPart

public abstract UriBuilder schemeSpecificPart(java.lang.String ssp)

Set the URI scheme-specific-part. This method will overwrite any existing values for authority, user-info, host, port and path.

Parameters:

ssp - the URI scheme-specific-part

Returns:

the updated UriBuilder

authority

public abstract UriBuilder authority(java.lang.String authority)

Set the URI authority. This method will overwrite any existing user-info host and port.

Parameters:

authority - the URI authority

Returns:

the updated UriBuilder

userInfo

public UriBuilder userInfo(java.lang.String ui)

Set the URI user-info using an unencoded value. Equivalent to userInfo(ui, true).

Parameters:

ui - the URI user-info

Returns:

the updated UriBuilder

userInfo

public abstract UriBuilder userInfo(java.lang.String ui,
                                    boolean encode)

Set the URI user-info.

Parameters:

ui - the URI user-info

encode - controls whether the supplied value is automatically encoded (true) or not (false). If false, the value must be valid with all illegal characters already escaped.

Returns:

the updated UriBuilder

host

public abstract UriBuilder host(java.lang.String host)

Set the URI host.

Parameters:

host - the URI host

Returns:

the updated UriBuilder

port

public abstract UriBuilder port(int port)

Set the URI port.

Parameters:

port - the URI port

Returns:

the updated UriBuilder

replacePath

public UriBuilder replacePath(java.lang.String path)

Set the URI path using an unencoded value, equivalent to replacePath(path, true). This method will overwrite any existing path segments.

Parameters:

path - the URI path, may contain URI template parameters

Returns:

the updated UriBuilder

replacePath

public abstract UriBuilder replacePath(java.lang.String path,
                                       boolean encode)

Set the URI path. This method will overwrite any existing path segments.

Parameters:

path - the URI path, may contain URI template parameters

encode - controls whether the supplied value is automatically encoded (true) or not (false). If false, the value must be valid with all illegal characters already escaped.

Returns:

the updated UriBuilder

path

public UriBuilder path(java.lang.String... segments)

Append unencoded path segments to the existing list of segments, equivalent to path(true, segments). When constructing the final path, each segment will be separated by '/' if necessary.

Parameters:

segments - the path segments, may contain URI template parameters

Returns:

the updated UriBuilder

path

public abstract UriBuilder path(boolean encode,
                                java.lang.String... segments)

Append path segments to the existing list of segments. When constructing the final path, each segment will be separated by '/' if necessary.

Parameters:

segments - the path segments, may contain URI template parameters

encode - controls whether the supplied values are automatically encoded (true) or not (false). If false, the values must be valid with all illegal characters already escaped.

Returns:

the updated UriBuilder

path

public abstract UriBuilder path(java.lang.Class resource)

Append path segments to the existing list of segments. When constructing the final path, each segment will be separated by '/' if necessary.

Parameters:

resource - a root resource whose @UriTemplate value will be used to obtain the path segments

Returns:

the updated UriBuilder

replaceMatrixParams

public UriBuilder replaceMatrixParams(java.lang.String matrix)

Set the matrix parameters of the final segment of the current URI path using an unencoded value, equivalent to replaceMatrixParams(matrix, true). This method will overwrite any existing matrix parameters on the final segment of the current URI path.

Parameters:

matrix - the matrix parameters, may contain URI template parameters

Returns:

the updated UriBuilder

replaceMatrixParams

public abstract UriBuilder replaceMatrixParams(java.lang.String matrix,
                                               boolean encode)

Set the matrix parameters of the final segment of the current URI path. This method will overwrite any existing matrix parameters on the final segment of the current URI path.

Parameters:

matrix - the matrix parameters, may contain URI template parameters

encode - controls whether the supplied value is automatically encoded (true) or not (false). If false, the value must be valid with all illegal characters already escaped.

Returns:

the updated UriBuilder

matrixParam

public UriBuilder matrixParam(java.lang.String name,
                              java.lang.String value)

Append a matrix parameter to the existing set of matrix parameters of the final segment of the current URI path, equivalent to matrixParam(name, value, true).

Parameters:

name - the matrix parameter name, may contain URI template parameters

value - the matrix parameter value, may contain URI template parameters

Returns:

the updated UriBuilder

matrixParam

public abstract UriBuilder matrixParam(java.lang.String name,
                                       java.lang.String value,
                                       boolean encode)

Append a matrix parameter to the existing set of matrix parameters of the final segment of the current URI path.

Parameters:

name - the matrix parameter name, may contain URI template parameters

value - the matrix parameter value, may contain URI template parameters

encode - controls whether the supplied name and value are automatically encoded (true) or not (false). If false, the name and value must be valid with all illegal characters already escaped.

Returns:

the updated UriBuilder

replaceQueryParams

public UriBuilder replaceQueryParams(java.lang.String query)

Set the URI query string using an unencoded value, equivalent to replaceQueryParams(query, true). This method will overwrite any existing query parameters.

Parameters:

query - the URI query string

Returns:

the updated UriBuilder

replaceQueryParams

public abstract UriBuilder replaceQueryParams(java.lang.String query,
                                              boolean encode)

Set the URI query string. This method will overwrite any existing query parameters.

Parameters:

query - the URI query string

encode - controls whether the supplied value is automatically encoded (true) or not (false). If false, the value must be valid with all illegal characters already escaped.

Returns:

the updated UriBuilder

queryParam

public UriBuilder queryParam(java.lang.String name,
                             java.lang.String value)

Append a query parameter to the existing set of query parameters, equivalent to queryParam(name, value, true).

Parameters:

name - the query parameter name, may contain URI template parameters

value - the query parameter value, may contain URI template parameters

Returns:

the updated UriBuilder

queryParam

public abstract UriBuilder queryParam(java.lang.String name,
                                      java.lang.String value,
                                      boolean encode)

Append a query parameter to the existing set of query parameters.

Parameters:

name - the query parameter name, may contain URI template parameters

value - the query parameter value, may contain URI template parameters

encode - controls whether the supplied name and value are automatically encoded (true) or not (false). If false, the name and value must be valid with all illegal characters already escaped.

Returns:

the updated UriBuilder

fragment

public UriBuilder fragment(java.lang.String fragment)

Set the URI fragment using an unencoded value, equivalent to fragment(fragment, true).

Parameters:

fragment - the URI fragment

Returns:

the updated UriBuilder

fragment

public abstract UriBuilder fragment(java.lang.String fragment,
                                    boolean encode)

Set the URI fragment.

Parameters:

fragment - the URI fragment

encode - controls whether the supplied value is automatically encoded (true) or not (false). If false, the value must be valid with all illegal characters already escaped.

Returns:

the updated UriBuilder

build

public abstract java.net.URI build()

Build a URI, any URI template parameters will be replaced by the empty string.

Returns:

the URI built from the UriBuilder

build

public abstract java.net.URI build(java.util.Map<java.lang.String,java.lang.String> values)

Build a URI, any URI template parameters will be replaced by the value in the supplied map. Any URI template parameters without a value will be replaced by the empty string.

Parameters:

values - a map of URI template parameter names and values

Returns:

the URI built from the UriBuilder

build

public abstract java.net.URI build(java.lang.String... values)

Build a URI, using the supplied values in order to replace any URI template parameters. Any URI template parameters without a value will be replaced by the empty string.

Parameters:

values - a list of URI template parameter values

Returns:

the URI built from the UriBuilder