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
Copy link
On this page
Annotation based model
Programmatic API based model
Differences
Up next