Package: Transport

Transport

Coverage

1: /*
2: * Copyright (c) 2008, 2020 Oracle and/or its affiliates. All rights reserved.
3: * Copyright (c) 2018 Payara Services Ltd.
4: *
5: * This program and the accompanying materials are made available under the
6: * terms of the Eclipse Public License v. 2.0, which is available at
7: * http://www.eclipse.org/legal/epl-2.0.
8: *
9: * This Source Code may also be made available under the following Secondary
10: * Licenses when the conditions for such availability set forth in the
11: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
12: * version 2 with the GNU Classpath Exception, which is available at
13: * https://www.gnu.org/software/classpath/license.html.
14: *
15: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
16: */
17:
18: package org.glassfish.grizzly;
19:
20: import java.io.IOException;
21: import java.util.concurrent.ExecutorService;
22: import java.util.concurrent.TimeUnit;
23:
24: import org.glassfish.grizzly.attributes.Attribute;
25: import org.glassfish.grizzly.attributes.AttributeBuilder;
26: import org.glassfish.grizzly.memory.MemoryManager;
27: import org.glassfish.grizzly.monitoring.MonitoringAware;
28: import org.glassfish.grizzly.monitoring.MonitoringConfig;
29: import org.glassfish.grizzly.threadpool.ThreadPoolConfig;
30: import org.glassfish.grizzly.threadpool.ThreadPoolProbe;
31: import org.glassfish.grizzly.utils.StateHolder;
32:
33: /**
34: * Transport interface describes the transport unit used in Grizzly.
35: *
36: * Transport implementation could operate over TCP, UDP or other custom protocol, using blocking, NIO or NIO.2 Java API.
37: *
38: * @author Alexey Stashok
39: */
40: public interface Transport extends MonitoringAware<TransportProbe> {
41:
42: /**
43: * The default read buffer size.
44: */
45: int DEFAULT_READ_BUFFER_SIZE = -1;
46:
47: /**
48: * The default write buffer size.
49: */
50: int DEFAULT_WRITE_BUFFER_SIZE = -1;
51:
52: /**
53: * Default read timeout in seconds.
54: */
55: int DEFAULT_READ_TIMEOUT = 30;
56:
57: /**
58: * Default write timeout in seconds.
59: */
60: int DEFAULT_WRITE_TIMEOUT = 30;
61:
62: enum State {
63: STARTING, STARTED, PAUSING, PAUSED, STOPPING, STOPPED
64: }
65:
66: /**
67: * Gets the {@link Transport} name.
68: *
69: * @return the {@link Transport} name.
70: */
71: String getName();
72:
73: /**
74: * Sets the {@link Transport} name.
75: *
76: * @param name the {@link Transport} name.
77: */
78: void setName(String name);
79:
80: /**
81: * Return the {@link Transport} state controller. Using the state controller, it is possible to get/set the
82: * {@link Transport} state in thread-safe manner.
83: *
84: * @return {@link StateHolder} state controller.
85: */
86: StateHolder<State> getState();
87:
88: /**
89: * Returns the {@link Transport} mode. <tt>true</tt>, if {@link Transport} is operating in blocking mode, or
90: * <tt>false</tt> otherwise. Specific {@link Transport} {@link Connection}s may override this setting by
91: * {@link Connection#isBlocking()}.
92: *
93: * @return the {@link Transport} mode. <tt>true</tt>, if {@link Transport} is operating in blocking mode, or
94: * <tt>false</tt> otherwise.
95: */
96: boolean isBlocking();
97:
98: /**
99: * Sets the {@link Transport} mode. Specific {@link Transport} {@link Connection}s may override this setting by
100: * {@link Connection#configureBlocking(boolean)}.
101: *
102: * @param isBlocking the {@link Transport} mode. <tt>true</tt>, if {@link Transport} should operate in blocking mode, or
103: * <tt>false</tt> otherwise.
104: */
105: void configureBlocking(boolean isBlocking);
106:
107: void configureStandalone(boolean isStandalone);
108:
109: boolean isStandalone();
110:
111: /**
112: * Gets the default {@link Processor}, which will process <tt>Transport</tt> {@link Connection}s I/O events in case, if
113: * {@link Connection} doesn't have own {@link Processor} preferences. If {@link Transport} associated {@link Processor}
114: * is <tt>null</tt>, and {@link Connection} doesn't have any preferred {@link Processor} - then {@link Transport} will
115: * try to get {@link Processor} using {@link ProcessorSelector#select(IOEvent, Connection)}.
116: *
117: * @param ioEvent the type of events the Processor should handle
118: * @param connection connection to obtain Processor for
119: * @return the default {@link Processor}, which will process {@link Connection} I/O events, if one doesn't have own
120: * {@link Processor} preferences.
121: */
122: Processor obtainProcessor(IOEvent ioEvent, Connection connection);
123:
124: /**
125: * Gets the default {@link Processor}, which will process {@link Connection} I/O events in case, if {@link Connection}
126: * doesn't have own {@link Processor} preferences. If {@link Transport} associated {@link Processor} is <tt>null</tt>,
127: * and {@link Connection} doesn't have any preferred {@link Processor} - then {@link Transport} will try to get
128: * {@link Processor} using {@link ProcessorSelector#select(IOEvent, Connection)}.
129: *
130: * @return the default {@link Processor}, which will process {@link Connection} I/O events, if one doesn't have own
131: * {@link Processor} preferences.
132: */
133: Processor getProcessor();
134:
135: /**
136: * Sets the default {@link Processor}, which will process {@link Connection} I/O events in case, if {@link Connection}
137: * doesn't have own {@link Processor} preferences.
138: *
139: * @param processor the default {@link Processor}, which will process {@link Connection} I/O events, if one doesn't have
140: * own {@link Processor} preferences.
141: */
142: void setProcessor(Processor processor);
143:
144: /**
145: * Gets the default {@link ProcessorSelector}, which will be used to get {@link Processor} to process {@link Connection}
146: * I/O events, in case if this {@link Transport}'s {@link Processor} is <tt>null</tt> and {@link Connection} doesn't
147: * have neither preferred {@link Processor} nor {@link ProcessorSelector}.
148: *
149: * {@link Transport}'s {@link ProcessorSelector} is the last place, where {@link Transport} will try to get
150: * {@link Processor} to process {@link Connection} I/O event. If {@link ProcessorSelector} is not set -
151: * {@link IllegalStateException} will be thrown.
152: *
153: * @return the default {@link ProcessorSelector}, which will be used to get {@link Processor} to process
154: * {@link Connection} I/O events, in case if this {@link Transport}'s {@link Processor} is <tt>null</tt> and
155: * {@link Connection} doesn't have neither preferred {@link Processor} nor {@link ProcessorSelector}.
156: */
157: ProcessorSelector getProcessorSelector();
158:
159: /**
160: * Sets the default {@link ProcessorSelector}, which will be used to get {@link Processor} to process {@link Connection}
161: * I/O events, in case if this {@link Transport}'s {@link Processor} is <tt>null</tt> and {@link Connection} doesn't
162: * have neither preferred {@link Processor} nor {@link ProcessorSelector}.
163: *
164: * {@link Transport}'s {@link ProcessorSelector} is the last place, where {@link Transport} will try to get
165: * {@link Processor} to process {@link Connection} I/O event. If {@link ProcessorSelector} is not set -
166: * {@link IllegalStateException} will be thrown.
167: *
168: * @param selector the default {@link ProcessorSelector}, which will be used to get {@link Processor} to process
169: * {@link Connection} I/O events, in case if this {@link Transport}'s {@link Processor} is <tt>null</tt> and
170: * {@link Connection} doesn't have neither preferred {@link Processor} nor {@link ProcessorSelector}.
171: */
172: void setProcessorSelector(ProcessorSelector selector);
173:
174: /**
175: * Get the {@link Transport} associated {@link MemoryManager}, which will be used by the {@link Transport}, its
176: * {@link Connection}s and by during processing I/O events, occurred on {@link Connection}s.
177: *
178: * @return the {@link Transport} associated {@link MemoryManager}, which will be used by the {@link Transport}, its
179: * {@link Connection}s and by during processing I/O events, occurred on {@link Connection}s.
180: */
181: MemoryManager getMemoryManager();
182:
183: /**
184: * Set the {@link Transport} associated {@link MemoryManager}, which will be used by the {@link Transport}, its
185: * {@link Connection}s and by during processing I/O events, occurred on {@link Connection}s.
186: *
187: * @param memoryManager the {@link Transport} associated {@link MemoryManager}, which will be used by the
188: * {@link Transport}, its {@link Connection}s and by during processing I/O events, occurred on {@link Connection}s.
189: */
190: void setMemoryManager(MemoryManager memoryManager);
191:
192: /**
193: * Get the {@link IOStrategy} implementation, which will be used by {@link Transport} to process {@link IOEvent}.
194: * {@link IOStrategy} is responsible for choosing the way, how I/O event will be processed: using current
195: * {@link Thread}, worker {@link Thread}; or make any other decisions.
196: *
197: * @return the {@link IOStrategy} implementation, which will be used by {@link Transport} to process {@link IOEvent}.
198: */
199: IOStrategy getIOStrategy();
200:
201: /**
202: * Set the {@link IOStrategy} implementation, which will be used by {@link Transport} to process {@link IOEvent}.
203: * {@link IOStrategy} is responsible for choosing the way, how I/O event will be processed: using current
204: * {@link Thread}, worker {@link Thread}; or make any other decisions.
205: *
206: * @param IOStrategy the {@link IOStrategy} implementation, which will be used by {@link Transport} to process
207: * {@link IOEvent}.
208: */
209: void setIOStrategy(IOStrategy IOStrategy);
210:
211: /**
212: * Get the default size of {@link Buffer}s, which will be allocated for reading data from {@link Transport}'s
213: * {@link Connection}s. For particular {@link Connection}, this setting could be overridden by
214: * {@link Connection#getReadBufferSize()}.
215: *
216: * @return the default size of {@link Buffer}s, which will be allocated for reading data from {@link Transport}'s
217: * {@link Connection}s.
218: */
219: int getReadBufferSize();
220:
221: /**
222: * Set the default size of {@link Buffer}s, which will be allocated for reading data from {@link Transport}'s
223: * {@link Connection}s. For particular {@link Connection}, this setting could be overridden by
224: * {@link Connection#setReadBufferSize(int)}.
225: *
226: * If not explicitly configured, this value will be set to {@link #DEFAULT_READ_BUFFER_SIZE}.
227: *
228: * @param readBufferSize the default size of {@link Buffer}s, which will be allocated for reading data from
229: * {@link Transport}'s {@link Connection}s.
230: */
231: void setReadBufferSize(int readBufferSize);
232:
233: /**
234: * Get the default size of {@link Buffer}s, which will be allocated for writing data to {@link Transport}'s
235: * {@link Connection}s. For particular {@link Connection}, this setting could be overridden by
236: * {@link Connection#getWriteBufferSize()}.
237: *
238: * @return the default size of {@link Buffer}s, which will be allocated for writing data to {@link Transport}'s
239: * {@link Connection}s.
240: */
241: int getWriteBufferSize();
242:
243: /**
244: * Set the default size of {@link Buffer}s, which will be allocated for writing data to {@link Transport}'s
245: * {@link Connection}s. For particular {@link Connection}, this setting could be overridden by
246: * {@link Connection#setWriteBufferSize(int)}.
247: *
248: * @param writeBufferSize the default size of {@link Buffer}s, which will be allocated for writing data to
249: * {@link Transport}'s {@link Connection}s.
250: */
251: void setWriteBufferSize(int writeBufferSize);
252:
253: /**
254: * Get a thread pool, which will run IOEvent processing (depending on Transport {@link IOStrategy}) to let kernel
255: * threads continue their job.
256: *
257: * @return {@link ExecutorService} transport worker thread pool.
258: */
259: ExecutorService getWorkerThreadPool();
260:
261: /**
262: * @return {@link ExecutorService} responsible for running Transport internal tasks. For example
263: * {@link org.glassfish.grizzly.nio.SelectorRunner} threads for NIO.
264: */
265: ExecutorService getKernelThreadPool();
266:
267: /**
268: * Set a thread pool, which will run IOEvent processing (depending on Transport {@link IOStrategy}) to let kernel
269: * threads continue their job.
270: *
271: * @param threadPool {@link ExecutorService} transport worker thread pool.
272: */
273: void setWorkerThreadPool(ExecutorService threadPool);
274:
275: /**
276: * Set a thread pool which will run Transport internal tasks. For example
277: * {@link org.glassfish.grizzly.nio.SelectorRunner} threads for NIO.
278: *
279: * @param threadPool {@link ExecutorService} for {@link org.glassfish.grizzly.nio.SelectorRunner}s
280: */
281: void setKernelThreadPool(ExecutorService threadPool);
282:
283: /**
284: * Set the {@link ThreadPoolConfig} to be used by the Transport internal thread pool.
285: *
286: * @param kernelConfig kernel thread pool configuration.
287: */
288: void setKernelThreadPoolConfig(final ThreadPoolConfig kernelConfig);
289:
290: /**
291: * Set the {@link ThreadPoolConfig} to be used by the worker thread pool.
292: *
293: * @param workerConfig worker thread pool configuration.
294: */
295: void setWorkerThreadPoolConfig(final ThreadPoolConfig workerConfig);
296:
297: /**
298: * @return the {@link ThreadPoolConfig} that will be used to construct the {@link java.util.concurrent.ExecutorService}
299: * which will run the {@link org.glassfish.grizzly.Transport}'s internal tasks. For example
300: * {@link org.glassfish.grizzly.nio.SelectorRunner}s for NIO.
301: */
302: ThreadPoolConfig getKernelThreadPoolConfig();
303:
304: /**
305: * @return the {@link ThreadPoolConfig} that will be used to construct the {@link java.util.concurrent.ExecutorService}
306: * for <code>IOStrategies</code> that require worker threads. Depending on the {@link IOStrategy} being used, this may
307: * return <code>null</code>.
308: */
309: ThreadPoolConfig getWorkerThreadPoolConfig();
310:
311: /**
312: * Get {@link Transport} associated {@link AttributeBuilder}, which will be used by {@link Transport} and its
313: * {@link Connection}s to store custom {@link Attribute}s.
314: *
315: * @return {@link Transport} associated {@link AttributeBuilder}, which will be used by {@link Transport} and its
316: * {@link Connection}s to store custom {@link Attribute}s.
317: */
318: AttributeBuilder getAttributeBuilder();
319:
320: /**
321: * Set {@link Transport} associated {@link AttributeBuilder}, which will be used by {@link Transport} and its
322: * {@link Connection}s to store custom {@link Attribute}s.
323: *
324: * @param attributeBuilder {@link Transport} associated {@link AttributeBuilder}, which will be used by
325: * {@link Transport} and its {@link Connection}s to store custom {@link Attribute}s.
326: */
327: void setAttributeBuilder(AttributeBuilder attributeBuilder);
328:
329: /**
330: * Starts the transport
331: *
332: * @throws IOException if transport fails to start. This may not occur if Transport was not in {@link State#STOPPED}.
333: */
334: void start() throws IOException;
335:
336: /**
337: * Stops the transport and closes all the connections
338: *
339: * @throws IOException if there was an error shutting down
340: *
341: * @deprecated Use {@link #shutdownNow()}.
342: */
343: @Deprecated
344: void stop() throws IOException;
345:
346: /**
347: * Gracefully stops the transport accepting new connections and allows existing work to complete before finalizing the
348: * shutdown. This method will wait indefinitely for all interested parties to signal it is safe to terminate the
349: * transport. Invoke {@link #shutdownNow()} to terminate the transport if the graceful shutdown is taking too long.
350: *
351: * @return a {@link GrizzlyFuture} which will return the stopped transport.
352: *
353: * @since 2.3.5
354: *
355: * @see GracefulShutdownListener
356: */
357: GrizzlyFuture<Transport> shutdown();
358:
359: /**
360: * Gracefully stops the transport accepting new connections and allows existing work to complete before finalizing the
361: * shutdown. This method will wait for the specified time for all interested parties to signal it is safe to terminate
362: * the transport. If the timeout is exceeded, the transport will be terminated forcefully.
363: *
364: * @param gracePeriod the grace period for a graceful shutdown before the transport is forcibly terminated. If
365: * gracePeriod is zero or less, then there is no time limit for the shutdown.
366: * @param timeUnit the {@link TimeUnit} of the specified grace period.
367: *
368: * @return a {@link GrizzlyFuture} which will return the stopped transport.
369: *
370: * @since 2.3.5
371: */
372: GrizzlyFuture<Transport> shutdown(final long gracePeriod, final TimeUnit timeUnit);
373:
374: /**
375: * Forcibly stops the transport and closes all connections.
376: *
377: * @throws IOException if there was an error shutting down
378: * @see #shutdown() to complete gracefully
379: * @since 2.3.5
380: */
381: void shutdownNow() throws IOException;
382:
383: /**
384: * Adds a {@link GracefulShutdownListener} which will be called when {@link #shutdown()} is called to enable graceful
385: * shutdown of transports. This allows the owner of the listener to signal that all shutdown tasks are complete and that
386: * it's safe to finalize the termination of the transport
387: *
388: * @param shutdownListener the {@link GracefulShutdownListener}
389: *
390: * @return <code>true</code> if the listener was successfully registered, otherwise <code>false</code>. When this method
391: * returns <code>false</code> it means one of two things: the transport is stopping or is stopped, or the listener has
392: * already been registered.
393: *
394: * @since 2.3.5
395: */
396: boolean addShutdownListener(final GracefulShutdownListener shutdownListener);
397:
398: /**
399: * Pauses the transport
400: */
401: void pause();
402:
403: /**
404: * Resumes the transport after a pause
405: */
406: void resume();
407:
408: /**
409: * Fires specific {@link IOEvent} on the {@link Connection}
410: *
411: * @param ioEvent I/O event
412: * @param connection {@link Connection}, on which we fire the event.
413: * @param listener I/O event life-cycle listener.
414: */
415: void fireIOEvent(IOEvent ioEvent, Connection connection, IOEventLifeCycleListener listener);
416:
417: /**
418: * Returns <tt>true</tt>, if this <tt>Transport</tt> is in stopped state, <tt>false</tt> otherwise.
419: *
420: * @return <tt>true</tt>, if this <tt>Transport</tt> is in stopped state, <tt>false</tt> otherwise.
421: */
422: boolean isStopped();
423:
424: boolean isPaused();
425:
426: /**
427: * Get the {@link Reader} to read data from the {@link Connection}. The <tt>Transport</tt> may decide to return blocking
428: * or non-blocking {@link Reader} depending on the {@link Connection} settings.
429: *
430: * @param connection {@link Connection}.
431: *
432: * @return {@link Reader}.
433: */
434: Reader getReader(Connection connection);
435:
436: /**
437: * Get the {@link Reader} implementation, depending on the requested mode.
438: *
439: * @param isBlocking blocking mode.
440: *
441: * @return {@link Reader}.
442: */
443: Reader getReader(boolean isBlocking);
444:
445: /**
446: * Get the {@link Writer} to write data to the {@link Connection}. The <tt>Transport</tt> may decide to return blocking
447: * or non-blocking {@link Writer} depending on the {@link Connection} settings.
448: *
449: * @param connection {@link Connection}.
450: *
451: * @return {@link Writer}.
452: */
453: Writer getWriter(Connection connection);
454:
455: /**
456: * Get the {@link Writer} implementation, depending on the requested mode.
457: *
458: * @param isBlocking blocking mode.
459: *
460: * @return {@link Writer}.
461: */
462: Writer getWriter(boolean isBlocking);
463:
464: /**
465: * Get the monitoring configuration for Transport {@link Connection}s.
466: *
467: * @return the configuration
468: */
469: MonitoringConfig<ConnectionProbe> getConnectionMonitoringConfig();
470:
471: /**
472: * Get the monitoring configuration for Transport thread pool.
473: *
474: * @return the configuration
475: */
476: MonitoringConfig<ThreadPoolProbe> getThreadPoolMonitoringConfig();
477:
478: /**
479: * Get the <tt>Transport</tt> monitoring configuration {@link MonitoringConfig}.
480: */
481: @Override
482: MonitoringConfig<TransportProbe> getMonitoringConfig();
483:
484: /**
485: * Method gets invoked, when error occur during the <tt>Transport</tt> lifecycle.
486: *
487: * @param error {@link Throwable}.
488: */
489: void notifyTransportError(Throwable error);
490:
491: /**
492: * Returns the current value for the blocking read timeout converted to the provided {@link TimeUnit} specification. If
493: * this value hasn't been explicitly set, it will default to {@value #DEFAULT_READ_TIMEOUT} seconds.
494: *
495: * @param timeUnit the {@link TimeUnit} to convert the returned result to.
496: * @return the value of the read timeout
497: *
498: * @since 2.3
499: */
500: long getReadTimeout(TimeUnit timeUnit);
501:
502: /**
503: * Specifies the timeout for the blocking reads. This may be overridden on a per-connection basis. A value of zero or
504: * less effectively disables the timeout.
505: *
506: * @param timeout the new timeout value
507: * @param timeUnit the {@link TimeUnit} specification of the provided value.
508: *
509: * @see Connection#setReadTimeout(long, java.util.concurrent.TimeUnit)
510: *
511: * @since 2.3
512: */
513: void setReadTimeout(long timeout, TimeUnit timeUnit);
514:
515: /**
516: * Returns the current value for the blocking write timeout converted to the provided {@link TimeUnit} specification. If
517: * this value hasn't been explicitly set, it will default to {@value #DEFAULT_WRITE_TIMEOUT} seconds.
518: *
519: * @param timeUnit the {@link TimeUnit} to convert the returned result to.
520: * @return the value of the write timeout
521: *
522: * @since 2.3
523: */
524: long getWriteTimeout(TimeUnit timeUnit);
525:
526: /**
527: * Specifies the timeout for the blocking writes. This may be overridden on a per-connection basis. A value of zero or
528: * less effectively disables the timeout.
529: *
530: * @param timeout the new timeout value
531: * @param timeUnit the {@link TimeUnit} specification of the provided value.
532: *
533: * @see Connection#setWriteTimeout(long, java.util.concurrent.TimeUnit)
534: *
535: * @since 2.3
536: */
537: void setWriteTimeout(long timeout, TimeUnit timeUnit);
538:
539: }