View Javadoc

1   /*
2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3    *
4    * Copyright (c) 2007-2010 Oracle and/or its affiliates. All rights reserved.
5    *
6    * The contents of this file are subject to the terms of either the GNU
7    * General Public License Version 2 only ("GPL") or the Common Development
8    * and Distribution License("CDDL") (collectively, the "License").  You
9    * may not use this file except in compliance with the License.  You can
10   * obtain a copy of the License at
11   * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
12   * or packager/legal/LICENSE.txt.  See the License for the specific
13   * language governing permissions and limitations under the License.
14   *
15   * When distributing the software, include this License Header Notice in each
16   * file and include the License file at packager/legal/LICENSE.txt.
17   *
18   * GPL Classpath Exception:
19   * Oracle designates this particular file as subject to the "Classpath"
20   * exception as provided by Oracle in the GPL Version 2 section of the License
21   * file that accompanied this code.
22   *
23   * Modifications:
24   * If applicable, add the following below the License Header, with the fields
25   * enclosed by brackets [] replaced by your own identifying information:
26   * "Portions Copyright [year] [name of copyright owner]"
27   *
28   * Contributor(s):
29   * If you wish your version of this file to be governed by only the CDDL or
30   * only the GPL Version 2, indicate your decision by adding "[Contributor]
31   * elects to include this software in this distribution under the [CDDL or GPL
32   * Version 2] license."  If you don't indicate a single choice of license, a
33   * recipient has the option to distribute your version of this file under
34   * either the CDDL, the GPL Version 2 or to extend the choice of license to
35   * its licensees as provided above.  However, if you add GPL Version 2 code
36   * and therefore, elected the GPL Version 2 license, then the option applies
37   * only if the new code is made subject to such option by the copyright
38   * holder.
39   */
40  
41  package com.sun.grizzly.async;
42  
43  import java.io.IOException;
44  import java.net.SocketAddress;
45  import java.nio.ByteBuffer;
46  import java.util.concurrent.Future;
47  
48  /**
49   * Object, which is able to send {@link ByteBuffer} data asynchronously,
50   * using queue.
51   * 
52   * @author Alexey Stashok
53   */
54  public interface AsyncQueueWritable {
55      /**
56       * Method writes {@link ByteBuffer} using async write queue.
57       * First, if write queue is empty - it tries to write {@link ByteBuffer}
58       * directly (without putting to the queue).
59       * If associated write queue is not empty or after direct writing 
60       * {@link ByteBuffer} still has ready data to be written - 
61       * {@link ByteBuffer} will be added to {@link AsyncQueue}.
62       * If an exception occurs, during direct writing - it will be propagated 
63       * to the caller directly, otherwise it will be just logged by 
64       * Grizzly framework.
65       * 
66       * @param buffer {@link ByteBuffer}
67       * @throws java.io.IOException
68       */
69      public Future<AsyncQueueWriteUnit> writeToAsyncQueue(ByteBuffer buffer)
70              throws IOException;
71      
72      /**
73       * Method writes {@link ByteBuffer} using async write queue.
74       * First, if write queue is empty - it tries to write {@link ByteBuffer}
75       * directly (without putting to the queue).
76       * If associated write queue is not empty or after direct writing 
77       * {@link ByteBuffer} still has ready data to be written - 
78       * {@link ByteBuffer} will be added to {@link AsyncQueue}.
79       * If an exception occurs, during direct writing - it will be propagated 
80       * to the caller directly, otherwise, if the {@link ByteBuffer} is 
81       * added to a writing queue - exception notification will come via 
82       * <code>AsyncWriteCallbackHandler.onIOException()</code>
83       * 
84       * @param buffer {@link ByteBuffer}
85       * @param callbackHandler {@link AsyncWriteCallbackHandler}, 
86       *                        which will get notified, when 
87       *                        {@link ByteBuffer} will be completely written
88       * @throws java.io.IOException
89       */
90      public Future<AsyncQueueWriteUnit> writeToAsyncQueue(ByteBuffer buffer,
91              AsyncWriteCallbackHandler callbackHandler) throws IOException;
92  
93      /**
94       * Method writes {@link ByteBuffer} using async write queue.
95       * First, if write queue is empty - it tries to write {@link ByteBuffer}
96       * directly (without putting to the queue).
97       * If associated write queue is not empty or after direct writing 
98       * {@link ByteBuffer} still has ready data to be written - 
99       * {@link ByteBuffer} will be added to {@link AsyncQueue}.
100      * If an exception occurs, during direct writing - it will be propagated 
101      * to the caller directly, otherwise, if the {@link ByteBuffer} is 
102      * added to a writing queue - exception notification will come via 
103      * <code>AsyncWriteCallbackHandler.onIOException()</code>
104      * Before data will be written on {@link SelectableChannel}, first it
105      * will be passed for preprocessing to <code>AsyncQueueDataProcessor</code>,
106      * and then preprocessor result data 
107      * (<code>AsyncQueueDataProcessor.getResultByteBuffer()</code>) will be 
108      * written on the {@link SelectableChannel}.
109      * 
110      * @param buffer {@link ByteBuffer}
111      * @param callbackHandler {@link AsyncWriteCallbackHandler}, 
112      *                        which will get notified, when 
113      *                        {@link ByteBuffer} will be completely written
114      * @param writePreProcessor <code>AsyncQueueDataProcessor</code>, which
115      *                        will perform data processing, before it will be 
116      *                        written on {@link SelectableChannel}
117      * @throws java.io.IOException
118      */
119     public Future<AsyncQueueWriteUnit> writeToAsyncQueue(ByteBuffer buffer,
120             AsyncWriteCallbackHandler callbackHandler,
121             AsyncQueueDataProcessor writePreProcessor) throws IOException;
122 
123     /**
124      * Method writes {@link ByteBuffer} using async write queue.
125      * First, if write queue is empty - it tries to write {@link ByteBuffer}
126      * directly (without putting to the queue).
127      * If associated write queue is not empty or after direct writing 
128      * {@link ByteBuffer} still has ready data to be written - 
129      * {@link ByteBuffer} will be added to {@link AsyncQueue}.
130      * If an exception occurs, during direct writing - it will be propagated 
131      * to the caller directly, otherwise, if the {@link ByteBuffer} is 
132      * added to a writing queue - exception notification will come via 
133      * <code>AsyncWriteCallbackHandler.onIOException()</code>
134      * Before data will be written on {@link SelectableChannel}, first it
135      * will be passed for preprocessing to <code>AsyncQueueDataProcessor</code>,
136      * and then preprocessor result data 
137      * (<code>AsyncQueueDataProcessor.getResultByteBuffer()</code>) will be 
138      * written on the {@link SelectableChannel}.
139      * 
140      * @param buffer {@link ByteBuffer}
141      * @param callbackHandler {@link AsyncWriteCallbackHandler}, 
142      *                        which will get notified, when 
143      *                        {@link ByteBuffer} will be completely written
144      * @param writePreProcessor <code>AsyncQueueDataProcessor</code>, which
145      *                        will perform data processing, before it will be 
146      *                        written on {@link SelectableChannel}
147      * @param isCloneByteBuffer if true - {@link AsyncQueueWriter} 
148      *                          will clone given
149      *                          {@link ByteBuffer} before puting it to the 
150      *                          {@link AsyncQueue}
151      * @throws java.io.IOException
152      */
153     public Future<AsyncQueueWriteUnit> writeToAsyncQueue(ByteBuffer buffer,
154             AsyncWriteCallbackHandler callbackHandler, 
155             AsyncQueueDataProcessor writePreProcessor,
156             ByteBufferCloner cloner) throws IOException;
157 
158     /**
159      * Method sends {@link ByteBuffer} using async write queue.
160      * First, if write queue is empty - it tries to send {@link ByteBuffer}
161      * to the given {@link SocketAddress} directly 
162      * (without putting to the queue).
163      * If associated write queue is not empty or after direct sending 
164      * {@link ByteBuffer} still has ready data to be written - 
165      * {@link ByteBuffer} will be added to {@link AsyncQueue}.
166      * If an exception occurs, during direct writing - it will be propagated 
167      * to the caller directly, otherwise it will be just logged by 
168      * Grizzly framework.
169      * 
170      * @param dstAddress destination {@link SocketAddress} data will 
171      *                   be sent to
172      * @param buffer {@link ByteBuffer}
173      * @throws java.io.IOException
174      */
175     public Future<AsyncQueueWriteUnit> writeToAsyncQueue(
176             SocketAddress dstAddress, ByteBuffer buffer) throws IOException;
177     
178     /**
179      * Method sends {@link ByteBuffer} using async write queue.
180      * First, if write queue is empty - it tries to send {@link ByteBuffer}
181      * to the given {@link SocketAddress} directly 
182      * (without putting to the queue).
183      * If associated write queue is not empty or after direct sending 
184      * {@link ByteBuffer} still has ready data to be written - 
185      * {@link ByteBuffer} will be added to {@link AsyncQueue}.
186      * If an exception occurs, during direct writing - it will be propagated 
187      * to the caller directly, otherwise, if the {@link ByteBuffer} is 
188      * added to a writing queue - exception notification will come via 
189      * <code>AsyncWriteCallbackHandler.onIOException()</code>
190      * 
191      * @param dstAddress destination {@link SocketAddress} data will 
192      *                   be sent to
193      * @param buffer {@link ByteBuffer}
194      * @param callbackHandler {@link AsyncWriteCallbackHandler}, 
195      *                        which will get notified, when 
196      *                        {@link ByteBuffer} will be completely written
197      * @throws java.io.IOException
198      */
199     public Future<AsyncQueueWriteUnit> writeToAsyncQueue(
200             SocketAddress dstAddress, ByteBuffer buffer,
201             AsyncWriteCallbackHandler callbackHandler) throws IOException;
202 
203     /**
204      * Method sends {@link ByteBuffer} using async write queue.
205      * First, if write queue is empty - it tries to send {@link ByteBuffer}
206      * to the given {@link SocketAddress} directly 
207      * (without putting to the queue).
208      * If associated write queue is not empty or after direct sending 
209      * {@link ByteBuffer} still has ready data to be written - 
210      * {@link ByteBuffer} will be added to {@link AsyncQueue}.
211      * If an exception occurs, during direct writing - it will be propagated 
212      * to the caller directly, otherwise, if the {@link ByteBuffer} is 
213      * added to a writing queue - exception notification will come via 
214      * <code>AsyncWriteCallbackHandler.onIOException()</code>
215      * Before data will be written on {@link SelectableChannel}, first it
216      * will be passed for preprocessing to <code>AsyncQueueDataProcessor</code>,
217      * and then preprocessor result data 
218      * (<code>AsyncQueueDataProcessor.getResultByteBuffer()</code>) will be 
219      * written on the {@link SelectableChannel}.
220      * 
221      * @param dstAddress destination {@link SocketAddress} data will 
222      *                   be sent to
223      * @param buffer {@link ByteBuffer}
224      * @param callbackHandler {@link AsyncWriteCallbackHandler}, 
225      *                        which will get notified, when 
226      *                        {@link ByteBuffer} will be completely written
227      * @param writePreProcessor <code>AsyncQueueDataProcessor</code>, which
228      *                        will perform data processing, before it will be 
229      *                        written on {@link SelectableChannel}
230      * @throws java.io.IOException
231      */
232     public Future<AsyncQueueWriteUnit> writeToAsyncQueue(
233             SocketAddress dstAddress, ByteBuffer buffer,
234             AsyncWriteCallbackHandler callbackHandler,
235             AsyncQueueDataProcessor writePreProcessor) throws IOException;
236 
237     /**
238      * Method sends {@link ByteBuffer} using async write queue.
239      * First, if write queue is empty - it tries to send {@link ByteBuffer}
240      * to the given {@link SocketAddress} directly 
241      * (without putting to the queue).
242      * If associated write queue is not empty or after direct sending 
243      * {@link ByteBuffer} still has ready data to be written - 
244      * {@link ByteBuffer} will be added to {@link AsyncQueue}.
245      * If an exception occurs, during direct writing - it will be propagated 
246      * to the caller directly, otherwise, if the {@link ByteBuffer} is 
247      * added to a writing queue - exception notification will come via 
248      * <code>AsyncWriteCallbackHandler.onIOException()</code>
249      * Before data will be written on {@link SelectableChannel}, first it
250      * will be passed for preprocessing to <code>AsyncQueueDataProcessor</code>,
251      * and then preprocessor result data 
252      * (<code>AsyncQueueDataProcessor.getResultByteBuffer()</code>) will be 
253      * written on the {@link SelectableChannel}.
254      * 
255      * @param dstAddress destination {@link SocketAddress} data will 
256      *                   be sent to
257      * @param buffer {@link ByteBuffer}
258      * @param callbackHandler {@link AsyncWriteCallbackHandler}, 
259      *                        which will get notified, when 
260      *                        {@link ByteBuffer} will be completely written
261      * @param writePreProcessor <code>AsyncQueueDataProcessor</code>, which
262      *                        will perform data processing, before it will be 
263      *                        written on {@link SelectableChannel}
264      * @param isCloneByteBuffer if true - {@link AsyncQueueWriter} 
265      *                          will clone given
266      *                          {@link ByteBuffer} before puting it to the 
267      *                          {@link AsyncQueue}
268      * @throws java.io.IOException
269      */
270     public Future<AsyncQueueWriteUnit> writeToAsyncQueue(
271             SocketAddress dstAddress, ByteBuffer buffer,
272             AsyncWriteCallbackHandler callbackHandler, 
273             AsyncQueueDataProcessor writePreProcessor,
274             ByteBufferCloner cloner) throws IOException;
275 }