rocks.xmpp.core.session

Class XmppSession

java.lang.Object

rocks.xmpp.core.session.XmppSession

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

XmppClient

public abstract class XmppSession
extends Object
implements AutoCloseable

The base class for different kinds of XMPP sessions.

To date there are three kinds of sessions:

• A normal client-to-server session. This is the default and most used XMPP session. It's concrete implementation is the XmppClient.
• An external component session (XEP-0114: Jabber Component Protocol).
• A client-to-client session (XEP-0174: Serverless Messaging) (no implementation yet).

This class provides the common functionality and abstract methods for connection establishment, sending and receiving XML stanzas, closing the session, etc.

Concrete implementations may have different concepts for authentication, e.g. normal C2S sessions use SASL, while the Jabber Component Protocol uses a different kind of handshake for authenticating.

See Also:

XmppClient, XEP-0114: Jabber Component Protocol, XEP-0174: Serverless Messaging

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	XmppSession.Status Represents the session status.

Method Summary

Modifier and Type	Method and Description
void	addConnectionListener(Consumer<ConnectionEvent> connectionListener) Adds a connection listener, which is triggered, when the connection used by this session is disconnected or reconnected.
static void	addCreationListener(Consumer<XmppSession> listener) Adds a listener, which is triggered, whenever a new session is created.
void	addInboundIQListener(Consumer<IQEvent> iqListener) Adds an inbound IQ listener to the session, which will get notified, whenever an IQ stanza is received.
void	addInboundMessageListener(Consumer<MessageEvent> messageListener) Adds an inbound message listener to the session, which will get notified, whenever a message is received.
void	addInboundPresenceListener(Consumer<PresenceEvent> presenceListener) Adds an inbound presence listener to the session, which will get notified, whenever a presence is received.
void	addIQHandler(Class<?> type, IQHandler iqHandler) Adds an IQ handler for a given payload type.
void	addIQHandler(Class<?> type, IQHandler iqHandler, boolean invokeAsync) Adds an IQ handler for a given payload type.
void	addMessageAcknowledgedListener(Consumer<MessageEvent> messageListener) Adds a listener, which gets called, when the server acknowledges the receipt of a message.
void	addOutboundIQListener(Consumer<IQEvent> iqListener) Adds an outbound IQ listener to the session, which will get notified, whenever an IQ stanza is sent.
void	addOutboundMessageListener(Consumer<MessageEvent> messageListener) Adds an outbound message listener to the session, which will get notified, whenever a message is sent.
void	addOutboundPresenceListener(Consumer<PresenceEvent> presenceListener) Adds an outbound presence listener to the session, which will get notified, whenever a presence is sent.
void	addSendFailedListener(BiConsumer<StreamElement,Throwable> sendFailedListener) Adds a listener, which gets called, whenever a stream element (e.g. message) has been sent unsuccessfully.
void	addSendSucceededListener(Consumer<StreamElement> sendSucceededListener) Adds a listener, which gets called, whenever a stream element (e.g. message) has been sent successfully.
void	addSessionStatusListener(Consumer<SessionStatusEvent> sessionStatusListener) Adds a session listener, which listens for session status changes.
void	close() Explicitly closes the session and performs a clean up of all listeners.
void	connect() Connects to the XMPP server.
abstract void	connect(rocks.xmpp.addr.Jid from)
Marshaller	createMarshaller() Creates a marshaller, which can be used to create XML from objects.
Unmarshaller	createUnmarshaller() Creates a new unmarshaller, which can be used to unmarshal XML to objects.
void	disableFeature(Class<? extends Manager> managerClass) Disables a feature by its manager class.
void	disableFeature(String name) Disables a feature by its name, usually a protocol namespace.
void	enableFeature(Class<? extends Manager> managerClass) Enables a feature by its manager class.
void	enableFeature(String name) Enables a feature by its name, usually a protocol namespace.
Connection	getActiveConnection() Gets the actively used connection.
XmppSessionConfiguration	getConfiguration() Gets the configuration for this session.
abstract rocks.xmpp.addr.Jid	getConnectedResource() The connected resource, which is assigned by the server.
List<Connection>	getConnections() Gets an unmodifiable list of connections, which this session will try during connecting.
XmppDebugger	getDebugger() Gets the debugger or null if no debugger class was specified in the configuration.
rocks.xmpp.addr.Jid	getDomain() Gets the XMPP domain of the connected server.
Set<String>	getEnabledFeatures() Gets the enabled features.
<T extends Manager> T	getManager(Class<T> clazz) Gets an instance of the specified manager class.
XmppSession.Status	getStatus() Gets the status of the session.
Queue<Stanza>	getUnacknowledgedStanzas()
boolean	handleElement(Object element) Handles an XMPP element.
boolean	isAuthenticated() Returns true, if the session is authenticated.
boolean	isConnected() Indicates, whether the session is connected.
void	markAcknowledged(Stanza acknowledgedStanza) Marks a stanza as acknowledged.
void	notifyException(Throwable e) Called if any unhandled exception is thrown during reading or writing.
AsyncResult<IQ>	query(IQ iq) Sends an <iq/> stanza and returns an async result, which can be used to wait for the response.
<T> AsyncResult<T>	query(IQ iq, Class<T> clazz) Sends an <iq/> stanza and returns an async result, which can be used to wait for the response.
AsyncResult<IQ>	query(IQ iq, Duration timeout) Sends an <iq/> stanza and returns an async result, which can be used to wait for the response.
void	removeConnectionListener(Consumer<ConnectionEvent> connectionListener) Removes a previously added connection listener.
static void	removeCreationListener(Consumer<XmppSession> listener) Removes a previously added creation listener.
void	removeInboundIQListener(Consumer<IQEvent> iqListener) Removes a previously added inbound IQ listener from the session.
void	removeInboundMessageListener(Consumer<MessageEvent> messageListener) Removes a previously added inbound message listener from the session.
void	removeInboundPresenceListener(Consumer<PresenceEvent> presenceListener) Removes a previously added inbound presence listener from the session.
void	removeIQHandler(Class<?> type) Removes an IQ handler.
void	removeMessageAcknowledgedListener(Consumer<MessageEvent> messageListener) Removes a previously added message acknowledge listener.
void	removeOutboundIQListener(Consumer<IQEvent> iqListener) Removes a previously added outbound IQ listener from the session.
void	removeOutboundMessageListener(Consumer<MessageEvent> messageListener) Removes a previously added outbound message listener from the session.
void	removeOutboundPresenceListener(Consumer<PresenceEvent> presenceListener) Removes a previously added outbound presence listener from the session.
void	removeSendFailedListener(BiConsumer<StreamElement,Throwable> sendFailedListener) Removes a previously added send failed listener.
void	removeSendSucceededListener(Consumer<StreamElement> sendSucceededListener) Removes a previously added send succeeded listener.
void	removeSessionStatusListener(Consumer<SessionStatusEvent> sessionStatusListener) Removes a previously added session listener.
Future<Void>	send(StreamElement element) Sends an XML element to the server, usually a stanza, i.e. a message, presence or IQ.
AsyncResult<Message>	sendAndAwaitMessage(Message stanza, Predicate<Message> filter) Sends a stanza and returns an async result which can wait for the message stanza, which matches the predicate, to arrive.
AsyncResult<Presence>	sendAndAwaitPresence(Presence stanza, Predicate<Presence> filter) Sends a stanza and returns an async result which can wait for the presence stanza, which matches the predicate, to arrive.
SendTask<IQ>	sendIQ(IQ iq) Sends an IQ.
SendTask<Message>	sendMessage(Message message) Sends a message.
SendTask<Presence>	sendPresence(Presence presence) Sends a presence.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addCreationListener

public static void addCreationListener(Consumer<XmppSession> listener)

Adds a listener, which is triggered, whenever a new session is created.

Parameters:

listener - The listener.

See Also:

removeCreationListener(Consumer)

removeCreationListener

public static void removeCreationListener(Consumer<XmppSession> listener)

Removes a previously added creation listener.

Parameters:

listener - The listener.

See Also:

addCreationListener(Consumer)

connect

public final void connect()
                   throws XmppException

Connects to the XMPP server.

Throws:

ConnectionException - If a connection error occurred on the transport layer, e.g. the socket could not connect.

StreamErrorException - If the server returned a stream error.

StreamNegotiationException - If any exception occurred during stream feature negotiation.

NoResponseException - If the server didn't return a response during stream establishment.

XmppException - If any other XMPP exception occurs.

IllegalStateException - If the session is in a wrong state, e.g. closed or already connected.

connect

public abstract void connect(rocks.xmpp.addr.Jid from)
                      throws XmppException

Throws:

XmppException

addInboundMessageListener

public final void addInboundMessageListener(Consumer<MessageEvent> messageListener)

Adds an inbound message listener to the session, which will get notified, whenever a message is received.

Parameters:

messageListener - The message listener.

See Also:

removeInboundMessageListener(Consumer)

removeInboundMessageListener

public final void removeInboundMessageListener(Consumer<MessageEvent> messageListener)

Removes a previously added inbound message listener from the session.

Parameters:

messageListener - The message listener.

See Also:

addInboundMessageListener(Consumer)

addOutboundMessageListener

public final void addOutboundMessageListener(Consumer<MessageEvent> messageListener)

Adds an outbound message listener to the session, which will get notified, whenever a message is sent.

Parameters:

messageListener - The message listener.

See Also:

removeOutboundMessageListener(Consumer)

removeOutboundMessageListener

public final void removeOutboundMessageListener(Consumer<MessageEvent> messageListener)

Removes a previously added outbound message listener from the session.

Parameters:

messageListener - The message listener.

See Also:

addOutboundMessageListener(Consumer)

addInboundPresenceListener

public final void addInboundPresenceListener(Consumer<PresenceEvent> presenceListener)

Adds an inbound presence listener to the session, which will get notified, whenever a presence is received.

Parameters:

presenceListener - The presence listener.

See Also:

removeInboundPresenceListener(Consumer)

removeInboundPresenceListener

public final void removeInboundPresenceListener(Consumer<PresenceEvent> presenceListener)

Removes a previously added inbound presence listener from the session.

Parameters:

presenceListener - The presence listener.

See Also:

addInboundPresenceListener(Consumer)

addOutboundPresenceListener

public final void addOutboundPresenceListener(Consumer<PresenceEvent> presenceListener)

Adds an outbound presence listener to the session, which will get notified, whenever a presence is sent.

Parameters:

presenceListener - The presence listener.

See Also:

removeOutboundPresenceListener(Consumer)

removeOutboundPresenceListener

public final void removeOutboundPresenceListener(Consumer<PresenceEvent> presenceListener)

Removes a previously added outbound presence listener from the session.

Parameters:

presenceListener - The presence listener.

See Also:

addOutboundPresenceListener(Consumer)

addInboundIQListener

public final void addInboundIQListener(Consumer<IQEvent> iqListener)

Adds an inbound IQ listener to the session, which will get notified, whenever an IQ stanza is received.

Parameters:

iqListener - The IQ listener.

See Also:

removeInboundIQListener(Consumer)

removeInboundIQListener

public final void removeInboundIQListener(Consumer<IQEvent> iqListener)

Removes a previously added inbound IQ listener from the session.

Parameters:

iqListener - The IQ listener.

See Also:

addInboundIQListener(Consumer)

addOutboundIQListener

public final void addOutboundIQListener(Consumer<IQEvent> iqListener)

Adds an outbound IQ listener to the session, which will get notified, whenever an IQ stanza is sent.

Parameters:

iqListener - The IQ listener.

See Also:

removeOutboundIQListener(Consumer)

removeOutboundIQListener

public final void removeOutboundIQListener(Consumer<IQEvent> iqListener)

Removes a previously added outbound IQ listener from the session.

Parameters:

iqListener - The IQ listener.

See Also:

addOutboundIQListener(Consumer)

addMessageAcknowledgedListener

public final void addMessageAcknowledgedListener(Consumer<MessageEvent> messageListener)

Adds a listener, which gets called, when the server acknowledges the receipt of a message.

Parameters:

messageListener - The message listener.

See Also:

removeMessageAcknowledgedListener(Consumer)

removeMessageAcknowledgedListener

public final void removeMessageAcknowledgedListener(Consumer<MessageEvent> messageListener)

Removes a previously added message acknowledge listener.

Parameters:

messageListener - The message listener.

See Also:

addMessageAcknowledgedListener(Consumer)

addSendSucceededListener

public final void addSendSucceededListener(Consumer<StreamElement> sendSucceededListener)

Adds a listener, which gets called, whenever a stream element (e.g. message) has been sent successfully.

Parameters:

sendSucceededListener - The listener.

See Also:

removeSendSucceededListener(Consumer)

removeSendSucceededListener

public final void removeSendSucceededListener(Consumer<StreamElement> sendSucceededListener)

Removes a previously added send succeeded listener.

Parameters:

sendSucceededListener - The listener.

See Also:

addSendSucceededListener(Consumer)

addSendFailedListener

public final void addSendFailedListener(BiConsumer<StreamElement,Throwable> sendFailedListener)

Adds a listener, which gets called, whenever a stream element (e.g. message) has been sent unsuccessfully.

Parameters:

sendFailedListener - The listener.

See Also:

removeSendFailedListener(BiConsumer)

removeSendFailedListener

public final void removeSendFailedListener(BiConsumer<StreamElement,Throwable> sendFailedListener)

Removes a previously added send failed listener.

Parameters:

sendFailedListener - The listener.

See Also:

addSendFailedListener(BiConsumer), addSendSucceededListener(Consumer)

addIQHandler

public final void addIQHandler(Class<?> type,
                               IQHandler iqHandler)

Adds an IQ handler for a given payload type. The handler will be processed asynchronously, which means it won't block the inbound stanza processing queue.

Parameters:

type - The payload type.

iqHandler - The IQ handler.

See Also:

removeIQHandler(Class), addIQHandler(Class, IQHandler, boolean)

addIQHandler

public final void addIQHandler(Class<?> type,
                               IQHandler iqHandler,
                               boolean invokeAsync)

Adds an IQ handler for a given payload type. The handler can either be processed asynchronously (which means it won't block the inbound stanza processing queue), or synchronously, which means IQ requests are processed on the same thread as other stanzas. In other words synchronous processing means, the IQ requests are processed in the same order as they arrive and no other stanzas can be processed until the handler has returned.

Parameters:

type - The payload type.

iqHandler - The IQ handler.

invokeAsync - True, if the handler should be processed asynchronously; false, if the handler should be processed asynchronously.

See Also:

removeIQHandler(Class)

removeIQHandler

public final void removeIQHandler(Class<?> type)

Removes an IQ handler.

Parameters:

type - The payload type.

See Also:

addIQHandler(Class, IQHandler)

addSessionStatusListener

public final void addSessionStatusListener(Consumer<SessionStatusEvent> sessionStatusListener)

Adds a session listener, which listens for session status changes. Each time the session status changes, all listeners will be notified.

Parameters:

sessionStatusListener - The session listener.

See Also:

removeSessionStatusListener(Consumer)

removeSessionStatusListener

public final void removeSessionStatusListener(Consumer<SessionStatusEvent> sessionStatusListener)

Removes a previously added session listener.

Parameters:

sessionStatusListener - The session listener.

See Also:

addSessionStatusListener(Consumer)

addConnectionListener

public final void addConnectionListener(Consumer<ConnectionEvent> connectionListener)

Adds a connection listener, which is triggered, when the connection used by this session is disconnected or reconnected.

Parameters:

connectionListener - The connection listener.

See Also:

removeConnectionListener(Consumer)

removeConnectionListener

public final void removeConnectionListener(Consumer<ConnectionEvent> connectionListener)

Removes a previously added connection listener.

Parameters:

connectionListener - The connection listener.

See Also:

addConnectionListener(Consumer)

query

public final AsyncResult<IQ> query(IQ iq)

Sends an <iq/> stanza and returns an async result, which can be used to wait for the response. The result is completed if the response IQ has arrived or the default timeout has exceeded, in which case the result completes with a NoResponseException.

Parameters:

iq - The <iq/> stanza, which must be of type get or set.

Returns:

The async IQ result.

query

public final AsyncResult<IQ> query(IQ iq,
                                   Duration timeout)

Sends an <iq/> stanza and returns an async result, which can be used to wait for the response. The result is completed if the response IQ has arrived or the timeout has exceeded, in which case the result completes with a NoResponseException.

Parameters:

iq - The <iq/> stanza, which must be of type get or set.

timeout - The timeout.

Returns:

The async IQ result.

query

public final <T> AsyncResult<T> query(IQ iq,
                                      Class<T> clazz)

Sends an <iq/> stanza and returns an async result, which can be used to wait for the response. The result is completed if the response IQ has arrived or the default timeout has exceeded, in which case the result completes with a NoResponseException. The payload of the response IQ is returned in the async result class.

Type Parameters:

T - The type.

Parameters:

iq - The <iq/> stanza, which must be of type get or set.

clazz - The class which is IQ response's payload.

Returns:

The async result with the IQ response's payload.

sendAndAwaitPresence

public final AsyncResult<Presence> sendAndAwaitPresence(Presence stanza,
                                                        Predicate<Presence> filter)

Sends a stanza and returns an async result which can wait for the presence stanza, which matches the predicate, to arrive.

Parameters:

stanza - The stanza, which is sent.

filter - The presence filter.

Returns:

The async presence result.

sendAndAwaitMessage

public final AsyncResult<Message> sendAndAwaitMessage(Message stanza,
                                                      Predicate<Message> filter)

Sends a stanza and returns an async result which can wait for the message stanza, which matches the predicate, to arrive.

Parameters:

stanza - The stanza, which is sent.

filter - The message filter.

Returns:

The async message result.

getActiveConnection

public final Connection getActiveConnection()

Gets the actively used connection.

Returns:

The actively used connection.

send

public Future<Void> send(StreamElement element)

Sends an XML element to the server, usually a stanza, i.e. a message, presence or IQ.

Parameters:

element - The XML element.

Returns:

The sent stream element, which is usually the same as the parameter, but may differ in case a stanza is sent, e.g. a Message is translated to a ClientMessage.

sendIQ

public SendTask<IQ> sendIQ(IQ iq)

Sends an IQ.

Parameters:

iq - The IQ.

Returns:

The send task, which allows to track the stanza.

sendMessage

public SendTask<Message> sendMessage(Message message)

Sends a message.

Parameters:

message - The message.

Returns:

The send task, which allows to track the stanza.

sendPresence

public SendTask<Presence> sendPresence(Presence presence)

Sends a presence.

Parameters:

presence - The presence.

Returns:

The send task, which allows to track the stanza.

getStatus

public final XmppSession.Status getStatus()

Gets the status of the session.

Returns:

The status.

getConnections

public final List<Connection> getConnections()

Gets an unmodifiable list of connections, which this session will try during connecting.

Returns:

The connections.

createUnmarshaller

public final Unmarshaller createUnmarshaller()

Creates a new unmarshaller, which can be used to unmarshal XML to objects.

Note that the returned unmarshaller is not thread-safe.

Returns:

The unmarshaller.

See Also:

createMarshaller()

createMarshaller

public final Marshaller createMarshaller()

Creates a marshaller, which can be used to create XML from objects.

The returned marshaller is configured with Marshaller.JAXB_FRAGMENT = true, so that no XML header is written (which is usually what we want in XMPP when writing stanzas).

Note that the returned unmarshaller is not thread-safe.

Returns:

The marshaller.

See Also:

createUnmarshaller()

isConnected

public final boolean isConnected()

Indicates, whether the session is connected.

Returns:

True, if the status is XmppSession.Status.CONNECTED, XmppSession.Status.AUTHENTICATED or XmppSession.Status.AUTHENTICATING.

See Also:

getStatus()

isAuthenticated

public final boolean isAuthenticated()

Returns true, if the session is authenticated. For a normal client-to-server session this means, when the user has logged in (successfully completed SASL negotiation and resource binding).

Returns:

True, if authenticated.

Since:

0.7.0

handleElement

public boolean handleElement(Object element)
                      throws XmppException

Handles an XMPP element.

This method should be called on the reader thread.

Parameters:

element - The XMPP element.

Returns:

True, if the stream needs to be restarted; otherwise false.

Throws:

StreamErrorException - If the element is a stream error.

StreamNegotiationException - If any exception occurred during stream feature negotiation.

XmppException - If any other XMPP exception occurs.

getManager

public final <T extends Manager> T getManager(Class<T> clazz)

Gets an instance of the specified manager class. The class MUST have a constructor which takes a single parameter, whose type is XmppSession.

Type Parameters:

T - The type.

Parameters:

clazz - The class of the manager.

Returns:

An instance of the specified manager.

close

public final void close()
                 throws XmppException

Explicitly closes the session and performs a clean up of all listeners. Calling this method, if the session is already closing or closed has no effect.

Specified by:

close in interface AutoCloseable

Throws:

XmppException - If an exception occurs while closing the connection, e.g. the underlying socket connection.

notifyException

public void notifyException(Throwable e)

Called if any unhandled exception is thrown during reading or writing.

This method will close the stream.

Parameters:

e - The exception. If an unrecoverable XMPP stream error occurred, the exception is a StreamError.

getDomain

public rocks.xmpp.addr.Jid getDomain()

Gets the XMPP domain of the connected server. This variable is set after server has responded with a stream header. The domain is the stream header's 'from' attribute.

Returns:

The XMPP domain.

getConfiguration

public final XmppSessionConfiguration getConfiguration()

Gets the configuration for this session.

Returns:

The configuration.

getDebugger

public final XmppDebugger getDebugger()

Gets the debugger or null if no debugger class was specified in the configuration.

Returns:

The debugger.

See Also:

XmppSessionConfiguration.getDebugger()

enableFeature

public final void enableFeature(String name)

Enables a feature by its name, usually a protocol namespace.

Parameters:

name - The associated manager class.

disableFeature

public final void disableFeature(String name)

Disables a feature by its name, usually a protocol namespace.

Parameters:

name - The associated manager class.

enableFeature

public final void enableFeature(Class<? extends Manager> managerClass)

Enables a feature by its manager class.

Parameters:

managerClass - The associated manager class.

disableFeature

public final void disableFeature(Class<? extends Manager> managerClass)

Disables a feature by its manager class.

Parameters:

managerClass - The associated manager class.

getEnabledFeatures

public final Set<String> getEnabledFeatures()

Gets the enabled features.

Returns:

The enabled features.

getConnectedResource

public abstract rocks.xmpp.addr.Jid getConnectedResource()

The connected resource, which is assigned by the server.

Returns:

The connected resource.

getUnacknowledgedStanzas

public final Queue<Stanza> getUnacknowledgedStanzas()

markAcknowledged

public final void markAcknowledged(Stanza acknowledgedStanza)

Marks a stanza as acknowledged. This method removes a stanza from the unacknowledged queue, so that it won't be resent during reconnection and notifies the acknowledged listeners.

Parameters:

acknowledgedStanza - The acknowledged stanza.

See Also:

addMessageAcknowledgedListener(Consumer)