# Lifecycle and Concurrency semantics

We have explored a lot of APIs components. For any serious application development, it's very important to understand the threading and concurrency aspects of both the application and the frameworks being used. This lesson covers these aspects and helps answer some common questions such as

* how many instances exist ?
* is an instance inherently thread safe?
* is concurrent access permitted (by the WebSocket implementation) ?

## `Session`

**Instances**: there is a unique `Session` instance per client-server pair i.e. one instance of `Session` is created for a each client which connects to the WebSocket server endpoint. In short, the number of unique `Session` instances is equal to number of connected clients

**Thread Safety**: A `Session` is thread safe in spite of the fact that multiple threads are allowed to invoke a single instance of Session. This is because the the specification mandates implementations to ensure the integrity of the mutable properties of the session under such circumstances.

## `Endpoint`

**Instances**: By default, there is one instance of an Endpoint per client unless this behavior is **overridden** by a **custom** `Configurator` implementation (see **Configuration** chapter for more details)

> **Example**
>
> If your application
>
> * has two endpoints: E1, E2
> * two clients connected to E1 and three clients connected to E2
>
> then total number of Endpoint instances
>
> * would be five, and
> * will decrease to three in case all the clients connected to E1 disconnect

**Thread Safety**: The container will allow only one thread (per client) to enter the (lifecycle callback) methods of the server endpoint. In case there is a custom `Configurator` implementation which changes this semantic e.g. provide a singleton endpoint, then multiple threads will be able to invoke this instance concurrently and thread safety has to be built in explicitly

## `MessageHandler`

**Instances**: In contrast to some of the other components, creation of a `MessageHandler` instance is controlled by the developer (not the container). Typically, each `Session` instance registers (via the `addMessageHandler` method) a separate instance of a `MessageHandler` i.e. there is a one-to-one relation b/w the peer who is sending a message (client), the `Session` (let's assume it's on the server end) and the `MessageHandler` instance (in this case it's responsible for receiving messages on the server side)

**Thread Safety**: The container will do as much as it can do ensure thread safety i.e. in case of `MessageHandler`s, it makes sure that only one thread enters a specific `MessageHandler` instance. In case the developer implementation is such that a single `MessageHandler` instance is registered to multiple `Session`s, then concurrent access is inevitable and this needs to be accounted for

## `Encoder` & `Decoder`

**Instances**: There is one instance of an `Encoder`/`Decoder` per connection (peer/client) for a specific server `Endpoint`

**Thread Safety**: A specific `Endpoint` instance itself is single-threaded (as mentioned above). In effect, what this means is that only thread can invoke an `Encoder`/`Decoder` instance specific to that endpoint

## `ServerEndpointConfig.Configurator` & `ClientEndpointConfig.Configurator`

**Instances**: There is a single instance of a configurator (server/client) which exists per endpoint

**Thread Safety**: Both `ServerEndpointConfig.Configurator` & `ClientEndpointConfig.Configurator` are not thread safe since the container does not serialize concurrent access to a single instance. One needs to bear this in mind when writing a custom implementation of the same

## `WebsocketContainer` & `ServerContainer`

**Instances**: A single instance exists per application

**Thread Safety**: It is thread safe in spite of the fact that multiple threads are allowed to invoke a single instance of the `WebSocketContainer`. This is because the the specification mandates implementations to ensure the integrity of the mutable properties of the session under such circumstances

> ### Recap

Here is a table for quick reference

| Component                                                                | Thread safe ?      |
| ------------------------------------------------------------------------ | ------------------ |
| `Session`                                                                | yes                |
| `Endpoint`                                                               | yes (default only) |
| `Encoder` & `Decoder`                                                    | yes                |
| `ServerEndpointConfig.Configurator` &`ClientEndpointConfig.Configurator` | No                 |
| `MessageHandler`                                                         | yes (default only) |
| `WebsocketContainer` & `ServerContainer`                                 | yes                |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/lifecycle_and_concurrency_semantics.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.