rocks.xmpp.core.session

Class XmppClient

java.lang.Object

rocks.xmpp.core.session.XmppSession

rocks.xmpp.core.session.XmppClient

All Implemented Interfaces:

AutoCloseable

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, TcpConnectionConfiguration, BoshConnectionConfiguration

Nested Class Summary

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

XmppSession.Status

Constructor Summary

Constructors

Constructor and Description
XmppClient(String xmppServiceDomain, ConnectionConfiguration... connectionConfigurations) Deprecated. Use create(String, ConnectionConfiguration...)
XmppClient(String xmppServiceDomain, XmppSessionConfiguration configuration, ConnectionConfiguration... connectionConfigurations) Deprecated. Use create(String, XmppSessionConfiguration, ConnectionConfiguration...)

Method Summary

Modifier and Type	Method and Description
void	connect(Jid from) Connects to the XMPP server.
static XmppClient	create(String xmppServiceDomain, ConnectionConfiguration... connectionConfigurations) Creates a new XMPP client instance.
static XmppClient	create(String xmppServiceDomain, XmppSessionConfiguration configuration, ConnectionConfiguration... 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.
AsyncResult<Boolean>	isSupported(String feature, Jid jid) Determines support of another XMPP entity for a given feature.
byte[]	login(String authorizationId, CallbackHandler callbackHandler, String resource) Authenticates against the server with a custom callback handler and binds a resource.
byte[]	login(String user, String password) Authenticates against the server and binds a random resource (assigned by the server).
byte[]	login(String user, String password, String resource) Authenticates against the server with username/password credential and binds a resource.
byte[]	login(String authorizationId, String user, String password, 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.
Future<?>	send(StreamElement element) Sends an XML element to the server, usually a stanza, i.e. a message, presence or IQ.
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 rocks.xmpp.core.session.XmppSession

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

Methods inherited from class java.lang.Object

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

Constructor Detail

XmppClient

@Deprecated
public XmppClient(String xmppServiceDomain,
                              ConnectionConfiguration... connectionConfigurations)

Deprecated. Use create(String, ConnectionConfiguration...)

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

Parameters:

xmppServiceDomain - The service domain.

connectionConfigurations - The connection configurations.

XmppClient

@Deprecated
public XmppClient(String xmppServiceDomain,
                              XmppSessionConfiguration configuration,
                              ConnectionConfiguration... connectionConfigurations)

Deprecated. Use create(String, XmppSessionConfiguration, ConnectionConfiguration...)

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

create

public static XmppClient create(String xmppServiceDomain,
                                ConnectionConfiguration... 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(String xmppServiceDomain,
                                XmppSessionConfiguration configuration,
                                ConnectionConfiguration... 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.

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

login

public final byte[] login(String user,
                          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.

StanzaException - 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(String user,
                          String password,
                          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.

StanzaException - 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(String authorizationId,
                          String user,
                          String password,
                          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.

StanzaException - 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(String authorizationId,
                          CallbackHandler callbackHandler,
                          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.

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

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

send

public final Future<?> send(StreamElement element)

Description copied from class: XmppSession

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

Overrides:

send in class XmppSession

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 final SendTask<IQ> sendIQ(IQ iq)

Description copied from class: XmppSession

Sends an IQ.

Specified by:

sendIQ in class XmppSession

Parameters:

iq - The IQ.

Returns:

The send task, which allows to track the stanza.

sendMessage

public final SendTask<Message> sendMessage(Message message)

Description copied from class: XmppSession

Sends a message.

Specified by:

sendMessage in class XmppSession

Parameters:

message - The message.

Returns:

The send task, which allows to track the stanza.

sendPresence

public final SendTask<Presence> sendPresence(Presence presence)

Description copied from class: XmppSession

Sends a presence.

Specified by:

sendPresence in class XmppSession

Parameters:

presence - The presence.

Returns:

The send task, which allows to track the stanza.

isSupported

public final AsyncResult<Boolean> isSupported(String feature,
                                              Jid jid)

Determines support of another XMPP entity for a given feature.

Note that if you want to determine support of another client, you have to provide that client's full JID (user@domain/resource). If you want to determine the server's capabilities provide only the domain JID of the server.

This method uses cached information and the presence based entity capabilities (XEP-0115) to determine support. Only if no information is available an explicit service discovery request is made.

Parameters:

feature - The feature, usually defined by an XMPP Extension Protocol, e.g. "urn:xmpp:ping".

jid - The XMPP entity.

Returns:

True, if the XMPP entity supports the given feature; otherwise false.