The following figure shows a use case describing the sending and receiving of HTTP requests and HTTP responses by specifying a Java type.

Figure 11-1 Use case describing the sending and receiving of HTTP requests and HTTP responses by specifying a Java type

#1

You can reference or change the properties included in a map by various methods. For details, see 11.4.3 Setting the properties and features.

#2

You can generate a request by using various methods of a client API. For details, see 11.4.3 Setting the properties and features.

#3

Sends an HTTP request entity body in the character string format by using the HTTP POST method and similarly, receives an HTTP response entity body in the character string format.

The client API also contains the methods corresponding to each HTTP method such as DELETE, GET, HEAD, OPTIONS, and PUT. For details, see 11.4.3 Setting the properties and features.

#4

HttpURLConnection establishes the HTTP communication. The JAX-RS engine establishes the communication until the HTTP message is created and then delegates the communication to HttpURLConnection of the Java SE.

The coding example corresponding to figure 11-1 is as follows:

The procedure in the example is as follows:

1. Create a client object by using the create() static method of the Client class.
2. Set a property in the changeable property map acquired with the getProperties() method of the Client class. You can also set the properties by using different methods. For details on properties and features, see 11.4.3 Setting the properties and features.
3. Create a WebResource object by calling the resource() method of the Client class and generate an HTTP request by calling a method of the WebResource object. The WebResource class is designed by using the builder pattern and contains various methods to generate an HTTP request.
4. Establish the HTTP communication by calling the post() method of the WebResource.Builder class. The WebResource class also contains the methods corresponding to each HTTP method, such as DELETE, GET, HEAD, OPTIONS, and PUT.

You can also receive an HTTP response in a generic type such as the ClientResponse object. Acquiring an HTTP response with the ClientResponse object enables a user to obtain various types of information of the received HTTP response (HTTP header, entity body, and status code).

You can acquire an entity body by using the getEntity() method, thereby specifying the Java type. For details on the methods supported by the ClientResponse class, see 25.1 The support range of client API interfaces and classes.

The method to acquire an HTTP response to be received with ClientResponse object is as follows:

To create an HTTP request by using the WebResource object, specify ClientResponse.class in the parameter that specifies the Java type of the HTTP response. Specify ClientResponse.class instead of String.class in the coding example described in 11.4.1(1) Sending and receiving HTTP requests and HTTP responses by specifying a Java type..

The HTTP response is always ClientResponse if you directly send an HTTP request using the Client class. For details on the Client class, see 11.4.1(3) Sending and receiving HTTP requests and HTTP responses in a generic type.

The following figure shows a use case describing sending and receiving HTTP requests and HTTP responses (ClientRequest and ClientResponse) in generic types.

Figure 11-2 Use case describing sending and receiving HTTP requests and HTTP responses in generic types.

#1

You can reference or change the properties included in a map with various methods. For details, see 11.4.3 Setting the properties and features.

#2

You can create a request by using various methods of a client API. For details, see 11.4.3 Setting the properties and features.

#3

You can send an HTTP request entity body in the character string format by using the HTTP POST method and similarly, receive an entity body of an HTTP response in the character string format.

A client API contains the methods corresponding to each HTTP method, such as DELETE, GET, HEAD, OPTIONS, and PUT. For details, see 11.4.3 Setting properties and features.

#4

HttpURLConnection establishes a connection. The JAX-RS engine establishes the communication until the HTTP message is created and then delegates the communication to HttpURLConnection of the Java SE.

The coding example corresponding to figure11-2 is as follows.

Client client = Client.create();
Map<String, Object> properties = client.getProperties();
properties.put(ClientConfig.PROPERTY_READ_TIMEOUT, 10000);
ClientRequest ro;
ClientRequest.Builder builder = ClientRequest.create();
builder.accept( MediaType.APPLICATION_JSON_TYPE );
builder.type( MediaType.TEXT_PLAIN_TYPE );
builder.entity("Some Request");
ro = builder.build(new URI("http://example.org/helloworld"), "POST");
ClientResponse clientResponse = client.handle(ro);
//The actual response in the form of String
String response = clientResponse.getEntity(String.class);

The procedure in the example is as follows:

1. Create a client object by using the create() static method of the Client class.
2. Set a property in the changeable property map acquired with the getProperties() method of the Client class. For details on the properties and features, see 11.4.3 Setting the properties and features.
3. Create a ClientRequest.Builder object by calling the create() method of the ClientRequest class and generate an HTTP request by calling a method of the ClientRequest.Builder object. The ClientRequest.Builder class is designed in the builder pattern and contains various methods to generate HTTP requests.
4. Call a build() method of the ClientRequest.Builder class and create a ClientRequest object. Then, establish the HTTP communication by using the handle() method of the Client class.