Notes

We recommend that you reuse the already created Client object because creating an object incurs process cost. When creating a WebResource object more than once, or calling a Web resource more than once by using a method of the Client class, you need not create more than one Client objects.

Similarly, because creating WebResource also incurs cost, we recommend that you reuse the already created WebResource object. When creating more than one builders and HTTP requests for the same Web resource (URL), you need not create more than one WebResource object.

The methods used to set a Client class or methods of a Client class that destroy objects, however, are not thread safe. To know whether the methods are thread safe, check the following:

When sharing a Client object across multiple threads, configure the settings for the Client object to be shared before multiple threads start operating.
Destroy the Client object after the operation of multiple threads is complete.

If you execute these operations during the operation of multiple threads, the communication might fail and an invalid HTTP request might be sent.

When implementing a Web resource client with servlets or EJBs, create a Client object by using the initialization methods of servlets and EJBs and configure the required settings. Similarly, destroy the Client objects by using the destroy methods.

The following example shows a client API for RESTful Web Services used in servlets:

@WebServlet("/example")
public class ClientServlet extends HttpServlet {
    
  // A client object to be shared
  private Client client = null;
 
  // A WebResource object to be shared
  private WebResource proxy = null;
 
  @PostConstruct
  public void postConstruct() {
    // Create a client object to use 
    // a client API for RESTful Web Services
    this.client = Client.create();
    // Setting the client: Obtain the property bag from the Client object
    Map<String, Object> properties = this.client.getProperties();
    // Setting the client: Set the read timeout
    properties.put(ClientConfig.PROPERTY_READ_TIMEOUT, 10000);
    //  Create a WebResource object from the Client object
    this.proxy = this.client.resource( "http://..." );
  }
 
 @PreDestroy
  public void preDestory() {
    //  destroy the Client object
    if( this.client != null ){
      this.client.destroy();
      this.client = null;
    }
  }
 
  @Override
  public void doGet( HttpServletRequest request, HttpServletResponse response )
    throws ServletException, IOException{
    ...
    ClientResponse clientResponse = null;
    // Invoke resource
    try {
      // Set a cookie and obtain an HTTP response from the Web resource
      Cookie cookie = new Cookie("cookie", "cookie%20value");
      clientResponse = this.proxy.cookie(cookie).get(ClientResponse.class);
    }catch (Exception e) {
      printStackTrace( e, out );
    }
    ...
  }
}

For details on the thread safety of a client API for RESTful Web Services, see 25.16 Thread safety of a client API for RESTful Web Services.

(2) Settings for proxy SSL connection and basic verification

(3) Notes for using the Windows environment

The following exception might be logged if you use an environment in which you can send large number of requests from the Web resource client.

java.net.BindException: Address already in use: connect  [errno=10048, syscall=select]

This exception is thrown when a large number of requests are received for a Web resource client implemented as a servlet.

In such cases, take either or both of the following measures:

Expand the range of port numbers available on the OS
Example: Changing the settings of MaxUserPort of the registry.
Decrease the duration of TIME_WAIT
Example: Changing the settings of TcpTimedWaitDelay of the registry.

However, see the documentation of your OS for details, as the specifications differ depending on the version, edition, and security update program installed on the OS. Note that the above settings are applied to the entire OS.

(4) Controlling the resending of a request

The JAX-RS engine on the Web resource client side communicates by using the HTTP client implemented by the JDK. The HTTP client implemented by the JDK resends the request only once if, in contradiction to RFC 2616, an error occurs in the HTTP communication and the client is unable to receive appropriate responses from the server. Using the system property of the JDK enables you to control the resending of a request. For details, see 10.20 Preventing the resending of a request by sun.net.www.http.HttpClient. Also, when reading, substitute Web Services client with RESTful Web Services client and substitute JAX-WS engine with JAX-RS engine.

11.4.5 Notes

(1) Reusing the objects

(2) Settings for proxy SSL connection and basic verification

(3) Notes for using the Windows environment

(4) Controlling the resending of a request

(5) Executing a client application using the command line