0
# Server Implementations
1

2
Various server types for different performance and scalability requirements. Thrift provides multiple server implementations ranging from simple single-threaded servers to high-performance non-blocking servers for different use cases.
3

4
## Capabilities
5

6
### Server Base Classes
7

8
Core server interfaces and abstract classes that all server implementations extend.
9

10
```java { .api }
11
/**
12
 * Abstract base class for all Thrift server implementations
13
 */
14
public abstract class TServer {
15
    /** Serve requests (blocking call that runs the server) */
16
    public abstract void serve();
17
    
18
    /** Stop the server */
19
    public void stop();
20
    
21
    /** Check if server is currently serving */
22
    public boolean isServing();
23
    
24
    /** Set event handler for server lifecycle events */
25
    public void setServerEventHandler(TServerEventHandler eventHandler);
26
    
27
    /** Get the server event handler */
28
    public TServerEventHandler getEventHandler();
29
    
30
    /**
31
     * Abstract base class for server configuration arguments
32
     */
33
    public static abstract class AbstractServerArgs<T extends AbstractServerArgs<T>> {
34
        /** Set the request processor */
35
        public T processor(TProcessor processor);
36
        
37
        /** Set the server transport */
38
        public T serverTransport(TServerTransport serverTransport);
39
        
40
        /** Set the protocol factory */
41
        public T protocolFactory(TProtocolFactory protocolFactory);
42
        
43
        /** Set the transport factory */
44
        public T transportFactory(TTransportFactory transportFactory);
45
        
46
        /** Set input protocol factory */
47
        public T inputProtocolFactory(TProtocolFactory inputProtocolFactory);
48
        
49
        /** Set output protocol factory */
50
        public T outputProtocolFactory(TProtocolFactory outputProtocolFactory);
51
        
52
        /** Set input transport factory */
53
        public T inputTransportFactory(TTransportFactory inputTransportFactory);
54
        
55
        /** Set output transport factory */
56
        public T outputTransportFactory(TTransportFactory outputTransportFactory);
57
        
58
        /** Set processor factory */
59
        public T processorFactory(TProcessorFactory processorFactory);
60
    }
61
}
62

63
/**
64
 * Interface for handling server lifecycle events
65
 */
66
public interface TServerEventHandler {
67
    /** Called when server starts serving */
68
    public void preServe();
69
    
70
    /** Called when a new client connects */
71
    public ServerContext createContext(TProtocol input, TProtocol output);
72
    
73
    /** Called when a client disconnects */
74
    public void deleteContext(ServerContext serverContext, TProtocol input, TProtocol output);
75
    
76
    /** Called before processing each request */
77
    public void processContext(ServerContext serverContext, TTransport inputTransport, TTransport outputTransport);
78
}
79

80
/**
81
 * Interface for server context information
82
 */
83
public interface ServerContext {
84
    /** Check if this context wraps an object of the given type */
85
    public <T> boolean isWrapperFor(Class<T> iface);
86
    
87
    /** Unwrap this context to the specified type */
88
    public <T> T unwrap(Class<T> iface);
89
}
90
```
91

92
### Simple Server
93

94
Single-threaded blocking server for basic use cases and development.
95

96
```java { .api }
97
/**
98
 * Simple single-threaded server that processes one request at a time
99
 */
100
public class TSimpleServer extends TServer {
101
    /** Create simple server with arguments */
102
    public TSimpleServer(AbstractServerArgs args);
103
    
104
    /** Serve requests in single thread (blocking) */
105
    public void serve();
106
    
107
    /** Stop the server */
108
    public void stop();
109
    
110
    /**
111
     * Configuration arguments for TSimpleServer
112
     */
113
    public static class Args extends AbstractServerArgs<Args> {
114
        /** Create args with server transport */
115
        public Args(TServerTransport transport);
116
    }
117
}
118
```
119

120
**Usage Examples:**
121

122
```java
123
import org.apache.thrift.server.TSimpleServer;
124
import org.apache.thrift.transport.TServerSocket;
125
import org.apache.thrift.protocol.TBinaryProtocol;
126

127
// Create server transport
128
TServerSocket serverTransport = new TServerSocket(9090);
129

130
// Create processor for your service
131
MyService.Processor<MyServiceHandler> processor = 
132
    new MyService.Processor<>(new MyServiceHandler());
133

134
// Create simple server
135
TSimpleServer server = new TSimpleServer(
136
    new TSimpleServer.Args(serverTransport)
137
        .processor(processor)
138
        .protocolFactory(new TBinaryProtocol.Factory())
139
);
140

141
// Start serving (blocks until stopped)
142
server.serve();
143
```
144

145
### Thread Pool Server
146

147
Multi-threaded server using a thread pool for concurrent request processing.
148

149
```java { .api }
150
/**
151
 * Multi-threaded server using thread pool for request processing
152
 */
153
public class TThreadPoolServer extends TServer {
154
    /** Create thread pool server with arguments */
155
    public TThreadPoolServer(AbstractServerArgs args);
156
    
157
    /** Serve requests using thread pool */
158
    public void serve();
159
    
160
    /** Stop the server and shutdown thread pool */
161
    public void stop();
162
    
163
    /**
164
     * Configuration arguments for TThreadPoolServer
165
     */
166
    public static class Args extends AbstractServerArgs<Args> {
167
        /** Create args with server transport */
168
        public Args(TServerTransport transport);
169
        
170
        /** Set minimum number of worker threads */
171
        public Args minWorkerThreads(int n);
172
        
173
        /** Set maximum number of worker threads */
174
        public Args maxWorkerThreads(int n);
175
        
176
        /** Set request timeout in milliseconds */
177
        public Args requestTimeout(int n);
178
        
179
        /** Set request timeout unit */
180
        public Args requestTimeoutUnit(TimeUnit timeoutUnit);
181
        
182
        /** Set stop timeout for graceful shutdown */
183
        public Args stopTimeoutVal(int stopTimeoutVal);
184
        
185
        /** Set stop timeout unit */
186
        public Args stopTimeoutUnit(TimeUnit stopTimeoutUnit);
187
        
188
        /** Set custom executor service */
189
        public Args executorService(ExecutorService executorService);
190
        
191
        /** Set custom thread factory */
192
        public Args executorService(ThreadFactory threadFactory);
193
    }
194
}
195
```
196

197
**Usage Examples:**
198

199
```java
200
import org.apache.thrift.server.TThreadPoolServer;
201
import org.apache.thrift.transport.TServerSocket;
202
import java.util.concurrent.Executors;
203
import java.util.concurrent.TimeUnit;
204

205
// Create thread pool server with custom configuration
206
TServerSocket serverTransport = new TServerSocket(9090);
207
MyService.Processor<MyServiceHandler> processor = 
208
    new MyService.Processor<>(new MyServiceHandler());
209

210
TThreadPoolServer server = new TThreadPoolServer(
211
    new TThreadPoolServer.Args(serverTransport)
212
        .processor(processor)
213
        .protocolFactory(new TBinaryProtocol.Factory())
214
        .minWorkerThreads(10)
215
        .maxWorkerThreads(100)
216
        .requestTimeout(30)
217
        .requestTimeoutUnit(TimeUnit.SECONDS)
218
);
219

220
// Or with custom executor
221
TThreadPoolServer customServer = new TThreadPoolServer(
222
    new TThreadPoolServer.Args(serverTransport)
223
        .processor(processor)
224
        .executorService(Executors.newFixedThreadPool(50))
225
);
226

227
server.serve();
228
```
229

230
### Non-blocking Server
231

232
Non-blocking server using NIO for high-performance single-threaded operation.
233

234
```java { .api }
235
/**
236
 * Non-blocking server implementation using NIO
237
 */
238
public class TNonblockingServer extends AbstractNonblockingServer {
239
    /** Create non-blocking server with arguments */
240
    public TNonblockingServer(AbstractNonblockingServerArgs args);
241
    
242
    /**
243
     * Configuration arguments for TNonblockingServer
244
     */
245
    public static class Args extends AbstractNonblockingServerArgs<Args> {
246
        /** Create args with non-blocking server transport */
247
        public Args(TNonblockingServerTransport transport);
248
    }
249
}
250

251
/**
252
 * Abstract base class for non-blocking server implementations
253
 */
254
public abstract class AbstractNonblockingServer extends TServer {
255
    /** Maximum read buffer size */
256
    public static final long MAX_READ_BUFFER_BYTES = Long.MAX_VALUE;
257
    
258
    /** Maximum frame size */
259
    public static final int MAX_FRAME_SIZE = 16384000;
260
    
261
    /** Serve requests using non-blocking I/O */
262
    public void serve();
263
    
264
    /** Stop the server */
265
    public void stop();
266
    
267
    /**
268
     * Abstract configuration arguments for non-blocking servers
269
     */
270
    public static abstract class AbstractNonblockingServerArgs<T extends AbstractNonblockingServerArgs<T>> 
271
            extends AbstractServerArgs<T> {
272
        /** Set maximum read buffer bytes */
273
        public T maxReadBufferBytes(long maxReadBufferBytes);
274
        
275
        /** Set maximum frame size */
276
        public T maxFrameSize(int maxFrameSize);
277
    }
278
}
279
```
280

281
**Usage Examples:**
282

283
```java
284
import org.apache.thrift.server.TNonblockingServer;
285
import org.apache.thrift.transport.TNonblockingServerSocket;
286
import org.apache.thrift.protocol.TBinaryProtocol;
287

288
// Create non-blocking server
289
TNonblockingServerSocket serverTransport = new TNonblockingServerSocket(9090);
290
MyService.Processor<MyServiceHandler> processor = 
291
    new MyService.Processor<>(new MyServiceHandler());
292

293
TNonblockingServer server = new TNonblockingServer(
294
    new TNonblockingServer.Args(serverTransport)
295
        .processor(processor)
296
        .protocolFactory(new TBinaryProtocol.Factory())
297
        .maxFrameSize(1024 * 1024)  // 1MB max frame
298
);
299

300
server.serve();
301
```
302

303
### Half-Sync/Half-Async Server
304

305
Server with non-blocking I/O and thread pool for processing.
306

307
```java { .api }
308
/**
309
 * Half-sync/half-async server: non-blocking I/O with thread pool processing
310
 */
311
public class THsHaServer extends AbstractNonblockingServer {
312
    /** Create HsHa server with arguments */
313
    public THsHaServer(AbstractNonblockingServerArgs args);
314
    
315
    /**
316
     * Configuration arguments for THsHaServer
317
     */
318
    public static class Args extends AbstractNonblockingServerArgs<Args> {
319
        /** Create args with non-blocking server transport */
320
        public Args(TNonblockingServerTransport transport);
321
        
322
        /** Set minimum worker threads */
323
        public Args minWorkerThreads(int n);
324
        
325
        /** Set maximum worker threads */
326
        public Args maxWorkerThreads(int n);
327
        
328
        /** Set stop timeout for graceful shutdown */
329
        public Args stopTimeoutVal(int stopTimeoutVal);
330
        
331
        /** Set stop timeout unit */
332
        public Args stopTimeoutUnit(TimeUnit stopTimeoutUnit);
333
        
334
        /** Set custom executor service for processing */
335
        public Args executorService(ExecutorService executorService);
336
    }
337
}
338
```
339

340
**Usage Examples:**
341

342
```java
343
import org.apache.thrift.server.THsHaServer;
344
import org.apache.thrift.transport.TNonblockingServerSocket;
345
import java.util.concurrent.TimeUnit;
346

347
// Create HsHa server for high concurrency
348
TNonblockingServerSocket serverTransport = new TNonblockingServerSocket(9090);
349
MyService.Processor<MyServiceHandler> processor = 
350
    new MyService.Processor<>(new MyServiceHandler());
351

352
THsHaServer server = new THsHaServer(
353
    new THsHaServer.Args(serverTransport)
354
        .processor(processor)
355
        .protocolFactory(new TBinaryProtocol.Factory())
356
        .minWorkerThreads(5)
357
        .maxWorkerThreads(50)
358
        .stopTimeoutVal(10)
359
        .stopTimeoutUnit(TimeUnit.SECONDS)
360
);
361

362
server.serve();
363
```
364

365
### Threaded Selector Server
366

367
High-performance server with multiple selector threads and thread pool.
368

369
```java { .api }
370
/**
371
 * High-performance server with multiple selector threads
372
 */
373
public class TThreadedSelectorServer extends AbstractNonblockingServer {
374
    /** Create threaded selector server with arguments */
375
    public TThreadedSelectorServer(AbstractNonblockingServerArgs args);
376
    
377
    /**
378
     * Configuration arguments for TThreadedSelectorServer
379
     */
380
    public static class Args extends AbstractNonblockingServerArgs<Args> {
381
        /** Create args with non-blocking server transport */
382
        public Args(TNonblockingServerTransport transport);
383
        
384
        /** Set number of selector threads */
385
        public Args selectorThreads(int selectorThreads);
386
        
387
        /** Set number of worker threads */
388
        public Args workerThreads(int workerThreads);
389
        
390
        /** Set stop timeout for graceful shutdown */
391
        public Args stopTimeoutVal(int stopTimeoutVal);
392
        
393
        /** Set stop timeout unit */
394
        public Args stopTimeoutUnit(TimeUnit stopTimeoutUnit);
395
        
396
        /** Set custom executor service for processing */
397
        public Args executorService(ExecutorService executorService);
398
        
399
        /** Set custom executor service for selector threads */
400
        public Args selectorExecutorService(ExecutorService selectorExecutorService);
401
        
402
        /** Set accept policy */
403
        public Args acceptPolicy(AcceptPolicy acceptPolicy);
404
        
405
        /** Set accept queue size per thread */
406
        public Args acceptQueueSizePerThread(int acceptQueueSizePerThread);
407
    }
408
    
409
    /**
410
     * Accept policy for new connections
411
     */
412
    public enum AcceptPolicy {
413
        ROUND_ROBIN,
414
        FAIR_ACCEPT
415
    }
416
}
417
```
418

419
**Usage Examples:**
420

421
```java
422
import org.apache.thrift.server.TThreadedSelectorServer;
423
import org.apache.thrift.transport.TNonblockingServerSocket;
424
import java.util.concurrent.Executors;
425

426
// Create threaded selector server for maximum performance
427
TNonblockingServerSocket serverTransport = new TNonblockingServerSocket(9090);
428
MyService.Processor<MyServiceHandler> processor = 
429
    new MyService.Processor<>(new MyServiceHandler());
430

431
TThreadedSelectorServer server = new TThreadedSelectorServer(
432
    new TThreadedSelectorServer.Args(serverTransport)
433
        .processor(processor)
434
        .protocolFactory(new TBinaryProtocol.Factory())
435
        .selectorThreads(4)           // 4 selector threads
436
        .workerThreads(32)            // 32 worker threads
437
        .acceptQueueSizePerThread(4)  // Accept queue size
438
        .acceptPolicy(TThreadedSelectorServer.AcceptPolicy.FAIR_ACCEPT)
439
);
440

441
server.serve();
442
```
443

444
### SASL Non-blocking Server
445

446
Non-blocking server with SASL authentication support.
447

448
```java { .api }
449
/**
450
 * Non-blocking server with SASL authentication
451
 */
452
public class TSaslNonblockingServer extends AbstractNonblockingServer {
453
    /** Create SASL non-blocking server with arguments */
454
    public TSaslNonblockingServer(AbstractNonblockingServerArgs args);
455
    
456
    /**
457
     * Configuration arguments for TSaslNonblockingServer
458
     */
459
    public static class Args extends AbstractNonblockingServerArgs<Args> {
460
        /** Create args with non-blocking server transport */
461
        public Args(TNonblockingServerTransport transport);
462
        
463
        // SASL-specific configuration methods would be added here
464
    }
465
}
466
```
467

468
### Servlet-based Servers
469

470
HTTP servlet-based server implementations for web containers.
471

472
```java { .api }
473
/**
474
 * Servlet-based Thrift server for web containers
475
 */
476
public class TServlet extends HttpServlet {
477
    /** Create servlet with processor and protocol factory */
478
    public TServlet(TProcessor processor, TProtocolFactory protocolFactory);
479
    
480
    /** Create servlet with processor factory */
481
    public TServlet(TProcessorFactory processorFactory, TProtocolFactory protocolFactory);
482
    
483
    /** Handle HTTP POST requests */
484
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
485
            throws ServletException, IOException;
486
    
487
    /** Handle HTTP GET requests (typically returns error) */
488
    protected void doGet(HttpServletRequest request, HttpServletResponse response) 
489
            throws ServletException, IOException;
490
}
491

492
/**
493
 * Extensible servlet with customizable request/response handling
494
 */
495
public class TExtensibleServlet extends TServlet {
496
    /** Create extensible servlet */
497
    public TExtensibleServlet(TProcessor processor, TProtocolFactory protocolFactory);
498
    
499
    /** Customize request handling */
500
    protected void customizeRequest(HttpServletRequest request);
501
    
502
    /** Customize response handling */
503
    protected void customizeResponse(HttpServletResponse response);
504
}
505
```
506

507
**Usage Examples:**
508

509
```java
510
import org.apache.thrift.server.TServlet;
511
import org.apache.thrift.protocol.TBinaryProtocol;
512
import javax.servlet.annotation.WebServlet;
513

514
// Servlet configuration
515
@WebServlet("/thrift")
516
public class MyThriftServlet extends TServlet {
517
    public MyThriftServlet() {
518
        super(new MyService.Processor<>(new MyServiceHandler()),
519
              new TBinaryProtocol.Factory());
520
    }
521
}
522

523
// Or create servlet programmatically
524
TServlet servlet = new TServlet(
525
    new MyService.Processor<>(new MyServiceHandler()),
526
    new TBinaryProtocol.Factory()
527
);
528
```
529

530
### Server Utilities
531

532
Utility classes and interfaces for server operations.
533

534
```java { .api }
535
/**
536
 * Represents a method invocation for logging and debugging
537
 */
538
public class Invocation {
539
    /** Create invocation */
540
    public Invocation(String methodName, Object[] args);
541
    
542
    /** Get method name */
543
    public String getMethodName();
544
    
545
    /** Get method arguments */
546
    public Object[] getArgs();
547
    
548
    /** String representation of invocation */
549
    public String toString();
550
}
551
```
552

553
**Complete Server Example:**
554

555
```java
556
import org.apache.thrift.server.*;
557
import org.apache.thrift.transport.*;
558
import org.apache.thrift.protocol.*;
559
import java.util.concurrent.TimeUnit;
560

561
public class ThriftServerExample {
562
    public static void main(String[] args) throws Exception {
563
        // Create server transport
564
        TServerSocket serverTransport = new TServerSocket(9090);
565
        
566
        // Create processor
567
        MyService.Processor<MyServiceHandler> processor = 
568
            new MyService.Processor<>(new MyServiceHandler());
569
        
570
        // Add server event handler
571
        TServerEventHandler eventHandler = new TServerEventHandler() {
572
            public void preServe() {
573
                System.out.println("Server starting...");
574
            }
575
            
576
            public ServerContext createContext(TProtocol input, TProtocol output) {
577
                System.out.println("Client connected");
578
                return null;
579
            }
580
            
581
            public void deleteContext(ServerContext ctx, TProtocol input, TProtocol output) {
582
                System.out.println("Client disconnected");
583
            }
584
            
585
            public void processContext(ServerContext ctx, TTransport in, TTransport out) {
586
                // Pre-process request
587
            }
588
        };
589
        
590
        // Create and configure server
591
        TThreadPoolServer server = new TThreadPoolServer(
592
            new TThreadPoolServer.Args(serverTransport)
593
                .processor(processor)
594
                .protocolFactory(new TBinaryProtocol.Factory())
595
                .transportFactory(new TFramedTransport.Factory())
596
                .minWorkerThreads(10)
597
                .maxWorkerThreads(100)
598
                .requestTimeout(30)
599
                .requestTimeoutUnit(TimeUnit.SECONDS)
600
        );
601
        
602
        server.setServerEventHandler(eventHandler);
603
        
604
        // Start server
605
        System.out.println("Starting server on port 9090...");
606
        server.serve();
607
    }
608
}
609
```