Programming Model

This chapter gives you a quick overview of programming models available supported by the Java WebSocket API

You'll see extensive coverage of these programming models through topics explored in other chapters

There are two programming models

• Annotation based (declarative) and

• Programmatic (using inheritance)

Annotation based model

This model makes use of class and method level annotations. These are used to denote classes as server or client end points and designate their methods as target of callbacks (connection opened or closed, message received, error) initiated by the WebSocket container

Annotation	Description
@ServerEndpoint	If decorated with @ServerEndpoint, the container ensures availability of the class as a WebSocket server listening to a specific URI space
@ClientEndpoint	A class decorated with this annotation is treated as a WebSocket client
@OnOpen	Annotate a Java method using @OnOpen for it to be invoked by the container when a new websocket connection is initiated
@OnMessage	A Java method, when annotated with @OnMessage, receives from the WebSocket container when a message is sent to the endpoint
@OnError	Decorate a method with @OnError for it to be invoked when there is a problem with the WebSocket communication
@OnClose	Used to decorate a Java method which you want to be called by the container when the WebSocket connection closes

Here is a snippet - for now, just notice the use of annotations

//annotated endpoint

@ServerEndpoint("/test/")
public class AnnotatedEndpoint {
    @OnOpen
    public void onOpenCallback(Session s, EndpointConfig ec){
      ...
    }
    @OnMessage
    public void OnMessageCallback(String messageFromClient){
      ...
    }
    @OnClose
    public void onCloseCallback(Session s, CloseReason cr){
      ...
    }
    @OnError
    public void onErrorCallback(Session s, Throwable t){
      ...
    }
}

Programmatic API based model

The Programmatic API revolves around extending the javax.websocket.Endpoint class. If you decide to adopt this model, you'll need to make use of the following interfaces and classes. Here is a preview

Programmatic API component	Description
Endpoint	Explained in the API Overview chapter
MessageHandler	Parent interface for specific message handler implementations
MessageHandler.Whole<T>	Custom implementation for 'whole' messages i.e. ones which are complete
MessageHandler.Partial<T>	Custom implementation which processes a part of the message (partial)

T is the generic type parameter representing the actual object type of the message

//programmatic endpoint

public class ProgrammaticEndpoint extends Endpoint {
    @Override
    public onOpen(Session session, EndpointConfig config) {
      session.addMessageHandler((String s) -> System.out.println("got msg "+ s));
    ....
    }
}

Differences

Now that you have a basic idea of these models, the differences might be obvious. The table below serves as a quick reference

Category	Annotated model	Programmatic model
Basic	Uses annotations	Uses inheritance (extends)
Deployment	Auto-detected by WebSocket container	Need custom code (using ServerApplicationConfig) for deployment
Message reception	Defined using @OnMessage callback	Needs a MessageHandler implementation

Up next

How can you use the API to Send Messages to connected peers ? This topic will be explored in the next chapter