# tootallnate/java-websocket architecture

> Architecture diagram of the GitHub repository tootallnate/java-websocket, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tootallnate/java-websocket
- Repository: https://github.com/tootallnate/java-websocket

## Overview

#### Purpose and Distribution

Java-WebSocket is a Java 8+ library providing non-blocking, event-driven WebSocket client and server implementations over `java.nio`. It implements RFC 6455 and RFC 7692 per-message deflate, packaged for Maven/Gradle consumers. Build entry points are `pom.xml` and `build.gradle`; Java 9 module metadata is at `src/main/java9/module-info.java`.

#### Public Application Entry Points

Consumers subclass the abstract client or server endpoints and implement lifecycle callbacks (`onOpen`, `onMessage`, `onClose`, `onError`):

- Client connection API: `src/main/java/org/java_websocket/client/WebSocketClient.java`
- Server accept/event-loop API: `src/main/java/org/java_websocket/server/WebSocketServer.java`
- Shared connection contract and callback bridge: `src/main/java/org/java_websocket/WebSocket.java`, `src/main/java/org/java_websocket/WebSocketListener.java`, `src/main/java/org/java_websocket/WebSocketAdapter.java`

Runnable usage references are under `src/main/example/ChatClient.java` and `src/main/example/ChatServer.java`.

#### Transport and Event Loop Boundary

`WebSocketServer` owns server-side non-blocking socket acceptance and connection processing; `WebSocketClient` initiates outbound URI-based connections. Channel I/O is separated from protocol parsing so raw `ByteBuffer` reads/writes can work with plain or wrapped channels:

- `src/main/java/org/java_websocket/SocketChannelIOHelper.java`
- `src/main/java/org/java_websocket/AbstractWrappedByteChannel.java`
- `src/main/java/org/java_websocket/WrappedByteChannel.java`

The central per-connection engine is `src/main/java/org/java_websocket/WebSocketImpl.java`, which manages connection state, incoming byte processing, outgoing frames, and listener notification.

#### Handshake and Protocol Negotiation

The opening HTTP Upgrade exchange is modeled separately from connected-frame traffic. Handshake data/builders carry request/response headers and enable server acceptance or rejection:

- `src/main/java/org/java_websocket/handshake/ClientHandshake.java`
- `src/main/java/org/java_websocket/handshake/ServerHandshake.java`
- `src/main/java/org/java_websocket/handshake/HandshakeImpl1Client.java`

`Draft` abstracts wire-protocol behavior; `Draft_6455` performs RFC 6455 handshake validation, frame translation, and extension/protocol negotiation:

- `src/main/java/org/java_websocket/drafts/Draft.java`
- `src/main/java/org/java_websocket/drafts/Draft_6455.java`
- `src/main/java/org/java_websocket/protocols/Protocol.java`

#### Frame Processing and Connection Lifecycle

After handshake completion, bytes flow through the selected draft into typed WebSocket frames, then to application callbacks. Outbound messages follow the reverse path: API send → frame encoding → channel write. Framing distinguishes text/binary data, fragmentation, ping/pong control traffic, and close semantics:

- `src/main/java/org/java_websocket/framing/Framedata.java`
- `src/main/java/org/java_websocket/framing/FramedataImpl1.java`
- `src/main/java/org/java_websocket/framing/CloseFrame.java`

Connection transitions and close-handshake rules are represented by `src/main/java/org/java_websocket/enums/ReadyState.java` and `src/main/java/org/java_websocket/enums/CloseHandshakeType.java`; malformed or invalid protocol input is surfaced via `src/main/java/org/java_websocket/exceptions/InvalidDataException`.

#### Extensions and Secure Transport

Extensions are negotiated during the opening handshake and applied at frame processing boundaries. The built-in RFC 7692 implementation provides per-message compression:

- `src/main/java/org/java_websocket/extensions/IExtension.java`
- `src/main/java/org/java_websocket/extensions/permessage_deflate/PerMessageDeflateExtension.java`

TLS/WSS is implemented through SSL channel wrappers and injectable client/server factories, using Java SSL infrastructure and caller-provided certificates/contexts:

- `src/main/java/org/java_websocket/SSLSocketChannel2.java`
- `src/main/java/org/java_websocket/server/DefaultSSLWebSocketServerFactory.java`
- `src/main/java/org/java_websocket/server/CustomSSLWebSocketServerFactory.java`

#### External Integration

The library depends on Java NIO/networking and Java SSL/TLS rather than an HTTP server framework. It emits logs through SLF4J, with binding selected by the consuming application. Maven Central is the intended artifact distribution channel. Autobahn interoperability artifacts and integration drivers are represented by `autobahn reports/` and `src/test/java/org/java_websocket/example/AutobahnServerTest.java`.

Main entry points: [`src/main/java/org/java_websocket/WebSocketImpl.java`](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/WebSocketImpl.java) (WebSocketImpl), [`src/main/java/org/java_websocket/drafts/Draft_6455.java`](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/drafts/Draft_6455.java) (Draft / RFC 6455), [`src/main/java/org/java_websocket/SocketChannelIOHelper.java`](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/SocketChannelIOHelper.java) (Channel I/O helper), [`src/main/java/org/java_websocket/SSLSocketChannel2.java`](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/SSLSocketChannel2.java) (SSL socket channel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_client["WebSocketClient<br/>client endpoint"]
  node_server["WebSocketServer<br/>server endpoint"]
  node_contract["WebSocket contract<br/>connection API<br/>[WebSocket.java]"]
  node_adapter["WebSocketAdapter<br/>callback adapter"]
end

subgraph group_runtime["Connection Runtime"]
  node_connection{{"WebSocketImpl<br/>connection engine<br/>[WebSocketImpl.java]"}}
  node_channelio["Channel I/O helper<br/>NIO transport"]
  node_wrappedchannel["Wrapped byte channel<br/>channel abstraction"]
end

subgraph group_protocol["WebSocket Protocol"]
  node_handshake["Handshake models<br/>HTTP Upgrade data"]
  node_draft{{"Draft / RFC 6455<br/>wire protocol<br/>[Draft_6455.java]"}}
  node_subprotocol["Protocol<br/>[Protocol.java]"]
  node_frames["WebSocket frames<br/>frame model<br/>[Framedata.java]"]
  node_lifecycle["Connection lifecycle<br/>state and close rules<br/>[ReadyState.java]"]
end

subgraph group_security["Extensions &amp; TLS"]
  node_compression["Per-message deflate<br/>RFC 7692 extension"]
  node_tlschannel["SSL socket channel<br/>TLS channel wrapper"]
  node_sslfactory["SSL server factories<br/>TLS factory"]
end

node_build["Maven / Gradle build<br/>distribution<br/>[pom.xml]"]
node_module["Java module metadata<br/>[module-info.java]"]
node_javanio(("Java NIO / SSL<br/>external platform"))
node_slf4j(("SLF4J<br/>external logging"))

node_build -->|"packages with"| node_module
node_client -->|"creates / drives"| node_connection
node_server -->|"accepts and drives"| node_connection
node_server -->|"event-loop I/O"| node_channelio
node_client -->|"connection I/O"| node_channelio
node_contract -->|"implemented by"| node_connection
node_adapter -->|"implements callbacks for"| node_contract
node_connection -->|"writes outbound buffers"| node_channelio
node_channelio -->|"uses when wrapped"| node_wrappedchannel
node_connection -->|"delegates bytes and frames"| node_draft
node_draft -->|"validates Upgrade"| node_handshake
node_draft -->|"negotiates"| node_subprotocol
node_draft -->|"decodes / encodes"| node_frames
node_connection -->|"transitions through"| node_lifecycle
node_draft -->|"negotiates and applies"| node_compression
node_sslfactory -->|"creates"| node_tlschannel
node_tlschannel -->|"wraps as"| node_wrappedchannel
node_channelio -->|"uses"| node_javanio
node_tlschannel -->|"uses SSL"| node_javanio
node_connection -.->|"logs through"| node_slf4j

click node_build "https://github.com/tootallnate/java-websocket/blob/master/pom.xml"
click node_module "https://github.com/tootallnate/java-websocket/blob/master/src/main/java9/module-info.java"
click node_client "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/client/WebSocketClient.java"
click node_server "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/server/WebSocketServer.java"
click node_contract "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/WebSocket.java"
click node_adapter "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/WebSocketAdapter.java"
click node_connection "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/WebSocketImpl.java"
click node_channelio "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/SocketChannelIOHelper.java"
click node_wrappedchannel "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/WrappedByteChannel.java"
click node_handshake "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/handshake/ClientHandshake.java"
click node_draft "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/drafts/Draft_6455.java"
click node_subprotocol "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/protocols/Protocol.java"
click node_frames "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/framing/Framedata.java"
click node_lifecycle "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/enums/ReadyState.java"
click node_compression "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/extensions/permessage_deflate/PerMessageDeflateExtension.java"
click node_tlschannel "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/SSLSocketChannel2.java"
click node_sslfactory "https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/server/DefaultSSLWebSocketServerFactory.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_server,node_contract,node_adapter toneBlue
class node_connection,node_channelio,node_wrappedchannel toneAmber
class node_handshake,node_draft,node_subprotocol,node_frames,node_lifecycle toneMint
class node_compression,node_tlschannel,node_sslfactory toneRose
class node_build,node_module,node_javanio,node_slf4j toneNeutral
```

## Components

### Public API

Consumer extension points and contracts.

- [WebSocketClient](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/client/WebSocketClient.java): client endpoint · Abstract outbound URI-based client API. · `src/main/java/org/java_websocket/client/WebSocketClient.java`
- [WebSocketServer](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/server/WebSocketServer.java): server endpoint · Abstract non-blocking accept and event-loop API. · `src/main/java/org/java_websocket/server/WebSocketServer.java`
- [WebSocket contract](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/WebSocket.java): connection API · Shared connection operations and callback bridge. · `src/main/java/org/java_websocket/WebSocket.java`
- [WebSocketAdapter](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/WebSocketAdapter.java): callback adapter · `src/main/java/org/java_websocket/WebSocketAdapter.java`

### Connection Runtime

NIO transport and per-connection processing.

- [WebSocketImpl](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/WebSocketImpl.java): connection engine · Owns connection state, byte processing, frames, and listener notification. · `src/main/java/org/java_websocket/WebSocketImpl.java`
- [Channel I/O helper](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/SocketChannelIOHelper.java): NIO transport · Reads and writes raw ByteBuffers. · `src/main/java/org/java_websocket/SocketChannelIOHelper.java`
- [Wrapped byte channel](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/WrappedByteChannel.java): channel abstraction · Supports plain and wrapped socket channels. · `src/main/java/org/java_websocket/WrappedByteChannel.java`

### WebSocket Protocol

Handshake negotiation and frame processing.

- [Handshake models](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/handshake/ClientHandshake.java): HTTP Upgrade data · Carries client and server request/response headers. · `src/main/java/org/java_websocket/handshake/ClientHandshake.java`
- [Draft / RFC 6455](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/drafts/Draft_6455.java): wire protocol · Validates upgrades, negotiates options, and translates frames. · `src/main/java/org/java_websocket/drafts/Draft_6455.java`
- [Protocol](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/protocols/Protocol.java): subprotocol negotiation · `src/main/java/org/java_websocket/protocols/Protocol.java`
- [WebSocket frames](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/framing/Framedata.java): frame model · Data, fragmentation, control, and close frames. · `src/main/java/org/java_websocket/framing/Framedata.java`
- [Connection lifecycle](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/enums/ReadyState.java): state and close rules · `src/main/java/org/java_websocket/enums/ReadyState.java`

### Extensions & TLS

Optional compression and secure channel support.

- [Per-message deflate](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/extensions/permessage_deflate/PerMessageDeflateExtension.java): RFC 7692 extension · Negotiated compression at frame boundaries. · `src/main/java/org/java_websocket/extensions/permessage_deflate/PerMessageDeflateExtension.java`
- [SSL socket channel](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/SSLSocketChannel2.java): TLS channel wrapper · Wraps NIO channels using Java SSL. · `src/main/java/org/java_websocket/SSLSocketChannel2.java`
- [SSL server factories](https://github.com/tootallnate/java-websocket/blob/master/src/main/java/org/java_websocket/server/DefaultSSLWebSocketServerFactory.java): TLS factory · Injects default or custom server TLS configuration. · `src/main/java/org/java_websocket/server/DefaultSSLWebSocketServerFactory.java`

### Other components

- [Maven / Gradle build](https://github.com/tootallnate/java-websocket/blob/master/pom.xml): distribution · Packages the Java library for consumers. · `pom.xml`
- [Java module metadata](https://github.com/tootallnate/java-websocket/blob/master/src/main/java9/module-info.java): module · `src/main/java9/module-info.java`
- **Java NIO / SSL**: external platform · Socket, selector, and TLS infrastructure.
- **SLF4J**: external logging · Binding is selected by the consuming application.

## Connections

- Maven / Gradle build → Java module metadata: packages with
- WebSocketClient → WebSocketImpl: creates / drives
- WebSocketServer → WebSocketImpl: accepts and drives
- WebSocketServer → Channel I/O helper: event-loop I/O
- WebSocketClient → Channel I/O helper: connection I/O
- WebSocket contract → WebSocketImpl: implemented by
- WebSocketAdapter → WebSocket contract: implements callbacks for
- WebSocketImpl → Channel I/O helper: writes outbound buffers
- Channel I/O helper → Wrapped byte channel: uses when wrapped
- WebSocketImpl → Draft / RFC 6455: delegates bytes and frames
- Draft / RFC 6455 → Handshake models: validates Upgrade
- Draft / RFC 6455 → Protocol: negotiates
- Draft / RFC 6455 → WebSocket frames: decodes / encodes
- WebSocketImpl → Connection lifecycle: transitions through
- Draft / RFC 6455 → Per-message deflate: negotiates and applies
- SSL server factories → SSL socket channel: creates
- SSL socket channel → Wrapped byte channel: wraps as
- Channel I/O helper → Java NIO / SSL: uses
- SSL socket channel → Java NIO / SSL: uses SSL
- WebSocketImpl → SLF4J: logs through