Package rocks.xmpp.core.session

Class XmppSession

    • Method Detail

      • addInboundMessageListener

        public final void addInboundMessageListener​(Consumer<MessageEvent> messageListener)
        Adds an inbound message listener to the session, which will get notified, whenever a message is received.
        Parameters:
        messageListener - The message listener.
        See Also:
        removeInboundMessageListener(Consumer)

      • removeInboundMessageListener

        public final void removeInboundMessageListener​(Consumer<MessageEvent> messageListener)
        Removes a previously added inbound message listener from the session.
        Parameters:
        messageListener - The message listener.
        See Also:
        addInboundMessageListener(Consumer)

      • addOutboundMessageListener

        public final void addOutboundMessageListener​(Consumer<MessageEvent> messageListener)
        Adds an outbound message listener to the session, which will get notified, whenever a message is sent.
        Parameters:
        messageListener - The message listener.
        See Also:
        removeOutboundMessageListener(Consumer)

      • removeOutboundMessageListener

        public final void removeOutboundMessageListener​(Consumer<MessageEvent> messageListener)
        Removes a previously added outbound message listener from the session.
        Parameters:
        messageListener - The message listener.
        See Also:
        addOutboundMessageListener(Consumer)

      • addInboundPresenceListener

        public final void addInboundPresenceListener​(Consumer<PresenceEvent> presenceListener)
        Adds an inbound presence listener to the session, which will get notified, whenever a presence is received.
        Parameters:
        presenceListener - The presence listener.
        See Also:
        removeInboundPresenceListener(Consumer)

      • removeInboundPresenceListener

        public final void removeInboundPresenceListener​(Consumer<PresenceEvent> presenceListener)
        Removes a previously added inbound presence listener from the session.
        Parameters:
        presenceListener - The presence listener.
        See Also:
        addInboundPresenceListener(Consumer)

      • addOutboundPresenceListener

        public final void addOutboundPresenceListener​(Consumer<PresenceEvent> presenceListener)
        Adds an outbound presence listener to the session, which will get notified, whenever a presence is sent.
        Parameters:
        presenceListener - The presence listener.
        See Also:
        removeOutboundPresenceListener(Consumer)

      • removeOutboundPresenceListener

        public final void removeOutboundPresenceListener​(Consumer<PresenceEvent> presenceListener)
        Removes a previously added outbound presence listener from the session.
        Parameters:
        presenceListener - The presence listener.
        See Also:
        addOutboundPresenceListener(Consumer)

      • addInboundIQListener

        public final void addInboundIQListener​(Consumer<IQEvent> iqListener)
        Adds an inbound IQ listener to the session, which will get notified, whenever an IQ stanza is received.
        Parameters:
        iqListener - The IQ listener.
        See Also:
        removeInboundIQListener(Consumer)

      • removeInboundIQListener

        public final void removeInboundIQListener​(Consumer<IQEvent> iqListener)
        Removes a previously added inbound IQ listener from the session.
        Parameters:
        iqListener - The IQ listener.
        See Also:
        addInboundIQListener(Consumer)

      • addOutboundIQListener

        public final void addOutboundIQListener​(Consumer<IQEvent> iqListener)
        Adds an outbound IQ listener to the session, which will get notified, whenever an IQ stanza is sent.
        Parameters:
        iqListener - The IQ listener.
        See Also:
        removeOutboundIQListener(Consumer)

      • removeOutboundIQListener

        public final void removeOutboundIQListener​(Consumer<IQEvent> iqListener)
        Removes a previously added outbound IQ listener from the session.
        Parameters:
        iqListener - The IQ listener.
        See Also:
        addOutboundIQListener(Consumer)

      • addMessageAcknowledgedListener

        public final void addMessageAcknowledgedListener​(Consumer<MessageEvent> messageListener)
        Adds a listener, which gets called, when the server acknowledges the receipt of a message.
        Parameters:
        messageListener - The message listener.
        See Also:
        removeMessageAcknowledgedListener(Consumer)

      • addSendSucceededListener

        public final void addSendSucceededListener​(Consumer<StreamElement> sendSucceededListener)
        Adds a listener, which gets called, whenever a stream element (e.g. message) has been sent successfully.
        Parameters:
        sendSucceededListener - The listener.
        See Also:
        removeSendSucceededListener(Consumer)

      • removeSendSucceededListener

        public final void removeSendSucceededListener​(Consumer<StreamElement> sendSucceededListener)
        Removes a previously added send succeeded listener.
        Parameters:
        sendSucceededListener - The listener.
        See Also:
        addSendSucceededListener(Consumer)

      • addIQHandler

        public final void addIQHandler​(IQHandler iqHandler)
        Adds an IQ handler for a given payload type. The handler will process the IQ stanzas asynchronously, but in order, i.e. IQ stanzas handled by the same handler are handled synchronously, but IQ stanzas with different payloads can be handled in parallel.
        Parameters:
        iqHandler - The IQ handler.
        See Also:
        removeIQHandler(IQHandler)

      • addIQHandler

        @Deprecated
public final void addIQHandler​(IQHandler iqHandler,
                               boolean invokeAsync)
        Deprecated.
        Simply use addIQHandler(IQHandler), this method now behaves the same.
        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.
        Parameters:
        iqHandler - The IQ handler.
        invokeAsync - True, if the handler should be processed asynchronously; false, if the handler should be processed asynchronously.
        See Also:
        removeIQHandler(IQHandler)

      • removeIQHandler

        public final void removeIQHandler​(IQHandler iqHandler)
        Removes an IQ handler.
        Parameters:
        iqHandler - The IQ handler.
        See Also:
        addIQHandler(IQHandler)

      • addConnectionListener

        public final void addConnectionListener​(Consumer<ConnectionEvent> connectionListener)
        Adds a connection listener, which is triggered, when the connection used by this session is disconnected or reconnected.
        Parameters:
        connectionListener - The connection listener.
        See Also:
        removeConnectionListener(Consumer)

      • query

        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.
        Parameters:
        iq - The <iq/> stanza, which must be of type get or set.
        Returns:
        The async IQ result.

      • query

        public final AsyncResult<IQ> query​(IQ iq,
                                   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.
        Parameters:
        iq - The <iq/> stanza, which must be of type get or set.
        timeout - The timeout.
        Returns:
        The async IQ result.

      • query

        public final <T> AsyncResult<T> query​(IQ iq,
                                      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.
        Type Parameters:
        T - The type.
        Parameters:
        iq - The <iq/> stanza, which must be of type get or set.
        clazz - The class which is IQ response's payload.
        Returns:
        The async result with the IQ response's payload.

      • sendAndAwaitPresence

        public final AsyncResult<Presence> sendAndAwaitPresence​(Presence stanza,
                                                        Predicate<Presence> filter)
        Sends a stanza and returns an async result which can wait for the presence stanza, which matches the predicate, to arrive.
        Parameters:
        stanza - The stanza, which is sent.
        filter - The presence filter.
        Returns:
        The async presence result.

      • sendAndAwaitMessage

        public final AsyncResult<Message> sendAndAwaitMessage​(Message stanza,
                                                      Predicate<Message> filter)
        Sends a stanza and returns an async result which can wait for the message stanza, which matches the predicate, to arrive.
        Parameters:
        stanza - The stanza, which is sent.
        filter - The message filter.
        Returns:
        The async message result.

      • getActiveConnection

        public final Connection getActiveConnection()
        Gets the actively used connection.
        Returns:
        The actively used connection.

      • send

        public AsyncResult<Void> send​(StreamElement element)
        Sends an XML element to the server, usually a stanza, i.e. a message, presence or IQ.
        Specified by:
        send in interface Session
        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 SendTask<IQ> sendIQ​(IQ iq)
        Sends an IQ.
        Parameters:
        iq - The IQ.
        Returns:
        The send task, which allows to track the stanza.

      • sendMessage

        public SendTask<Message> sendMessage​(Message message)
        Sends a message.
        Parameters:
        message - The message.
        Returns:
        The send task, which allows to track the stanza.

      • sendPresence

        public SendTask<Presence> sendPresence​(Presence presence)
        Sends a presence.
        Parameters:
        presence - The presence.
        Returns:
        The send task, which allows to track the stanza.

      • getStatus

        public final XmppSession.Status getStatus()
        Gets the status of the session.
        Returns:
        The status.

      • getConnections

        public final List<ClientConnectionConfiguration> getConnections()
        Gets an unmodifiable list of connections, which this session will try during connecting.
        Returns:
        The connections.

      • createUnmarshaller

        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.

        Returns:
        The unmarshaller.
        See Also:
        createMarshaller()

      • createUnmarshaller

        public final javax.xml.bind.Unmarshaller createUnmarshaller​(Locale rootLocale)
        Creates a new unmarshaller with a default locale. If child objects have not explicitly set a locale, the default locale is assigned to them.

        Note that the returned unmarshaller is not thread-safe.

        Parameters:
        rootLocale - The root locale, usually set in the stream header.
        Returns:
        The unmarshaller.
        See Also:
        createUnmarshaller()

      • 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).

        Note that the returned unmarshaller is not thread-safe.

        Returns:
        The marshaller.
        See Also:
        createUnmarshaller()

      • isAuthenticated

        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).
        Returns:
        True, if authenticated.
        Since:
        0.7.0

      • handleElement

        public boolean handleElement​(Object element)
                      throws XmppException
        Handles an XMPP element.

        This method should be called on the reader thread.

        Specified by:
        handleElement in interface StreamHandler
        Parameters:
        element - The XMPP element.
        Returns:
        True, if the stream needs to be restarted; otherwise false.
        Throws:
        StreamErrorException - If the element is a stream error.
        StreamNegotiationException - If any exception occurred during stream feature negotiation.
        XmppException - If any other XMPP exception occurs.

      • getManager

        public final <T> T getManager​(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.
        Type Parameters:
        T - The type.
        Parameters:
        clazz - The class of the manager.
        Returns:
        An instance of the specified manager.

      • getLocalXmppAddress

        public final Jid getLocalXmppAddress()
        Description copied from interface: Session
        Gets the local XMPP address. This method may return null, e.g. for client-to-server sessions before resource binding.
        Specified by:
        getLocalXmppAddress in interface Session
        Returns:
        The local XMPP address or null.

      • getRemoteXmppAddress

        public final Jid getRemoteXmppAddress()
        Description copied from interface: Session
        Gets the remote XMPP address. This method may return null, if the session is not fully negotiated.
        Specified by:
        getRemoteXmppAddress in interface Session
        Returns:
        The remote XMPP address or null.

      • close

        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.
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Session
        Throws:
        XmppException - If an exception occurs while closing the connection, e.g. the underlying socket connection.

      • closeAsync

        public final CompletionStage<Void> closeAsync()
        Description copied from interface: Session
        Asynchronously closes the session.

        Closing usually involves a round-trip with the peer on the XMPP layer first by sending a closing stream element, then waiting on the response and then closing the underlying transport layer.

        Specified by:
        closeAsync in interface Session
        Returns:
        The completion stage, which is complete, when the session is closed.
        See Also:
        Session.close(), Connection.closeAsync()

      • notifyException

        public void notifyException​(Throwable 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.

      • getDomain

        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.
        Returns:
        The XMPP domain.

      • getConfiguration

        public final XmppSessionConfiguration getConfiguration()
        Gets the configuration for this session.
        Returns:
        The configuration.

      • enableFeature

        public final void enableFeature​(String name)
        Enables a feature by its name, usually a protocol namespace.
        Parameters:
        name - The associated manager class.

      • enableFeature

        public final void enableFeature​(Class<?> managerClass)
        Enables a feature by its manager class.
        Parameters:
        managerClass - The associated manager class.

      • disableFeature

        public final void disableFeature​(String name)
        Disables a feature by its name, usually a protocol namespace.
        Parameters:
        name - The associated manager class.

      • disableFeature

        public final void disableFeature​(Class<? extends Manager> managerClass)
        Disables a feature by its manager class.
        Parameters:
        managerClass - The associated manager class.

      • getEnabledFeatures

        public final Set<String> getEnabledFeatures()
        Gets the enabled features.
        Returns:
        The enabled features.

      • getConnectedResource

        public final Jid getConnectedResource()
        The connected resource, which is assigned by the server.
        Returns:
        The connected resource.

      • getUnacknowledgedStanzas

        public final Queue<Stanza> getUnacknowledgedStanzas()

      • markAcknowledged

        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.
        Parameters:
        acknowledgedStanza - The acknowledged stanza.
        See Also:
        addMessageAcknowledgedListener(Consumer)

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