ClientHandler


1   /*
2    * This file is part of the QuickServer library 
3    * Copyright (C) 2003-2005 QuickServer.org
4    *
5    * Use, modification, copying and distribution of this software is subject to
6    * the terms and conditions of the GNU Lesser General Public License. 
7    * You should have received a copy of the GNU LGP License along with this 
8    * library; if not, you can download a copy from <http://www.quickserver.org/>.
9    *
10   * For questions, suggestions, bug-reports, enhancement-requests etc.
11   * visit http://www.quickserver.org
12   *
13   */
14  
15  package org.quickserver.net.server;
16  
17  import java.io.BufferedInputStream  ;
18  import java.io.BufferedOutputStream  ;
19  import java.io.BufferedReader  ;
20  import java.io.BufferedWriter  ;
21  import java.io.IOException  ;
22  import java.io.InputStream  ;
23  import java.io.ObjectInputStream  ;
24  import java.io.ObjectOutputStream  ;
25  import java.io.OutputStream  ;
26  import java.io.OutputStreamWriter  ;
27  import java.net.InetAddress  ;
28  import java.net.Socket  ;
29  import java.net.SocketException  ;
30  import java.nio.channels.ClosedChannelException  ;
31  import java.nio.channels.SelectionKey  ;
32  import java.nio.channels.SocketChannel  ;
33  import java.security.KeyManagementException  ;
34  import java.security.NoSuchAlgorithmException  ;
35  import java.sql.Connection  ;
36  import java.util.Date  ;
37  import java.util.logging.Level  ;
38  import java.util.logging.Logger  ;
39  import javax.net.ssl.SSLSocket;
40  import org.quickserver.util.MyString;
41  
42  /**
43   * Interface that represents client handle in QuickServer.
44   * <p> This class is used by {@link QuickServer} to handle each new client 
45   * connected. This class is responsible to handle client sockets. It can operate 
46   * in both blocking mode and non-blocking mode (java nio) based on its
47   * implementation.</p>
48   * @author Akshathkumar Shetty
49   */
50  public interface ClientHandler extends Runnable   {
51  
52      /** 
53       * Adds the ClientEvent. 
54       * @since 1.4.5
55       */
56      void addEvent(ClientEvent event);
57  
58      /** 
59       * Removes the ClientEvent. 
60       * @since 1.4.5
61       */
62      void removeEvent(ClientEvent event);
63  
64      void clean();
65  
66      /** Closes client socket associated. */
67      void closeConnection();
68  
69      /**
70       * Force the closing of the client by closing the associated socket.
71       * @since 1.3.3
72       */
73      void forceClose() throws IOException  ;
74  
75      /** 
76       * Returns client SelectionKey associated, if any. 
77       * @since 1.4.5
78       */
79      Logger   getAppLogger();
80  
81      /**
82       *Returns the {@link java.io.BufferedInputStream} associated with 
83       * the Client being handled. Can be null if not available at the time of method call. 
84       * @see #getBufferedOutputStream
85       * @since 1.4.6
86       */
87      BufferedInputStream   getBufferedInputStream();
88  
89      /**
90       * Returns the {@link java.io.BufferedOutputStream} associated with 
91       * the Client being handled. Can be null if not available at the time of method call. 
92       * @see #getBufferedInputStream
93       * @since 1.4.6
94       */
95      BufferedOutputStream   getBufferedOutputStream();
96  
97      /**
98       * Returns the {@link java.io.BufferedReader} associated with 
99       * the Client being handled. Note that this is only available under blocking mode. 
100      * @see #getBufferedWriter
101      */
102     BufferedReader   getBufferedReader();
103 
104 
105     /**
106      * Returns Charset to be used for String decoding and encoding..
107      * @see #setCharset
108      * @since 1.4.5
109      */
110     String   getCharset();
111 
112     /**
113      * Returns the date/time when the client socket was assigned to this
114      * ClientHanlder. If no client is currently connected it will return
115      * <code>null</code>
116      * @since 1.3.1
117      */
118     Date   getClientConnectedTime();
119 
120     /**
121      * Returns the ClientData object associated with this ClientHandler, 
122      * if not set will return <code>null</code>
123      * @see ClientData
124      */
125     ClientData getClientData();
126 
127     /**
128      * Returns the communication logging flag.
129      * @see #setCommunicationLogging
130      * @since 1.3.2
131      */
132     boolean getCommunicationLogging();
133 
134     /**
135      * Returns the {@link DataMode} of the ClientHandler for the 
136      * DataType.
137      * @since 1.2
138      */
139     DataMode getDataMode(DataType dataType);
140 
141     /**
142      * Returns cached socket host ip address.
143      * @since 1.4.5
144      */
145     String   getHostAddress();
146 
147     /**
148      * Returns the {@link java.io.InputStream} associated with 
149      * the Client being handled.
150      */
151     InputStream   getInputStream();
152 
153     /**
154      * Returns the date/time when the client socket last sent a data to this
155      * ClientHanlder. If no client is currently connected it will return
156      * <code>null</code>
157      * @since 1.3.3
158      */
159     Date   getLastCommunicationTime();
160 
161     /**
162      * Returns message to be displayed to the client when maximum 
163      * connection reaches.
164      * @since 1.4.5
165      */
166     String   getMaxConnectionMsg();
167 
168     /**
169      * Returns the ClientHandler name
170      * @since 1.4.6
171      */
172     String   getName();
173 
174     /**
175      * Returns the {@link java.io.ObjectInputStream} associated with 
176      * the Client being handled.
177      * It will be <code>null</code> if no {@link ClientObjectHandler} 
178      * was set in {@link QuickServer}.
179      * @see #getObjectOutputStream
180      * @since 1.2
181      */
182     ObjectInputStream   getObjectInputStream();
183 
184     /**
185      * Returns the {@link java.io.ObjectOutputStream} associated with 
186      * the Client being handled.
187      * It will be <code>null</code> if no {@link ClientObjectHandler} 
188      * was set in {@link QuickServer}.
189      * @see #getObjectInputStream
190      * @since 1.2
191      */
192     ObjectOutputStream   getObjectOutputStream();
193 
194     /**
195      * Returns the {@link java.io.OutputStream} associated with 
196      * the Client being handled.
197      * @see #setOutputStream
198      */
199     OutputStream   getOutputStream();
200 
201     /** 
202      * Returns client SelectionKey associated, if any. 
203      * @since 1.4.5
204      */
205     SelectionKey   getSelectionKey();
206 
207     /**
208      * Returns the QuickServer object that created it.
209      */
210     QuickServer getServer();
211 
212     /** Returns client socket associated. */
213     Socket   getSocket();
214 
215     /** 
216      * Returns client socket channel associated, if any. 
217      * @since 1.4.5
218      */
219     SocketChannel   getSocketChannel();
220 
221     /**
222      * Returns the Client socket timeout in milliseconds.
223      * @see #setTimeout
224      * @since 1.4.5
225      */
226     int getTimeout();
227 
228     /**
229      * Associates the ClientHanlder with the client encapsulated by 
230      * <code>theClient</code>.
231      * @param theClient object that encapsulates client socket 
232      *  and its configuration details.
233      */
234     void handleClient(TheClient theClient);
235 
236     /** 
237      * Checks if this client has the event. 
238      * @since 1.4.5
239      */
240     boolean hasEvent(ClientEvent event);
241 
242     /**
243      * Returns the ClientHandler detailed information.
244      * If ClientData is present and is ClientIdentifiable will return ClientInfo else
245      * it will return Clients InetAddress and port information.
246      */
247     String   info();
248 
249     /**
250      * Checks if the passed ClientEvent is the one next for 
251      * processing if a thread is allowed through this object.
252      * @since 1.4.6
253      */
254     boolean isClientEventNext(ClientEvent clientEvent);
255 
256     /**
257      * Checks if the client is closed.
258      * @since 1.4.1
259      */
260     boolean isClosed();
261   
262 
263     /**
264      * Checks if the client is still connected.
265      * @exception SocketException if Socket is not open.
266      * @since 1.4.5
267      */
268     boolean isConnected() throws SocketException  ;
269 
270     /**
271      * Checks if the client is still connected and if socket is open. This is same as isConnected() 
272      * but does not throw SocketException.
273      * @since 1.4.6
274      */
275     boolean isOpen();
276 
277     /**
278      * Returns flag indicating if the client is connected in secure mode 
279      * (SSL or TLS).
280      * @return secure flag
281      * @since 1.4.0
282      */
283     boolean isSecure();
284 
285     /**
286      * Makes current Client connection to secure protocol based on the 
287      * secure configuration set to the server. This method will just call 
288      * <code>makeSecure(false, false, true, null)</code>.
289      * @throws IOException
290      * @throws NoSuchAlgorithmException
291      * @throws KeyManagementException
292      * @since 1.4.0
293      */
294     void makeSecure() throws IOException  , NoSuchAlgorithmException  , KeyManagementException  ;
295 
296     /**
297      * Makes current Client connection to secure protocol.
298      * @param useClientMode falg if the socket should start its first handshake in "client" mode.
299      * @param needClientAuth flag if the clients must authenticate themselves.
300      * @param autoClose close the underlying socket when this socket is closed 
301      * @param protocol the standard name of the requested protocol. If <code>null</code> will use the protocol set in secure configuration of the server.
302      * @throws IOException
303      * @throws NoSuchAlgorithmException
304      * @throws KeyManagementException
305      * @since 1.4.0
306      */
307     void makeSecure(boolean useClientMode, boolean needClientAuth, boolean autoClose, String   protocol) throws IOException  , NoSuchAlgorithmException  , KeyManagementException  ;
308 
309     /**
310      * Makes current Client connection to secure protocol.
311      * This method will just call <code>makeSecure(false, false, true, protocol)</code>.
312      * @throws IOException
313      * @throws NoSuchAlgorithmException
314      * @throws KeyManagementException
315      * @since 1.4.0
316      */
317     void makeSecure(String   protocol) throws IOException  , NoSuchAlgorithmException  , KeyManagementException  ;
318 
319     /**
320      * Read the binary input. This will block till some data is
321      * received from the stream. Allowed only when 
322      * <code>DataType.IN</code> is in <code>DataMode.BINARY</code> mode.
323      * @return The data as a String
324      * @since 1.4
325      */
326     byte[] readBinary() throws IOException  ;
327 
328     /**
329      * Read the byte input. This will block till some data is
330      * received from the stream. Allowed only when 
331      * <code>DataType.IN</code> is in <code>DataMode.BYTE</code> mode.
332      * @return The data as a String
333      * @since 1.3.2
334      */
335     String   readBytes() throws IOException  ;
336 
337     /**
338      * Register OP_READ with the SelectionKey associated with the channel. If SelectionKey is
339      * not set then it registers the channel with the Selector.
340      * @since 1.4.5
341      */
342     void registerForRead() throws IOException  , ClosedChannelException  ;
343 
344     /**
345      * Register OP_WRITE with the SelectionKey associated with the channel.
346      * @since 1.4.5
347      */
348     void registerForWrite() throws IOException  , ClosedChannelException  ;
349 
350     void run();
351 
352     /**
353      * Send a binary data to the connected client.
354      * If client is not connected it will just return.
355      * @since 1.4
356      * @exception IOException
357      *        if Socket IO Error or Socket was closed by the client.
358      */
359     void sendClientBinary(byte[] data) throws IOException  ;
360 
361     /**
362      * Send a binary data to the connected client.
363      * If client is not connected it will just return.
364      * @since 1.4.5
365      * @exception IOException
366      *        if Socket IO Error or Socket was closed by the client.
367      */
368     void sendClientBinary(byte[] data, int off, int len) throws IOException  ;
369 
370     /**
371      * Send a String message to the connected client as a string of bytes.
372      * If client is not connected it will just return.
373      * @since 1.3.1
374      * @exception IOException
375      *        if Socket IO Error or Socket was closed by the client.
376      */
377     void sendClientBytes(String   msg) throws IOException  ;
378 
379     /**
380      * Send a String message to the connected client
381      * it adds a new line{\r\n} to the end of the string.
382      * If client is not connected it will just return.
383      * @exception IOException 
384      *        if Socket IO Error or Socket was closed by the client.
385      */
386     void sendClientMsg(String   msg) throws IOException  ;
387 
388     /**
389      * Send a Object message to the connected client. The message Object
390      * passed must be serializable. If client is not connected it 
391      * will just return.
392      * @exception IOException if Socket IO Error or Socket was closed 
393      * by the client.
394      * @exception IllegalStateException if DataType.OUT is not in 
395      *  DataMode.OBJECT
396      * @see #setDataMode
397      * @since 1.2
398      */
399     void sendClientObject(Object   msg) throws IOException  ;
400 
401     /**
402      * Send a String message to the logger associated with 
403      * {@link QuickServer#getAppLogger} with Level.INFO as its level.
404      */
405     void sendSystemMsg(String   msg);
406 
407     /**
408      * Send a String message to the logger associated with 
409      * {@link QuickServer#getAppLogger}.
410      * @since 1.2
411      */
412     void sendSystemMsg(String   msg, Level   level);
413 
414     /**
415      * Sets the Charset to be used for String decoding and encoding.
416      * @param charset to be used for String decoding and encoding
417      * @see #getCharset
418      * @since 1.4.5
419      */
420     void setCharset(String   charset);
421 
422     /**
423      * Sets the communication logging flag.
424      * @see #getCommunicationLogging
425      * @since 1.3.2
426      */
427     void setCommunicationLogging(boolean communicationLogging);
428 
429     /**
430      * Sets the {@link DataMode} for the ClientHandler
431      *
432      * Note: When mode is DataMode.OBJECT and type is DataType.IN
433      * this call will block until the client ObjectOutputStream has
434      * written and flushes the header.
435      * @since 1.2
436      * @exception IOException if mode could not be changed.
437      * @param dataMode mode of data exchange - String or Object.
438      * @param dataType type of data for which mode has to be set.
439      */
440     void setDataMode(DataMode dataMode, DataType dataType) throws IOException  ;
441 
442     /** 
443      * Sets message to be displayed when maximum connection reaches.
444      * @since 1.4.5
445      */
446     void setMaxConnectionMsg(String   msg);
447 
448     /**
449      * Set the {@link java.io.OutputStream} associated with 
450      * the Client being handled.
451      * @since 1.1
452      * @see #getOutputStream
453      * @exception IOException if ObjectOutputStream could not be created.
454      */
455     void setOutputStream(OutputStream   out) throws IOException  ;
456 
457     /**
458      * Sets flag indicating if the client is connected in secure mode 
459      * (SSL or TLS).
460      * @param secure
461      * @since 1.4.0
462      */
463     void setSecure(boolean secure);
464 
465     /** 
466      * Sets client SelectionKey associated, if any. 
467      * @since 1.4.5
468      */
469     void setSelectionKey(SelectionKey   selectionKey);
470 
471     /** 
472      * Returns client socket associated. 
473      * @since 1.4.0
474      * @see #updateInputOutputStreams
475      */
476     void setSocket(Socket   socket);
477 
478     /** 
479      * Sets client socket channel associated, if any. 
480      * @since 1.4.5
481      */
482     void setSocketChannel(SocketChannel   socketChannel);
483 
484     /**
485      * Sets the client socket's timeout.
486      * @param time client socket timeout in milliseconds.
487      * @see #getTimeout
488      * @since 1.4.5
489      */
490     void setTimeout(int time);
491 
492     /**
493      * Returns the ClientHandler information.
494      * If ClientData is present and is ClientIdentifiable will return ClientInfo else
495      * it will return Clients InetAddress and port information.
496      */
497     String   toString();
498 
499     /**
500      * Updates the InputStream and OutputStream for the ClientHandler for the 
501      * set Socket.
502      * @since 1.4.0
503      * @see #setSocket
504      */
505     void updateInputOutputStreams() throws IOException  ;
506 
507     /**
508      * Updates the last communication time for this client
509      * @since 1.3.3
510      */
511     void updateLastCommunicationTime();
512 
513     /**
514      * Returns the {@link java.sql.Connection} object for the 
515      * DatabaseConnection that is identified by id passed. If id passed
516      * does not match with any connection loaded by this class it will
517      * return <code>null</code>.
518      * This just calls <code>getServer().getDBPoolUtil().getConnection(id)</code>
519      * @since 1.3
520      * @deprecated as of v1.4.5 use <code>getServer().getDBPoolUtil().getConnection(id)</code>
521      */
522     Connection   getConnection(String   id) throws Exception  ;
523 
524      /**
525      * Checks if the client is still connected.
526      * @exception SocketException if Socket is not open.
527      * @deprecated since 1.4.5 Use {@link #isConnected}
528      */
529     boolean isConected() throws SocketException  ;
530 
531      /**
532      * Send a String message to the system output stream.
533      * @param newline indicates if new line required at the end.
534      * @deprecated Use {@link #sendSystemMsg(java.lang.String)}, 
535      *   since it uses Logging.
536      */
537     void sendSystemMsg(String   msg, boolean newline);
538 
539      /**
540      * Returns the {@link java.io.BufferedWriter} associated with 
541      * the Client being handled.
542      * @deprecated since 1.4.5 use getOutputStream()
543      */
544     BufferedWriter   getBufferedWriter();
545 }
546
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags