Part-1: Tying in with the Java EE Platform

The Java WebSocket API baked into the Java EE Platform (Java EE 7 and above). This chapter talks about other Java EE technologies which the WebSocket API integrates with. We will explore interoperability with the following Java EE specifications.

  • Enterprise Java Beans (EJB)

  • Context and Dependency Injection (CDI)

Before we dive in, please note that

container managed injection features are not available to WebSocket endpoints which override the container implemented initialization (using the ServerEndpointConfig.Configurator)

EJB integration

In this section, we'll look at how WebSocket endpoints can integrate with EJBs. The following aspects will be explored

Decorating WebSocket endpoints with EJB

Important: Please note that support for EJB annotations on WebSocket endpoints is not a standard (specification mandated) feature

@Singleton

By default, the container creates a new WebSocket (server) endpoint instance per client. In case you need a single instance, you can implement this using a custom ServerEndpointConfig.Configurator (override the getEndpointInstance to be specific and return the same instance). As mentioned in the Configuration chapter, this means that you might have to sacrifice some of the (Java EE) platform related services like dependency injection

Alternate solution - A similar behavior can be achieved by decorating the WebSocket endpoint with @Singleton

@Singleton
@ServerEndpoint("/singleton/")
public class SingletonlEndpoint {

    @OnOpen
    public void onOpen(Session s) throws IOException {
        s.getBasicRemote().sendText(String.valueOf(hashCode()));
    }

    @PreDestroy
    public void onDestroy() {
        System.out.println("Singleton bean " + hashCode() + " will be destroyed");
    }

    @OnClose
    public void onClose(Session session, CloseReason closeReason) {
        System.out.println("Closed " + session.getId() + " due to " + closeReason.getCloseCode());
    }
}

Concurrency semantics

In case of a @Singleton, all the clients will interact with one server endpoint instance. Here is a quick summary of how the EJB as well as WebSocket threading semantics are applied

  • The Singleton bean default approach (WRITE lock) ensures single threaded access across all connected clients

  • If thread-safety is not a concern (e.g. in case where you do not deal with client specific data/state in your logic) and you do not want the single-threaded access model to be a bottleneck, override the default behavior by switching to a READ lock which allows concurrent threads to access the methods (unless of course a WRITE lock is not already in effect)

The above mentioned semantics are with respect to ALL the WebSocket clients. From the point of view of a single client, the default strategy of one thread at a time, per endpoint instance per client continues to apply (more in the Concurrency chapter)

@Stateful

It's only possible to have one @Stateful EJB instance per WebSocket client - this is in tune with the default behavior outlined by the WebSocket specification. Things would get interesting from a state management perspective

  • passivation capabilities of Stateful beans can be leveraged if needed (be careful about not storing references to non java.io.Serializable objects)

  • EJB containers also support replication of Stateful beans across clusters which means that client state can be saved across multiple JVMs. With some custom logic (since javax.websocket.Session is not Serializable), it might be possible to implement a highly availabile (HA) setup for WebSocket applications

@Stateful
@ServerEndpoint("/chat/{user}")
public class StatefulChat {
    private transient Session s;
    private String userID;
    private List<History> history;

    @OnOpen
    public void onOpen(@PathParam("user") String user, Session s) throws IOException {
        this.userID= user;
        this.s = s;
    ....
    }

    @OnMessage
    public void chat(String msg) {
        history.add(msg);
       //route message to intended recipient(s)
    }
    ...
}

In the above example

  • userId and (chat) history are user specific state which can be passivated, restored and replicated (across JVMs)

  • Session is marked transient since we do not intend to serialize it to disk not over network (other JVMs in cluster)

@Stateless

Using @Stateless style endpoints can prove to be useful as well. Here are some of the noteworthy points

  • Instance creation: A random instance is picked up from the EJB pool (as per availability). It's possible to fine tune the pool in order to extract maximum performance (e.g. deploy time initilization if EJBs etc.)

  • Once allocated, the same bean instance is used throughtout the lifecycle of the Session 

@Stateless
@ServerEndpoint("/stateless/")
public class StatelessEndpoint {

    @OnOpen
    public void onopen(Session s) throws IOException {
        s.getBasicRemote().sendText(String.valueOf(hashCode()));
    }

    //same logic as in @Singleton endpoint

}

Dependency Injection

All EJB flavors (except MessageDriven) Stateless, Stateful and Singleton can be injected into WebSocket endpoints. A good strategy would be to implement core business logic using EJBs which can be then invoked from within WebSocket endpoint lifecycle (callback) methods

Injecting a @Stateful EJB

There is a one-to-one association between the WebSocket client & endpoint (which is by default) as well as the injected Stateful EJB instance, which makes it an ideal candidate for storing client specific state. It offers advanced semantics as compared to simple java.util.Map interface exposed by getUserProperties method in javax.websocket.Session)

@ServerEndpoint("/letschat/{login-id}")
public class ChatEndpoint {

    @EJB
    private ClientChatState ccs; //stateful EJB

    private String userID;

    @OnOpen
    public void connOpened(@PathParam("login-id") String loginID, Session session) {
        ccs.setUser(loginID)
           .currentState(State.JOINED); //everyone likes a fluent API!
    }

    @OnMessage
    public void onMessage(String msg, Session session) {
        ccs.lastReceivedMsg(msg);
    }

    @OnClose
    public void onClose(Session session) {
        ccs.dispose(); //method annotated with @Remove
    }
    ...
}

Tip: Implement a @Remove annotated method in the Stateful EJB and call it from the @OnClose callback method. This will ensure that the EJB is removed from the memory immediately rather than depending upon @StatefulTimeout configuration

Injecting @Stateless and @Singleton EJBs

@Stateless and @Singleton EJBs can also be injected seamlessly. All the EJB features like transactions, simpler concurrency model, lifecycle management etc. can be leveraged

@ServerEndpoint("/chat/")
public class ChatEndpoint {

    @EJB
    private ChatHistory ch; //stateless EJB

    @EJB
    private ConnectedUsers users; //singleton EJB 

    @OnMessage
    public void onMessage(Session session){
        //business logic which makes use of the injected instances
    }
    ...
}

The table below summarizes the behavior when EJBs are injected into WebSocket endpoints

Injected EJB type

Behavior

@Stateless

a random instance is picked up from the pool

@Singleton

the same instance is injected

@Stateful

the bean is tied to the endpoint instance

beans.xml (in WEB-INF) is required in order to leverage Dependency Injection support

Interceptors

Just like EJB based injection support, Interceptor support in not officially supported by the WebSocket specification. You can implement cross-cutting business logic and then tie them to specific classes/methods using the @Interceptors annotation. You should employ the annotation for the type of interceptor i.e. @AroundInvoke, @AroundConstruct etc.

public class LoggingInerceptor {

    @AroundInvoke
    public Object log(InvocationContext ic) throws Exception {
        Object retVal = null;

        try {
            Logger.getAnonymousLogger().entering(ic.getTarget().getClass().getSimpleName(), 
                                                 ic.getMethod().getName());

            retVal = ic.proceed(); //allow intercepted method to be invoked

        } catch (Exception e) {
            Logger.getAnonymousLogger().severe(e.getMessage());
        } finally {
            Logger.getAnonymousLogger().exiting(ic.getTarget().getClass().getSimpleName(),
                                                ic.getMethod().getName());
        }

        return retVal;
    }
}

Apply the interceptor

@ServerEndpoint("/chat/")
public class ChatEndpoint {

    @Interceptors(LoggingInteceptor.class)
    @OnMessage
    public void onMessage(Session session){
        //business logic
    }
    ...
}

CDI integration

Although CDI integration offers features similar to that of the EJB ones i.e. Dependency Injection and Interceptors, it's worth noting that these are officialy supported by the specification (Section 7.1.1)

Dependency Injection

As part of the the DI support, @javax.inject.Inject can be used (on constructor, method, field) to inject CDI managed beans

@RequestScoped //CDI annotation
public class CDIManagedBean {
    ....
}
@ServerEndpoint("/stocks/")
public class StockTracker {

    @Inject
    private CDIManagedBean cdiBean;

    @OnOpen
    public void onOpenCallback(Session s){
        cdiBean.doSomething(); //use injected instance
    }
}
@ServerEndpoint("/weather/")
@Stateless // works with an EJB as well
public class WeatherTracker {

    @Inject
    private CDIManagedBean cdiBean;

    @OnOpen
    public void onOpenCallback(Session s){
        cdiBean.doSomething(); //use injected instance
    }
}

Interceptors

CDI Interceptors introduce an additional layer of abstraction. Let's look at a simple example

First up, we need to define an Interceptor binding

//the interceptor binding

@Inherited
@InterceptorBinding
@Retention(RUNTIME)
@Target({METHOD, TYPE})
public @interface LoggingInterceptorBinding {}

Implement our interceptor and bind it

//The interceptor implementation - notice the usage of additional annotations as compared to the EJB interceptors

@Interceptor
@LoggingInterceptorBinding
public class CDIBasedLoggingInterceptor {

    //implementation is the same (as in the case of EJB based interceptor)
    @AroundInvoke
    public Object log(InvocationContext ic) throws Exception {
        Object retVal = null;

        try {
            Logger.getAnonymousLogger().entering(ic.getTarget().getClass().getSimpleName(), 
                                                 ic.getMethod().getName());

            retVal = ic.proceed(); //allow intercepted method to be invoked

        } catch (Exception e) {
            Logger.getAnonymousLogger().severe(e.getMessage());
        } finally {
            Logger.getAnonymousLogger().exiting(ic.getTarget().getClass().getSimpleName(),
                                                ic.getMethod().getName());
        }

        return retVal;
    }
}

Apply the interceptor where needed (via the binding)

@ServerEndpoint("/chat/")
public class ChatEndpoint {

    @LoggingInterceptorBinding //binding the CDIBasedLoggingInterceptor
    @OnMessage
    public void onChatMsgRecieved(String chatMsg) {
        //....
    }
}

Oh, and don't forget to specify the interceptor in beans.xml (compulsory)

//Interceptors need to be defind in beans.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/beans_1_1.xsd"
bean-discovery-mode="all">
    <interceptors>
        <class>com.wordpress.abhirockzz.jaws.handbook.CDIBasedLoggingInterceptor</class>
    </interceptors>
</beans>

The CDI based interceptor works for EJB based WebSocket endpoints as well

Summary

Here is a quick review of what's supported for WebSocket in terms of CDI and EJB integration. Everything works.. Awesome!

Feature

Supported in EJB Annotated WebSocket Endpoint ?

Supported in Plain WebSocket endpoint ?

Inject CDI managed beans

yes

yes

Inject EJBs with @Inject

yes

yes

Inject EJBs with @EJB

yes

yes

Use CDI interceptors

yes

yes

Use EJB interceptors

yes

yes

Coming up

This concludes part I of this chapter. The second (and final) part will cover Servlet and Security related integration points

PreviousDeploymentNextPart-2: Tying in with the Java EE Platform

Last updated