public abstract class XmppSession extends java.lang.Object implements StreamHandler, java.lang.AutoCloseable
The base class for different kinds of XMPP sessions.
To date there are three kinds of sessions:
XmppClient
.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.Modifier and Type | Class and Description |
---|---|
static class |
XmppSession.Status
Represents the session status.
|
Modifier and Type | Method and Description |
---|---|
void |
addConnectionListener(java.util.function.Consumer<ConnectionEvent> connectionListener)
Adds a connection listener, which is triggered, when the connection used by this session is disconnected or reconnected.
|
static void |
addCreationListener(java.util.function.Consumer<XmppSession> listener)
Adds a listener, which is triggered, whenever a new session is created.
|
void |
addInboundIQListener(java.util.function.Consumer<IQEvent> iqListener)
Adds an inbound IQ listener to the session, which will get notified, whenever an IQ stanza is received.
|
void |
addInboundMessageListener(java.util.function.Consumer<MessageEvent> messageListener)
Adds an inbound message listener to the session, which will get notified, whenever a message is received.
|
void |
addInboundPresenceListener(java.util.function.Consumer<PresenceEvent> presenceListener)
Adds an inbound presence listener to the session, which will get notified, whenever a presence is received.
|
void |
addIQHandler(java.lang.Class<?> type,
IQHandler iqHandler)
Adds an IQ handler for a given payload type.
|
void |
addIQHandler(java.lang.Class<?> type,
IQHandler iqHandler,
boolean invokeAsync)
Adds an IQ handler for a given payload type.
|
void |
addMessageAcknowledgedListener(java.util.function.Consumer<MessageEvent> messageListener)
Adds a listener, which gets called, when the server acknowledges the receipt of a message.
|
void |
addOutboundIQListener(java.util.function.Consumer<IQEvent> iqListener)
Adds an outbound IQ listener to the session, which will get notified, whenever an IQ stanza is sent.
|
void |
addOutboundMessageListener(java.util.function.Consumer<MessageEvent> messageListener)
Adds an outbound message listener to the session, which will get notified, whenever a message is sent.
|
void |
addOutboundPresenceListener(java.util.function.Consumer<PresenceEvent> presenceListener)
Adds an outbound presence listener to the session, which will get notified, whenever a presence is sent.
|
void |
addSendFailedListener(java.util.function.BiConsumer<StreamElement,java.lang.Throwable> sendFailedListener)
Adds a listener, which gets called, whenever a stream element (e.g. message) has been sent unsuccessfully.
|
void |
addSendSucceededListener(java.util.function.Consumer<StreamElement> sendSucceededListener)
Adds a listener, which gets called, whenever a stream element (e.g. message) has been sent successfully.
|
void |
addSessionStatusListener(java.util.function.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) |
javax.xml.bind.Marshaller |
createMarshaller()
Creates a marshaller, which can be used to create XML from objects.
|
javax.xml.bind.Unmarshaller |
createUnmarshaller()
Creates a new unmarshaller, which can be used to unmarshal XML to objects.
|
void |
disableFeature(java.lang.Class<? extends Manager> managerClass)
Disables a feature by its manager class.
|
void |
disableFeature(java.lang.String name)
Disables a feature by its name, usually a protocol namespace.
|
void |
enableFeature(java.lang.Class<? extends Manager> managerClass)
Enables a feature by its manager class.
|
void |
enableFeature(java.lang.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.
|
java.util.List<ClientConnectionConfiguration> |
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.
|
java.util.Set<java.lang.String> |
getEnabledFeatures()
Gets the enabled features.
|
<T extends Manager> |
getManager(java.lang.Class<T> clazz)
Gets an instance of the specified manager class.
|
XmppSession.Status |
getStatus()
Gets the status of the session.
|
java.util.Queue<Stanza> |
getUnacknowledgedStanzas() |
boolean |
handleElement(java.lang.Object element)
Handles an XMPP element.
|
boolean |
isAuthenticated()
Returns true, if the session is authenticated.
|
boolean |
isConnected()
Indicates, whether the session is connected.
|
AsyncResult<java.lang.Boolean> |
isSupported(java.lang.String feature,
Jid jid)
Determines support of another XMPP entity for a given feature.
|
void |
markAcknowledged(Stanza acknowledgedStanza)
Marks a stanza as acknowledged.
|
void |
notifyException(java.lang.Throwable e)
Called if any unhandled exception is thrown during reading or writing.
|
AsyncResult<IQ> |
query(IQ iq)
Sends an
<iq/> stanza and returns an async result, which can be used to wait for the response. |
<T> AsyncResult<T> |
query(IQ iq,
java.lang.Class<T> clazz)
Sends an
<iq/> stanza and returns an async result, which can be used to wait for the response. |
AsyncResult<IQ> |
query(IQ iq,
java.time.Duration timeout)
Sends an
<iq/> stanza and returns an async result, which can be used to wait for the response. |
void |
removeConnectionListener(java.util.function.Consumer<ConnectionEvent> connectionListener)
Removes a previously added connection listener.
|
static void |
removeCreationListener(java.util.function.Consumer<XmppSession> listener)
Removes a previously added creation listener.
|
void |
removeInboundIQListener(java.util.function.Consumer<IQEvent> iqListener)
Removes a previously added inbound IQ listener from the session.
|
void |
removeInboundMessageListener(java.util.function.Consumer<MessageEvent> messageListener)
Removes a previously added inbound message listener from the session.
|
void |
removeInboundPresenceListener(java.util.function.Consumer<PresenceEvent> presenceListener)
Removes a previously added inbound presence listener from the session.
|
void |
removeIQHandler(java.lang.Class<?> type)
Removes an IQ handler.
|
void |
removeMessageAcknowledgedListener(java.util.function.Consumer<MessageEvent> messageListener)
Removes a previously added message acknowledge listener.
|
void |
removeOutboundIQListener(java.util.function.Consumer<IQEvent> iqListener)
Removes a previously added outbound IQ listener from the session.
|
void |
removeOutboundMessageListener(java.util.function.Consumer<MessageEvent> messageListener)
Removes a previously added outbound message listener from the session.
|
void |
removeOutboundPresenceListener(java.util.function.Consumer<PresenceEvent> presenceListener)
Removes a previously added outbound presence listener from the session.
|
void |
removeSendFailedListener(java.util.function.BiConsumer<StreamElement,java.lang.Throwable> sendFailedListener)
Removes a previously added send failed listener.
|
void |
removeSendSucceededListener(java.util.function.Consumer<StreamElement> sendSucceededListener)
Removes a previously added send succeeded listener.
|
void |
removeSessionStatusListener(java.util.function.Consumer<SessionStatusEvent> sessionStatusListener)
Removes a previously added session listener.
|
java.util.concurrent.Future<java.lang.Void> |
send(StreamElement element)
Sends an XML element to the server, usually a stanza, i.e. a message, presence or IQ.
|
AsyncResult<Message> |
sendAndAwaitMessage(Message stanza,
java.util.function.Predicate<Message> filter)
Sends a stanza and returns an async result which can wait for the message stanza, which matches the predicate, to arrive.
|
AsyncResult<Presence> |
sendAndAwaitPresence(Presence stanza,
java.util.function.Predicate<Presence> filter)
Sends a stanza and returns an async result which can wait for the presence stanza, which matches the predicate, to arrive.
|
SendTask<IQ> |
sendIQ(IQ iq)
Sends an IQ.
|
SendTask<Message> |
sendMessage(Message message)
Sends a message.
|
SendTask<Presence> |
sendPresence(Presence presence)
Sends a presence.
|
public static void addCreationListener(java.util.function.Consumer<XmppSession> listener)
Adds a listener, which is triggered, whenever a new session is created.
listener
- The listener.removeCreationListener(Consumer)
public static void removeCreationListener(java.util.function.Consumer<XmppSession> listener)
Removes a previously added creation listener.
listener
- The listener.addCreationListener(Consumer)
public final void connect() throws XmppException
Connects to the XMPP server.
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.public abstract void connect(Jid from) throws XmppException
XmppException
public final void addInboundMessageListener(java.util.function.Consumer<MessageEvent> messageListener)
Adds an inbound message listener to the session, which will get notified, whenever a message is received.
messageListener
- The message listener.removeInboundMessageListener(Consumer)
public final void removeInboundMessageListener(java.util.function.Consumer<MessageEvent> messageListener)
Removes a previously added inbound message listener from the session.
messageListener
- The message listener.addInboundMessageListener(Consumer)
public final void addOutboundMessageListener(java.util.function.Consumer<MessageEvent> messageListener)
Adds an outbound message listener to the session, which will get notified, whenever a message is sent.
messageListener
- The message listener.removeOutboundMessageListener(Consumer)
public final void removeOutboundMessageListener(java.util.function.Consumer<MessageEvent> messageListener)
Removes a previously added outbound message listener from the session.
messageListener
- The message listener.addOutboundMessageListener(Consumer)
public final void addInboundPresenceListener(java.util.function.Consumer<PresenceEvent> presenceListener)
Adds an inbound presence listener to the session, which will get notified, whenever a presence is received.
presenceListener
- The presence listener.removeInboundPresenceListener(Consumer)
public final void removeInboundPresenceListener(java.util.function.Consumer<PresenceEvent> presenceListener)
Removes a previously added inbound presence listener from the session.
presenceListener
- The presence listener.addInboundPresenceListener(Consumer)
public final void addOutboundPresenceListener(java.util.function.Consumer<PresenceEvent> presenceListener)
Adds an outbound presence listener to the session, which will get notified, whenever a presence is sent.
presenceListener
- The presence listener.removeOutboundPresenceListener(Consumer)
public final void removeOutboundPresenceListener(java.util.function.Consumer<PresenceEvent> presenceListener)
Removes a previously added outbound presence listener from the session.
presenceListener
- The presence listener.addOutboundPresenceListener(Consumer)
public final void addInboundIQListener(java.util.function.Consumer<IQEvent> iqListener)
Adds an inbound IQ listener to the session, which will get notified, whenever an IQ stanza is received.
iqListener
- The IQ listener.removeInboundIQListener(Consumer)
public final void removeInboundIQListener(java.util.function.Consumer<IQEvent> iqListener)
Removes a previously added inbound IQ listener from the session.
iqListener
- The IQ listener.addInboundIQListener(Consumer)
public final void addOutboundIQListener(java.util.function.Consumer<IQEvent> iqListener)
Adds an outbound IQ listener to the session, which will get notified, whenever an IQ stanza is sent.
iqListener
- The IQ listener.removeOutboundIQListener(Consumer)
public final void removeOutboundIQListener(java.util.function.Consumer<IQEvent> iqListener)
Removes a previously added outbound IQ listener from the session.
iqListener
- The IQ listener.addOutboundIQListener(Consumer)
public final void addMessageAcknowledgedListener(java.util.function.Consumer<MessageEvent> messageListener)
Adds a listener, which gets called, when the server acknowledges the receipt of a message.
messageListener
- The message listener.removeMessageAcknowledgedListener(Consumer)
public final void removeMessageAcknowledgedListener(java.util.function.Consumer<MessageEvent> messageListener)
Removes a previously added message acknowledge listener.
messageListener
- The message listener.addMessageAcknowledgedListener(Consumer)
public final void addSendSucceededListener(java.util.function.Consumer<StreamElement> sendSucceededListener)
Adds a listener, which gets called, whenever a stream element (e.g. message) has been sent successfully.
sendSucceededListener
- The listener.removeSendSucceededListener(Consumer)
public final void removeSendSucceededListener(java.util.function.Consumer<StreamElement> sendSucceededListener)
Removes a previously added send succeeded listener.
sendSucceededListener
- The listener.addSendSucceededListener(Consumer)
public final void addSendFailedListener(java.util.function.BiConsumer<StreamElement,java.lang.Throwable> sendFailedListener)
Adds a listener, which gets called, whenever a stream element (e.g. message) has been sent unsuccessfully.
sendFailedListener
- The listener.removeSendFailedListener(BiConsumer)
public final void removeSendFailedListener(java.util.function.BiConsumer<StreamElement,java.lang.Throwable> sendFailedListener)
Removes a previously added send failed listener.
sendFailedListener
- The listener.addSendFailedListener(BiConsumer)
,
addSendSucceededListener(Consumer)
public final void addIQHandler(java.lang.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.
type
- The payload type.iqHandler
- The IQ handler.removeIQHandler(Class)
,
addIQHandler(Class, IQHandler, boolean)
public final void addIQHandler(java.lang.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.
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.removeIQHandler(Class)
public final void removeIQHandler(java.lang.Class<?> type)
Removes an IQ handler.
type
- The payload type.addIQHandler(Class, IQHandler)
public final void addSessionStatusListener(java.util.function.Consumer<SessionStatusEvent> sessionStatusListener)
Adds a session listener, which listens for session status changes. Each time the session status changes, all listeners will be notified.
sessionStatusListener
- The session listener.removeSessionStatusListener(Consumer)
public final void removeSessionStatusListener(java.util.function.Consumer<SessionStatusEvent> sessionStatusListener)
Removes a previously added session listener.
sessionStatusListener
- The session listener.addSessionStatusListener(Consumer)
public final void addConnectionListener(java.util.function.Consumer<ConnectionEvent> connectionListener)
Adds a connection listener, which is triggered, when the connection used by this session is disconnected or reconnected.
connectionListener
- The connection listener.removeConnectionListener(Consumer)
public final void removeConnectionListener(java.util.function.Consumer<ConnectionEvent> connectionListener)
Removes a previously added connection listener.
connectionListener
- The connection listener.addConnectionListener(Consumer)
public final AsyncResult<IQ> query(IQ iq)
Sends an <iq/>
stanza and returns an async result, which can be used to wait for the response. The result is completed if the response IQ has arrived or the default timeout has exceeded, in which case the result completes with a NoResponseException
.
public final AsyncResult<IQ> query(IQ iq, java.time.Duration timeout)
Sends an <iq/>
stanza and returns an async result, which can be used to wait for the response. The result is completed if the response IQ has arrived or the timeout has exceeded, in which case the result completes with a NoResponseException
.
public final <T> AsyncResult<T> query(IQ iq, java.lang.Class<T> clazz)
Sends an <iq/>
stanza and returns an async result, which can be used to wait for the response. The result is completed if the response IQ has arrived or the default timeout has exceeded, in which case the result completes with a NoResponseException
. The payload of the response IQ is returned in the async result class.
public final AsyncResult<Presence> sendAndAwaitPresence(Presence stanza, java.util.function.Predicate<Presence> filter)
Sends a stanza and returns an async result which can wait for the presence stanza, which matches the predicate, to arrive.
stanza
- The stanza, which is sent.filter
- The presence filter.public final AsyncResult<Message> sendAndAwaitMessage(Message stanza, java.util.function.Predicate<Message> filter)
Sends a stanza and returns an async result which can wait for the message stanza, which matches the predicate, to arrive.
stanza
- The stanza, which is sent.filter
- The message filter.public final Connection getActiveConnection()
Gets the actively used connection.
public java.util.concurrent.Future<java.lang.Void> send(StreamElement element)
Sends an XML element to the server, usually a stanza, i.e. a message, presence or IQ.
element
- The XML element.Message
is translated to a ClientMessage
.public SendTask<IQ> sendIQ(IQ iq)
Sends an IQ.
iq
- The IQ.public SendTask<Message> sendMessage(Message message)
Sends a message.
message
- The message.public SendTask<Presence> sendPresence(Presence presence)
Sends a presence.
presence
- The presence.public final XmppSession.Status getStatus()
Gets the status of the session.
public final java.util.List<ClientConnectionConfiguration> getConnections()
Gets an unmodifiable list of connections, which this session will try during connecting.
public final javax.xml.bind.Unmarshaller createUnmarshaller()
Creates a new unmarshaller, which can be used to unmarshal XML to objects.
Note that the returned unmarshaller is not thread-safe.
createMarshaller()
public final javax.xml.bind.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).
createUnmarshaller()
public final boolean isConnected()
Indicates, whether the session is connected.
XmppSession.Status.CONNECTED
, XmppSession.Status.AUTHENTICATED
or XmppSession.Status.AUTHENTICATING
.getStatus()
public final boolean isAuthenticated()
Returns true, if the session is authenticated. For a normal client-to-server session this means, when the user has logged in (successfully completed SASL negotiation and resource binding).
public boolean handleElement(java.lang.Object element) throws XmppException
Handles an XMPP element.
This method should be called on the reader thread.
handleElement
in interface StreamHandler
element
- The XMPP element.StreamErrorException
- If the element is a stream error.StreamNegotiationException
- If any exception occurred during stream feature negotiation.XmppException
- If any other XMPP exception occurs.public final <T extends Manager> T getManager(java.lang.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
.
T
- The type.clazz
- The class of the manager.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.
close
in interface java.lang.AutoCloseable
XmppException
- If an exception occurs while closing the connection, e.g. the underlying socket connection.public void notifyException(java.lang.Throwable e)
Called if any unhandled exception is thrown during reading or writing.
This method will close the stream.
e
- The exception. If an unrecoverable XMPP stream error occurred, the exception is a StreamError
.public 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.
public final XmppSessionConfiguration getConfiguration()
Gets the configuration for this session.
public final XmppDebugger getDebugger()
Gets the debugger or null if no debugger class was specified in the configuration.
XmppSessionConfiguration.getDebugger()
public final void enableFeature(java.lang.String name)
Enables a feature by its name, usually a protocol namespace.
name
- The associated manager class.public final void disableFeature(java.lang.String name)
Disables a feature by its name, usually a protocol namespace.
name
- The associated manager class.public final void enableFeature(java.lang.Class<? extends Manager> managerClass)
Enables a feature by its manager class.
managerClass
- The associated manager class.public final void disableFeature(java.lang.Class<? extends Manager> managerClass)
Disables a feature by its manager class.
managerClass
- The associated manager class.public final java.util.Set<java.lang.String> getEnabledFeatures()
Gets the enabled features.
public abstract Jid getConnectedResource()
The connected resource, which is assigned by the server.
public final java.util.Queue<Stanza> getUnacknowledgedStanzas()
public final void markAcknowledged(Stanza acknowledgedStanza)
Marks a stanza as acknowledged. This method removes a stanza from the unacknowledged queue, so that it won’t be resent during reconnection and notifies the acknowledged listeners.
acknowledgedStanza
- The acknowledged stanza.addMessageAcknowledgedListener(Consumer)
public final AsyncResult<java.lang.Boolean> isSupported(java.lang.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.feature
- The feature, usually defined by an XMPP Extension Protocol, e.g. “urn:xmpp:ping”.jid
- The XMPP entity.Copyright © 2014–2019 XMPP.rocks. All rights reserved.