In the traditional request-response model used in HTTP, the client requests resources and the server provides responses. The exchange is always initiated by the client; the server cannot send any data without the client requesting it first. This model worked well for the World Wide Web when clients made occasional requests for documents that changed infrequently, but the limitations of this approach are increasingly apparent as content changes quickly and users expect a more interactive experience on the web. The WebSocket protocol addresses these limitations by providing a full-duplex communication channel between the client and the server. Combined with other client technologies, such as JavaScript and HTML5, WebSocket enables web applications to deliver a richer user experience.

In a WebSocket application, the server publishes a WebSocket endpoint and the client uses the endpoint's URI to connect to the server.

A WebSocket endpoint is represented by a URI in one of the following formats:

ws://host:port/path?query
wss://host:port/path?query

The ws scheme represents an unencrypted WebSocket connection.

The wss scheme represents an encrypted WebSocket connection.

The remaining components in these formats are as follows:

host

The host as defined in [RFC3986], Section 3.2.2.

port

Optional. The port as defined in [RFC3986], Section 3.2.3. The default port number is 80 for unencrypted connections and 443 for encrypted connections.

path

The path as defined in [RFC3986], Section 3.3. In a WebSocket endpoint, the path indicates the location of the endpoint within a server.

query

Optional. A query as defined in [RFC3986], Section 3.4.

To initiate a WebSocket connection, the client sends a handshake request to a WebSocket endpoint that the server has published. The client locates the endpoint by using the end point's URI. The connection is established if the handshake request passes validation, and the server accepts the request. The handshake is compatible with existing HTTP-based infrastructure: web servers interpret the handshake as an HTTP connection upgrade request.

GET /path/to/websocket/endpoint HTTP/1.1
Host: localhost
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: xqBt3ImNzJbYqRINxEFlkg==
Origin: http://localhost
Sec-WebSocket-Version: 13

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: K7DJLdLooIwIG/MOpvWFB3y3FE8=

The WebSocket protocol is symmetrical after the connection has been established: the client and the WebLogic Server instance can send messages to each other at any time while the connection is open, and they can close the connection at any time. Typically, clients connect to only one server, but servers accept connections from multiple clients.

WebSocket supports text messages (encoded as UTF-8) and binary messages. The control frames in WebSocket are close, ping, and pong (a response to a ping frame). Ping and pong frames may also contain application data.

The WebSocket protocol implementation in WebLogic Server is provided by the reference implementation of the Jakarta WebSocket specification. This implementation of the WebSocket protocol handles connection upgrades, establishes and manages connections, and handles exchanges with the client.

The WebLogic WebSocket API is provided by the reference implementation of JSR 356 Java API for WebSocket. This API consists of the following packages:

javax.websocket.server

This package contains annotations, classes, and interfaces to create and configure server endpoints.

javax.websocket

This package contains annotations, classes, interfaces, and exceptions that are common to client and server endpoints.

The API reference documentation for these packages is available in the following sections of the Java EE 8 Specification APIs:

• Package javax.websocket

• Package javax.websocket.server

Protocol fallback provides a mechanism for using an alternative transport for WebSocket messaging when the WebSocket protocol is not supported. Typically the WebSocket protocol is not supported either because the WebSocket object is not available or because WebSocket frames are blocked by a firewall. In this release, the only supported alternative transport is HTTP Long Polling.

Protocol fallback enables you to rely on standard programming APIs to perform WebSocket messaging regardless of whether or not the runtime environment supports the WebSocket protocol. For more information, see Enabling Protocol Fallback for WebSocket Messaging.

If the WebLogic Server Examples component is installed and configured on your machine, you can use the WebSocket examples to demonstrate using WebSockets in WebLogic Server. For more information about running these examples, see Sample Applications and Code Examples in Understanding Oracle WebLogic Server.

1. Write a Plain Old Java Object (POJO) class to represent the server endpoint.
   The class must have a public no-argument constructor.
2. Annotate the class declaration of the POJO class with the javax.websocket.server.ServerEndpoint annotation.
   This annotation denotes that the class represents a WebSocket server endpoint.
3. .Set the value element of the ServerEndpoint annotation to the relative path to which the endpoint is to be deployed.
   The path must begin with a forward slash (/).

import javax.websocket.server.ServerEndpoint;
...
@ServerEndpoint("/echo")
public class EchoEndpoint {
...
}

import javax.websocket.ClientEndpoint;
...
@ClientEndpoint
public class ExampleEndpoint {
 ...
}

1. Invoke the javax.websocket.server.ServerEndpointConfig.Builder.create static method to obtain an instance of the javax.websocket.server.ServerEndpointConfig.Builder class.

   In the invocation of the create method, pass the following information as parameters to the method:

   • The class of the endpoint

   • The path relative to the application at which the endpoint is to be available

2. Invoke the build method on the ServerEndpointConfig.Builder object that you obtained in the previous step.

ws://host:port/application/path

import javax.websocket.server.ServerEndpointConfig.Builder;
...
ServerEndpointConfig.Builder.create(EchoEndpoint.class, "/echo").build();
...

1. Adding a method to your endpoint class to handle the event

   The allowed method parameters are defined by the annotation that you will use to designate the event.

2. Annotating the method declaration with the annotation that designates the event that the method is to handle.

@OnOpen
public void open(Session session, 
                 EndpointConfig conf) { }

@OnMessage
public String message (String msg) { }

@OnError
public void error(Session session, 
                  Throwable error) { }

@OnClose
public void close(Session session, 
                  CloseReason reason) { }

• Handling a Connection Opened Event
  
• Handling a Message Received Event
  
• Handling an Error Event
  
• Handling a Connection Closed Event
  

Table 19-2 summarizes how to handle lifecycle events in a programmatic WebSocket endpoint.

Example 19-12 shows how handle incoming text messages for a programmatic endpoint by handling connection opened events and message received events.

import java.io.IOException;
import javax.websocket.EndpointConfig;
import javax.websocket.MessageHandler;
import javax.websocket.Session;
...
   @Override
   public void onOpen(final Session session, EndpointConfig config) {
      session.addMessageHandler(new MessageHandler.Whole<String>() {
         @Override
         public void onMessage(String msg) {
            try {
               session.getBasicRemote().sendText(msg);
            } catch (IOException e) { ... }
         }
      });
   }
...

1. Obtain the Session object from the connection.

   The Session object is available as a parameter in the lifecycle methods of the endpoint. How to obtain this object depends on whether the message that you are sending is a response to a message from a peer.

   • If the message is a response, obtain the Session object from inside the method that received the message.

   • If the message is not a response, store the Session object as an instance variable of the endpoint class in the method for handling a connection opened event. Storing the Session object in this way enables you to access it from other methods.

2. Use the Session object to obtain an object that implements one of the subinterfaces of javax.websocket.RemoteEndpoint.

   • If you are sending the message synchronously, obtain a RemoteEndpoint.Basic object. This object provides blocking methods for sending a message.

     To obtain a RemoteEndpoint.Basic object, invoke the Session.getBasicRemote() method.

   • If you are sending the message asynchronously, obtain a RemoteEndpoint.Async object. This object provides non-blocking methods for sending a message.

     To obtain a RemoteEndpoint.Async object, invoke the Session.getAsyncRemote() method.

3. Use the RemoteEndpoint object that you obtained in the previous step to send the message to the peer.

   The following list shows some of the methods you can use to send a message to the peer:

   • void RemoteEndpoint.Basic.sendText(String text)

     Send a text message to the peer. This method blocks until the whole message has been transmitted.

   • void RemoteEndpoint.Basic.sendBinary(ByteBuffer data)

     Send a binary message to the peer. This method blocks until the whole message has been transmitted.

   • void RemoteEndpoint.sendPing(ByteBuffer appData)

     Send a ping frame to the peer.

   • void RemoteEndpoint.sendPong(ByteBuffer appData)

     Send a pong frame to the peer.

import java.io.IOException;
 
import javax.websocket.OnMessage;
import javax.websocket.Session;
...
   @OnMessage
   public void onMessage(Session session, String msg) {
      try {
         session.getBasicRemote().sendText(msg);
      } catch (IOException e) { ... }
   }
...

1. Obtain the set of all open WebSocket sessions that represent connections to the endpoint.

   Invoke the getOpenSessions method on the endpoint's Session object for this purpose.

2. Send the message to each open session that you obtained in the previous step.
   1. Use the session to obtain a RemoteEndpoint object.
   2. Use the RemoteEndpoint object to send the message.
      See Sending a Message to a Single Peer of an Endpoint

import java.io.IOException;
 
import javax.websocket.OnMessage;
import javax.websocket.Session;
import javax.websocket.server.ServerEndpoint;
 ...
@ServerEndpoint("/echoall")
public static class EchoAllEndpoint {
    @OnMessage
    public void messageReceived(Session session, String msg) {
        for (Session sess : session.getOpenSessions()) {
            try {
                sess.getBasicRemote().sendText(msg);
            } catch (IOException e) {
                // handle exception
            }
        }
    }
}

The Jakarta API for WebSocket specification requires that Jakarta EE implementations instantiate endpoint classes once per connection. This requirement facilitates the development of WebSocket endpoints because you are guaranteed that only one thread is executing the code in a WebSocket endpoint class at any given time. When you introduce a new thread in an endpoint, you must ensure that variables and methods accessed by more than one thread are thread safe.

1. For each custom Java type that you want to send as a WebSocket message, implement the appropriate interface for the type of the WebSocket message:

   • For a text message, implement javax.websocket.Encoder.Text<T>.

   • For a binary message, implement javax.websocket.Encoder.Binary<T>.

   These interfaces specify the encode method.

2. Specify that your endpoint will use your encoder implementations.

   • For an annotated endpoint, add the names of your encoder implementations to the encoders optional element of the ServerEndpoint annotation.

   • For a programmatic endpoint, pass a list of the names of your encoder implementations as a parameter of the encoders method of a javax.websocket.server.ServerEndpointConfig.Builder object.

3. Use the sendObject(Object data) method of the RemoteEndpoint.Basic or RemoteEndpoint.Async interfaces to send your objects as messages.

   The container looks for an encoder that matches your type and uses it to covert the object to a WebSocket message.

package com.example.game.encoder;

import javax.websocket.EncodeException;
import javax.websocket.Encoder;
import javax.websocket.EndpointConfig;

import com.example.game.message.MessageA;
...
public class MessageATextEncoder implements Encoder.Text<MessageA> {
   @Override
   public void init(EndpointConfig ec) { }
   @Override
   public void destroy() { }
   @Override
   public String encode(MessageA msgA) throws EncodeException {
      // Access msgA's properties and convert to JSON text...
      return msgAJsonString;
   }
...
}

package com.example.game;

import javax.websocket.server.ServerEndpoint;

import com.example.game.encoder.MessageATextEncoder;
import com.example.game.encoder.MessageBTextEncoder;
...

@ServerEndpoint(
   value = "/myendpoint",
   encoders = { MessageATextEncoder.class, MessageBTextEncoder.class }
...
)
public class EncEndpoint { ... }

import javax.websocket.Session;
...
import com.example.game.message.MessageA;
import com.example.game.message.MessageB;
...
MessageA msgA = new MessageA(...);
MessageB msgB = new MessageB(...);
session.getBasicRemote.sendObject(msgA);
session.getBasicRemote.sendObject(msgB);
...

1. Implement the appropriate interface for the type of the WebSocket message:

   • For a text message, implement javax.websocket.Decoder.Text<T>.

   • For a binary message, implement javax.websocket.Decoder.Binary<T>.

   These interfaces specify the willDecode and decode methods.

2. Specify that your endpoint will use your decoder implementations.

   • For an annotated endpoint, add the names of your decoder implementations to the decoders optional element of the ServerEndpoint annotation.

   • For a programmatic endpoint, pass a list of the names of your decoder implementations as a parameter of the decoders method of a javax.websocket.server.ServerEndpointConfig.Builder object.

3. Ensure that the method in your endpoint for handling a message received event takes your custom Java type as a parameter.

   See Handling Life Cycle Events for a WebSocket Connection.

   When the endpoint receives a message that can be decoded by one of the decoders you specified, the container calls the method that takes your custom Java type as a parameter if this method exists.

package com.example.game.decoder;

import javax.websocket.DecodeException;
import javax.websocket.Decoder;
import javax.websocket.EndpointConfig;

import com.example.game.message.Message;
import com.example.game.message.MessageA;
import com.example.game.message.MessageB;
...

public class MessageTextDecoder implements Decoder.Text<Message> {
   @Override
   public void init(EndpointConfig ec) { }
   @Override
   public void destroy() { }
   @Override
   public Message decode(String string) throws DecodeException {
      // Read message...
      if ( /* message is an A message */ )
         return new MessageA(...);
      else if ( /* message is a B message */ )
         return new MessageB(...);
   }
   @Override
   public boolean willDecode(String string) {
      // Determine if the message can be converted into either a
      // MessageA object or a MessageB object...
      return canDecode;
   }
}

package com.example.game;

import javax.websocket.server.ServerEndpoint;

import com.example.game.encoder.MessageATextEncoder;
import com.example.game.encoder.MessageBTextEncoder;
import com.example.game.decoder.MessageTextDecoder;
...
@ServerEndpoint(
   value = "/myendpoint",
   encoders = { MessageATextEncoder.class, MessageBTextEncoder.class },
   decoders = { MessageTextDecoder.class }
)
public class EncEndpoint { ... }

import javax.websocket.OnMessage;
import javax.websocket.Session;
...
import com.example.game.message.Message;
import com.example.game.message.MessageA;
import com.example.game.message.MessageB;
...
@OnMessage
public void message(Session session, Message msg) {
   if (msg instanceof MessageA) {
      // We received a MessageA object...
   else if (msg instanceof MessageB) {
      // We received a MessageB object...
   }
}

1. The client opens a WebSocket connection to the server hosting the WebSocket endpoint, using the ws:// or wss:// protocol prefix. For more information, see Establishing Secure WebSocket Connections.

   var url = ((window.location.protocol == "https:") ? "wss:" : "ws:") 
   + "//" + window.location.host 
   + "/websocket-helloworld-wls/helloworld_delay.ws";
    
   var ws = new WebSocket(url);
   

2. The client registers listeners with the WebSocket object to respond to events, such as opening, closing, and receiving messages. Based on the event and the information received, the client performs the appropriate action.

   ws.onopen = function(event) {
       document.getElementById("status").innerHTML = "OPEN"
   }
    
   ws.onmessage = function(event) {
       msg = event.data
         document.getElementById("short_msg").innerHTML =
         event.data;
   }
   

3. The client sends messages to the server over the WebSocket object as needed by the application.

   function sendMsg() {
       // Check if connection is open before sending
       if(ws == null || ws.readyState != 1) {
           document.getElementById("reason").innerHTML 
           = "Not connected can't send msg"
       } else {
           ws.send(document.getElementById("name").value);
       }
   }
    
   <input id="send_button" class="button" type="button" value="send" onclick="sendMsg()"/>

The javax.websocket package contains annotations, classes, interfaces, and exceptions that are common to client and server endpoints. Use the APIs in this package for writing a Java WebSocket client in the same way as for writing a server. Additional programming tasks that are specific to writing a client are described in the subsections that follow.

• Configuring a WebSocket Client Endpoint Programmatically
  
• Connecting a Java WebSocket Client to a Server Endpoint
  
• Setting the Maximum Number of Threads for Dispatching Messages from a WebSocket Client
  

Modern browsers use same-origin policies to prevent scripts that are running on Web pages loaded from one origin from interacting with resources from a different origin. The WebSocket Protocol (RFC 6455) uses a verified-origin policy that enables the server to decide whether or not to consent to a cross-origin connection.

When a script sends an opening handshake request to a WebSocket application, an Origin HTTP header is sent with the WebSocket handshake request. If the application does not verify the Origin, then it accepts connections from any origin. If the application is configured not to accept connections from origins other than the expected origin, then the WebSocket application can reject the connection.

You can ensure that the WebSocket application verifies the Origin by extending the javax.websocket.server.ServerEndpointConfig.Configurator class.

The following code example demonstrates applying a verified-origin policy:

...
import javax.websocket.server.ServerEndpointConfig;
 
public class MyConfigurator extends ServerEndpointConfig.Configurator {
 ...  
    private static final String ORIGIN = "http://www.example.com:7001";
 
    @Override
    public boolean checkOrigin(String originHeaderValue) {
        return ORIGIN.equals(originHeaderValue)   
    }
}
...

For more information, see Configuring a Server Endpoint Programmatically.

The WebSocket Protocol (RFC 6455) does not specify an authentication method for WebSocket clients during the handshake process. You can use standard Web container authentication and authorization functionality to prevent unauthorized clients from opening WebSocket connections on the server.

All configurations of the <auth-method> element that are supported for Web applications can also be used for WebSocket applications. These authentication types include BASIC, FORM, CLIENT-CERT, and so on. See Developing Secure Web Applications in Developing Applications with the WebLogic Security Service.

You can secure the path to the endpoint within your application by configuring the relevant <security-constraint> element in the web.xml deployment descriptor file of the WebSocket application. By configuring <security-constraint>, clients must authenticate themselves before sending WebSocket handshake requests. Otherwise, the server rejects the WebSocket handshake request. For more information about the <security-constraint> element, see web.xml Deployment Descriptor Elements in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

The following code example demonstrates securing the path to the endpoint within your application, where the path is /demo:

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Secured WebSocket Endpoint</web-resource-name>
      <url-pattern>/demo</url-pattern>
      <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
      <role-name>user</role-name>
    </auth-constraint>
  </security-constraint>
  <login-config>
    <auth-method>FORM</auth-method>
    <form-login-config>
      <form-login-page>/login.jsp</form-login-page>
      <form-error-page>/error.jsp</form-error-page>
    </form-login-config>
  </login-config>
  <security-role>
    <role-name>user</role-name>
  </security-role>

• Authorizing WebSocket Clients
  

To establish a WebSocket connection, the client sends a handshake request to the server. When using the ws scheme to open the WebSocket connection, the handshake request is a plain HTTP request; the data being transferred over the established WebSocket connection is not encrypted.

To establish a secure WebSocket connection and prevent data from being intercepted, WebSocket applications should use the wss scheme. The wss scheme ensures that clients send handshake requests as HTTPS requests, encrypting transferred data by TLS/SSL.

You can configure a WebSocket application to accept only HTTPS handshake requests, where all WebSocket connections must be encrypted and unencrypted WebSocket handshake requests are rejected. Specify the <user-data-constraint> element in the web.xml deployment descriptor file of the WebSocket application. For more information about the <user-data-constraint> element, see web.xml Deployment Descriptor Elements in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

The following code example demonstrates configuring the <user-data-constraint> element:

<security-constraint>
    <web-resource-collection>
      <web-resource-name>Secured WebSocket Endpoint</web-resource-name>
      <url-pattern>/demo</url-pattern>
      <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
      <role-name>user</role-name>
    </auth-constraint>
    <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
  </security-constraint>

If a script attempts to open a WebSockets connection through the ws:// URI (using a plain HTTP request), but the top-level Web page is retrieved through an HTTPS request, the Web page is referred to as mixed content. Although most browsers no longer allow mixed content, some still do. WebSocket applications should avoid mixed content, because it allows certain information that should be protected, such as JSESSIONID and cookies, to be exposed.

For more information about mixed content, see "Web Security Context: User Interface Guidelines" at http://www.w3.org/TR/wsc-ui/#securepage.

By specifying limits for a WebSocket connection, you can prevent clients from exhausting server resources, such as memory, sockets, and so forth.

You can specify the following limits for a WebSocket connection:

• Maximum message size. To set the maximum message size for a WebSocket connection, set the maxMessageSize element of the onMessage annotation to the size in bytes.

• Idle timeout value. To set the idle timeout value for a WebSocket connection, invoke one of the following methods:

  • For an individual connection, invoke the setMaxIdleTimeout method of the Session object.

  • For the entire container, invoke the setDefaultMaxSessionIdleTimeout method of a WebSocketContainer object.

The JavaScript API for WebSocket fallback provides an implementation of the standard W3C WebSocket API and additional APIs to facilitate WebSocket fallback. For information about the JavaScript API for WebSocket fallback, see JavaScript API Reference for WebSocket Fallback. For information about the W3C WebSocket API, see: http://www.w3.org/TR/websockets/.

When you use the standard W3C WebSocket JavaScript API, code your application without regard to whether the WebSocket protocol is supported.

• Configuring WebSocket Fallback
  
• Creating a WebSocket Object
  
• Handling Life Cycle Events for a JavaScript WebSocket Client
  
• Sending a Message from a JavaScript WebSocket Client
  

Package the orasocket.min.js file in the scripts directory of your web application.

In the client application, add the following script element to specify the location of orasocket.min.js.

<script type="text/javascript" src="scripts/orasocket.min.js"></script>

By default, WebSocket fallback is disabled.

To enable WebSocket fallback, set the com.oracle.tyrus.fallback.enabled context parameter to true in the application's deployment descriptor file web.xml.

 <?xml version="1.0" encoding="UTF-8"?>
 <web-app version="3.0" ...>
    ...
   <context-param>
     <description>Enable fallback mechanism</description> 
     <param-name>com.oracle.tyrus.fallback.enabled</param-name> 
     <param-value>true</param-value>
   </context-param>
 </web-app>

Table 19-9 shows the proprietary WebLogic Server WebSocket API and the corresponding JSR 356 API to use to perform tasks for developing a WebSocket application. The table shows only the JSR 356 API to use for an annotated endpoint. For each task, the table also provides a cross-reference to instructions for performing the task by using the JSR 356 API.

The pathPatterns element of the WebSocket annotation in the deprecated API accepts the /* suffix in a path pattern string. The /* suffix matches the path pattern with any resource path that starts with the path pattern before the /* suffix. For example, the resource path /ws/chat is matched by path pattern /ws/*.

No equivalent to the /* suffix exists in the JSR 356 API. If your existing endpoint relies on the /* suffix, you must rewrite your code to achieve the same result as the /* suffix. How to rewrite your code depends on whether the /* suffix represents variable path parameters in an endpoint URI or additional data for an endpoint.

• Replacing a /* Suffix that Represents Variable Path Parameters in an Endpoint URI
  
• Replacing a /* Suffix that Represents Additional Data for an Endpoint
  

Example 19-41 shows how to convert a proprietary WebSocket server endpoint to use he JSR 356 API from the deprecated API.

package examples.webapp.html5.websocket;
 
//import weblogic.websocket.ClosingMessage;       Deprecated
//import weblogic.websocket.WebSocketAdapter;     Deprecated
//import weblogic.websocket.WebSocketConnection;  Deprecated
//import weblogic.websocket.annotation.WebSocket; Deprecated
 
  import javax.websocket.CloseReason;              //JSR 356
  import javax.websocket.OnMessage;                //JSR 356
  import javax.websocket.Session;                  //JSR 356
  import javax.websocket.server.ServerEndpoint;    //JSR 356
 
  import java.io.IOException;
 
//@WebSocket(  Deprecated
//  timeout = -1,  Deprecated
//  pathPatterns = {"/ws"}   Deprecated 
//)
  @ServerEndpoint("/ws") //JSR 356
//public class MessageListener extends WebSocketAdapter {  Deprecated
  public class MessageListener {
//@Override  Not required. Replaced by @OnMessage in a POJO class
  @OnMessage //JSR 356
//public void onMessage(WebSocketConnection connection, String payload) { Deprecated
  public void onMessage(Session connection, String payload) //JSR 356
   throws IOException {                                     //JSR 356
    // Sends message from the browser back to the client.
    String msgContent = "Message \"" + payload + "\" has been received by server.";
    try {
//    connection.send(msgContent); Deprecated
      connection.getBasicRemote().sendText(msgContent); //JSR 356
    } catch (IOException e) {
//    connection.close(ClosingMessage.SC_GOING_AWAY); Deprecated
      connection.close(new                                             //JSR 356
       CloseReason(CloseReason.CloseCodes.GOING_AWAY, "Going away.")); //JSR 356
    }  
  }
}