rocks.xmpp.core.session

Class XmppClient

java.lang.Object

rocks.xmpp.core.session.XmppSession

rocks.xmpp.core.session.XmppClient

All Implemented Interfaces:

java.lang.AutoCloseable, StreamHandler

public final class XmppClient
extends XmppSession

The base class for establishing an XMPP session with a server, i.e. client-to-server sessions.

Establishing an XMPP Session

The following example shows the most simple way to establish a session:

XmppClient xmppClient = XmppClient.create("domain");
xmppClient.connect();
xmppClient.login("username", "password");

By default, the session will try to establish a TCP connection over port 5222 and will try BOSH as fallback. You can configure a session and its connection methods by passing appropriate configurations in its constructor.

Sending Messages

Once connected, you can send messages:

xmppClient.sendMessage(new Message(Jid.of("juliet@example.net"), Message.Type.CHAT));

Closing the Session

xmppClient.close();

Listening for Messages and Presence

Note: Adding the following listeners should be added before logging in, otherwise they might not trigger.

// Listen for messages
xmppClient.addInboundMessageListener(e ->
// Handle inbound message.
);
// Listen for presence changes
xmppClient.addInboundPresenceListener(e ->
// Handle inbound presence.
);

This class is thread-safe, which means you can safely add listeners or call send(), close() (and other methods) from different threads.

See Also:

XmppSessionConfiguration, SocketConnectionConfiguration, BoshConnectionConfiguration

Nested Class Summary

Nested classes/interfaces inherited from class rocks.xmpp.core.session.XmppSession

XmppSession.Status

Method Summary

Modifier and Type	Method and Description
void	connect(Jid from) Connects to the XMPP server.
static XmppClient	create(java.lang.String xmppServiceDomain, ClientConnectionConfiguration... connectionConfigurations) Creates a new XMPP client instance.
static XmppClient	create(java.lang.String xmppServiceDomain, XmppSessionConfiguration configuration, ClientConnectionConfiguration... connectionConfigurations) Creates a new XMPP client instance.
Jid	getConnectedResource() Gets the connected resource, which is assigned by the server after resource binding.
boolean	isAnonymous() Indicates whether the session has been logged in anonymously.
byte[]	login(java.lang.String authorizationId, javax.security.auth.callback.CallbackHandler callbackHandler, java.lang.String resource) Authenticates against the server with a custom callback handler and binds a resource.
byte[]	login(java.lang.String user, java.lang.String password) Authenticates against the server and binds a random resource (assigned by the server).
byte[]	login(java.lang.String user, java.lang.String password, java.lang.String resource) Authenticates against the server with username/password credential and binds a resource.
byte[]	login(java.lang.String authorizationId, java.lang.String user, java.lang.String password, java.lang.String resource) Authenticates against the server with an authorization id and username/password credential and binds a resource.
byte[]	loginAnonymously() Logs in anonymously and binds a resource.

Methods inherited from class rocks.xmpp.core.session.XmppSession

addConnectionListener, addCreationListener, addInboundIQListener, addInboundMessageListener, addInboundPresenceListener, addIQHandler, addIQHandler, addMessageAcknowledgedListener, addOutboundIQListener, addOutboundMessageListener, addOutboundPresenceListener, addSendFailedListener, addSendSucceededListener, addSessionStatusListener, close, connect, createMarshaller, createUnmarshaller, disableFeature, disableFeature, enableFeature, enableFeature, getActiveConnection, getConfiguration, getConnections, getDebugger, getDomain, getEnabledFeatures, getManager, getStatus, getUnacknowledgedStanzas, handleElement, isAuthenticated, isConnected, isSupported, markAcknowledged, notifyException, query, query, query, removeConnectionListener, removeCreationListener, removeInboundIQListener, removeInboundMessageListener, removeInboundPresenceListener, removeIQHandler, removeMessageAcknowledgedListener, removeOutboundIQListener, removeOutboundMessageListener, removeOutboundPresenceListener, removeSendFailedListener, removeSendSucceededListener, removeSessionStatusListener, send, sendAndAwaitMessage, sendAndAwaitPresence, sendIQ, sendMessage, sendPresence

Methods inherited from class java.lang.Object

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

Method Detail

create

public static XmppClient create(java.lang.String xmppServiceDomain,
                                ClientConnectionConfiguration... connectionConfigurations)

Creates a new XMPP client instance. Any registered creation listeners are triggered.

Parameters:

xmppServiceDomain - The XMPP service domain.

connectionConfigurations - The connection methods, which are used to connect.

Returns:

The XMPP client.

create

public static XmppClient create(java.lang.String xmppServiceDomain,
                                XmppSessionConfiguration configuration,
                                ClientConnectionConfiguration... connectionConfigurations)

Creates a new XMPP client instance. Any registered creation listeners are triggered.

Parameters:

xmppServiceDomain - The XMPP service domain.

configuration - The configuration.

connectionConfigurations - The connection methods, which are used to connect.

Returns:

The XMPP client.

connect

public final void connect(Jid from)
                   throws XmppException

Connects to the XMPP server.

Specified by:

connect in class XmppSession

Parameters:

from - The ‘from’ attribute.

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.

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

login

public final byte[] login(java.lang.String user,
                          java.lang.String password)
                   throws XmppException

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.

Returns:

The additional data with success, i.e. the data returned upon successful authentication.

Throws:

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

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.

StanzaErrorException - If the server returned a stanza error during resource binding or roster retrieval.

XmppException - If the login failed, due to another error.

login

public final byte[] login(java.lang.String user,
                          java.lang.String password,
                          java.lang.String resource)
                   throws XmppException

Authenticates against the server with username/password credential 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.

Returns:

The additional data with success, i.e. the data returned upon successful authentication.

Throws:

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

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.

StanzaErrorException - If the server returned a stanza error during resource binding or roster retrieval.

XmppException - If the login failed, due to another error.

login

public final byte[] login(java.lang.String authorizationId,
                          java.lang.String user,
                          java.lang.String password,
                          java.lang.String resource)
                   throws XmppException

Authenticates against the server with an authorization id and username/password credential and binds a resource.

Parameters:

authorizationId - The authorization id.

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.

Returns:

The additional data with success, i.e. the data returned upon successful authentication.

Throws:

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

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.

StanzaErrorException - If the server returned a stanza error during resource binding or roster retrieval.

XmppException - If the login failed, due to another error.

login

public final byte[] login(java.lang.String authorizationId,
                          javax.security.auth.callback.CallbackHandler callbackHandler,
                          java.lang.String resource)
                   throws XmppException

Authenticates against the server with a custom callback handler and binds a resource.

Parameters:

authorizationId - The authorization id.

callbackHandler - The callback handler.

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

Returns:

The additional data with success, i.e. the data returned upon successful authentication.

Throws:

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

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.

StanzaErrorException - If the server returned a stanza error during resource binding or roster retrieval.

XmppException - If the login failed, due to another error.

loginAnonymously

public final byte[] loginAnonymously()
                              throws XmppException

Logs in anonymously and binds a resource.

Returns:

The additional data with success, i.e. the data returned upon successful authentication.

Throws:

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

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.

StanzaErrorException - If the server returned a stanza error during resource binding.

XmppException - If the login failed, due to another error.

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”.

Specified by:

getConnectedResource in class XmppSession

Returns:

The connected resource.

isAnonymous

public final boolean isAnonymous()

Indicates whether the session has been logged in anonymously. If never logged in at all, returns false.

Returns:

True, if the session is anonymous.