0
# Eclipse Jetty IO Module
1

2
Eclipse Jetty IO is a high-performance, asynchronous I/O library that provides the foundational networking components for the Eclipse Jetty web server and HTTP client. It offers non-blocking I/O abstractions, buffer pooling, content streaming, and SSL/TLS support designed for scalable network applications.
3

4
## Package Information
5

6
- **Package Name**: jetty-io
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>org.eclipse.jetty</groupId><artifactId>jetty-io</artifactId><version>12.0.21</version></dependency>`
10
- **Module**: `org.eclipse.jetty.io`
11

12
## Core Imports
13

14
```java
15
import org.eclipse.jetty.io.*;
16
import org.eclipse.jetty.io.content.*;
17
import org.eclipse.jetty.io.ssl.*;
18
```
19

20
## Basic Usage
21

22
```java
23
import org.eclipse.jetty.io.*;
24
import org.eclipse.jetty.io.content.*;
25
import org.eclipse.jetty.util.Callback;
26
import java.nio.ByteBuffer;
27

28
// Buffer pooling
29
ByteBufferPool pool = new ArrayByteBufferPool();
30
RetainableByteBuffer buffer = pool.acquire(1024, false);
31
try {
32
    ByteBuffer bb = buffer.getByteBuffer();
33
    // Use buffer for I/O operations
34
} finally {
35
    buffer.release();
36
}
37

38
// Content handling
39
Content.Source source = Content.Source.from("Hello World");
40
Content.Chunk chunk = source.read();
41
if (chunk != null) {
42
    ByteBuffer data = chunk.getByteBuffer();
43
    // Process data
44
}
45

46
// Async content copying
47
Content.Source source = Content.Source.from(inputStream);
48
Content.Sink sink = Content.Sink.asBuffered(outputSink);
49
Content.copy(source, sink, Callback.NOOP);
50
```
51

52
## Architecture
53

54
Jetty IO is built around several key architectural patterns:
55

56
- **Non-blocking I/O**: Built on Java NIO with asynchronous callbacks for scalable network operations
57
- **Reference Counting**: Automatic resource management through the Retainable interface
58
- **Content Streaming**: Demand-based content processing with backpressure support
59
- **Protocol Layering**: Connection upgrade mechanism for protocol switching (HTTP/1.1 → HTTP/2, HTTP → WebSocket)
60
- **Transport Abstraction**: Pluggable transport layer supporting TCP, UDP, and Unix domain sockets
61

62
## Capabilities
63

64
### Core I/O Abstractions
65

66
Essential interfaces and abstract base classes that define the I/O model, including non-blocking endpoints, connections, and lifecycle management.
67

68
```java { .api }
69
interface EndPoint extends Closeable {
70
    int fill(ByteBuffer buffer) throws IOException;
71
    boolean flush(ByteBuffer... buffers) throws IOException;
72
    void fillInterested(Callback callback) throws ReadPendingException;
73
    void write(Callback callback, ByteBuffer... buffers) throws WritePendingException;
74
    Connection getConnection();
75
    void setConnection(Connection connection);
76
}
77

78
interface Connection extends Closeable {
79
    void onOpen();
80
    void onClose(Throwable cause);
81
    EndPoint getEndPoint();
82
    boolean onIdleExpired(TimeoutException timeoutException);
83
}
84
```
85

86
[Core I/O Abstractions](./core-io.md)
87

88
### Buffer Management
89

90
High-performance buffer pooling and reference-counted buffer management for memory efficiency in high-throughput applications.
91

92
```java { .api }
93
interface ByteBufferPool {
94
    RetainableByteBuffer acquire(int size, boolean direct);
95
    void clear();
96
}
97

98
interface RetainableByteBuffer extends Retainable {
99
    ByteBuffer getByteBuffer();
100
    boolean isDirect();
101
    int capacity();
102
    void clear();
103
}
104

105
interface Retainable {
106
    void retain();
107
    boolean release();
108
    boolean canRetain();
109
}
110
```
111

112
[Buffer Management](./buffer-management.md)
113

114
### Content Streaming
115

116
Demand-driven content processing system with support for backpressure, async operations, and integration with reactive streams.
117

118
```java { .api }
119
class Content {
120
    interface Source {
121
        Chunk read();
122
        void demand(Runnable demandCallback);
123
        void fail(Throwable failure);
124
        long getLength();
125
        static Source from(ByteBuffer... buffers);
126
        static Source from(Path path);
127
        static Source from(InputStream inputStream);
128
    }
129
    
130
    interface Sink {
131
        void write(boolean last, ByteBuffer byteBuffer, Callback callback);
132
        static Sink asBuffered(Sink sink);
133
        static OutputStream asOutputStream(Sink sink);
134
    }
135
    
136
    interface Chunk {
137
        ByteBuffer getByteBuffer();
138
        boolean isLast();
139
        boolean hasRemaining();
140
        Throwable getFailure();
141
    }
142
}
143
```
144

145
[Content Streaming](./content-streaming.md)
146

147
### Connection Management
148

149
Client connection factories, transport abstractions, and connection lifecycle management for establishing and managing network connections.
150

151
```java { .api }
152
interface ClientConnectionFactory {
153
    Connection newConnection(EndPoint endPoint, Map<String, Object> context) throws IOException;
154
}
155

156
interface Transport {
157
    boolean isIntrinsicallySecure();
158
    void connect(SocketAddress socketAddress, Map<String, Object> context);
159
    Connection newConnection(EndPoint endPoint, Map<String, Object> context) throws IOException;
160
}
161
```
162

163
[Connection Management](./connection-management.md)
164

165
### SSL/TLS Support  
166

167
Secure connection implementations with SSL/TLS encryption, handshake management, and ALPN (Application Layer Protocol Negotiation) support.
168

169
```java { .api }
170
class SslConnection extends AbstractConnection implements Connection.UpgradeTo {
171
    // SSL connection wrapper
172
}
173

174
interface SslHandshakeListener extends EventListener {
175
    default void handshakeSucceeded(Event event) {}
176
    default void handshakeFailed(Event event, Throwable failure) {}
177
}
178

179
interface ALPNProcessor {
180
    void process(SSLEngine sslEngine, List<String> protocols, String selected);
181
}
182
```
183

184
[SSL/TLS Support](./ssl-support.md)
185

186
### Selector Management
187

188
Non-blocking I/O management using Java NIO selectors for handling multiple connections efficiently in a single-threaded or thread-pool model.
189

190
```java { .api }
191
abstract class SelectorManager extends ContainerLifeCycle {
192
    protected abstract EndPoint newEndPoint(SelectableChannel channel, ManagedSelector selector, SelectionKey key);
193
    protected abstract Connection newConnection(EndPoint endPoint, Object attachment);
194
}
195

196
class ManagedSelector extends AbstractLifeCycle implements Dumpable {
197
    // Single-threaded NIO selector management
198
}
199
```
200

201
[Selector Management](./selector-management.md)
202

203
## Types
204

205
### Core Types
206

207
```java { .api }
208
// Exception types
209
class EofException extends EOFException implements QuietException {
210
    EofException();
211
    EofException(String reason);
212
    EofException(Throwable cause);
213
}
214

215
interface QuietException {
216
    static boolean isQuiet(Throwable throwable);
217
}
218

219
class RuntimeIOException extends RuntimeException {
220
    RuntimeIOException(IOException cause);
221
}
222

223
// Timeout management
224
interface IdleTimeout {
225
    long getIdleTimeout();
226
    void setIdleTimeout(long idleTimeout);
227
    boolean isIdleTimeoutExpired();
228
    void onIdleExpired(TimeoutException timeout);
229
}
230

231
// Statistics and monitoring
232
class ConnectionStatistics extends AbstractLifeCycle implements Connection.Listener {
233
    long getConnectionsTotal();
234
    long getConnectionsOpened();
235
    long getConnectionsClosed();
236
    long getMessagesIn();
237
    long getMessagesOut();
238
    long getBytesIn();
239
    long getBytesOut();
240
}
241
```