Class OutgoingSessionPromise


  • public class OutgoingSessionPromise
    extends Object
    An OutgoingSessionPromise provides an asynchronous way for sending packets to remote servers. When looking for a route to a remote server that does not have an existing connection, a session promise is returned.

    This class will queue packets and process them in another thread. The processing thread will use a pool of thread that will actually do the hard work. The threads in the pool will try to connect to remote servers and deliver the packets. If an error occurred while establishing the connection or sending the packet an error will be returned to the sender of the packet.

    Author:
    Gaston Dombiak, Dave Cridland, Guus der Kinderen
    • Method Detail

      • shutdown

        public void shutdown()
        Shuts down the thread that consumes the queued packets and also stops the pool of threads that actually send the packets to the remote servers.
      • createProcess

        public void createProcess​(@Nonnull
                                  DomainPair domainPair,
                                  @Nonnull
                                  org.xmpp.packet.Packet packet)
        Start a new process to establish a new outgoing connection, queuing the stanza that's addressed to the remote domain for delivery after that has occurred. Only one process can exist for any given domainPair. This method will throw an exception when it is invoked for a DomainPair for which a process already exists. The returned value of hasProcess(DomainPair) can be used to determine if a process exists. The invocations of that method and this method should be guarded by the mutex returned by getMutex(DomainPair) to ensure thread safety, as holding that mutex will prevent other threads from starting a new process.
        Parameters:
        domainPair - The domainPair that describes the local and remote domain between which the stanza is to be sent
        packet - the stanza to send to the remote domain (addressing must correspond with the domainPair argument)
        Throws:
        IllegalStateException - when a process already exists for this domainPair
      • queue

        public void queue​(@Nonnull
                          DomainPair domainPair,
                          @Nonnull
                          org.xmpp.packet.Packet packet)
        Queues a stanza for delivery to a remote domain after an ongoing process to establish that connection has finished. A process for the target DomainPair must exist. This method will throw an exception when it does not. The returned value of hasProcess(DomainPair) can be used to determine if a process exists. The invocations of that method and this method should be guarded by the mutex returned by getMutex(DomainPair) to ensure thread safety, as holding that mutex will prevent other threads to finish the running process.
        Parameters:
        domainPair - The domainPair that describes the local and remote domain between which the stanza is to be sent
        packet - the stanza to send to the remote domain (addressing must correspond with the domainPair argument)
        Throws:
        IllegalStateException - when a process does not exist for the domainPair
      • getMutex

        public Object getMutex​(@Nonnull
                               DomainPair domainPair)
        Generates an object that is suitable as a mutex for operations that involve the provided DomainPair instance.
        Parameters:
        domainPair - The DomainPair for which the mutex is issued
        Returns:
        An object suitable to be a mutex.
      • hasProcess

        public boolean hasProcess​(@Nonnull
                                  DomainPair domainPair)
        Checks if an outgoing session is in process of being created, which includes both establishment of the (possibly authenticated) connection as well as delivery of all queued stanzas.
        Parameters:
        domainPair - The connection to check.
        Returns:
        true if an outgoing session is currently being created, otherwise false.