javax.ws.rs.core
Class UriBuilder

java.lang.Object
  extended by 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