001: /**
002: * $RCSfile: Connection.java,v $
003: * $Revision: 3187 $
004: * $Date: 2005-12-11 13:34:34 -0300 (Sun, 11 Dec 2005) $
005: *
006: * Copyright (C) 2007 Jive Software. All rights reserved.
007: *
008: * This software is published under the terms of the GNU Public License (GPL),
009: * a copy of which is included in this distribution.
010: */package org.jivesoftware.openfire;
011:
012: import org.jivesoftware.openfire.auth.UnauthorizedException;
013: import org.jivesoftware.openfire.session.LocalSession;
014: import org.xmpp.packet.Packet;
015:
016: import javax.net.ssl.SSLSession;
017: import java.net.UnknownHostException;
018:
019: /**
020: * Represents a connection on the server.
021: *
022: * @author Iain Shigeoka
023: */
024: public interface Connection {
025:
026: /**
027: * Verifies that the connection is still live. Typically this is done by
028: * sending a whitespace character between packets.
029: *
030: * @return true if the socket remains valid, false otherwise.
031: */
032: public boolean validate();
033:
034: /**
035: * Initializes the connection with it's owning session. Allows the
036: * connection class to configure itself with session related information
037: * (e.g. stream ID).
038: *
039: * @param session the session that owns this connection
040: */
041: public void init(LocalSession session);
042:
043: /**
044: * Returns the raw IP address of this <code>InetAddress</code>
045: * object. The result is in network byte order: the highest order
046: * byte of the address is in <code>getAddress()[0]</code>.
047: *
048: * @return the raw IP address of this object.
049: * @throws java.net.UnknownHostException if IP address of host could not be determined.
050: */
051: public byte[] getAddress() throws UnknownHostException;
052:
053: /**
054: * Returns the IP address string in textual presentation.
055: *
056: * @return the raw IP address in a string format.
057: * @throws java.net.UnknownHostException if IP address of host could not be determined.
058: */
059: public String getHostAddress() throws UnknownHostException;
060:
061: /**
062: * Gets the host name for this IP address.
063: *
064: * <p>If this InetAddress was created with a host name,
065: * this host name will be remembered and returned;
066: * otherwise, a reverse name lookup will be performed
067: * and the result will be returned based on the system
068: * configured name lookup service. If a lookup of the name service
069: * is required, call
070: * {@link java.net.InetAddress#getCanonicalHostName() getCanonicalHostName}.
071: *
072: * <p>If there is a security manager, its
073: * <code>checkConnect</code> method is first called
074: * with the hostname and <code>-1</code>
075: * as its arguments to see if the operation is allowed.
076: * If the operation is not allowed, it will return
077: * the textual representation of the IP address.
078: *
079: * @return the host name for this IP address, or if the operation
080: * is not allowed by the security check, the textual
081: * representation of the IP address.
082: * @throws java.net.UnknownHostException if IP address of host could not be determined.
083: *
084: * @see java.net.InetAddress#getCanonicalHostName
085: * @see SecurityManager#checkConnect
086: */
087: public String getHostName() throws UnknownHostException;
088:
089: /**
090: * Returns the underlying {@link SSLSession} for the connection.
091: *
092: * @return <tt>null</tt> if no {@link SSLSession} is initialized yet.
093: */
094: public SSLSession getSSLSession();
095:
096: /**
097: * Close this session including associated socket connection. The order of
098: * events for closing the session is:
099: * <ul>
100: * <li>Set closing flag to prevent redundant shutdowns.
101: * <li>Call notifyEvent all listeners that the channel is shutting down.
102: * <li>Close the socket.
103: * </ul>
104: */
105: public void close();
106:
107: /**
108: * Notification message indicating that the server is being shutdown. Implementors
109: * should send a stream error whose condition is system-shutdown before closing
110: * the connection.
111: */
112: public void systemShutdown();
113:
114: /**
115: * Returns true if the connection/session is closed.
116: *
117: * @return true if the connection is closed.
118: */
119: public boolean isClosed();
120:
121: /**
122: * Returns true if this connection is secure.
123: *
124: * @return true if the connection is secure (e.g. SSL/TLS)
125: */
126: public boolean isSecure();
127:
128: /**
129: * Registers a listener for close event notification. Registrations after
130: * the Session is closed will be immediately notified <em>before</em>
131: * the registration call returns (within the context of the
132: * registration call). An optional handback object can be associated with
133: * the registration if the same listener is registered to listen for multiple
134: * connection closures.
135: *
136: * @param listener the listener to register for events.
137: * @param handbackMessage the object to send in the event notification.
138: */
139: public void registerCloseListener(ConnectionCloseListener listener,
140: Object handbackMessage);
141:
142: /**
143: * Removes a registered close event listener. Registered listeners must
144: * be able to receive close events up until the time this method returns.
145: * (i.e. it is possible to call unregister, receive a close event registration,
146: * and then have the unregister call return.)
147: *
148: * @param listener the listener to deregister for close events.
149: */
150: public void removeCloseListener(ConnectionCloseListener listener);
151:
152: /**
153: * Delivers the packet to this connection without checking the recipient.
154: * The method essentially calls <code>socket.send(packet.getWriteBuffer())</code>.
155: *
156: * @param packet the packet to deliver.
157: * @throws org.jivesoftware.openfire.auth.UnauthorizedException if a permission error was detected.
158: */
159: public void deliver(Packet packet) throws UnauthorizedException;
160:
161: /**
162: * Delivers raw text to this connection. This is a very low level way for sending
163: * XML stanzas to the client. This method should not be used unless you have very
164: * good reasons for not using {@link #deliver(org.xmpp.packet.Packet)}.<p>
165: *
166: * This method avoids having to get the writer of this connection and mess directly
167: * with the writer. Therefore, this method ensures a correct delivery of the stanza
168: * even if other threads were sending data concurrently.
169: *
170: * @param text the XML stanzas represented kept in a String.
171: */
172: public void deliverRawText(String text);
173:
174: /**
175: * Returns true if the connected client is a flash client. Flash clients need
176: * to receive a special character (i.e. \0) at the end of each xml packet. Flash
177: * clients may send the character \0 in incoming packets and may start a connection
178: * using another openning tag such as: "flash:client".
179: *
180: * @return true if the connected client is a flash client.
181: */
182: public boolean isFlashClient();
183:
184: /**
185: * Sets whether the connected client is a flash client. Flash clients need to
186: * receive a special character (i.e. \0) at the end of each xml packet. Flash
187: * clients may send the character \0 in incoming packets and may start a
188: * connection using another openning tag such as: "flash:client".
189: *
190: * @param flashClient true if the if the connection is a flash client.
191: */
192: public void setFlashClient(boolean flashClient);
193:
194: /**
195: * Returns the major version of XMPP being used by this connection
196: * (major_version.minor_version. In most cases, the version should be
197: * "1.0". However, older clients using the "Jabber" protocol do not set a
198: * version. In that case, the version is "0.0".
199: *
200: * @return the major XMPP version being used by this connection.
201: */
202: public int getMajorXMPPVersion();
203:
204: /**
205: * Returns the minor version of XMPP being used by this connection
206: * (major_version.minor_version. In most cases, the version should be
207: * "1.0". However, older clients using the "Jabber" protocol do not set a
208: * version. In that case, the version is "0.0".
209: *
210: * @return the minor XMPP version being used by this connection.
211: */
212: public int getMinorXMPPVersion();
213:
214: /**
215: * Sets the XMPP version information. In most cases, the version should be "1.0".
216: * However, older clients using the "Jabber" protocol do not set a version. In that
217: * case, the version is "0.0".
218: *
219: * @param majorVersion the major version.
220: * @param minorVersion the minor version.
221: */
222: public void setXMPPVersion(int majorVersion, int minorVersion);
223:
224: /**
225: * Returns the language code that should be used for this connection
226: * (e.g. "en").
227: *
228: * @return the language code for the connection.
229: */
230: public String getLanguage();
231:
232: /**
233: * Sets the language code that should be used for this connection (e.g. "en").
234: *
235: * @param language the language code.
236: */
237: public void setLanaguage(String language);
238:
239: /**
240: * Returns true if the connection is using compression.
241: *
242: * @return true if the connection is using compression.
243: */
244: boolean isCompressed();
245:
246: /**
247: * Returns whether compression is optional or is disabled.
248: *
249: * @return whether compression is optional or is disabled.
250: */
251: CompressionPolicy getCompressionPolicy();
252:
253: /**
254: * Sets whether compression is enabled or is disabled.
255: *
256: * @param compressionPolicy whether Compression is enabled or is disabled.
257: */
258: void setCompressionPolicy(CompressionPolicy compressionPolicy);
259:
260: /**
261: * Returns whether TLS is mandatory, optional or is disabled. When TLS is mandatory clients
262: * are required to secure their connections or otherwise their connections will be closed.
263: * On the other hand, when TLS is disabled clients are not allowed to secure their connections
264: * using TLS. Their connections will be closed if they try to secure the connection. in this
265: * last case.
266: *
267: * @return whether TLS is mandatory, optional or is disabled.
268: */
269: TLSPolicy getTlsPolicy();
270:
271: /**
272: * Sets whether TLS is mandatory, optional or is disabled. When TLS is mandatory clients
273: * are required to secure their connections or otherwise their connections will be closed.
274: * On the other hand, when TLS is disabled clients are not allowed to secure their connections
275: * using TLS. Their connections will be closed if they try to secure the connection. in this
276: * last case.
277: *
278: * @param tlsPolicy whether TLS is mandatory, optional or is disabled.
279: */
280: void setTlsPolicy(TLSPolicy tlsPolicy);
281:
282: /**
283: * Returns the packet deliverer to use when delivering a packet over the socket fails. The
284: * packet deliverer will retry to send the packet using some other connection, will store
285: * the packet offline for later retrieval or will just drop it.
286: *
287: * @return the packet deliverer to use when delivering a packet over the socket fails.
288: */
289: PacketDeliverer getPacketDeliverer();
290:
291: /**
292: * Secures the plain connection by negotiating TLS with the other peer. In a server-2-server
293: * connection the server requesting the TLS negotiation will be the client and the other server
294: * will be the server during the TLS negotiation. Therefore, the server requesting the TLS
295: * negotiation must pass <code>true</code> in the <tt>clientMode</tt> parameter and the server
296: * receiving the TLS request must pass <code>false</code> in the <tt>clientMode</tt> parameter.
297: * Both servers should specify the xmpp domain of the other server in the <tt>remoteServer</tt>
298: * parameter.<p>
299: *
300: * In the case of client-2-server the XMPP server must pass <code>false</code> in the
301: * <tt>clientMode</tt> parameter since it will behave as the server in the TLS negotiation. The
302: * <tt>remoteServer</tt> parameter will always be <tt>null</tt>.
303: *
304: * @param clientMode boolean indicating if this entity is a client or a server in the TLS negotiation.
305: * @param remoteServer xmpp domain of the remote server or <tt>null</tt>. When null a
306: * {@link org.jivesoftware.openfire.net.ClientTrustManager} will be used for verifying certificates
307: * otherwise a {@link org.jivesoftware.openfire.net.ServerTrustManager} will be used.
308: * @param authentication policy to use for authenticating the remote peer.
309: * @throws Exception if an error occured while securing the connection.
310: */
311: void startTLS(boolean clientMode, String remoteServer,
312: ClientAuth authentication) throws Exception;
313:
314: /**
315: * Adds the compression filter to the connection but only filter incoming traffic. Do not filter
316: * outgoing traffic since we still need to send an uncompressed stanza to the client indicating
317: * that he can start compressing the traffic. After we sent the uncompresses stanza we can
318: * start compression outgoing traffic as well.
319: */
320: void addCompression();
321:
322: /**
323: * Start compressing outgoing traffic for this connection. Compression will only be available after
324: * TLS has been negotiated. This means that a connection can never be using compression before
325: * TLS. However, it is possible to use compression without TLS.
326: */
327: void startCompression();
328:
329: /**
330: * Enumeration of possible compression policies required to interact with the server.
331: */
332: enum CompressionPolicy {
333:
334: /**
335: * compression is optional to interact with the server.
336: */
337: optional,
338:
339: /**
340: * compression is not available. Entities that request a compression negotiation
341: * will get a stream error and their connections will be closed.
342: */
343: disabled
344: }
345:
346: /**
347: * Enumeration of possible TLS policies required to interact with the server.
348: */
349: enum TLSPolicy {
350:
351: /**
352: * TLS is required to interact with the server. Entities that do not secure their
353: * connections using TLS will get a stream error and their connections will be closed.
354: */
355: required,
356:
357: /**
358: * TLS is optional to interact with the server. Entities may or may not secure their
359: * connections using TLS.
360: */
361: optional,
362:
363: /**
364: * TLS is not available. Entities that request a TLS negotiation will get a stream
365: * error and their connections will be closed.
366: */
367: disabled
368: }
369:
370: /**
371: * Enumeration that specifies if clients should be authenticated (and how) while
372: * negotiating TLS.
373: */
374: enum ClientAuth {
375:
376: /**
377: * No authentication will be performed on the client. Client credentials will not
378: * be verified while negotiating TLS.
379: */
380: disabled,
381:
382: /**
383: * Clients will try to be authenticated. Unlike {@link #needed}, if the client
384: * chooses not to provide authentication information about itself, the TLS negotiations
385: * will stop and the connection will be dropped. This option is only useful for
386: * engines in the server mode.
387: */
388: wanted,
389:
390: /**
391: * Clients need to be authenticated. Unlike {@link #wanted}, if the client
392: * chooses not to provide authentication information about itself, the TLS negotiations
393: * will continue. This option is only useful for engines in the server mode.
394: */
395: needed
396: }
397: }
|