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 is disconnected or reconnected.
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	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	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(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 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.
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.
boolean	handleElement(Object element) Handles an XMPP element.
boolean	isConnected() Indicates, whether the session is connected.
void	notifyException(Throwable e) Called if any unhandled exception is thrown during reading or writing.
IQ	query(IQ iq) Sends an <iq/> stanza and waits for the response.
IQ	query(IQ iq, long timeout) Sends an <iq/> stanza and waits for the response.
void	removeConnectionListener(Consumer<ConnectionEvent> connectionListener) Removes a previously added connection 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	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	removeSessionStatusListener(Consumer<SessionStatusEvent> sessionStatusListener) Removes a previously added session listener.
StreamElement	send(StreamElement element) Sends an XML element to the server, usually a stanza, i.e. a message, presence or IQ.
Message	sendAndAwaitMessage(StreamElement stanza, Predicate<Message> filter) Sends a stanza and then waits for a message stanza to arrive.
Presence	sendAndAwaitPresence(StreamElement stanza, Predicate<Presence> filter) Sends a stanza and then waits for a presence stanza to arrive.

Methods inherited from class java.lang.Object

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

Method Detail

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(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)

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 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 IQ query(IQ iq)
         throws XmppException

Sends an <iq/> stanza and waits for the response.

This method blocks until a result was received or a timeout occurred.

Parameters:

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

Returns:

The result <iq/> stanza.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

query

public IQ query(IQ iq,
                long timeout)
         throws XmppException

Sends an <iq/> stanza and waits for the response.

This method blocks until a result was received or a timeout occurred.

Parameters:

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

timeout - The timeout.

Returns:

The result <iq/> stanza.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

sendAndAwaitPresence

public final Presence sendAndAwaitPresence(StreamElement stanza,
                                           Predicate<Presence> filter)
                                    throws XmppException

Sends a stanza and then waits for a presence stanza to arrive. The filter determines the characteristics of the presence stanza.

Parameters:

stanza - The stanza, which is sent.

filter - The presence filter.

Returns:

The presence stanza.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

sendAndAwaitMessage

public final Message sendAndAwaitMessage(StreamElement stanza,
                                         Predicate<Message> filter)
                                  throws XmppException

Sends a stanza and then waits for a message stanza to arrive. The filter determines the characteristics of the message stanza.

Parameters:

stanza - The stanza, which is sent.

filter - The message filter.

Returns:

The message stanza.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

getActiveConnection

public final Connection getActiveConnection()

Gets the actively used connection.

Returns:

The actively used connection.

send

public StreamElement 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.

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()

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 final 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 Jid getConnectedResource()

The connected resource, which is assigned by the server.

Returns:

The connected resource.