Package: Connection$CloseListener

Connection$CloseListener

Coverage

1: /*
2: * Copyright (c) 2022 Contributors to the Eclipse Foundation
3: * Copyright (c) 2008, 2020 Oracle and/or its affiliates. All rights reserved.
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.Future;
22: import java.util.concurrent.TimeUnit;
23:
24: import java.util.function.Supplier;
25: import org.glassfish.grizzly.attributes.AttributeStorage;
26: import org.glassfish.grizzly.memory.MemoryManager;
27: import org.glassfish.grizzly.monitoring.MonitoringAware;
28: import org.glassfish.grizzly.monitoring.MonitoringConfig;
29:
30: /**
31: * Common interface, which represents any kind of connection.
32: *
33: * @param <L> the Connection address type
34: *
35: * @author Alexey Stashok
36: */
37: public interface Connection<L> extends Readable<L>, Writeable<L>, Closeable, AttributeStorage, MonitoringAware<ConnectionProbe> {
38:
39: /**
40: * Returns id of this instance, unique in the context of the JVM and the implementation class.
41: *
42: * @return id of this instance, never null.
43: */
44: long getId();
45:
46: /**
47: * Get the {@link Transport}, to which this {@link Connection} belongs to.
48: *
49: * @return the {@link Transport}, to which this {@link Connection} belongs to.
50: */
51: Transport getTransport();
52:
53: /**
54: * Is {@link Connection} open and ready. Returns <tt>true</tt>, if connection is open and ready, or <tt>false</tt>
55: * otherwise.
56: *
57: * @return <tt>true</tt>, if connection is open and ready, or <tt>false</tt> otherwise.
58: */
59: @Override
60: boolean isOpen();
61:
62: /**
63: * Checks if this <tt>Connection</tt> is open and ready to be used. If this <tt>Connection</tt> is closed - this method
64: * throws {@link IOException} giving the reason why this <tt>Connection</tt> was closed.
65: *
66: */
67: @Override
68: void assertOpen() throws IOException;
69:
70: /**
71: * Returns {@link CloseReason} if this <tt>Connection</tt> has been closed, or <tt>null</tt> otherwise.
72: *
73: * @return {@link CloseReason} if this <tt>Connection</tt> has been closed, or <tt>null</tt> otherwise
74: */
75: CloseReason getCloseReason();
76:
77: /**
78: * Sets the {@link Connection} mode.
79: *
80: * @param isBlocking the {@link Connection} mode. <tt>true</tt>, if {@link Connection} should operate in blocking mode,
81: * or <tt>false</tt> otherwise.
82: */
83: void configureBlocking(boolean isBlocking);
84:
85: /**
86: * @return the {@link Connection} mode. <tt>true</tt>, if {@link Connection} is operating in blocking mode, or
87: * <tt>false</tt> otherwise.
88: */
89: boolean isBlocking();
90:
91: @Deprecated
92: void configureStandalone(boolean isStandalone);
93:
94: @Deprecated
95: boolean isStandalone();
96:
97: /**
98: * Gets the {@link Processor}, which will process {@link Connection} I/O event. If {@link Processor} is <tt>null</tt>, -
99: * then {@link Transport} will try to get {@link Processor} using {@link Connection}'s
100: * {@link ProcessorSelector#select(IOEvent, Connection)}. If {@link ProcessorSelector}, associated withthe
101: * {@link Connection} is also <tt>null</tt> - will ask {@link Transport} for a {@link Processor}.
102: *
103: * @param ioEvent event to obtain the processor for
104: * @return the default {@link Processor}, which will process {@link Connection} I/O events.
105: */
106: Processor obtainProcessor(IOEvent ioEvent);
107:
108: /**
109: * Gets the default {@link Processor}, which will process {@link Connection} I/O events. If {@link Processor} is
110: * <tt>null</tt>, - then {@link Transport} will try to get {@link Processor} using {@link Connection}'s
111: * {@link ProcessorSelector#select(IOEvent, Connection)}. If {@link ProcessorSelector}, associated withthe
112: * {@link Connection} is also <tt>null</tt> - {@link Transport} will try to get {@link Processor} using own settings.
113: *
114: * @return the default {@link Processor}, which will process {@link Connection} I/O events.
115: */
116: Processor getProcessor();
117:
118: /**
119: * Sets the default {@link Processor}, which will process {@link Connection} I/O events. If {@link Processor} is
120: * <tt>null</tt>, - then {@link Transport} will try to get {@link Processor} using {@link Connection}'s
121: * {@link ProcessorSelector#select(IOEvent, Connection)}. If {@link ProcessorSelector}, associated withthe
122: * {@link Connection} is also <tt>null</tt> - {@link Transport} will try to get {@link Processor} using own settings.
123: *
124: * @param preferableProcessor the default {@link Processor}, which will process {@link Connection} I/O events.
125: */
126: void setProcessor(Processor preferableProcessor);
127:
128: /**
129: * Gets the default {@link ProcessorSelector}, which will be used to get {@link Processor} to process {@link Connection}
130: * I/O events, in case if this {@link Connection}'s {@link Processor} is <tt>null</tt>.
131: *
132: * @return the default {@link ProcessorSelector}, which will be used to get {@link Processor} to process
133: * {@link Connection} I/O events, in case if this {@link Connection}'s {@link Processor} is <tt>null</tt>.
134: */
135: ProcessorSelector getProcessorSelector();
136:
137: /**
138: * Sets the default {@link ProcessorSelector}, which will be used to get {@link Processor} to process {@link Connection}
139: * I/O events, in case if this {@link Connection}'s {@link Processor} is <tt>null</tt>.
140: *
141: * @param preferableProcessorSelector the default {@link ProcessorSelector}, which will be used to get {@link Processor}
142: * to process {@link Connection} I/O events, in case if this {@link Connection}'s {@link Processor} is <tt>null</tt>.
143: */
144: void setProcessorSelector(ProcessorSelector preferableProcessorSelector);
145:
146: /**
147: * Returns the {@link Processor} state associated with this <tt>Connection</tt>.
148: *
149: * @param <E> state of the {@link Processor}
150: * @param processor {@link Processor}
151: * @param factory factory that is used to initialise the state
152: *
153: * @return the {@link Processor} state associated with this <tt>Connection</tt>.
154: */
155: <E> E obtainProcessorState(Processor processor, Supplier<E> factory);
156:
157: /**
158: * Executes the {@link Runnable} in the thread, responsible for running the given type of event on this
159: * <tt>Connection</tt>. The thread will be chosen based on {@link #getTransport() Transport} settings, especially
160: * current I/O strategy.
161: *
162: * @param event event to get the thread pool from
163: * @param runnable Runnable to run in the thread
164: */
165: void executeInEventThread(IOEvent event, Runnable runnable);
166:
167: /**
168: * @return an associated {@link MemoryManager}. It's a shortcut for
169: * {@link #getTransport()}{@link Transport#getMemoryManager() .getMemoryManager()}
170: * @since 2.3.18
171: */
172: MemoryManager<?> getMemoryManager();
173:
174: /**
175: * Get the connection peer address
176: *
177: * @return the connection peer address
178: */
179: L getPeerAddress();
180:
181: /**
182: * Get the connection local address
183: *
184: * @return the connection local address
185: */
186: L getLocalAddress();
187:
188: /**
189: * Get the default size of {@link Buffer}s, which will be allocated for reading data from {@link Connection}. The value
190: * less or equal to zero will be ignored.
191: *
192: * @return the default size of {@link Buffer}s, which will be allocated for reading data from {@link Connection}.
193: */
194: int getReadBufferSize();
195:
196: /**
197: * Set the default size of {@link Buffer}s, which will be allocated for reading data from {@link Connection}. The value
198: * less or equal to zero will be ignored.
199: *
200: * @param readBufferSize the default size of {@link Buffer}s, which will be allocated for reading data from
201: * {@link Connection}.
202: */
203: void setReadBufferSize(int readBufferSize);
204:
205: /**
206: * Get the default size of {@link Buffer}s, which will be allocated for writing data to {@link Connection}.
207: *
208: * @return the default size of {@link Buffer}s, which will be allocated for writing data to {@link Connection}.
209: */
210: int getWriteBufferSize();
211:
212: /**
213: * Set the default size of {@link Buffer}s, which will be allocated for writing data to {@link Connection}.
214: *
215: * @param writeBufferSize the default size of {@link Buffer}s, which will be allocated for writing data to
216: * {@link Connection}.
217: */
218: void setWriteBufferSize(int writeBufferSize);
219:
220: /**
221: * Get the max size (in bytes) of asynchronous write queue associated with connection.
222: *
223: * @return the max size (in bytes) of asynchronous write queue associated with connection.
224: *
225: * @since 2.2
226: */
227: int getMaxAsyncWriteQueueSize();
228:
229: /**
230: * Set the max size (in bytes) of asynchronous write queue associated with connection.
231: *
232: * @param maxAsyncWriteQueueSize the max size (in bytes) of asynchronous write queue associated with connection.
233: *
234: * @since 2.2
235: */
236: void setMaxAsyncWriteQueueSize(int maxAsyncWriteQueueSize);
237:
238: /**
239: * Returns the current value for the blocking read timeout converted to the provided {@link TimeUnit} specification. If
240: * this value hasn't been explicitly set, it will default to 30 seconds.
241: *
242: * @param timeUnit the {@link TimeUnit} to convert the returned result to.
243: * @return the read timeout value
244: *
245: * @since 2.3
246: */
247: long getReadTimeout(TimeUnit timeUnit);
248:
249: /**
250: * Specifies the timeout for the blocking reads. This may be overridden on a per-connection basis. A value of zero or
251: * less effectively disables the timeout.
252: *
253: * @param timeout the new timeout value
254: * @param timeUnit the {@link TimeUnit} specification of the provided value.
255: *
256: * @see Connection#setReadTimeout(long, java.util.concurrent.TimeUnit)
257: *
258: * @since 2.3
259: */
260: void setReadTimeout(long timeout, TimeUnit timeUnit);
261:
262: /**
263: * Returns the current value for the blocking write timeout converted to the provided {@link TimeUnit} specification. If
264: * this value hasn't been explicitly set, it will default to 30 seconds.
265: *
266: * @param timeUnit the {@link TimeUnit} to convert the returned result to.
267: * @return the write timeout value
268: *
269: * @since 2.3
270: */
271: long getWriteTimeout(TimeUnit timeUnit);
272:
273: /**
274: * Specifies the timeout for the blocking writes. This may be overridden on a per-connection basis. A value of zero or
275: * less effectively disables the timeout.
276: *
277: * @param timeout the new timeout value
278: * @param timeUnit the {@link TimeUnit} specification of the provided value.
279: *
280: * @see Connection#setWriteTimeout(long, java.util.concurrent.TimeUnit)
281: *
282: * @since 2.3
283: */
284: void setWriteTimeout(long timeout, TimeUnit timeUnit);
285:
286: void simulateIOEvent(final IOEvent ioEvent) throws IOException;
287:
288: void enableIOEvent(final IOEvent ioEvent) throws IOException;
289:
290: void disableIOEvent(final IOEvent ioEvent) throws IOException;
291:
292: /**
293: * @return the <tt>Connection</tt> monitoring configuration {@link MonitoringConfig}.
294: */
295: @Override
296: MonitoringConfig<ConnectionProbe> getMonitoringConfig();
297:
298: /**
299: * Close the {@link Connection} silently, no notification required on completion or failure.
300: */
301: @Override
302: void terminateSilently();
303:
304: /**
305: * Close the {@link Connection}
306: *
307: * @return {@link Future}, which could be checked in case, if close operation will be run asynchronously
308: */
309: @Override
310: GrizzlyFuture<Closeable> terminate();
311:
312: /**
313: * Closes the <tt>Connection</tt> and provides the reason description.
314: *
315: * This method is similar to {@link #terminateSilently()}, but additionally provides the reason why the
316: * <tt>Connection</tt> will be closed.
317: *
318: */
319: @Override
320: void terminateWithReason(IOException reason);
321:
322: /**
323: * Gracefully close the {@link Connection}
324: *
325: * @return {@link Future}, which could be checked in case, if close operation will be run asynchronously
326: */
327: @Override
328: GrizzlyFuture<Closeable> close();
329:
330: /**
331: * Gracefully close the {@link Connection}
332: *
333: * @param completionHandler {@link CompletionHandler} to be called, when the connection is closed.
334: *
335: * @deprecated use {@link #close()} with the following
336: * {@link GrizzlyFuture#addCompletionHandler(org.glassfish.grizzly.CompletionHandler)}.
337: */
338: @Deprecated
339: @Override
340: void close(CompletionHandler<Closeable> completionHandler);
341:
342: /**
343: * Gracefully close the {@link Connection} silently, no notification required on completion or failure.
344: */
345: @Override
346: void closeSilently();
347:
348: /**
349: * Gracefully closes the <tt>Connection</tt> and provides the reason description.
350: *
351: * This method is similar to {@link #closeSilently()}, but additionally provides the reason why the <tt>Connection</tt>
352: * will be closed.
353: *
354: */
355: @Override
356: void closeWithReason(IOException reason);
357:
358: /**
359: * Add the {@link CloseListener}, which will be notified once <tt>Connection</tt> will be closed.
360: *
361: * @param closeListener {@link CloseListener}.
362: *
363: * @since 2.3
364: */
365: @Override
366: void addCloseListener(org.glassfish.grizzly.CloseListener closeListener);
367:
368: /**
369: * Remove the {@link CloseListener}.
370: *
371: * @param closeListener {@link CloseListener}.
372: *
373: * @since 2.3
374: */
375: @Override
376: boolean removeCloseListener(org.glassfish.grizzly.CloseListener closeListener);
377:
378: /**
379: * Add the {@link CloseListener}, which will be notified once <tt>Connection</tt> will be closed.
380: *
381: * @param closeListener {@link CloseListener}
382: *
383: * @deprecated use {@link #addCloseListener(org.glassfish.grizzly.CloseListener)}
384: */
385: @Deprecated
386: void addCloseListener(CloseListener closeListener);
387:
388: /**
389: * Remove the {@link CloseListener}.
390: *
391: * @param closeListener {@link CloseListener}.
392: * @return true if listener successfully removed
393: *
394: * @deprecated use {@link #removeCloseListener(org.glassfish.grizzly.CloseListener)}
395: */
396: @Deprecated
397: boolean removeCloseListener(CloseListener closeListener);
398:
399: /**
400: * Method gets invoked, when error occur during the <tt>Connection</tt> lifecycle.
401: *
402: * @param error {@link Throwable}.
403: */
404: void notifyConnectionError(Throwable error);
405:
406: // ------------------------------------------------------------------- Nested Classes
407:
408: /**
409: * This interface will be removed in 3.0.
410: *
411: * @deprecated use {@link org.glassfish.grizzly.CloseListener}
412: *
413: * @see GenericCloseListener
414: */
415: @Deprecated
416: interface CloseListener extends org.glassfish.grizzly.CloseListener<Connection, CloseType> {
417:
418: @Override
419: void onClosed(Connection connection, CloseType type) throws IOException;
420:
421: }
422:
423: /**
424: * This enum will be removed in 3.0.
425: *
426: * @deprecated use {@link org.glassfish.grizzly.CloseType}
427: */
428: @Deprecated
429: enum CloseType implements ICloseType {
430: LOCALLY, REMOTELY
431: }
432:
433: }