session-java
A lightweight, async WebSocket protocol for Java.
## Introduction
This library provides **type-safe WebSocket communication** with a request-response and notification system built on top of a flexible protocol.
It ensures compile-time guarantees for message structure, reduces runtime errors, and simplifies building Java client/server applications.
- **Dynamic Methods**: Each message includes a method enum for type safety.
- **Typed Requests & Responses**: Automatic serialization and deserialization.
- **Optional Notifications**: Send asynchronous notifications across sessions.
## Features
- Fully typed WebSocket sessions
- Type-safe request/response mechanism
- Typed notifications
- Lightweight, minimal runtime overhead
## Installation
`session-java` is published to the Gitea package registry at `git.selimaj.dev`.
```groovy
repositories {
maven { url 'https://git.selimaj.dev/api/packages/selimaj-dev/maven' }
}
dependencies {
implementation 'dev.selimaj:session-java:0.2.0'
}
```
Versions up to 0.1.6 were published through JitPack as `com.github.selimaj-dev:session-java`.
## Usage
```java
static final Method DATA =
new Method<>("data", String.class, String.class, String.class);
Session session = Session.connect("ws://localhost:8080/", 10, TimeUnit.SECONDS);
// Handle requests and notifications from the server.
session.onRequest(DATA, (id, data) -> SessionResult.ok("echo: " + data));
session.onNotification(DATA, data -> System.out.println("notified: " + data));
// Find out when the connection ends, from either side.
session.onClose(() -> System.out.println("disconnected"));
// Send a request, with or without a deadline.
String reply = session.request(DATA, "Hello", Duration.ofSeconds(10)).get();
session.close();
```
### Semantics
- A request completes exceptionally with:
- `SessionErrorException` when the peer answers with an error response (`getError()` has the payload)
- `SessionClosedException` when the session closes before the response arrives
- `TimeoutException` when the timeout passes, if one was given
- `onClose` handlers run exactly once, whether the session was closed locally, by the peer, or by a network failure. A handler registered after close runs immediately.
- Sends are serialized, so the session is safe to use from multiple threads.
- A request for an unknown method is answered with an error response instead of no reply.
## Publishing
```sh
GITEA_TOKEN= ./gradlew publish
```
## Protocol
Every message is a JSON text frame with a `type` tag.
#### Request
The `id` is chosen by the sender and increments per peer.
```json
{ "type": "request", "id": 1, "method": "data", "data": "Hello from client" }
```
#### Response
A response **must** carry the id of the request it answers.
```json
{ "type": "response", "id": 1, "result": "Hello from server" }
```
#### Error response
```json
{ "type": "errorresponse", "id": 1, "error": "Invalid data" }
```
#### Notification
A notification is fire-and-forget and gets no response.
```json
{ "type": "notification", "method": "data", "data": "Hello from server" }
```