tootallnate/java-websocket

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.