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 = new XmppClient("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.send(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) Creates a session with the specified service domain, by using the default configuration.
XmppClient(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	connect(rocks.xmpp.addr.Jid from) Connects to the XMPP server.
rocks.xmpp.addr.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.
boolean	isSupported(String feature, rocks.xmpp.addr.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.
StreamElement	send(StreamElement element) Sends an XML element to the server, usually a stanza, i.e. a message, presence or IQ.

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

addConnectionListener, addInboundIQListener, addInboundMessageListener, addInboundPresenceListener, addIQHandler, addIQHandler, addOutboundIQListener, addOutboundMessageListener, addOutboundPresenceListener, addSessionStatusListener, close, connect, createMarshaller, createUnmarshaller, disableFeature, disableFeature, enableFeature, enableFeature, getActiveConnection, getConfiguration, getConnections, getDebugger, getDomain, getEnabledFeatures, getManager, getStatus, handleElement, isConnected, notifyException, query, query, removeConnectionListener, removeInboundIQListener, removeInboundMessageListener, removeInboundPresenceListener, removeIQHandler, 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

public XmppClient(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.

XmppClient

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

connect

public final void connect(rocks.xmpp.addr.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 rocks.xmpp.addr.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 StreamElement 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.

isSupported

public final boolean isSupported(String feature,
                                 rocks.xmpp.addr.Jid jid)
                          throws XmppException

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.

Throws:

XmppException - If an error occurred while discovering support.