# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://abhishek-gupta.gitbook.io/java-websocket-api-handbook/programming-model.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.