0
# Eclipse Jetty Utilities
1

2
Eclipse Jetty Utilities is a comprehensive Java utility library that provides essential infrastructure and helper classes for the Eclipse Jetty web server. It offers a wide range of functionality including thread management, data structures, I/O utilities, security components, resource management, and networking utilities designed for high-performance, low-latency web applications.
3

4
## Package Information
5

6
- **Package Name**: jetty-util
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.eclipse.jetty
10
- **Artifact ID**: jetty-util
11
- **Installation**: Add to your Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>org.eclipse.jetty</groupId>
16
    <artifactId>jetty-util</artifactId>
17
    <version>12.0.21</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
// Core utilities
25
import org.eclipse.jetty.util.BufferUtil;
26
import org.eclipse.jetty.util.StringUtil;
27
import org.eclipse.jetty.util.URIUtil;
28
import org.eclipse.jetty.util.IO;
29
import org.eclipse.jetty.util.Callback;
30
import org.eclipse.jetty.util.Promise;
31

32
// Component lifecycle
33
import org.eclipse.jetty.util.component.LifeCycle;
34
import org.eclipse.jetty.util.component.ContainerLifeCycle;
35

36
// Threading
37
import org.eclipse.jetty.util.thread.ThreadPool;
38
import org.eclipse.jetty.util.thread.QueuedThreadPool;
39
import org.eclipse.jetty.util.thread.Scheduler;
40

41
// Data structures
42
import org.eclipse.jetty.util.Fields;
43
import org.eclipse.jetty.util.MultiMap;
44
import org.eclipse.jetty.util.Pool;
45
import org.eclipse.jetty.util.ConcurrentPool;
46

47
// Resources
48
import org.eclipse.jetty.util.resource.Resource;
49
import org.eclipse.jetty.util.resource.ResourceFactory;
50
import org.eclipse.jetty.util.resource.PathResourceFactory;
51
```
52

53
## Basic Usage
54

55
### Simple Buffer Operations
56

57
```java
58
import org.eclipse.jetty.util.BufferUtil;
59
import java.nio.ByteBuffer;
60
import java.nio.charset.StandardCharsets;
61

62
// Create and manipulate ByteBuffers
63
ByteBuffer buffer = BufferUtil.allocate(1024);
64
BufferUtil.append(buffer, "Hello World".getBytes(StandardCharsets.UTF_8));
65
String content = BufferUtil.toString(buffer, StandardCharsets.UTF_8);
66
```
67

68
### Lifecycle Management
69

70
```java
71
import org.eclipse.jetty.util.component.AbstractLifeCycle;
72

73
public class MyComponent extends AbstractLifeCycle {
74
    @Override
75
    protected void doStart() throws Exception {
76
        // Component startup logic
77
        super.doStart();
78
    }
79
    
80
    @Override
81
    protected void doStop() throws Exception {
82
        // Component shutdown logic
83
        super.doStop();
84
    }
85
}
86

87
// Usage
88
MyComponent component = new MyComponent();
89
component.start();
90
// ... use component
91
component.stop();
92
```
93

94
### Thread Pool Usage
95

96
```java
97
import org.eclipse.jetty.util.thread.QueuedThreadPool;
98

99
// Create and configure a thread pool
100
QueuedThreadPool threadPool = new QueuedThreadPool();
101
threadPool.setMinThreads(5);
102
threadPool.setMaxThreads(50);
103
threadPool.start();
104

105
// Submit tasks
106
threadPool.execute(() -> {
107
    // Task implementation
108
    System.out.println("Task executing in: " + Thread.currentThread().getName());
109
});
110

111
threadPool.stop();
112
```
113

114
### Asynchronous Operations
115

116
```java
117
import org.eclipse.jetty.util.Callback;
118
import org.eclipse.jetty.util.FutureCallback;
119
import org.eclipse.jetty.util.FuturePromise;
120

121
// Using callbacks for async operations
122
public void performAsyncOperation(Callback callback) {
123
    // Simulate async work
124
    new Thread(() -> {
125
        try {
126
            Thread.sleep(1000);
127
            callback.succeeded();
128
        } catch (Exception e) {
129
            callback.failed(e);
130
        }
131
    }).start();
132
}
133

134
// Usage with Future-based callback
135
FutureCallback callback = new FutureCallback();
136
performAsyncOperation(callback);
137
try {
138
    callback.get(); // Wait for completion
139
    System.out.println("Operation completed successfully");
140
} catch (Exception e) {
141
    System.out.println("Operation failed: " + e.getMessage());
142
}
143
```
144

145
## Architecture
146

147
Eclipse Jetty Utilities is built around several key architectural components:
148

149
- **Lifecycle Management**: Comprehensive component lifecycle with `LifeCycle` interface for consistent start/stop semantics
150
- **Asynchronous Patterns**: Rich callback and promise APIs for non-blocking operations with `Callback` and `Promise` interfaces
151
- **Resource Abstraction**: Unified resource API supporting files, memory, JARs, and URLs through the `Resource` interface
152
- **Thread Management**: Sophisticated threading utilities with pluggable execution strategies and virtual thread support
153
- **Object Pooling**: Generic pooling infrastructure for resource reuse with the `Pool` interface
154
- **Diagnostics**: Consistent diagnostic capabilities through the `Dumpable` interface for runtime introspection
155
- **Security Integration**: Comprehensive SSL/TLS support and credential management
156
- **Statistics Collection**: Built-in metrics and monitoring capabilities
157

158
## Capabilities
159

160
### Core Utilities
161

162
Essential utility classes for common operations including buffer manipulation, string processing, URI handling, and I/O operations.
163

164
```java { .api }
165
public class BufferUtil {
166
    public static ByteBuffer allocate(int capacity);
167
    public static String toString(ByteBuffer buffer, Charset charset);
168
    public static byte[] toArray(ByteBuffer buffer);
169
    public static void writeTo(ByteBuffer buffer, OutputStream out) throws IOException;
170
}
171

172
public class StringUtil {
173
    public static boolean isBlank(String str);
174
    public static boolean isEmpty(String str);
175
    public static String[] split(String str, char delimiter);
176
    public static List<String> csvSplit(String str);
177
}
178
```
179

180
[Core Utilities](./core-utilities.md)
181

182
### Data Structures
183

184
Specialized data structures for high-performance web applications including multi-maps, tries, pools, and concurrent collections.
185

186
```java { .api }
187
public class Fields implements Iterable<Fields.Field> {
188
    public void add(String name, String value);
189
    public String get(String name);
190
    public List<String> getValues(String name);
191
    public boolean remove(String name);
192
}
193

194
public interface Pool<P> {
195
    Pool.Entry<P> acquire();
196
    boolean release(Pool.Entry<P> entry);
197
    int getMaxEntries();
198
    int size();
199
}
200
```
201

202
[Data Structures](./data-structures.md)
203

204
### Asynchronous Operations
205

206
Comprehensive callback and promise APIs for building non-blocking, asynchronous applications with various callback implementations.
207

208
```java { .api }
209
public interface Callback {
210
    void succeeded();
211
    void failed(Throwable x);
212
    
213
    static Callback from(Runnable success, Consumer<Throwable> failure);
214
}
215

216
public interface Promise<C> extends Callback {
217
    void succeeded(C result);
218
}
219

220
public class FuturePromise<C> implements Future<C>, Promise<C> {
221
    public FuturePromise();
222
    public C get() throws InterruptedException, ExecutionException;
223
    public C get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException;
224
}
225
```
226

227
[Asynchronous Operations](./async-operations.md)
228

229
### Component Lifecycle
230

231
Robust component lifecycle management with container support, event notifications, and graceful shutdown capabilities.
232

233
```java { .api }
234
public interface LifeCycle {
235
    void start() throws Exception;
236
    void stop() throws Exception;
237
    boolean isRunning();
238
    boolean isStarted();
239
    boolean isStopped();
240
    boolean isFailed();
241
    
242
    void addLifeCycleListener(LifeCycle.Listener listener);
243
    void removeLifeCycleListener(LifeCycle.Listener listener);
244
}
245
```
246

247
[Component Lifecycle](./component-lifecycle.md)
248

249
### Threading
250

251
Advanced threading utilities including thread pools, schedulers, execution strategies, and concurrency primitives optimized for server applications.
252

253
```java { .api }
254
public interface ThreadPool extends Executor, LifeCycle {
255
    void join() throws InterruptedException;
256
    int getThreads();
257
    int getIdleThreads();
258
    boolean isLowOnThreads();
259
}
260

261
public interface Scheduler extends LifeCycle {
262
    Scheduler.Task schedule(Runnable task, long delay, TimeUnit unit);
263
    Scheduler.Task scheduleWithFixedDelay(Runnable task, long initialDelay, long delay, TimeUnit unit);
264
}
265
```
266

267
[Threading](./threading.md)
268

269
### Resource Management
270

271
Unified resource management API supporting various resource types with automatic cleanup and efficient access patterns.
272

273
```java { .api }
274
public interface Resource {
275
    boolean exists();
276
    boolean isDirectory();
277
    boolean isFile();
278
    Resource resolve(String subUriPath);
279
    InputStream newInputStream() throws IOException;
280
    Path getPath();
281
}
282

283
public interface ResourceFactory {
284
    Resource newResource(String uriOrPath);
285
    Resource newResource(Path path);
286
    Resource newResource(URI uri);
287
}
288
```
289

290
[Resource Management](./resource-management.md)
291

292
### Security
293

294
Comprehensive security utilities including SSL/TLS context management, credential providers, and certificate utilities.
295

296
```java { .api }
297
public abstract class SslContextFactory extends AbstractLifeCycle {
298
    public abstract SSLEngine newSSLEngine();
299
    public abstract SSLEngine newSSLEngine(String host, int port);
300
    public abstract void customize(SSLEngine sslEngine);
301
}
302

303
public interface CredentialProvider {
304
    Credential getCredential(String credential);
305
}
306
```
307

308
[Security](./security.md)
309

310
### Statistics
311

312
Built-in statistics collection and monitoring capabilities for performance tracking and system diagnostics.
313

314
```java { .api }
315
public class CounterStatistic {
316
    public void increment();
317
    public void decrement();
318
    public void add(long value);
319
    public long getCurrent();
320
    public long getMax();
321
    public void reset();
322
}
323
```
324

325
[Statistics](./statistics.md)
326

327
## Types
328

329
```java { .api }
330
// Lifecycle states
331
enum LifeCycle.State {
332
    STOPPED, STARTING, STARTED, STOPPING, FAILED
333
}
334

335
// Invocation types for threading
336
enum Invocable.InvocationType {
337
    BLOCKING, NON_BLOCKING, EITHER
338
}
339

340
// Pool entry interface
341
interface Pool.Entry<P> {
342
    P getPooled();
343
    boolean release();
344
    boolean remove();
345
}
346

347
// Callback exception handling
348
class CallbackWrapper implements Callback {
349
    public CallbackWrapper(Callback callback);
350
    // Wraps another callback with additional functionality
351
}
352
```