Configuring JAX-RS 2.0 client
For Java™ API for XML RESTful Web Services 2.0, you can configure the client to access REST endpoints. JAX-RS 2.0 introduces a new and standardized Client API so that you can make http requests to your remote RESTful web services.
About this task
Client
is required to access a Web resource using the
Client API. The default instance of Client can be obtained by calling newClient
or
build
on ClientBuilder
. After you create the client, you can
configure it at the server level or within the client application.Procedure
What to do next
After you create the JAX-RS 2.0 client, you can configure it either by defining
webTarget
elements in the server.xml file or by programmatically configuring
properties in the client application.
To configure
properties in the server.xml file with the webTarget
XML
element:
<webTarget URI="value" property="value" property="value".../>
When a webTarget
object is instantiated and its URI matches the URI value in this
element, the properties are applied to the webTarget
object. Consider the following
configuration information when you define the webTarget
element:- The URI can be exact, such as
http://foo
, or end with a trailing*
, such ashttp://foo*
. When you use a trailing*
, the properties are applied to anywebTarget
object with a URI that begins withhttp://foo
. - If more than one
webTarget
element in the server.xml file matches the URI, exact matches are applied first, then wildcard matches, in sorted order by URI. - Property name matching is case-insensitive.
- Any provided JAX-RS property name and value can be used. To find the shortened names for configuration properties, see webTarget JAX-RS Client Properties.
To programmatically configure properties in the JAX-RS 2.0 application:
- Use the com.ibm.ws.jaxrs.client.connection.timeout client property and the
com.ibm.ws.jaxrs.client.receive.timeout client property to set the timeout value.
- com.ibm.ws.jaxrs.client.connection.timeout
javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.connection.timeout", "1000"); Client c = cb.build();
-
com.ibm.ws.jaxrs.client.receive.timeout
javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.receive.timeout", "1000"); Client c = cb.build();
Tip: The value of the timeout property is millisecond, and the type must be long or int. If the type of the value is invalid, the following message is displayed:CWWKW0700E: The timeout value {0} that you specified in the property com.ibm.ws.jaxrs.client.receive.timeout on the JAX-RS Client side is invalid. The value is set to default 30000. {3}
- com.ibm.ws.jaxrs.client.connection.timeout
- Use the com.ibm.ws.jaxrs.client.keepalive.connection property to set the
desired persistent connection
behavior.
. keep-alive (default) - specifies that the connections should persist across multiple requests javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.keepalive.connection", "keep-alive"); Client c = cb.build(); . close - specifies that the connections should closed following each request javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.keepalive.connection", "close"); Client c = cb.build();
- Use the following client properties for client proxy support:
ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.proxy.host", "hostname"); cb.property("com.ibm.ws.jaxrs.client.proxy.port", "8888";); cb.property("com.ibm.ws.jaxrs.client.proxy.type", "HTTP"); Client c = cb.build();
- com.ibm.ws.jaxrs.client.proxy.host
- com.ibm.ws.jaxrs.client.proxy.portTip: The type of the proxy server port value must be int. The default value is 80. If the value type is invalid, the following message is displayed:
CWWKW0701E: The proxy server port value {0} that you specified in the property com.ibm.ws.jaxrs.client.proxy.port on the JAX-RS Client side is invalid. The value is set to default 80. {3}
- com.ibm.ws.jaxrs.client.proxy.typeTip: The value of the proxy server type must be HTTP or SOCKS. The default value is HTTP. If the type of the proxy server is invalid, the following message is displayed:
CWWKW0702E: The proxy server type value {0} that you specified in the property com.ibm.ws.jaxrs.client.proxy.type on the JAX-RS Client side is invalid. The value is set to default HTTP. {3}
- Use the com.ibm.ws.jaxrs.client.ltpa.handler client property to set SSO
cookie and set the value to true.
If you want to use the Secure Sockets Layer (SSL) function in JAX-RS 2.0, you need to enable the transportSecurity-1.0 or appSecurity-2.0 feature. For the LTPA token function, the appSecurity-2.0 feature is required.ClientBuilder cb = ClientBuilder.newBuilder(); Client c = cb.build(); c.property("com.ibm.ws.jaxrs.client.ltpa.handler", "true");
For more information about how to configure the environment to have JAX-RS 2.0 client to run with SSL through IHS, see Configuring IBM® HTTP server SSL support.
Note: The transportSecurity-1.0 feature is a subfeature of the appSecurity-2.0 feature. If you enable the jaxrsClient-2.0 feature and the transportSecurity-1.0 feature, the appSecurity-2.0 feature is enabled automatically. - Use the com.ibm.ws.jaxrs.client.ssl.config client property to set the SSL
reference ID of server.xml.
For more information about establishing trust by extracting certificate from IHS key file and add it to the Liberty JKS file, see Create a key database file and certificates needed to authenticate the Web server during an SSL handshake.ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.ssl.config", "mySSLRefId"); Client c = cb.build();
Note: The configuration in server.xml shows as follows:<ssl id="mySSLRefId" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore" />
- Instead of programmatically setting the
com.ibm.ws.jaxrs.client.ssl.config client property, configure outbound SSL so that the JAX-RS 2.0
client can rely on the SSL configuration to identify the outbound SSL to use.
To configure outbound SSL, you can configure both the outbound SSL filters and the outbound SSL default, or you can configure either one of the two options. No matter which combination of options you implement, you must enable the transportSecurity-1.0 feature.
- Enable the transportSecurity-1.0 feature in your server.xml
file:
<featureManager> <feature>transportSecurity-1.0</feature> </featureManager>
- Configure outbound SSL filters so that they specify the SSL configuration for a destination
host, or both a destination host and a destination port. The configuration in the server.xml file that you are to update is as follows:
For more information about outbound SSL filters, see Outbound filters for SSL configurations.<ssl id="mySSLRefId" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore"> <outboundConnection host="myhost.atdomain.com" port="9443" /> <outboundConnection host="theotherhost.atdomain.com" port="8020" /> </ssl> <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" > <outboundConnection host="defaulthost.domain.com" /> </ssl>
- Configure the outbound SSL default.
If no SSL filter exists to match the outbound connection, the JAX-RS client uses the outbound SSL default.
The configuration in the server.xml file that you are to update is as follows:
For more information about the SSL outbound default, see Configuring SSL Settings for outbound communications.<sslDefault outboundSSLRef="mySSLRefId" /> <ssl id="mySSLRefId" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore"/> <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" />
- Enable the transportSecurity-1.0 feature in your server.xml
file:
- Use the com.ibm.ws.jaxrs.client.disableCNCheck client property to disable the
common name
check.
ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.disableCNCheck", true);