KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ubermq > kernel > IDatagramFactory


1 package com.ubermq.kernel;
2
3 import java.nio.*;
4
5 /**
6  * The interface for the factory object responsible for interpreting
7  * a sequence of bytes and producing a datagram from it. <P>
8  *
9  * There are two parts to this process:<P>
10  * 1. framing <br>
11  * 2. processing <br>
12  * <P>
13  *
14  * Framing entails examining the existing buffer, which may be incomplete,
15  * accepting or rejecting the data buffer,
16  * determining how many bytes need to be read, if any, and returning this
17  * meta information to the I/O thread.
18  *<P>
19  * Processing involves actually processing bytes and creating a Datagram
20  * object from those bytes.
21  * <P>
22  * The factory also is charged with producing the outgoing datagram
23  * footprint. This is a two-step process:<br>
24  * 1. pre output frame<br>
25  * 2. finalize frame<br>
26  * <P>
27  * Output is done in two phases so the header can be data-dependent, or include
28  * the length (as is commonly done).
29  * <P>
30  * This is the core interface to implement if you are interested in modifying
31  * the wire format of UberMQ JMS messages.<P>
32  */
33 public interface IDatagramFactory
34 {
35     /**
36      * Reads and processes bytes from a buffer and produces an instance
37      * of IDatagram that can be passed to datagram processing logic.
38      * <P>
39      * The byte buffer that is passed into this method is a subset
40      * of the buffer passed into the frame() method call immediately preceding,
41      * and the buffer begins with the header information that may have been
42      * processed by frame.
43      * <P>
44      * @param bb a byte buffer with the position set to zero and the
45      * limit set to the number of bytes in the buffer,
46      * @return the datagram object encoded in the byte stream
47      * @throws IllegalArgumentException if the byte buffer does not contain
48      * a valid datagram.
49      */
50     public IDatagram incoming(ByteBuffer bb)
51         throws IllegalArgumentException JavaDoc;
52     
53     /**
54      * Provides information to the I/O processing thread about a
55      * raw incoming data stream. The byte buffer passed as a parameter
56      * could potentially be the actual read buffer owned by the I/O thread.
57      * It is critical that this method not change the limit, or
58      * capacity of the buffer. <P>
59      *
60      * when this method returns, the byte buffer's position should be set to the
61      * origin of the next datagram. the frame logic is allowed to skip arbitrary
62      * bytes in the input stream that are deemed invalid or extraneous.
63      *
64      * the caller of this method will call incoming() with an appropriate, well-formed
65      * byte buffer when <code>length</code> bytes are available starting at
66      * the position set when this call returns.
67      *
68      * @return int the length of the datagram, in terms of the buffer passed as a parameter.
69      * If this value is greater than the number of bytes remaining in the buffer,
70      * or is equal to Integer.MAX_VALUE, a valid datagram is assumed not to exist
71      * in the remaining byte stream.
72      * @throws IOException if the buffer is hopelessly unintelligible
73      * and the connection/buffer should be terminated.
74      */
75     public int frame(ByteBuffer bb)
76         throws java.io.IOException JavaDoc;
77     
78     /**
79      * Outputs a datagram to the specified write buffer. The position of the
80      * write buffer should be zero on input. When the call returns, the position
81      * of the write buffer should be after the last byte of data to be
82      * output to the connection.
83      *<P>
84      * @param bb a byte buffer, with position 0 and limit equal to the maximum
85      * amount of data writeable in a single transaction.
86      * @param d the datagram that will be written to the buffer following this
87      * header.
88      */
89     public void outgoing(ByteBuffer bb, IDatagram d);
90     
91         
92 }
93
Popular Tags