Java EE 7: Building Web Applications with WebSocket, JavaScript and HTML5
Overview
Purpose This tutorial shows you how to create an application that uses the WebSocket API for real-time communication between a client and a server. You learn how to: Create a Java Platform, Enterprise Edition 7 (Java EE 7) application that uses the WebSocket API Use the OnOpen and OnMessage WebSocket lifecycle events to perform different actions on the Java EE 7 application. Define a client-side WebSocket endpoint by using JavaScript Operate on Plain Plain Old Java Objects (POJOs), in real-time, with actions invoked from a web browser client
Time to Complete Approximately 1 hour
Introduction Modern web applications require more more interactivity than ever before for client/server client/server communications. communications. HTTP, however, wasn't built to deliver the kind of interactivity needed today. "Push" or Comet techniques, such as long-polling, long-polling, emerged as a way to allow a server to push data to a browser. Because these techniques usually rely on HTTP, they present some disadvantages for client/server communications, such as HTTP overhead. These disadvantages result in less efficient communication between the server and the web browser, especially for real-time applications. WebSocket provides an alternative to this limitation by providing bi-directional, full-duplex, real-time, client/server communications. The server can send data to the client at any time. Because WebSocket runs over TCP, it also reduces the overhead of each message. WebSocket also provides greater scalability for message-intensive applications because only one connection per client is used (whereas HTTP creates one request per message). Finally, WebSocket is part of Java EE 7, so you can use other technologies in the Java EE 7 stack.
Scenario In this tutorial, you create Java WebSocket Home, a smart home control web application based on Java EE 7. Java WebSocket Home has a user interface for connecting and controlling fictitious devices from a web browser to a Java application. This application provides real-time updates to all clients that are connected to the Java WebSocket Home server.
Software Requirements The following is a list of software requirements needed for this tutorial: Download and install the Java EE 7 software development kit (SDK) from http://www.oracle.com/technetwork/java/javaee/downloads/index.html. Download and install the Java NetBeans 7.3.1 integrated development environment (IDE) from http://www.netbeans.org/downloads/index.html. Download and install Oracle GlassFish Server 4.0 from http://www.oracle.com/us/products/middleware/cloud-app-foundation/glassfish-server/overview/index.html.
Prerequisites Before starting this tutorial, you should have: Knowledge of the Java programming language Basic knowledge of Java EE 7 Basic knowledge of HTML 5, JavaScript, and cascading style sheets (CSS)
Introduction to the WebSocket API in Java EE 7 Introduced as part of the HTML 5 initiative, the WebSocket protocol is a standard web technology that simplifies communication and connection management between clients and a server. By maintaining a constant connection, WebSocket provides full-duplex client/server communication. It also provides a low-latency, low-level communication that works on the underlying TCP/IP connection. The Java API for WebSocket (JSR-356) simplifies the integration of WebSocket into Java EE 7 applications. Here are some of the features of the Java API for WebSocket: Annotation-driven programming that allows developers to use POJOs to interact with WebSocket lifecycle events Interface-driven programming that allows developers to implement interfaces and methods to interact with WebSocket lifecycle events Integration with other Java EE technologies (You can inject objects and Enterprise JavaBeans by using components such as Contexts and Dependency Injection.)
Creating a Java EE 7 Project In this section, you create a Java EE 7 web application. 1. Open the NetBeans IDE. IDE. 2. From the File menu, select New Project. Project.
3. In the New Project dialog box, perform the following steps: a. Select Java Web from Web from Categories. b. Select Web Application from Application from Projects. c. Click Next. Next.
4. Enter WebsocketHome as the project name and click Next. Next.
5. In the New Web Application dialog box, perform the following steps: a. Select GlassFish Server from the Server list. b. Enter WebsocketHome as the context path. c. Click Finish.
The WebsocketHome project has been created.
6. Right-click the WebsocketHome project and select Run to test your application.
A browser window displays a TODO write content message.
You successfully created a Java EE 7 web application by using NetBeans.
Creating the Device Model In this section, you create the class that contains a device's attributes. 1. Select File > New File.
2. In the New File dialog box, perform the following steps: a. Select Java from Categories. b. Select Java Class from File Types. c. Click Next.
3. In the New Java Class dialog box, perform the following steps: a. Enter Device as the class name. b. Enter org.example.model as the package. c. Click Finish.
The Device class is added to the project.
4. Add the following code to the Device.java class to define the class constructor, and its getter and setter methods:
View Code 5. Select File > Save to save the file.
You successfully created the Device class.
Creating the WebSocket Server Endpoint In this section, you create a WebSocket endpoint. 1. Select File > New File.
2. In the New File dialog box, perform the following steps: a. Select Java from Categories. b. Select Java Class from File Types. c. Click Next.
3. In the New Java Class dialog box, perform the following steps: a. Enter DeviceWebSocketServer as the class name. b. Enter org.example.websocket as the package. c. Click Finish.
The DeviceWebSocketServer class is added to the project.
4. Define the WebSocket server endpoint path by adding the following code:
package org.example.websocket; import javax.websocket.server.ServerEndpoint; @ServerEndpoint ("/actions" ) public class DeviceWebSocketServer { }
5. Define the WebSocket lifecycle annotations by adding the following methods and imports to the DeviceWebSocketServer class:
import javax.websocket.OnClose; import javax.websocket.OnError; import javax.websocket.OnMessage; import javax.websocket.OnOpen; import javax.websocket.Session; import javax.websocket.server.ServerEndpoint; @ServerEndpoint ("/actions" ) public class DeviceWebSocketServer { @OnOpen public void open(Session session) {
}
@OnClose public void close(Session session) { } @OnError public void onError(Throwable error) { }
}
@OnMessage public void handleMessage(String message, Session session) { }
The WebSocket lifecycle annotations are mapped to Java methods. In this example, the @OnOpen annotation is mapped to the open() method; the @OnMessage annotation is mapped to the handleMessage() method; the @OnClose annotation to the close() method; and the @OnError annotation to the onError() method. 6. Specify that the class is application-scoped by adding the @ApplicationScoped annotation and importing its package.
... import javax.websocket.OnOpen; import javax.websocket.Session; import javax.enterprise.context.ApplicationScoped; @ApplicationScoped @ServerEndpoint ("/actions" ) public class DeviceWebSocketServer { ... }
7. Save the file. You successfully created the WebSocket server endpoint.
Creating the Session Handler In this section, you create a class for handling the sessions that are connected to the server. 1. Select File > New File.
2. In the New File dialog box, perform the following steps: a. Select Java from Categories. b. Select Java Class from File Types. c. Click Next.
3. In the New Java Class dialog box, perform the following steps: a. Enter DeviceSessionHandler as the class name. b. Enter org.example.websocket as the package. c. Click Finish.
The DeviceSessionHandler class is added to the project.
4. Specify that the class is application-scoped by adding the @ApplicationScoped annotation and importing its corresponding package.
package org.example.websocket; import javax.enterprise.context.ApplicationScoped; @ApplicationScoped public class DeviceSessionHandler { }
5. Declare a HashSet for storing the list of devices added to the application and the active sessions in the application, and import their packages.
package org.example.websocket; import javax.enterprise.context.ApplicationScoped; import java.util.HashSet; import java.util.Set; import javax.websocket.Session; import org.example.model.Device; @ApplicationScoped public class DeviceSessionHandler { private final Set sessions = new HashSet<>(); private final Set devices = new HashSet<>(); }
Note: Each client connected to the application has its own session. 6. Define the following methods for adding and removing sessions to the server.
package org.example.websocket; ... @ApplicationScoped public class DeviceSessionHandler { ...
}
public void addSession(Session session) { sessions.add(session); } public void removeSession(Session session) { sessions.remove(session);
}
7. Define the methods that operate on the Device object. These methods are: addDevice() - Add a device to the application. removeDevice() - Remove a device from the application. toggleDevice() - Toggle the device status. getDevices() - Retrieve the list of devices and their attributes. getDeviceById() - Retrieve a device with a specific identifier. createAddMessage() - Build a JSON message for adding a device to the application. sendToSession() - Send an event message to a client. sendToAllConnectedSessions() - Send an event message to all connected clients.
package org.example.websocket; ... public class DeviceSessionHandler { ... public List getDevices() { return new ArrayList<>(devices); } public void addDevice(Device device) { } public void removeDevice(int id) { } public void toggleDevice(int id) { } private Device getDeviceById( int id) { return null; } private JsonObject createAddMessage(Device device) { return null; } private void sendToAllConnectedSessions(JsonObject message) { }
}
private void sendToSession(Session session, JsonObject message) { }
8. Save the file. You successfully created the session handler.
Rendering the User Interface In this section, you create the Java WebSocket Home user interface (UI) by using HTML5 and CSS. 1. Open the index.html file. 2. Enter the following code to add the proper elements for adding and displaying devices on the web browser client. View Code 3. Save the file. 4. Select File > New File.
5. In the New File dialog dialog box, perform the following steps: a. Select Web from Categories. b. Select Cascading Style Sheet from File Types. c. Click Next.
6. In the New Cascading Style Sheet dialog box, perform the following steps: a. Enter style as the file name. b. Select Web Pages as the location. c. Click Finish.
The style.css file is added to the project.
7. Copy the following code into the style.css file. View Code 8. Save the file. You successfully created the UI elements for the Java WebSocket Home application.
Creating the WebSocket Client Endpoint In this section, you specify the client endpoint by using JavaScript. 1. Select File > New File.
2. In the New File dialog box, perform the following steps: a. Select Web from Categories. b. Select JavaScript File from File Types. c. Click Next.
3. Enter websocket as the file name and click Finish.
The websocket.js file is added to the project.
The file performs the following actions: Maps the WebSocket server endpoint to the URI defined in "Creating the WebSocket Server Endpoint". Captures the JavaScript events for adding, removing, and changing a device's status and pushes those events to the WebSocket server. These methods are addDevice() , removeDevice() , and toggleDevice() . The actions are sent in JSON messages to the WebSocket server. Defines a callback method for the WebSocket onmessage event. The onmessage event captures the events sent from the WebSocket server (in JSON) and processes those actions. In this application, these actions are usually rendering changes in the client UI. Toggles the visibility of an HTML form for adding a new device. 4. Add the following code to the websocket.js file. View Code 5. Save the file. You successfully created the WebSocket client endpoint and the defined actions for handling WebSocket events in the client.
Processing WebSocket Events in the Server In this section, you process WebSocket lifecycle events in the DeviceWebSocketServer class. 1. Open the DeviceWebSocketServer class. 2. Inject a DeviceSessionHandler object to process the WebSocket lifecycle events in each session and import its corresponding package. View Code 3. Process the OnMessage WebSocket lifecycle event by adding the following code to the open method. View Code The OnMessage method performs the following actions: Reads device actions and attributes sent from the client. Invokes the session handler to perform the proper operations on the specified Device object. In this application, the add action sent from the client invokes the addDevice method, the remove action invokes the removeDevice method, and the toggle action invokes the toggleDevice method. 4. Process the OnOpen WebSocket event and add the missing imports. View Code The OnOpen event reads the attributes sent from the client in JSON and creates a new Device object with the specified parameters. 5. Implement the OnClose and OnError actions and add the missing imports. View Code 6. Save the file. You successfully processed WebSocket lifecycle events in the DeviceWebSocketServer class.
Implementing the WebSocket Actions in the Session Handler In this section, you perform operations in the Device object by using the DeviceSessionHandler class. 1. Open the DeviceSessionHandler.java class. 2. Define a variable for storing the device identifiers in the server.
... public class DeviceSessionHandler { private int deviceId = 0; private final Set sessions = new HashSet<>(); private final Set devices = new HashSet<>(); ... }
3. Add the for loop to the addSession method to send the list of devices to the connected client.
public void addSession(Session session) { sessions.add(session); for (Device device : devices) { JsonObject addMessage = createAddMessag e(device); sendToSession(s ession, addMessage); } }
4. Implement the addDevice method by adding the following code.
public void addDevice(Device device) { device.setId(deviceId); devices.add(device); deviceId++; JsonObject addMessage = createAddMessa ge(device); sendToAllConnectedSessions(addMessage); }
The addDevice method performs the following actions: Creates a new Device object with the current value of the deviceID variable and the parameters specified by the user in the client. Sends a message, in JSON, to all sessions or active clients in the WebSocket server. 5. Implement the removeDevice method.
public void removeDevice(int id) { Device device = getDeviceById( id); if (device != null) { devices.remove(device); JsonProvider provider = JsonProvider.pr ovider(); JsonObject removeMessage = provider.creat eObjectBuilder() .add("action", "remove") .add("id", id) .build(); sendToAllConnectedSessions(removeMessage); } }
The removeDevice method removes the device object specified by the user and sends a message, in JSON, to all sessions that are active in the WebSocket server. 6. Implement the toggleDevice method.
public void toggleDevice(int id) { JsonProvider provider = JsonProvider.p rovider(); Device device = getDeviceById( id); if (device != null) { if ("On".equals(de vice.getStatus() )) { device.setStatus("Off"); } else { device.setStatus("On"); } JsonObject updateDevMessag e = provider.creat eObjectBuilder() .add("action", "toggle") .add("id", device.getId()) .add("status", device.getStatus ()) .build(); sendToAllConnectedSessions(updateDevMessage); } }
The toggleDevice method toggles the device status and sends the event to all sessions that are still active in the WebSocket server. 7. Implement missing methods. View Code 8. Save the file. You successfully implemented the WebSocket actions in the session handler.
Testing the Java WebSocket Home Application In this section, you test the Java WebSocket Home application. 1. Right-click the WebsocketHome project and click Run to build and deploy the project.
A Web browser displays the Java WebSocketHome index page. 2. Open another web browser and place it next to the first one.
3. In either window, click Add a device to display the "Add a new device" form.
4. In the "Add a new device form," perform the following steps: a. b. c. d.
Enter Microwave as the name. Select Appliance as the type. Enter Kitchen as the description. Click Add.
A device is added to the Java WebSocket Home server and it is rendered in both web browsers.
5. Optional: Add more devices of different types.
6. On any device, click Turn on.
The device status changes to Off in the server and all clients.
7. On any device, click Remove device.
The device is removed from the server and all clients.
Summary Congratulations! You created a smart home control web application by using Java EE 7 and the WebSocket API. You also learned how to: Define a WebSocket server endpoint in a Java class by using the WebSocket API annotations Send messages to and from the client to the WebSocket server in JSON Use the WebSocket API lifec cle annotations to handle WebSocket events
Process WebSocket lifecycle events in the client by using HTML5 and JavaScript
Resources For more information about the topics in this tutorial, see: Java EE 7: New Features, an Oracle-instructed course on the new features of Java EE 7 Java EE 7 Tutorial The Java EE 7 Tutorial chapter on WebSocket Using WebSocket for Real-Time Communication in Java Platform, Enterpise Edition 7, a tutorial about WebSocket for Java EE 7. The Aquarium Blog JSR 356: Java API for WebSocket WebSocket.org, a WebSocket community "Java EE7 - Embracing HTML5" article in Java Magazine To learn more about Java EE 7, refer to additional OBEs in the Oracle Learning Library.
Credits Lead Curriculum Developer: Miguel Salazar Other Contributors: Eduardo Moranchel
