Connection


1   /**
2    * $RCSfile: Connection.java,v $
3    * $Revision: 1.12 $
4    * $Date: 2005/05/23 18:00:38 $
5    *
6    * Copyright (C) 2004 Jive Software. All rights reserved.
7    *
8    * This software is published under the terms of the GNU Public License (GPL),
9    * a copy of which is included in this distribution.
10   */
11  
12  package org.jivesoftware.messenger;
13  
14  import org.xmpp.packet.Packet;
15  import org.jivesoftware.messenger.auth.UnauthorizedException;
16  
17  import java.net.InetAddress  ;
18  import java.net.UnknownHostException  ;
19  import java.io.Writer  ;
20  
21  /**
22   * Represents a connection on the server.
23   *
24   * @author Iain Shigeoka
25   */
26  public interface Connection {
27  
28      /**
29       * Verifies that the connection is still live. Typically this is done by
30       * sending a whitespace character between packets.
31       *
32       * @return true if the socket remains valid, false otherwise.
33       */
34      public boolean validate();
35  
36      /**
37       * Initializes the connection with it's owning session. Allows the
38       * connection class to configure itself with session related information
39       * (e.g. stream ID).
40       *
41       * @param session the session that owns this connection
42       */
43      public void init(Session session);
44  
45      /**
46       * Returns the InetAddress describing the connection.
47       *
48       * @return the InetAddress describing the underlying connection properties.
49       */
50      public InetAddress   getInetAddress() throws UnknownHostException  ;
51  
52       /**
53        * Returns the Writer used to send data to the connection. The writer should be
54        * used with caution. In the majority of cases, the {@link #deliver(Packet)}
55        * method should be used to send data instead of using the writer directly.
56        * You must synchronize on the writer before writing data to it to ensure
57        * data consistency:
58        *
59        * <pre>
60        * Writer writer = connection.getWriter();
61        * synchronized(writer) {
62        *     // write data....
63        * }</pre>
64        *
65        * @return the Writer for this connection.
66        */
67      public Writer   getWriter();
68  
69      /**
70       * Close this session including associated socket connection. The order of
71       * events for closing the session is:
72       * <ul>
73       *      <li>Set closing flag to prevent redundant shutdowns.
74       *      <li>Call notifyEvent all listeners that the channel is shutting down.
75       *      <li>Close the socket.
76       * </ul>
77       */
78      public void close();
79  
80      /**
81       * Returns true if the connection/session is closed.
82       *
83       * @return true if the connection is closed.
84       */
85      public boolean isClosed();
86  
87      /**
88       * Returns true if this connection is secure.
89       *
90       * @return true if the connection is secure (e.g. SSL/TLS)
91       */
92      public boolean isSecure();
93  
94      /**
95       * Registers a listener for close event notification. Registrations after
96       * the Session is closed will be immediately notified <em>before</em>
97       * the registration call returns (within the context of the
98       * registration call). An optional handback object can be associated with
99       * the registration if the same listener is registered to listen for multiple
100      * connection closures.
101      *
102      * @param listener the listener to register for events.
103      * @param handbackMessage the object to send in the event notification.
104      * @return the message previously registered for this channel or <tt>null</tt>
105      *      if no registration existed
106      */
107     public Object   registerCloseListener(ConnectionCloseListener listener, Object   handbackMessage);
108 
109     /**
110      * Removes a registered close event listener. Registered listeners must
111      * be able to receive close events up until the time this method returns.
112      * (i.e. it is possible to call unregister, receive a close event registration,
113      * and then have the unregister call return.)
114      *
115      * @param listener the listener to deregister for close events.
116      * @return the Message registered with this listener or <tt>null</tt> if the
117      *      channel was never registered.
118      */
119     public Object   removeCloseListener(ConnectionCloseListener listener);
120 
121     /**
122      * Delivers the packet to this connection without checking the recipient.
123      * The method essentially calls <code>socket.send(packet.getWriteBuffer())</code>.
124      *
125      * @param packet the packet to deliver.
126      */
127     public void deliver(Packet packet) throws UnauthorizedException;
128 
129     /**
130      * Delivers raw text to this connection. This is a very low level way for sending
131      * XML stanzas to the client. This method should not be used unless you have very
132      * good reasons for not using {@link #deliver(org.xmpp.packet.Packet)}.<p>
133      *
134      * This method avoids having to get the writer of this connection and mess directly
135      * with the writer. Therefore, this method ensures a correct delivery of the stanza
136      * even if other threads were sending data concurrently.
137      *
138      * @param text the XML stanzas represented kept in a String.
139      */
140     public void deliverRawText(String   text);
141 
142     /**
143      * Returns true if the connected client is a flash client. Flash clients need
144      * to receive a special character (i.e. \0) at the end of each xml packet. Flash
145      * clients may send the character \0 in incoming packets and may start a connection
146      * using another openning tag such as: "flash:client".
147      *
148      * @return true if the connected client is a flash client.
149      */
150     public boolean isFlashClient();
151 
152     /**
153      * Returns the major version of XMPP being used by this connection
154      * (major_version.minor_version. In most cases, the version should be
155      * "1.0". However, older clients using the "Jabber" protocol do not set a
156      * version. In that case, the version is "0.0".
157      *
158      * @return the major XMPP version being used by this connection.
159      */
160     public int getMajorXMPPVersion();
161 
162     /**
163      * Returns the minor version of XMPP being used by this connection
164      * (major_version.minor_version. In most cases, the version should be
165      * "1.0". However, older clients using the "Jabber" protocol do not set a
166      * version. In that case, the version is "0.0".
167      *
168      * @return the minor XMPP version being used by this connection.
169      */
170     public int getMinorXMPPVersion();
171 
172     /**
173      * Returns the language code that should be used for this connection
174      * (e.g. "en").
175      *
176      * @return the language code for the connection.
177      */
178     public String   getLanguage();
179 }
180
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags