public class JerseyWebTarget extends Object implements WebTarget, Initializable<JerseyWebTarget>
JAX-RS client target
contract.Modifier | Constructor and Description |
---|---|
protected |
JerseyWebTarget(UriBuilder uriBuilder,
ClientConfig clientConfig)
Create new web target instance.
|
protected |
JerseyWebTarget(UriBuilder uriBuilder,
JerseyWebTarget that)
Create new web target instance.
|
Modifier and Type | Method and Description |
---|---|
ClientConfig |
getConfiguration()
Get a live view of an internal configuration state of this configurable instance.
|
URI |
getUri()
Get the URI identifying the resource.
|
UriBuilder |
getUriBuilder()
Get the URI builder initialized with the
URI of the current resource target. |
JerseyWebTarget |
matrixParam(String name,
Object... values)
Create a new
WebTarget instance by appending a matrix parameter to the existing set of matrix parameters of
the current final segment of the URI of the current target instance. |
JerseyWebTarget |
path(String path)
Create a new
WebTarget instance by appending path to the URI of the current target instance. |
JerseyWebTarget |
preInitialize()
Pre-initializes the runtime and runtime
configuration of this component
in order to improve performance during the first request. |
JerseyWebTarget |
property(String name,
Object value)
Set the new configuration property, if already set, the existing value of the property will be updated.
|
JerseyWebTarget |
queryParam(String name,
Object... values)
Create a new
WebTarget instance by configuring a query parameter on the URI of the current target instance. |
JerseyWebTarget |
register(Class<?> providerClass)
Register a class of a custom JAX-RS component (such as an extension provider or a
feature meta-provider) to be instantiated and used in the scope of this configurable context. |
JerseyWebTarget |
register(Class<?> providerClass,
Class<?>... contracts)
Register a class of a custom JAX-RS component (such as an extension provider or a
feature meta-provider) to be instantiated and used in the scope of this configurable context. |
JerseyWebTarget |
register(Class<?> providerClass,
int bindingPriority)
Register a class of a custom JAX-RS component (such as an extension provider or a
feature meta-provider) to be instantiated and used in the scope of this configurable context. |
JerseyWebTarget |
register(Class<?> providerClass,
Map<Class<?>,Integer> contracts)
Register a class of a custom JAX-RS component (such as an extension provider or a
feature meta-provider) to be instantiated and used in the scope of this configurable context. |
JerseyWebTarget |
register(Object provider)
Register an instance of a custom JAX-RS component (such as an extension provider or a
feature meta-provider) to be instantiated and used in the scope of this configurable context. |
JerseyWebTarget |
register(Object provider,
Class<?>... contracts)
Register an instance of a custom JAX-RS component (such as an extension provider or a
feature meta-provider) to be instantiated and used in the scope of this configurable context. |
JerseyWebTarget |
register(Object provider,
int bindingPriority)
Register an instance of a custom JAX-RS component (such as an extension provider or a
feature meta-provider) to be instantiated and used in the scope of this configurable context. |
JerseyWebTarget |
register(Object provider,
Map<Class<?>,Integer> contracts)
Register an instance of a custom JAX-RS component (such as an extension provider or a
feature meta-provider) to be instantiated and used in the scope of this configurable context. |
JerseyInvocation.Builder |
request()
Start building a request to the targeted web resource.
|
JerseyInvocation.Builder |
request(MediaType... acceptedResponseTypes)
Start building a request to the targeted web resource and define the accepted response media types.
|
JerseyInvocation.Builder |
request(String... acceptedResponseTypes)
Start building a request to the targeted web resource and define the accepted response media types.
|
JerseyWebTarget |
resolveTemplate(String name,
Object value)
Create a new
WebTarget instance by resolving a URI template with a given name in the URI of the
current target instance using a supplied value. |
JerseyWebTarget |
resolveTemplate(String name,
Object value,
boolean encodeSlashInPath)
Create a new
WebTarget instance by resolving a URI template with a given name in the URI of the
current target instance using a supplied value. |
JerseyWebTarget |
resolveTemplateFromEncoded(String name,
Object value)
Create a new
WebTarget instance by resolving a URI template with a given name in the URI of the
current target instance using a supplied encoded value. |
JerseyWebTarget |
resolveTemplates(Map<String,Object> templateValues)
Create a new
WebTarget instance by resolving one or more URI templates in the URI of the current target
instance using supplied name-value pairs. |
JerseyWebTarget |
resolveTemplates(Map<String,Object> templateValues,
boolean encodeSlashInPath)
Create a new
WebTarget instance by resolving one or more URI templates in the URI of the current target
instance using supplied name-value pairs. |
JerseyWebTarget |
resolveTemplatesFromEncoded(Map<String,Object> templateValues)
Create a new
WebTarget instance by resolving one or more URI templates in the URI of the current target
instance using supplied name-encoded value pairs. |
String |
toString() |
protected JerseyWebTarget(UriBuilder uriBuilder, JerseyWebTarget that)
uriBuilder
- builder for the target URI.that
- original target to copy the internal data from.protected JerseyWebTarget(UriBuilder uriBuilder, ClientConfig clientConfig)
uriBuilder
- builder for the target URI.clientConfig
- target configuration.public URI getUri()
WebTarget
public UriBuilder getUriBuilder()
WebTarget
URI
of the current resource target. The returned URI builder is
detached from the target, i.e. any updates in the URI builder MUST NOT have any effects on the URI of the originating
target.getUriBuilder
in interface WebTarget
public JerseyWebTarget path(String path) throws NullPointerException
WebTarget
WebTarget
instance by appending path to the URI of the current target instance.
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.
A snapshot of the present configuration of the current (parent) target instance is taken and is inherited by the newly constructed (child) target instance.
path
in interface WebTarget
path
- the path, may contain URI template parameters.NullPointerException
- if path is null
.public JerseyWebTarget matrixParam(String name, Object... values) throws NullPointerException
WebTarget
WebTarget
instance by appending a matrix parameter to the existing set of matrix parameters of
the current final segment of the URI of the current target instance.
If multiple values are supplied the parameter will be added once per value. In case a single null
value is
entered, all parameters with that name in the current final path segment are removed (if present) from the collection
of last segment matrix parameters inherited from the current target.
Note that the matrix parameters are tied to a particular path segment; appending a value to an existing matrix parameter name will not affect the position of the matrix parameter in the URI path.
A snapshot of the present configuration of the current (parent) target instance is taken and is inherited by the newly constructed (child) target instance.
matrixParam
in interface WebTarget
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.NullPointerException
- if the parameter name is null
or if there are multiple values present and any of
those values is null
.public JerseyWebTarget queryParam(String name, Object... values) throws NullPointerException
WebTarget
WebTarget
instance by configuring a query parameter on the URI of the current target instance.
If multiple values are supplied the parameter will be added once per value. In case a single null
value is
entered, all parameters with that name are removed (if present) from the collection of query parameters inherited
from the current target.
A snapshot of the present configuration of the current (parent) target instance is taken and is inherited by the newly constructed (child) target instance.
queryParam
in interface WebTarget
name
- the query parameter name, may contain URI template parametersvalues
- the query parameter value(s), each object will be converted to a String
using its
toString()
method. Stringified values may contain URI template parameters.NullPointerException
- if the parameter name is null
or if there are multiple values present and any of
those values is null
.public JerseyInvocation.Builder request()
WebTarget
public JerseyInvocation.Builder request(String... acceptedResponseTypes)
WebTarget
Invoking this method is identical to:
webTarget.request().accept(types);
public JerseyInvocation.Builder request(MediaType... acceptedResponseTypes)
WebTarget
Invoking this method is identical to:
webTarget.request().accept(types);
public JerseyWebTarget resolveTemplate(String name, Object value) throws NullPointerException
WebTarget
WebTarget
instance by resolving a URI template with a given name
in the URI of the
current target instance using a supplied value.
In case a null
template name or value is entered a NullPointerException
is thrown.
A snapshot of the present configuration of the current (parent) target instance is taken and is inherited by the newly constructed (child) target instance.
resolveTemplate
in interface WebTarget
name
- name of the URI template.value
- value to be used to resolve the template.NullPointerException
- if the resolved template name or value is null
.public JerseyWebTarget resolveTemplate(String name, Object value, boolean encodeSlashInPath) throws NullPointerException
WebTarget
WebTarget
instance by resolving a URI template with a given name
in the URI of the
current target instance using a supplied value.
In case a null
template name or value is entered a NullPointerException
is thrown.
A snapshot of the present configuration of the current (parent) target instance is taken and is inherited by the newly constructed (child) target instance.
resolveTemplate
in interface WebTarget
name
- name of the URI template.value
- value to be used to resolve the template.encodeSlashInPath
- if true
, the slash ('/'
) characters in template values will be encoded if
the template is placed in the URI path component, otherwise the slash characters will not be encoded in path
templates.NullPointerException
- if the resolved template name or value is null
.public JerseyWebTarget resolveTemplateFromEncoded(String name, Object value) throws NullPointerException
WebTarget
WebTarget
instance by resolving a URI template with a given name
in the URI of the
current target instance using a supplied encoded value.
A template with a matching name will be replaced by the supplied value. Value is converted to String
using
its toString()
method and is then encoded to match the rules of the URI component to which they pertain. All
% characters in the stringified values that are not followed by two hexadecimal numbers will be encoded.
In case a null
template name or value is entered a NullPointerException
is thrown.
A snapshot of the present configuration of the current (parent) target instance is taken and is inherited by the newly constructed (child) target instance.
resolveTemplateFromEncoded
in interface WebTarget
name
- name of the URI template.value
- encoded value to be used to resolve the template.NullPointerException
- if the resolved template name or value is null
.public JerseyWebTarget resolveTemplates(Map<String,Object> templateValues) throws NullPointerException
WebTarget
WebTarget
instance by resolving one or more URI templates in the URI of the current target
instance using supplied name-value pairs.
A call to the method with an empty parameter map is ignored, i.e. same WebTarget
instance is returned.
A snapshot of the present configuration of the current (parent) target instance is taken and is inherited by the newly constructed (child) target instance.
resolveTemplates
in interface WebTarget
templateValues
- a map of URI template names and their values.NullPointerException
- if the name-value map or any of the names or values in the map is null
.public JerseyWebTarget resolveTemplates(Map<String,Object> templateValues, boolean encodeSlashInPath) throws NullPointerException
WebTarget
WebTarget
instance by resolving one or more URI templates in the URI of the current target
instance using supplied name-value pairs.
A call to the method with an empty parameter map is ignored, i.e. same WebTarget
instance is returned.
A snapshot of the present configuration of the current (parent) target instance is taken and is inherited by the newly constructed (child) target instance.
resolveTemplates
in interface WebTarget
templateValues
- a map of URI template names and their values.encodeSlashInPath
- if true
, the slash ('/'
) characters in template values will be encoded if
the template is placed in the URI path component, otherwise the slash characters will not be encoded in path
templates.NullPointerException
- if the name-value map or any of the names or values in the map is null
.public JerseyWebTarget resolveTemplatesFromEncoded(Map<String,Object> templateValues) throws NullPointerException
WebTarget
WebTarget
instance by resolving one or more URI templates in the URI of the current target
instance using supplied name-encoded value pairs.
All templates with their name matching one of the keys in the supplied map will be replaced by the value in the
supplied map. 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 that are not
followed by two hexadecimal numbers will be encoded.
A call to the method with an empty parameter map is ignored, i.e. same WebTarget
instance is returned.
A snapshot of the present configuration of the current (parent) target instance is taken and is inherited by the newly constructed (child) target instance.
resolveTemplatesFromEncoded
in interface WebTarget
templateValues
- a map of URI template names and their encoded values.NullPointerException
- if the name-value map or any of the names or encoded values in the map is null
.public JerseyWebTarget register(Class<?> providerClass)
Configurable
feature
meta-provider) to be instantiated and used in the scope of this configurable context.
Implementations SHOULD warn about and ignore registrations that do not conform to the requirements of supported
JAX-RS component types in the given configurable context. Any subsequent registration attempts for a component type,
for which a class or instance-based registration already exists in the system MUST be rejected by the JAX-RS
implementation and a warning SHOULD be raised to inform the user about the rejected registration.
The registered JAX-RS component class is registered as a contract provider of all the recognized JAX-RS or
implementation-specific extension contracts including meta-provider contracts, such as Feature
or
DynamicFeature
.
As opposed to component instances registered via Configurable.register(Object)
method, the lifecycle of components
registered using this class-based register(...)
method is fully managed by the JAX-RS implementation or any
underlying IoC container supported by the implementation.
register
in interface Configurable<WebTarget>
providerClass
- JAX-RS component class to be configured in the scope of this configurable context.public JerseyWebTarget register(Object provider)
Configurable
feature
meta-provider) to be instantiated and used in the scope of this configurable context.
Implementations SHOULD warn about and ignore registrations that do not conform to the requirements of supported
JAX-RS component types in the given configurable context. Any subsequent registration attempts for a component type,
for which a class or instance-based registration already exists in the system MUST be rejected by the JAX-RS
implementation and a warning SHOULD be raised to inform the user about the rejected registration.
The registered JAX-RS component is registered as a contract provider of all the recognized JAX-RS or
implementation-specific extension contracts including meta-provider contracts, such as Feature
or
DynamicFeature
.
As opposed to components registered via Configurable.register(Class)
method, the lifecycle of providers registered using
this instance-based register(...)
is not managed by JAX-RS runtime. The same registered component instance is
used during the whole lifespan of the configurable context. Fields and properties of all registered JAX-RS component
instances are injected with their declared dependencies (see Context
) by the JAX-RS runtime prior to use.
register
in interface Configurable<WebTarget>
provider
- JAX-RS component instance to be configured in the scope of this configurable context.public JerseyWebTarget register(Class<?> providerClass, int bindingPriority)
Configurable
feature
meta-provider) to be instantiated and used in the scope of this configurable context.
This registration method provides the same functionality as Configurable.register(Class)
except that any priority
specified on the registered JAX-RS component class via jakarta.annotation.Priority
annotation is overridden
with the supplied priority
value.
Note that in case the priority is not applicable to a particular provider contract implemented by the class of the
registered component, the supplied priority
value will be ignored for that contract.
register
in interface Configurable<WebTarget>
providerClass
- JAX-RS component class to be configured in the scope of this configurable context.bindingPriority
- the overriding priority for the registered component and all the provider contracts the component
implements.public JerseyWebTarget register(Class<?> providerClass, Class<?>... contracts)
Configurable
feature
meta-provider) to be instantiated and used in the scope of this configurable context.
This registration method provides the same functionality as Configurable.register(Class)
except the JAX-RS component
class is only registered as a provider of the listed extension provider or meta-provider contracts
. All
explicitly enumerated contract types must represent a class or an interface implemented or extended by the registered
component. Contracts that are not assignable from
the registered component
class MUST be ignored and implementations SHOULD raise a warning to inform users about the ignored contract(s).
register
in interface Configurable<WebTarget>
providerClass
- JAX-RS component class to be configured in the scope of this configurable context.contracts
- the specific extension provider or meta-provider contracts implemented by the component for which
the component should be registered. Implementations MUST ignore attempts to register a component class for an empty
or null
collection of contracts via this method and SHOULD raise a warning about such event.public JerseyWebTarget register(Class<?> providerClass, Map<Class<?>,Integer> contracts)
Configurable
feature
meta-provider) to be instantiated and used in the scope of this configurable context.
This registration method provides same functionality as Configurable.register(Class, Class[])
except that any priority
specified on the registered JAX-RS component class via jakarta.annotation.Priority
annotation is overridden for
each extension provider contract type separately with an integer priority value specified as a value in the supplied
map of [contract type, priority] pairs.
Note that in case a priority is not applicable to a provider contract registered for the JAX-RS component, the supplied priority value is ignored for such contract.
register
in interface Configurable<WebTarget>
providerClass
- JAX-RS component class to be configured in the scope of this configurable context.contracts
- map of the specific extension provider and meta-provider contracts and their associated priorities
for which the JAX-RS component is registered. All contracts in the map must represent a class or an interface
implemented or extended by the JAX-RS component. Contracts that are not assignable from
the registered component class MUST be ignored and implementations SHOULD raise a warning to inform
users about the ignored contract(s).public JerseyWebTarget register(Object provider, int bindingPriority)
Configurable
feature
meta-provider) to be instantiated and used in the scope of this configurable context.
This registration method provides the same functionality as Configurable.register(Object)
except that any priority
specified on the registered JAX-RS component class via jakarta.annotation.Priority
annotation is overridden
with the supplied priority
value.
Note that in case the priority is not applicable to a particular provider contract implemented by the class of the
registered component, the supplied priority
value will be ignored for that contract.
register
in interface Configurable<WebTarget>
provider
- JAX-RS component instance to be configured in the scope of this configurable context.bindingPriority
- the overriding priority for the registered component and all the provider contracts the component
implements.public JerseyWebTarget register(Object provider, Class<?>... contracts)
Configurable
feature
meta-provider) to be instantiated and used in the scope of this configurable context.
This registration method provides the same functionality as Configurable.register(Object)
except the JAX-RS component
class is only registered as a provider of the listed extension provider or meta-provider contracts
. All
explicitly enumerated contract types must represent a class or an interface implemented or extended by the registered
component. Contracts that are not assignable from
the registered component
class MUST be ignored and implementations SHOULD raise a warning to inform users about the ignored contract(s).
register
in interface Configurable<WebTarget>
provider
- JAX-RS component instance to be configured in the scope of this configurable context.contracts
- the specific extension provider or meta-provider contracts implemented by the component for which
the component should be registered. Implementations MUST ignore attempts to register a component class for an empty
or null
collection of contracts via this method and SHOULD raise a warning about such event.public JerseyWebTarget register(Object provider, Map<Class<?>,Integer> contracts)
Configurable
feature
meta-provider) to be instantiated and used in the scope of this configurable context.
This registration method provides same functionality as Configurable.register(Object, Class[])
except that any priority
specified on the registered JAX-RS component class via jakarta.annotation.Priority
annotation is overridden for
each extension provider contract type separately with an integer priority value specified as a value in the supplied
map of [contract type, priority] pairs.
Note that in case a priority is not applicable to a provider contract registered for the JAX-RS component, the supplied priority value is ignored for such contract.
register
in interface Configurable<WebTarget>
provider
- JAX-RS component instance to be configured in the scope of this configurable context.contracts
- map of the specific extension provider and meta-provider contracts and their associated priorities
for which the JAX-RS component is registered. All contracts in the map must represent a class or an interface
implemented or extended by the JAX-RS component. Contracts that are not assignable from
the registered component class MUST be ignored and implementations SHOULD raise a warning to inform
users about the ignored contract(s).public JerseyWebTarget property(String name, Object value)
Configurable
null
value into a property effectively removes the property from the property bag.property
in interface Configurable<WebTarget>
name
- property name.value
- (new) property value. null
value removes the property with the given name.public ClientConfig getConfiguration()
Configurable
Configurable
instance will be reflected in the returned
Configuration
instance.
The returned Configuration
instance and the collection data it provides are not thread-safe wrt. modification
made using methods on the parent configurable object.
getConfiguration
in interface Configurable<WebTarget>
getConfiguration
in interface Initializable<JerseyWebTarget>
public JerseyWebTarget preInitialize()
Initializable
configuration
of this component
in order to improve performance during the first request.
Once this method is called no other method implementing Configurable
should be called
on this pre initialized component, otherwise the initialized client runtime will be discarded and the configuration
will change back to uninitialized.
preInitialize
in interface Initializable<JerseyWebTarget>
Copyright © 2007-2024, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.