Obtaining an HTTP Request Builder

You need to use a builder object, which is an instance of the HttpRequest.Builder class, to create an HttpRequest. You can get an HttpRequest.Builder using one of the following static methods of the HttpRequest class:

• HttpRequest.Builder newBuilder()

• HttpRequest.Builder newBuilder(URI uri)

The following snippet of code shows you how to use these methods to get an HttpRequest.Builder instance:

// A URI to point to google
URI googleUri = new URI("http://www.google.com");

// Get a builder for the google URI
HttpRequest.Builder builder1 = HttpRequest.newBuilder(googleUri);

// Get a builder without specifying a URI at this time
HttpRequest.Builder builder2 = HttpRequest.newBuilder();

Setting HTTP Request Parameters

Once you have an HTTP request builder, you can set different parameters for the request using the builder’s methods. All methods return the builder itself, so you can chain them. Those methods are as follows:

• HttpRequest.Builder DELETE(HttpRequest.BodyProcessor body)

• HttpRequest.Builder expectContinue(boolean enable)

• HttpRequest.Builder GET()

• HttpRequest.Builder header(String name, String value)

• HttpRequest.Builder headers(String... headers)

• HttpRequest.Builder method(String method, HttpRequest.BodyProcessor body)

• HttpRequest.Builder POST(HttpRequest.BodyProcessor body)

• HttpRequest.Builder PUT(HttpRequest.BodyProcessor body)

• HttpRequest.Builder setHeader(String name, String value)

• HttpRequest.Builder timeout(Duration duration)

• HttpRequest.Builder uri(URI uri)

• HttpRequest.Builder version(HttpClient.Version version)

An HttpRequest is sent to a server using an HttpClient. When you are building an HTTP request, you can set the HTTP version value through its the HttpRequest.Builder object using the version() method that will override the HTTP version set in the HttpClient when this request is sent. The following snippet of code sets the HTTP version to 2.0 for a request, which overrides the default value of NEVER in the default HttpClient object:

// By default a client uses HTTP 1.1. All requests sent using this
// HttpClient will use HTTP 1.1 unless overridden by the request
HttpClient client = HttpClient.newHttpClient();
                                                                                      
// A URI to point to google
URI googleUri = new URI("http://www.google.com");

// Get an HttpRequest that uses HTTP 2.0
HttpRequest request = HttpRequest.newBuilder(googleUri)
                                 .version(HttpClient.Version.HTTP_2)
                                 .build();
// The client object contains HTTP version as 1.1 and the request
// object contains HTTP version 2.0. The following statement will
// send the request using HTTP 2.0, which is in the request object.
HttpResponse<String> r = client.send(request, BodyHandler.asString());

The timeout() method specifies a timeout for the request. If a response is not received within the specified timeout period, an HttpTimeoutException is thrown.

An HTTP request may contain a header named expect with its value "100-Continue". If this header is set, the client sends only headers to the server and the server is expected to send back an error response or a 100-Continue response. Upon receiving this response, the client sends the request body to the server. A client uses this techniques to check if the server can process the request based on the request’s headers, before the client sends the actual request body. This header is not set by default. You need to call the expectContinue(true) method of the request builder to enable this. Note that calling the header("expect", "100-Continue") method of the request builder does not enable this feature. You must use the expectContinue(true) method to enable it.

// Enable the expect=100-Continue header in the request
HttpRequest.Builder builder = HttpRequest.newBuilder()                                                               
                                         .expectContinue(true);

The following sections describe how to set the headers, body, and method of an HTTP request.

// Create a URI
URI calc = new URI("http://localhost:8080/webapp/Calculator");

// Use the header() method
HttpRequest.Builder builder1 = HttpRequest.newBuilder(calc)
    .header("Content-Type", "application/x-www-form-urlencoded")
    .header("Accept", "text/plain");

// Use the headers() method
HttpRequest.Builder builder2 = HttpRequest.newBuilder(calc)                
    .headers("Content-Type", "application/x-www-form-urlencoded",
             "Accept", "text/plain");

// Use the setHeader() method
HttpRequest.Builder builder3 = HttpRequest.newBuilder(calc)                
    .setHeader("Content-Type", "application/x-www-form-urlencoded")
    .setHeader("Accept", "text/plain");

URI calc = new URI("http://localhost:8080/webapp/Calculator");

// Compose the form data with n1 = 10, n2 = 20. And op = +      
String formData = "n1=" + URLEncoder.encode("10","UTF-8") +
                  "&n2=" + URLEncoder.encode("20","UTF-8") +
                  "&op=" + URLEncoder.encode("+","UTF-8")  ;

HttpRequest.Builder builder = HttpRequest.newBuilder(calc)                
    .header("Content-Type", "application/x-www-form-urlencoded")
    .header("Accept", "text/plain")
    .POST(HttpRequest.BodyProcessor.fromString(formData));

HttpRequest request = HttpRequest.newBuilder()
                                 .uri(new URI("http://www.google.com"))
                                 .GET()
                                 .build();

// Build the URI and the form’s data
URI calc = new URI("http://localhost:8080/webapp/Calculator");               
String formData = "n1=" + URLEncoder.encode("10","UTF-8") +
                  "&n2=" + URLEncoder.encode("20","UTF-8") +
                  "&op=" + URLEncoder.encode("+","UTF-8");

// Build the HttpRequest object
HttpRequest request = HttpRequest.newBuilder(calc)   
   .header("Content-Type", "application/x-www-form-urlencoded")
   .header("Accept", "text/plain")   
   .POST(HttpRequest.BodyProcessor.fromString(formData))
   .build();

HttpRequest request =
    HttpRequest.newBuilder(new URI("http://www.google.com"))   
               .method("HEAD", HttpRequest.noBody())
               .build();

// GoogleHeadersTest.java
package com.jdojo.http.client;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import jdk.incubator.http.HttpClient;
import jdk.incubator.http.HttpRequest;
import jdk.incubator.http.HttpResponse;

public class GoogleHeadersTest {
    public static void main(String[] args) {
        try {
            URI googleUri = new URI("http://www.google.com");
            HttpClient client = HttpClient.newHttpClient();
            HttpRequest request =
                HttpRequest.newBuilder(googleUri)
                           .method("HEAD", HttpRequest.noBody())
                           .build();
            HttpResponse<?> response =
              client.send(request, HttpResponse.BodyHandler.discard(null));

            // Print the response status code and headers                                                            
            System.out.println("Response Status Code:" +
                               response.statusCode());

            System.out.println("Response Headers are:");
            response.headers()
                    .map()
                    .entrySet()
                    .forEach(System.out::println);
        } catch (URISyntaxException | InterruptedException |
                 IOException e) {
            e.printStackTrace();
        }
    }
}
WARNING: Using incubator modules: jdk.incubator.httpclient
Response Status Code:200
Response Headers are:
accept-ranges=[none]
cache-control=[private, max-age=0]
content-type=[text/html; charset=ISO-8859-1]
date=[Sun, 26 Feb 2017 16:39:36 GMT]
expires=[-1]
p3p=[CP="This is not a P3P policy! See https://www.google.com/support/accounts/answer/151657?hl=en for more info."]
server=[gws]
set-cookie=[NID=97=Kmz52m8Zdf4lsNDsnMyrJomx_2kD7lnWYcNEuwPWsFTFUZ7yli6DbCB98Wv-SlxOfKA0OoOBIBgysuZw3ALtgJjX67v7-mC5fPv88n8VpwxrNcjVGCfFrxVro6gRNIrye4dAWZvUVfY28eOM; expires=Mon, 28-Aug-2017 16:39:36 GMT; path=/; domain=.google.com; HttpOnly]
transfer-encoding=[chunked]
vary=[Accept-Encoding]
x-frame-options=[SAMEORIGIN]
x-xss-protection=[1; mode=block]                                                                                               

import java.net.URI;
import jdk.incubator.http.HttpClient;
import jdk.incubator.http.HttpRequest;
import jdk.incubator.http.HttpResponse;
import static jdk.incubator.http.HttpResponse.BodyHandler.asString;
...
// Build the request
HttpRequest request = HttpRequest.newBuilder()
                .uri(new URI("http://google.com"))
                .GET()
                .build();

// Send the request and get a Response
HttpResponse<String> response = HttpClient.newHttpClient()
                                          .send(request, asString());

// Get the response body and print it
String body = response.body();
System.out.println(body);<HTML><HEAD><meta http-equiv="content-type"
WARNING: Using incubator modules: jdk.incubator.httpclient
<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="http://www.google.com/">here</A>.
</BODY></HTML>

// The request will follow the redirects issues by the server       
HttpResponse<String> response = HttpClient.newBuilder()
    .followRedirects(HttpClient.Redirect.ALWAYS)                
    .build()
    .send(request, asString());

// CalculatorTest.java
package com.jdojo.http.client;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URLEncoder;
import jdk.incubator.http.HttpClient;
import jdk.incubator.http.HttpRequest;
import static jdk.incubator.http.HttpRequest.BodyProcessor.fromString;
import jdk.incubator.http.HttpResponse;

public class CalculatorTest {
    public static void main(String[] args) {
        try {
            URI calcUri =
                new URI("http://localhost:8080/webapp/Calculator");

            String formData = "n1=" + URLEncoder.encode("10","UTF-8") +
                              "&n2=" + URLEncoder.encode("20","UTF-8") +
                              "&op=" + URLEncoder.encode("+","UTF-8")  ;

            // Create a request
            HttpRequest request = HttpRequest.newBuilder()
                .uri(calcUri)
                .header("Content-Type", "application/x-www-form-urlencoded")
                .header("Accept", "text/plain")                
                .POST(fromString(formData))
                .build();

            // Process the response asynchronously. When the response
            // is ready, the processResponse() method of this class will
            // be called.
            HttpClient.newHttpClient()
                      .sendAsync(request,
                                 HttpResponse.BodyHandler.asString())
                      .whenComplete(CalculatorTest::processResponse);

            try {
                // Let the current thread sleep for 5 seconds,
                // so the async response processing is complete
                Thread.sleep(5000);
            } catch (InterruptedException ex) {
                ex.printStackTrace();
            }
        } catch (URISyntaxException | IOException e) {
            e.printStackTrace();
        }                                                                                              
    }

    private static void processResponse(HttpResponse<String> response,
                                       Throwable t) {

         if (t == null ) {
             System.out.println("Response Status Code: " +  
                                 response.statusCode());
             System.out.println("Response Body: " + response.body());
         } else {
            System.out.println("An exception occurred while " +
                "processing the HTTP request. Error: " +  t.getMessage());
         }
     }
}
WARNING: Using incubator modules: jdk.incubator.httpclient
Response Status Code: 200
Response Body: 10 + 20 = 30.0

HttpClient.newBuilder()
          .followRedirects(HttpClient.Redirect.ALWAYS)
          .build()
          .sendAsync(HttpRequest.newBuilder()           
                                .uri(new URI("http://www.google.com"))
                                .GET()
                                .build(),
                                asFile(Paths.get("google.html")))
           .whenComplete((HttpResponse<Path> response,
                          Throwable exception) -> {
               if(exception == null) {
                  System.out.println("File saved to " +
                                     response.body().toAbsolutePath());
              } else {
                  exception.printStackTrace();
              }
            });                                                                                      

// Get an HTTP response
HttpResponse<String> response = HttpClient.newBuilder()
                  .followRedirects(HttpClient.Redirect.ALWAYS)
                  .build()
                  .send(HttpRequest.newBuilder()           
                                   .uri(new URI("http://www.google.com"))
                                   .GET()
                                   .build(),
                                   asString());
// Read the response body
String body = response.body();
// Process trailers
response.trailers()
        .whenComplete((HttpHeaders trailers, Throwable t) -> {
             if(t == null) {
                 trailers.map()
                         .entrySet()
                         .forEach(System.out::println);
             } else {
                  t.printStackTrace();
             }
         });

Creating a Server Endpoint

Creating a server endpoint requires using Java EE. This book is focused on Java SE 9. I explain briefly how to create a server endpoint to be used in the example in this section. Without covering the details, I use Java EE 7 annotations to create a WebSocket server endpoint.

Listing 14-4 contains the code for a class named TimeServerEndPoint. The class is included in the web application in the webapp directory of the book’s source code. When you deploy the web application to a web server, this class will be deployed as a server endpoint .

Listing 14-4. A WebSocket Server Endpoint

// TimeServerEndPoint.java
package com.jdojo.ws;

import java.io.IOException;
import java.time.ZonedDateTime;
import java.util.concurrent.TimeUnit;
import javax.websocket.CloseReason;
import javax.websocket.OnMessage;
import javax.websocket.OnOpen;
import javax.websocket.OnClose;
import javax.websocket.OnError;
import javax.websocket.Session;
import javax.websocket.server.ServerEndpoint;
import static javax.websocket.CloseReason.CloseCodes.NORMAL_CLOSURE;

@ServerEndpoint("/servertime")
public class TimeServerEndPoint {
    @OnOpen
    public void onOpen(Session session) {                
        System.out.println("Client connected. ");
    }
    @OnClose
    public void onClose(Session session) {        
        System.out.println("Connection closed.");
    }
    @OnError
    public void onError(Session session, Throwable t) {
        System.out.println("Error occurred:" + t.getMessage());
    }
    @OnMessage                                                
    public void onMessage(String message, Session session) {
        System.out.println("Client: " + message);                
        // Send messages to the client
        sendMessages(session);
    }
    private void sendMessages(Session session) {
        /* Start a new thread and send 3 messages to the
           client. Each message contains the current date and
           time with zone.
        */
        new Thread(() -> {
            for(int i = 0; i < 3; i++) {
                String currentTime =
                    ZonedDateTime.now().toString();
                try {
                    session.getBasicRemote()
                           .sendText(currentTime, true);
                    TimeUnit.SECONDS.sleep(5);
                } catch(InterruptedException | IOException e) {
                    e.printStackTrace();
                    break;
                }
            }
            try {
                // Let us close the WebSocket
                session.close(new CloseReason(NORMAL_CLOSURE,
                                              "Done"));
            } catch (IOException e) {
                e.printStackTrace();
            }
        })
        .start();
    }
}

Using the @ServerEndpoint("/servertime") annotation on the TimeServerEndPoint class makes this class a server endpoint when it is deployed to a web server. The value of the value element of the annotation is /servertime, which will make the web server publish this endpoint at this URL.

The class contains four methods, which have been annotated with @onOpen, @onMessage, @onClose, and @onError annotations. I named these methods the same as these annotations. These methods are called at different points in the lifecycle of the server endpoint. They take a Session object as an argument. The Session object represents the interaction of this endpoint with its peer, which would be the client endpoint.

The onOpen() method is called when an opening handshake with a peer is successful. The method prints a message that a client is connected .

The onMessage() is called when a message is received from the peer. The method prints the message it receives and calls a private method named sendMessages(). The sendMessages() method starts a new thread and sends three messages to the peer. The thread sleeps for five seconds after sending each message. The message contains the current date and time with the time zone. You can send messages to peers synchronously or asynchronously. To send a message, you need to get a reference of the RemoteEndpoint interface that represents the conversation with a peer. Use the getBasicRemote() and getAsyncRemote() methods on the Session instance to get a RemoteEndpoint.Basic and RemoteEndpont.Async instances that can send messages synchronously and asynchronously, respectively. Once you get a reference of the peer (the remote endpoint), you can call several of its sendXxx() methods to send different types of data to the peer.

// Send a synchronous text message to the peer
session.getBasicRemote()
       .sendText(currentTime, true);

The second argument in the sendText() method indicates whether it is the last part of the partial message being sent. If your message is complete, use true.

After all messages are sent to the peer, a close message is sent using the sendClose() method. The method takes an object of the CloseReason class that encapsulates a close code and a close reason. When the peer receives a close message, the peer needs to respond with a close message, and, after that, the WebSocket connection is closed. Note that, after sending a close message, the server endpoint is not supposed to send more messages to its peer.

The onError() method is called when an error occurs that is not handled by the WebSocket protocol.

You cannot use this endpoint by itself. You need create a client endpoint, which I cover in detail in the next section. You will see this endpoint in action in the section entitled “Running the WebSocket Program,” later in this chapter.

Creating a Client Endpoint

Developing a WebSocket client endpoint involves using the WebSocket interface, which is part of the HTTP/2 Client API in JDK 9. The WebSocket interface contains the following nested types:

• WebSocket.Builder

• WebSocket.Listener

• WebSocket.MessagePart

An instance of the WebSocket interface represents a WebSocket client endpoint. A builder, which is an instance of the WebSocket.Builder interface, is used to create a WebSocket instance. The newWebSocketBuilder(URI uri, WebSocket.Listener listener) method of the HttpClient class returns an instance of the WebSocket.Builder interface.

When events occur on a client endpoint, for example, the completion of the opening handshake, a message arrival, closing handshake, etc., notifications are sent to a listener, which is an instance of the WebSocket.Listener interface. The interface contains a default method for each type of notification. You will need to create a class that implements this interface. You implement only those methods that correspond to the events of which you are interested in receiving notifications. You need to specify a listener when you create a WebSocket instance.

When you send a close message to a peer, you may specify a close status code. The WebSocket interface contains the following constants of type int that can be used as the WebSocket Close message status code:

• CLOSED_ABNORMALLY: Represents a WebSocket Close message status code (1006), which means that the connection was closed abnormally, for example, without sending or receiving a Close message.

• NORMAL_CLOSURE: Represents a WebSocket Close message status code (1000), which means that the connection was closed normally. This means that the purpose for which the connection was established was fulfilled.

The server endpoint may send partial messages. Messages are marked as first, part, last, or whole, which indicates their position. The WebSocket.MessagePart enum defines four constants corresponding to a message’s position: FIRST, PART, LAST, and WHOLE. You will receive these values as part of a message when your listener receives a notification that a message has been received.

The following sections describe each step in setting up a client endpoint in detail.

// Allow one more message to be received
webSocket.request(1);

WebSocket.Listener listener =  new WebSocket.Listener() {
    @Override
    public CompletionStage<?> onText(WebSocket webSocket,
                                     CharSequence message,
                                     WebSocket.MessagePart part) {

        // Allow one message to be received by the listener
        webSocket.request(1);
        // Print the message received from the server
        System.out.println("Server: " + message);
        // Return null indicating that we are done processing this message
        return null;
     }
};

WebSocket.Builder newWebSocketBuilder(URI uri, WebSocket.Listener listener)                  

URI serverUri = new URI("ws://localhost:8080/webapp/servertime");

// Get a listener
WebSocket.Listener listener = ...;
// Build an endpoint using the default HttpClient
HttpClient.newHttpClient()
          .newWebSocketBuilder(serverUri, listener)
          .buildAsync()
          .whenComplete((WebSocket webSocket, Throwable t) -> {
               // More code goes here
           });

Running the WebSocket Program

It is time to see a WebSocket client endpoint and a WebSocket server endpoint exchanging messages. Listing 14-5 contains code for a class named WebSocketClient that encapsulates a client endpoint . Its intended use is as follows:

// Create a client WebSocket
WebSocketClient wsClient = new WebSocketClient(new URI(“<server-uri>”));
// Connect to the server and exchange messages
wsClient.connect();

Listing 14-5. A Class That Encapsulates a Client Endpoint and Its Operations

// WebSocketClient.java
package com.jdojo.http.client;

import java.net.URI;
import java.util.concurrent.CompletionStage;
import jdk.incubator.http.HttpClient;
import jdk.incubator.http.WebSocket;

public class WebSocketClient {
    private WebSocket webSocket;
    private final URI serverUri;
    private boolean inError = false;
    public WebSocketClient(URI serverUri) {
        this.serverUri = serverUri;
    }

    public boolean isClosed() {
        return (webSocket != null && webSocket.isClosed())
               ||
               this.inError;        
    }

    public void connect() {
        HttpClient.newHttpClient()
                  .newWebSocketBuilder(serverUri, this.getListener())
                  .buildAsync()
                  .whenComplete(this::statusChanged);
    }

    private void statusChanged(WebSocket webSocket, Throwable t) {
        this.webSocket = webSocket;
        if (t == null) {        
            this.talkToServer();                                                                              
        } else {
            this.inError = true;
            System.out.println("Could not connect to the server." +
                               " Error: " + t.getMessage());
        }
    }
    private void talkToServer() {
        // Allow one message to be received by the listener
        webSocket.request(1);
        // Send the server a request for time
        webSocket.sendText("Hello");
    }

    private WebSocket.Listener getListener() {
        return new WebSocket.Listener() {
            @Override
            public void onOpen(WebSocket webSocket) {
                // Allow one more message to be received by the listener
                webSocket.request(1);
                // Notify the user that we are connected
                System.out.println("A WebSocket has been opened.");                
            }

            @Override
            public CompletionStage<?> onClose(WebSocket webSocket,
                             int statusCode, String reason) {
                // Server closed the web socket. Let us respond to
                // the close message from the server
                webSocket.sendClose();
                System.out.println("The WebSocket is closed." +
                                   " Close Code: " + statusCode +
                                   ", Close Reason: " + reason);                                                                               
                // Return null indicating that this WebSocket
                // can be closed immediately
                return null;
            }
            @Override
            public void onError(WebSocket webSocket, Throwable t) {
                System.out.println("An error occurred: " + t.getMessage());
            }

            @Override
            public CompletionStage<?> onText(WebSocket WebSocket,
                CharSequence message, WebSocket.MessagePart part) {

                // Allow one more message to be received by the listener
                webSocket.request(1);
                // Print the message received from the server
                System.out.println("Server: " + message);
                // Return null indicating that we are done
                // processing this message
                return null;
            }
        };
    }
}

The WebSocketClient class works as follows:

• The webSocket instance variable holds the reference of the client endpoint.

• The serverUri instance variable stores the URI of the server endpoint.

• The isError instance variable stores an indicator whether this endpoint is in error or not.

• The isClosed() method checks whether the endpoint is already closed or is in error.

• The webSocket instance variable will be null until the opening handshake is successful. Its value is updated inside the statusChanged() method.

• The connect() method builds a WebSocket and starts an opening handshake. Note that it calls the statusChanged() method when the opening handshake is complete, irrespective of the connection status.

• The statusChanged() method talks to the server by calling the talkToServer() method when the opening handshake is successful. Otherwise, it prints an error message and sets the isError flag to true.

• The talkToServer() method allows for one more message to be received by the listener and sends a text message to the server endpoint. Note that the server endpoint sends three messages with a five-second interval when it receives a text message from a client endpoint. Sending this message from the talkToServer() method initiates the message exchange between the two endpoints.

• The getListener() method creates and returns a WebSocket.Listener instance. The server endpoint will send three messages followed by a close message. The onClose() method in the listener responds to the close message from the server by sending an empty close message, which will end the client endpoint operations.

Listing 14-6 contains the program to run the client endpoint. If you run the WebSocketClientTest class, make sure that your web application with the server endpoint is running. You will also need to modify the SERVER_URI static variable to match the URI of the server endpoint for your web application. Refer to the next section, “Troubleshooting the WebSocket Application,” if you do not get output similar to the one shown. The output prints the current date and time with the time zone, so you may get different output.

Listing 14-6. A Program to Run the Client Endpoint

// WebSocketClientTest.java
package com.jdojo.http.client;

import java.net.URI;
import java.net.URISyntaxException;
import java.util.concurrent.TimeUnit;

public class WebSocketClientTest {    
    // Please change the URI to point to your server endpoint
    static final String SERVER_URI ="ws://localhost:8080/webapp/servertime";
    public static void main(String[] args)
       throws URISyntaxException, InterruptedException {
        // Create a client WebSocket
        WebSocketClient wsClient = new WebSocketClient(new URI(SERVER_URI));
        // Connect to the Server
        wsClient.connect();
        // Wait until the WebSocket is closed                                                
        while(!wsClient.isClosed()) {            
            TimeUnit.SECONDS.sleep(1);
        }

        // Need to exit
        System.exit(0);
    }
}
A WebSocket has been opened.
Server: 2016-12-15T14:19:53.311-06:00[America/Chicago]
Server: 2016-12-15T14:19:58.312-06:00[America/Chicago]
Server: 2016-12-15T14:20:03.313-06:00[America/Chicago]
The WebSocket is closed.  Close Code: 1000, Close Reason: Done

Troubleshooting the WebSocket Application

A number of things can go wrong when you are trying to test the WebSocket application . Table 14-1 lists a few of these problems and their solutions.