rocks.xmpp.core.session

Class XmppSession

java.lang.Object

rocks.xmpp.core.session.XmppSession

All Implemented Interfaces:

Closeable, AutoCloseable

public class XmppSession
extends Object
implements Closeable

The base class for establishing an XMPP session with a server.

Author:

Christian Schudt

Nested Class Summary

Nested Classes

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

Constructor Summary

Constructors

Constructor and Description
XmppSession(String xmppServiceDomain, ConnectionConfiguration... connectionConfigurations) Creates a session with the specified service domain, by using the default configuration.
XmppSession(String xmppServiceDomain, XmppSessionConfiguration configuration, ConnectionConfiguration... connectionConfigurations) Creates a session with the specified service domain by using a configuration.

Method Summary

Modifier and Type	Method and Description
void	addIQListener(IQListener iqListener) Adds an IQ listener to the connection, which will get notified, whenever an IQ stanza is received.
void	addMessageListener(MessageListener messageListener) Adds a message listener to the connection, which will get notified, whenever a message is received.
void	addPresenceListener(PresenceListener presenceListener) Adds a presence listener to the connection, which will get notified, whenever a presence is received.
void	addSessionStatusListener(SessionStatusListener sessionStatusListener) Adds a session listener, which listens for session status changes.
void	close() Explicitly closes the connection and performs a clean up of all listeners.
void	connect() Connects to the XMPP server.
Connection	getActiveConnection() Gets the actively used connection.
AuthenticationManager	getAuthenticationManager() Gets the authentication manager, which is responsible for SASL negotiation.
ChatManager	getChatManager() Gets the chat manager, which is responsible for one-to-one chat sessions.
XmppSessionConfiguration	getConfiguration()
Jid	getConnectedResource() Gets the connected resource, which is assigned by the server after resource binding.
List<Connection>	getConnections() Gets an unmodifiable list of connections.
int	getDefaultTimeout() Gets the default timeout for synchronous operations.
String	getDomain() Gets the XMPP domain of the connected server.
<T extends ExtensionManager> T	getExtensionManager(Class<T> clazz)
FeaturesManager	getFeaturesManager() Gets the features manager, which is responsible for negotiating features.
Marshaller	getMarshaller() Gets the marshaller, which is used to marshal XML during writing to the output stream.
PresenceManager	getPresenceManager() Gets the presence manager, which is responsible for presence subscriptions.
ReconnectionManager	getReconnectionManager() Gets the reconnection manager, which is responsible for automatic reconnection.
RosterManager	getRosterManager() Gets the roster manager, which is responsible for retrieving, updating and deleting contacts from the roster.
XmppSession.Status	getStatus() Gets the status of the connection.
Unmarshaller	getUnmarshaller() Gets the unmarshaller, which is used to unmarshal XML during reading from the input stream.
boolean	handleElement(Object element) Handles a XMPP element.
boolean	isConnected() Indicates, whether the session is connected.
void	login(String user, String password) Authenticates against the server and binds a random resource (assigned by the server).
void	login(String user, String password, String resource) Authenticates against the server and binds a resource.
void	loginAnonymously() Logs in anonymously and binds a resource.
void	notifyException(Exception 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	reconnect() Reconnects to the XMPP server and automatically logs in by using the last known information (e.g. user name, password and bound resource).
void	removeIQListener(IQListener iqListener) Removes a previously added IQ listener from the connection.
void	removeMessageListener(MessageListener messageListener) Removes a previously added message listener from the connection.
void	removePresenceListener(PresenceListener presenceListener) Removes a previously added presence listener from the connection.
void	removeSessionStatusListener(SessionStatusListener sessionStatusListener) Removes a previously added connection listener.
void	send(ClientStreamElement element) Sends an XML element to the server, usually a stanza, i.e. a message, presence or IQ.
IQ	sendAndAwaitIQ(ClientStreamElement stanza, StanzaFilter<IQ> filter) Sends a stanza and then waits for an IQ stanza to arrive.
IQ	sendAndAwaitIQ(ClientStreamElement stanza, StanzaFilter<IQ> filter, long timeout) Sends a stanza and then waits for an IQ stanza to arrive.
Message	sendAndAwaitMessage(ClientStreamElement stanza, StanzaFilter<Message> filter) Sends a stanza and then waits for a message stanza to arrive.
Presence	sendAndAwaitPresence(ClientStreamElement stanza, StanzaFilter<Presence> filter) Sends a stanza and then waits for a presence stanza to arrive.
Presence	sendAndAwaitPresence(ClientStreamElement stanza, StanzaFilter<Presence> filter, long timeout) Sends a stanza and then waits for a presence stanza to arrive.
void	setXmppServiceDomain(String xmppServiceDomain) Sets the XMPP service domain.
protected void	waitUntilSaslNegotiationStarted() Waits until SASL negotiation has started and then releases the lock.

Methods inherited from class java.lang.Object

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

Constructor Detail

XmppSession

public XmppSession(String xmppServiceDomain,
                   ConnectionConfiguration... connectionConfigurations)

Creates a session with the specified service domain, by using the default configuration.

Parameters:

xmppServiceDomain - The service domain.

connectionConfigurations - The connection configurations.

XmppSession

public XmppSession(String xmppServiceDomain,
                   XmppSessionConfiguration configuration,
                   ConnectionConfiguration... connectionConfigurations)

Creates a session with the specified service domain by using a configuration.

Parameters:

xmppServiceDomain - The service domain.

configuration - The configuration.

connectionConfigurations - The connection configurations.

Method Detail

getActiveConnection

public Connection getActiveConnection()

Gets the actively used connection.

Returns:

The actively used connection.

setXmppServiceDomain

public void setXmppServiceDomain(String xmppServiceDomain)

Sets the XMPP service domain. This should only be set by a connection implementation.

Parameters:

xmppServiceDomain - The XMPP service domain.

addMessageListener

public final void addMessageListener(MessageListener messageListener)

Adds a message listener to the connection, which will get notified, whenever a message is received.

Parameters:

messageListener - The message listener.

See Also:

removeMessageListener(MessageListener)

removeMessageListener

public final void removeMessageListener(MessageListener messageListener)

Removes a previously added message listener from the connection.

Parameters:

messageListener - The message listener.

See Also:

addMessageListener(MessageListener)

addPresenceListener

public final void addPresenceListener(PresenceListener presenceListener)

Adds a presence listener to the connection, which will get notified, whenever a presence is received.

Parameters:

presenceListener - The presence listener.

See Also:

removePresenceListener(PresenceListener)

removePresenceListener

public final void removePresenceListener(PresenceListener presenceListener)

Removes a previously added presence listener from the connection.

Parameters:

presenceListener - The presence listener.

See Also:

addPresenceListener(PresenceListener)

addIQListener

public final void addIQListener(IQListener iqListener)

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

Parameters:

iqListener - The IQ listener.

See Also:

removeIQListener(IQListener)

removeIQListener

public final void removeIQListener(IQListener iqListener)

Removes a previously added IQ listener from the connection.

Parameters:

iqListener - The IQ listener.

See Also:

addIQListener(IQListener)

addSessionStatusListener

public final void addSessionStatusListener(SessionStatusListener 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(SessionStatusListener)

removeSessionStatusListener

public final void removeSessionStatusListener(SessionStatusListener sessionStatusListener)

Removes a previously added connection listener.

Parameters:

sessionStatusListener - The session listener.

See Also:

addSessionStatusListener(SessionStatusListener)

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

sendAndAwaitIQ

public IQ sendAndAwaitIQ(ClientStreamElement stanza,
                         StanzaFilter<IQ> filter)
                  throws NoResponseException,
                         StanzaException

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

Parameters:

stanza - The stanza, which is sent.

filter - The presence filter.

Returns:

The presence stanza.

Throws:

NoResponseException - If no IQ stanza has arrived in time.

StanzaException - If the returned IQ contains a stanza error.

sendAndAwaitIQ

public IQ sendAndAwaitIQ(ClientStreamElement stanza,
                         StanzaFilter<IQ> filter,
                         long timeout)
                  throws NoResponseException,
                         StanzaException

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

Parameters:

stanza - The stanza, which is sent.

filter - The presence filter.

timeout - The timeout.

Returns:

The presence stanza.

Throws:

NoResponseException - If no IQ stanza has arrived in time.

StanzaException - If the returned presence IQ a stanza error.

sendAndAwaitPresence

public Presence sendAndAwaitPresence(ClientStreamElement stanza,
                                     StanzaFilter<Presence> filter)
                              throws NoResponseException,
                                     StanzaException

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:

NoResponseException - If no presence stanza has arrived in time.

StanzaException - If the returned presence contains a stanza error.

sendAndAwaitPresence

public Presence sendAndAwaitPresence(ClientStreamElement stanza,
                                     StanzaFilter<Presence> filter,
                                     long timeout)
                              throws NoResponseException,
                                     StanzaException

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.

timeout - The timeout.

Returns:

The presence stanza.

Throws:

NoResponseException - If no presence stanza has arrived in time.

StanzaException - If the returned presence contains a stanza error.

sendAndAwaitMessage

public Message sendAndAwaitMessage(ClientStreamElement stanza,
                                   StanzaFilter<Message> filter)
                            throws NoResponseException,
                                   StanzaException

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:

NoResponseException - If no message stanza has arrived in time.

StanzaException - If the returned message contains a stanza error.

reconnect

public final void reconnect()
                     throws IOException,
                            LoginException

Reconnects to the XMPP server and automatically logs in by using the last known information (e.g. user name, password and bound resource).

Throws:

IOException - If an exception occurred while connecting.

LoginException - If an exception occurred while logging in.

connect

public void connect()
             throws IOException

Connects to the XMPP server.

Throws:

IOException - If anything went wrong, e.g. the host was not found.

close

public void close()
           throws IOException

Explicitly closes the connection and performs a clean up of all listeners.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

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

send

public void send(ClientStreamElement element)

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

Parameters:

element - The XML element.

login

public final void login(String user,
                        String password)
                 throws LoginException

Authenticates against the server and binds a random resource (assigned by the server).

Parameters:

user - The user name. Usually this is the local part of the user's JID. Must not be null.

password - The password. Must not be null.

Throws:

LoginException - If the login failed, due to a SASL error reported by the server.

FailedLoginException - If the login failed, due to a wrong username or password. It is thrown if the server reports a <not-authorized/> SASL error.

AccountLockedException - If the login failed, because the account has been disabled. It is thrown if the server reports a <account-disabled/> SASL error.

CredentialExpiredException - If the login failed, because the credentials have expired. It is thrown if the server reports a <credentials-expired/> SASL error.

login

public final void login(String user,
                        String password,
                        String resource)
                 throws LoginException

Authenticates against the server and binds a resource.

Parameters:

user - The user name. Usually this is the local part of the user's JID. Must not be null.

password - The password. Must not be null.

resource - The resource. If null or empty, the resource is randomly assigned by the server.

Throws:

LoginException - If the login failed, due to a SASL error reported by the server.

FailedLoginException - If the login failed, due to a wrong username or password. It is thrown if the server reports a <not-authorized/> SASL error.

AccountLockedException - If the login failed, because the account has been disabled. It is thrown if the server reports a <account-disabled/> SASL error.

CredentialExpiredException - If the login failed, because the credentials have expired. It is thrown if the server reports a <credentials-expired/> SASL error.

loginAnonymously

public final void loginAnonymously()
                            throws LoginException

Logs in anonymously and binds a resource.

Throws:

LoginException - If the anonymous login failed.

See Also:

AuthenticationManager.authenticateAnonymously()

handleElement

public final boolean handleElement(Object element)
                            throws Exception

Handles a 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:

StreamException - If the element is a stream error.

Exception - If any exception occurred during feature negotiation.

notifyException

public final void notifyException(Exception 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.

getExtensionManager

public final <T extends ExtensionManager> T getExtensionManager(Class<T> clazz)

Type Parameters:

T - The type.

Parameters:

clazz - The class of the extension manager.

Returns:

An instance of the specified extension manager.

getAuthenticationManager

public final AuthenticationManager getAuthenticationManager()

Gets the authentication manager, which is responsible for SASL negotiation.

Returns:

The authentication manager.

getRosterManager

public final RosterManager getRosterManager()

Gets the roster manager, which is responsible for retrieving, updating and deleting contacts from the roster.

Returns:

The roster manager.

getPresenceManager

public final PresenceManager getPresenceManager()

Gets the presence manager, which is responsible for presence subscriptions.

Returns:

The presence manager.

getReconnectionManager

public final ReconnectionManager getReconnectionManager()

Gets the reconnection manager, which is responsible for automatic reconnection.

Returns:

The reconnection manager.

getFeaturesManager

public final FeaturesManager getFeaturesManager()

Gets the features manager, which is responsible for negotiating features.

Returns:

The features manager.

getChatManager

public final ChatManager getChatManager()

Gets the chat manager, which is responsible for one-to-one chat sessions.

Returns:

The chat manager.

getConnectedResource

public final Jid getConnectedResource()

Gets the connected resource, which is assigned by the server after resource binding.

7.1. Fundamentals

After a client has bound a resource to the stream, it is referred to as a "connected resource".

Returns:

The connected resource.

getDomain

public final String 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.

getStatus

public final XmppSession.Status getStatus()

Gets the status of the connection.

Returns:

The status.

getConnections

public List<Connection> getConnections()

Gets an unmodifiable list of connections.

Returns:

The connections.

getUnmarshaller

public Unmarshaller getUnmarshaller()

Gets the unmarshaller, which is used to unmarshal XML during reading from the input stream.

Returns:

The unmarshaller.

getMarshaller

public Marshaller getMarshaller()

Gets the marshaller, which is used to marshal XML during writing to the output stream.

Returns:

The marshaller.

waitUntilSaslNegotiationStarted

protected final void waitUntilSaslNegotiationStarted()
                                              throws NoResponseException,
                                                     IOException

Waits until SASL negotiation has started and then releases the lock. This method must be invoked at the end of the connect() method.

Throws:

NoResponseException - If no response was received from the server.

IOException - If any exception occurred during stream negotiation.

getDefaultTimeout

public final int getDefaultTimeout()

Gets the default timeout for synchronous operations.

Returns:

The default timeout.

isConnected

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

getConfiguration

public XmppSessionConfiguration getConfiguration()