KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sapia > ubik > net > nio > Cycle


1 package org.sapia.ubik.net.nio;
2
3 import java.nio.ByteBuffer JavaDoc;
4 import java.nio.channels.Channel JavaDoc;
5
6 /**
7  * This interface models a cycle in a client-server communication. It specifies
8  * various states (in the form of constants) that represents the actual states
9  * in which an instance of this interface can be.
10  * <p>
11  * From a server point of view, a cycle goes as follows: first, the request is
12  * read; then, some processing occurs; finally, a response is written and the
13  * communication is over (in the case of stateless servers) or it resumes (to a
14  * read) in the context of stateful servers.
15  * <p>
16  * In which state an instance of this interface starts depends on the underlying
17  * framework (client or server). Then, the instance's state is later on
18  * determined by <code>ChannelHandler</code> s - a channel handler calls the
19  * <code>state(int)</code> method on an instance of this class to set the
20  * "next" state in which the instance will be.
21  *
22  * @author Yanick Duchesne
23  *
24  * <dl>
25  * <dt><b>Copyright: </b>
26  * <dd>Copyright &#169; 2002-2005 <a HREF="http://www.sapia-oss.org">Sapia Open
27  * Source Software </a>. All Rights Reserved.</dd>
28  * </dt>
29  * <dt><b>License: </b>
30  * <dd>Read the license.txt file of the jar or visit the <a
31  * HREF="http://www.sapia-oss.org/license.html">license page </a> at the Sapia
32  * OSS web site</dd>
33  * </dt>
34  * </dl>
35  */
36 public interface Cycle {
37
38   /**
39    * This constant's value is used to indicate the "read" state.
40    */
41   public static final int STATE_READ = 0;
42
43   /**
44    * This constant's value is used to indicate the "write" state.
45    */
46   public static final int STATE_WRITE = 1;
47
48   /**
49    * This constant's value is used to indicate the "process" state.
50    */
51   public static final int STATE_PROCESS = 2;
52
53   /**
54    * This constant's value is used to indicate the "recycle" state.
55    */
56   public static final int STATE_RECYCLE = 3;
57
58   /**
59    * This constant's value is used to indicate the "complete" state.
60    */
61   public static final int STATE_COMPLETE = 4;
62
63   /**
64    * This constant's value is used to indicate the "error" state.
65    */
66   public static final int STATE_ERROR = 5;
67
68   /**
69    * @return the identifier of the current state of this instance.
70    *
71    * @see #STATE_READ
72    * @see #STATE_WRITE
73    * @see #STATE_PROCESS
74    * @see #STATE_RECYCLE
75    */
76   public int state();
77
78   /**
79    * Sets the next state that this instance should be in.
80    *
81    * @param nextState
82    * the next state.
83    *
84    * @see #STATE_READ
85    * @see #STATE_WRITE
86    * @see #STATE_PROCESS
87    * @see #STATE_RECYCLE
88    */
89   public void state(int nextState);
90
91   /**
92    * This method is used to signal an error. This cycle will thereafter be
93    * aborted.
94    *
95    * @param err
96    * a <code>Throwable</code>.
97    *
98    * @see #STATE_ERROR
99    * @see #getError()
100    * @see #isError()
101    */
102   public void error(Throwable JavaDoc err);
103
104   /**
105    * Triggers the asynchronous execution of the next state.
106    * <p>
107    * This method should not be called by applications.
108    */
109   public void next();
110
111   /**
112    * @return <code>true</code> if this instance is in "read" state.
113    */
114   public boolean isRead();
115
116   /**
117    * @return <code>true</code> if this instance is in "write" state.
118    */
119   public boolean isWrite();
120
121   /**
122    * @return <code>true</code> if the read/write (or write/read) is completed.
123    */
124   public boolean isComplete();
125
126   /**
127    * @return <code>true</code> if this instance is in "process" state.
128    */
129   public boolean isProcess();
130
131   /**
132    * @return <code>true</code> if this instance is in "recycle" state.
133    */
134   public boolean isRecycle();
135
136   /**
137    * @return <code>true</code> if this instance has an error.
138    */
139   public boolean isError();
140
141   /**
142    * @return the <code>Throwable</code> instance corresponding to the error
143    * that this instance holds.
144    */
145   public Throwable JavaDoc getError();
146
147   /**
148    * @return the <code>ByteBuffer</code> that this instance holds.
149    */
150   public ByteBuffer JavaDoc getByteBuffer();
151
152   /**
153    * releases the byte buffer that this instance holds.
154    */
155   public void releaseByteBuffer();
156
157   /**
158    * @return the <code>Channel</code> that this instance holds.
159    */
160   public Channel JavaDoc getChannel();
161
162   /**
163    * @return the <code>ChannelHandler</code> that handles this instance.
164    */
165   public ChannelHandler getHandler();
166
167   /**
168    * @return the <code>ChannelManager</code> to which this instance
169    * corresponds.
170    */
171   public ChannelManager getChannelManager();
172
173   /**
174    * Releases all system resources that this instance holds. This method should
175    * not be called by applications.
176    *
177    */
178   public void destroy();
179
180 }
181
Popular Tags