Interface Connection
- All Superinterfaces:
AutoCloseable
,Closeable
- All Known Implementing Classes:
AbstractConnection
,ClientSessionConnection
,HttpSession.HttpVirtualConnection
,NettyConnection
,SocketConnection
,VirtualConnection
,WebSocketConnection
- Author:
- Iain Shigeoka
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic enum
Enumeration that specifies if clients should be authenticated (and how) while negotiating TLS.static enum
Enumeration of possible compression policies required to interact with the server.static enum
Used to specify operational status for the corresponding connectionstatic enum
Enumeration of possible TLS policies required to interact with the server. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Adds the compression filter to the connection but only filter incoming traffic.default void
close()
Close this connection including associated session.default void
close
(org.xmpp.packet.StreamError error) Close this connection including associated session, optionally citing a stream error.void
close
(org.xmpp.packet.StreamError error, boolean networkInterruption) Close this connection including associated session, optionally citing a stream error.void
deliver
(org.xmpp.packet.Packet packet) Delivers the packet to this connection without checking the recipient.void
deliverRawText
(String text) Delivers raw text to this connection.Set<org.dom4j.Namespace>
When a connection is used to transmit an XML data, the root element of that data can define XML namespaces other than the ones that are default (eg: 'jabber:client', 'jabber:server', etc).byte[]
Returns the raw IP address of thisInetAddress
object.Returns the TLS cipher suite name used by the connection of the session, if any.Returns a representation of the desired state for this connection.Returns the IP address string in textual presentation.Gets the host name for this IP address.Returns the local underlyingX509Certificate
chain for the connection.int
Returns the major version of XMPP being used by this connection (major_version.minor_version.int
Returns the minor version of XMPP being used by this connection (major_version.minor_version.Returns the packet deliverer to use when delivering a packet over the socket fails.Returns the underlyingX509Certificate
for the connection of the peer.Returns the TLS protocol name used by the connection of the session, if any.void
init
(LocalSession session) Initializes the connection with it's owning session.boolean
isClosed()
Returns true if the connection/session is closed.boolean
Returns true if the connection is using compression.boolean
Returns true if this connection is encrypted.boolean
Checks if the connection has finished initialization.boolean
Returns true if the other peer of this session presented a self-signed certificate.void
registerCloseListener
(ConnectionCloseListener listener, Object handbackMessage) Registers a listener for close event notification.void
reinit
(LocalSession session) Reinitializes the connection to switch to a different session.void
removeCloseListener
(ConnectionCloseListener listener) Removes a registered close event listener.void
setAdditionalNamespaces
(Set<org.dom4j.Namespace> additionalNamespaces) When a connection is used to transmit an XML data, the root element of that data can define XML namespaces other than the ones that are default (eg: 'jabber:client', 'jabber:server', etc).void
setUsingSelfSignedCertificate
(boolean isSelfSigned) Keeps track if the other peer of this session presented a self-signed certificate.void
setXMPPVersion
(int majorVersion, int minorVersion) Sets the XMPP version information.void
Start compressing outgoing traffic for this connection.void
startTLS
(boolean clientMode, boolean directTLS) Encrypts the plain connection by negotiating TLS with the other peer.void
Notification message indicating that the server is being shutdown.boolean
validate()
Verifies that the connection is still live.
-
Method Details
-
validate
boolean validate()Verifies that the connection is still live. Typically, this is done by sending a whitespace character between packets.- Returns:
- true if the socket remains valid, false otherwise.
-
init
Initializes the connection with it's owning session. Allows the connection class to configure itself with session related information (e.g. stream ID).- Parameters:
session
- the session that owns this connection
-
reinit
Reinitializes the connection to switch to a different session. This allows for XEP-0198 resumption and transport-switching.- Parameters:
session
- The new session now owning the connection.
-
isInitialized
boolean isInitialized()Checks if the connection has finished initialization.- Returns:
- true if connection has finished initialization.
-
getAddress
Returns the raw IP address of thisInetAddress
object. The result is in network byte order: the highest order byte of the address is ingetAddress()[0]
.- Returns:
- the raw IP address of this object.
- Throws:
UnknownHostException
- if IP address of host could not be determined.
-
getHostAddress
Returns the IP address string in textual presentation.- Returns:
- the raw IP address in a string format.
- Throws:
UnknownHostException
- if IP address of host could not be determined.
-
getHostName
Gets the host name for this IP address.If this InetAddress was created with a host name, this host name will be remembered and returned; otherwise, a reverse name lookup will be performed and the result will be returned based on the system configured name lookup service. If a lookup of the name service is required, call
getCanonicalHostName
.If there is a security manager, its
checkConnect
method is first called with the hostname and-1
as its arguments to see if the operation is allowed. If the operation is not allowed, it will return the textual representation of the IP address.- Returns:
- the host name for this IP address, or if the operation is not allowed by the security check, the textual representation of the IP address.
- Throws:
UnknownHostException
- if IP address of host could not be determined.- See Also:
-
getLocalCertificates
Certificate[] getLocalCertificates()Returns the local underlyingX509Certificate
chain for the connection.- Returns:
- an ordered array of certificates, with the local certificate
first followed by any certificate authorities. If no certificates
is present for the connection, then
null
is returned.
-
getPeerCertificates
Certificate[] getPeerCertificates()Returns the underlyingX509Certificate
for the connection of the peer.- Returns:
- an ordered array of peer certificates, with the peer's own certificate first followed by any certificate authorities.
-
setUsingSelfSignedCertificate
void setUsingSelfSignedCertificate(boolean isSelfSigned) Keeps track if the other peer of this session presented a self-signed certificate. When using self-signed certificate for server-2-server sessions then SASL EXTERNAL will not be used and instead server-dialback will be preferred for verifying the identify of the remote server.- Parameters:
isSelfSigned
- true if the other peer presented a self-signed certificate.
-
isUsingSelfSignedCertificate
boolean isUsingSelfSignedCertificate()Returns true if the other peer of this session presented a self-signed certificate. When using self-signed certificate for server-2-server sessions then SASL EXTERNAL will not be used and instead server-dialback will be preferred for verifying the identify of the remote server.- Returns:
- true if the other peer of this session presented a self-signed certificate.
-
close
default void close()Close this connection including associated session. The events for closing the connection are:- Set closing flag to prevent redundant shutdowns.
- Close the socket.
- Notify all listeners that the channel is shut down.
close(StreamError, boolean)
for processing of unexpected disconnects (that are potentially resumable).- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
close
default void close(@Nullable org.xmpp.packet.StreamError error) Close this connection including associated session, optionally citing a stream error. The events for closing the connection are:- Set closing flag to prevent redundant shutdowns.
- Close the socket.
- Notify all listeners that the channel is shut down.
close(StreamError, boolean)
for processing of unexpected disconnects (that are potentially resumable).- Parameters:
error
- If non-null, the end-stream tag will be preceded with this error.
-
close
void close(@Nullable org.xmpp.packet.StreamError error, boolean networkInterruption) Close this connection including associated session, optionally citing a stream error. The 'networkInterruption' argument should be set to 'true' if the connection is being closed because it is known or assumed that the network connection between Openfire and the peer was unexpectedly terminated (eg: due to a networking failure). These typically are scenarios where a peer becomes unresponsive (without having terminated its session with a </stream:stream> or comparable message). When the 'networkInterruption' argument is set to 'true', then a session is eligible for resumption (if Stream Management was activiated for the session). The events for closing the connection are:- Set closing flag to prevent redundant shutdowns.
- Close the socket.
- Notify all listeners that the channel is shut down.
- Parameters:
error
- If non-null, the end-stream tag will be preceded with this error.
-
systemShutdown
void systemShutdown()Notification message indicating that the server is being shutdown. Implementors should send a stream error whose condition is system-shutdown before closing the connection. -
isClosed
boolean isClosed()Returns true if the connection/session is closed.- Returns:
- true if the connection is closed.
-
isEncrypted
boolean isEncrypted()Returns true if this connection is encrypted.- Returns:
- true if the connection is encrypted (e.g. uses TLS)
-
registerCloseListener
Registers a listener for close event notification. Registrations after the Session is closed will be immediately notified before the registration call returns (within the context of the registration call). An optional handback object can be associated with the registration if the same listener is registered to listen for multiple connection closures.- Parameters:
listener
- the listener to register for events.handbackMessage
- the object to send in the event notification.
-
removeCloseListener
Removes a registered close event listener. Registered listeners must be able to receive close events up until the time this method returns. (i.e. it is possible to call unregister, receive a close event registration, and then have the unregister call return.)- Parameters:
listener
- the listener to deregister for close events.
-
deliver
Delivers the packet to this connection without checking the recipient. The method essentially callssocket.send(packet.getWriteBuffer())
. Use with caution! This code is unlikely to be called directly. Instead, ensure that data sent to the entities is sent through the appropriate LocalSession object. For clients, this prevents, for example, synchronisation issues with stanza counts related to Stream Management (XEP-0198).- Parameters:
packet
- the packet to deliver.- Throws:
UnauthorizedException
- if a permission error was detected.
-
deliverRawText
Delivers raw text to this connection. This is a very low level way for sending XML stanzas to the client. This method should not be used unless you have very good reasons for not usingdeliver(org.xmpp.packet.Packet)
.This method avoids having to get the writer of this connection and mess directly with the writer. Therefore, this method ensures a correct delivery of the stanza even if other threads were sending data concurrently.
- Parameters:
text
- the XML stanzas represented kept in a String.
-
getMajorXMPPVersion
int getMajorXMPPVersion()Returns the major version of XMPP being used by this connection (major_version.minor_version. In most cases, the version should be "1.0". However, older clients using the "Jabber" protocol do not set a version. In that case, the version is "0.0".- Returns:
- the major XMPP version being used by this connection.
-
getMinorXMPPVersion
int getMinorXMPPVersion()Returns the minor version of XMPP being used by this connection (major_version.minor_version. In most cases, the version should be "1.0". However, older clients using the "Jabber" protocol do not set a version. In that case, the version is "0.0".- Returns:
- the minor XMPP version being used by this connection.
-
setXMPPVersion
void setXMPPVersion(int majorVersion, int minorVersion) Sets the XMPP version information. In most cases, the version should be "1.0". However, older clients using the "Jabber" protocol do not set a version. In that case, the version is "0.0".- Parameters:
majorVersion
- the major version.minorVersion
- the minor version.
-
isCompressed
boolean isCompressed()Returns true if the connection is using compression.- Returns:
- true if the connection is using compression.
-
getTLSProtocolName
Returns the TLS protocol name used by the connection of the session, if any.- Returns:
- a TLS protocol (version) name.
-
getCipherSuiteName
Returns the TLS cipher suite name used by the connection of the session, if any.- Returns:
- cipher suite name.
-
getPacketDeliverer
Returns the packet deliverer to use when delivering a packet over the socket fails. The packet deliverer will retry to send the packet using some other connection or will store the packet offline for later retrieval. When null, packets will just be dropped.- Returns:
- the packet deliverer to use when delivering a packet over the socket fails.
-
startTLS
Encrypts the plain connection by negotiating TLS with the other peer. In a server-2-server connection the server requesting the TLS negotiation will be the client and the other server will be the server during the TLS negotiation. Therefore, the server requesting the TLS negotiation must passtrue
in theclientMode
parameter and the server receiving the TLS request must passfalse
in theclientMode
parameter.In the case of client-2-server the XMPP server must pass
false
in theclientMode
parameter since it will behave as the server in the TLS negotiation.- Parameters:
clientMode
- boolean indicating if this entity is a client or a server in the TLS negotiation.directTLS
- boolean indicating if the negotiation is directTLS (true) or startTLS (false).- Throws:
Exception
- if an error occurred while encrypting the connection.
-
addCompression
void addCompression()Adds the compression filter to the connection but only filter incoming traffic. Do not filter outgoing traffic since we still need to send an uncompressed stanza to the client indicating that he can start compressing the traffic. After we sent the uncompresses stanza we can start compression outgoing traffic as well. -
startCompression
void startCompression()Start compressing outgoing traffic for this connection. Compression will only be available after TLS has been negotiated. This means that a connection can never be using compression before TLS. However, it is possible to use compression without TLS. -
getConfiguration
ConnectionConfiguration getConfiguration()Returns a representation of the desired state for this connection. Note that this is different from the current state of the connection. For example, TLS can be required by configuration, but while the connection has yet to be fully initialized, the current state might not be TLS-encrypted.- Returns:
- The desired configuration for the connection (never null).
-
getAdditionalNamespaces
Set<org.dom4j.Namespace> getAdditionalNamespaces()When a connection is used to transmit an XML data, the root element of that data can define XML namespaces other than the ones that are default (eg: 'jabber:client', 'jabber:server', etc). For an XML parser to be able to parse stanzas or other elements that are defined in that namespace (eg: are prefixed), these namespaces are recorded here.- Returns:
- A collection that contains all non-default namespaces that the peer defined when last opening a new stream.
-
setAdditionalNamespaces
When a connection is used to transmit an XML data, the root element of that data can define XML namespaces other than the ones that are default (eg: 'jabber:client', 'jabber:server', etc). For an XML parser to be able to parse stanzas or other elements that are defined in that namespace (eg: are prefixed), these namespaces are recorded here.- Parameters:
additionalNamespaces
- A collection that contains all non-default namespaces that the peer defined when last opening a new stream.
-