Package org.apache.activemq.artemis.api.core.client

## Interface ClientSessionFactory

- All Superinterfaces:
    `java.lang.AutoCloseable`

      public interface ClientSessionFactory
      extends java.lang.AutoCloseable

  A ClientSessionFactory is the entry point to create and configure ActiveMQ Artemis resources to produce and consume messages.
  It is possible to configure a factory using the setter methods only if no session has been created. Once a session is created, the configuration is fixed and any call to a setter method will throw an IllegalStateException.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ClientSessionFactory` | `addFailoverListener​(FailoverEventListener listener)` | Adds a FailoverEventListener to the session which is notified if a failover event occurs on the session.
    `void` | `cleanup()` | Opposed to close, will call cleanup only on every created session and children objects.
    `void` | `close()` | Closes this factory and any session created by it.
    `ClientSession` | `createSession()` | Creates a non-transacted session.
    `ClientSession` | `createSession​(boolean autoCommitSends, boolean autoCommitAcks)` | Creates a session.
    `ClientSession` | `createSession​(boolean xa, boolean autoCommitSends, boolean autoCommitAcks)` | Creates a session.
    `ClientSession` | `createSession​(boolean xa, boolean autoCommitSends, boolean autoCommitAcks, boolean preAcknowledge)` | Creates a session.
    `ClientSession` | `createSession​(boolean autoCommitSends, boolean autoCommitAcks, int ackBatchSize)` | Creates a session.
    `ClientSession` | `createSession​(java.lang.String username, java.lang.String password, boolean xa, boolean autoCommitSends, boolean autoCommitAcks, boolean preAcknowledge, int ackBatchSize)` | Creates an authenticated session.
    `ClientSession` | `createSession​(java.lang.String username, java.lang.String password, boolean xa, boolean autoCommitSends, boolean autoCommitAcks, boolean preAcknowledge, int ackBatchSize, java.lang.String clientID)` | Creates an authenticated session.
    `ClientSession` | `createTransactedSession()` | Creates a transacted session.
    `ClientSession` | `createXASession()` | Creates a session with XA transaction semantics.
    `RemotingConnection` | `getConnection()` | Returns the code connection used by this session factory.
    `TransportConfiguration` | `getConnectorConfiguration()` | Return the configuration used
    `ServerLocator` | `getServerLocator()` |
    `boolean` | `isClosed()` |
    `boolean` | `removeFailoverListener​(FailoverEventListener listener)` | Removes a FailoverEventListener to the session.

- - ### Method Detail

    - #### createXASession

          ClientSession createXASession()
                                 throws org.apache.activemq.artemis.api.core.ActiveMQException

      Creates a session with XA transaction semantics.
      Returns:
        a ClientSession with XA transaction semantics
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while creating the session

    - #### createTransactedSession

          ClientSession createTransactedSession()
                                         throws org.apache.activemq.artemis.api.core.ActiveMQException

      Creates a transacted session.

      It is up to the client to commit when sending and acknowledging messages.

      Returns:
        a transacted ClientSession
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while creating the session
      See Also:
        `ClientSession.commit()`

    - #### createSession

          ClientSession createSession()
                               throws org.apache.activemq.artemis.api.core.ActiveMQException

      Creates a non-transacted session. Message sends and acknowledgements are automatically committed by the session. This does not mean that messages are automatically acknowledged, only that when messages are acknowledged, the session will automatically commit the transaction containing the acknowledgements.
      Returns:
        a non-transacted ClientSession
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while creating the session

    - #### createSession

          ClientSession createSession​(boolean autoCommitSends,
                                      boolean autoCommitAcks)
                               throws org.apache.activemq.artemis.api.core.ActiveMQException

      Creates a session.
      Parameters:
        `autoCommitSends` - `true` to automatically commit message sends, `false` to commit manually
        `autoCommitAcks` - `true` to automatically commit message acknowledgement, `false` to commit manually
      Returns:
        a ClientSession
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while creating the session

    - #### createSession

          ClientSession createSession​(boolean autoCommitSends,
                                      boolean autoCommitAcks,
                                      int ackBatchSize)
                               throws org.apache.activemq.artemis.api.core.ActiveMQException

      Creates a session.
      Parameters:
        `autoCommitSends` - `true` to automatically commit message sends, `false` to commit manually
        `autoCommitAcks` - `true` to automatically commit message acknowledgement, `false` to commit manually
        `ackBatchSize` - the batch size of the acknowledgements
      Returns:
        a ClientSession
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while creating the session

    - #### createSession

          ClientSession createSession​(boolean xa,
                                      boolean autoCommitSends,
                                      boolean autoCommitAcks)
                               throws org.apache.activemq.artemis.api.core.ActiveMQException

      Creates a session.
      Parameters:
        `xa` - whether the session support XA transaction semantic or not
        `autoCommitSends` - `true` to automatically commit message sends, `false` to commit manually
        `autoCommitAcks` - `true` to automatically commit message acknowledgement, `false` to commit manually
      Returns:
        a ClientSession
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while creating the session

    - #### createSession

          ClientSession createSession​(boolean xa,
                                      boolean autoCommitSends,
                                      boolean autoCommitAcks,
                                      boolean preAcknowledge)
                               throws org.apache.activemq.artemis.api.core.ActiveMQException

      Creates a session.

      It is possible to pre-acknowledge messages on the server so that the client can avoid additional network trip to the server to acknowledge messages. While this increase performance, this does not guarantee delivery (as messages can be lost after being pre-acknowledged on the server). Use with caution if your application design permits it.

      Parameters:
        `xa` - whether the session support XA transaction semantic or not
        `autoCommitSends` - `true` to automatically commit message sends, `false` to commit manually
        `autoCommitAcks` - `true` to automatically commit message acknowledgement, `false` to commit manually
        `preAcknowledge` - `true` to pre-acknowledge messages on the server, `false` to let the client acknowledge the messages
      Returns:
        a ClientSession
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while creating the session

    - #### createSession

          ClientSession createSession​(java.lang.String username,
                                      java.lang.String password,
                                      boolean xa,
                                      boolean autoCommitSends,
                                      boolean autoCommitAcks,
                                      boolean preAcknowledge,
                                      int ackBatchSize)
                               throws org.apache.activemq.artemis.api.core.ActiveMQException

      Creates an authenticated session.

      It is possible to pre-acknowledge messages on the server so that the client can avoid additional network trip to the server to acknowledge messages. While this increase performance, this does not guarantee delivery (as messages can be lost after being pre-acknowledged on the server). Use with caution if your application design permits it.

      Parameters:
        `username` - the user name
        `password` - the user password
        `xa` - whether the session support XA transaction semantic or not
        `autoCommitSends` - `true` to automatically commit message sends, `false` to commit manually
        `autoCommitAcks` - `true` to automatically commit message acknowledgement, `false` to commit manually
        `preAcknowledge` - `true` to pre-acknowledge messages on the server, `false` to let the client acknowledge the messages
      Returns:
        a ClientSession
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while creating the session

    - #### createSession

          ClientSession createSession​(java.lang.String username,
                                      java.lang.String password,
                                      boolean xa,
                                      boolean autoCommitSends,
                                      boolean autoCommitAcks,
                                      boolean preAcknowledge,
                                      int ackBatchSize,
                                      java.lang.String clientID)
                               throws org.apache.activemq.artemis.api.core.ActiveMQException

      Creates an authenticated session.

      It is possible to pre-acknowledge messages on the server so that the client can avoid additional network trip to the server to acknowledge messages. While this increase performance, this does not guarantee delivery (as messages can be lost after being pre-acknowledged on the server). Use with caution if your application design permits it.

      Parameters:
        `username` - the user name
        `password` - the user password
        `xa` - whether the session support XA transaction semantic or not
        `autoCommitSends` - `true` to automatically commit message sends, `false` to commit manually
        `autoCommitAcks` - `true` to automatically commit message acknowledgement, `false` to commit manually
        `preAcknowledge` - `true` to pre-acknowledge messages on the server, `false` to let the client acknowledge the messages
        `clientID` - the session clientID
      Returns:
        a ClientSession
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while creating the session

    - #### close

          void close()

      Closes this factory and any session created by it.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`

    - #### isClosed

          boolean isClosed()

      Returns:
        `true` if the factory is closed, `false` otherwise.

    - #### addFailoverListener

          ClientSessionFactory addFailoverListener​(FailoverEventListener listener)

      Adds a FailoverEventListener to the session which is notified if a failover event occurs on the session.
      Parameters:
        `listener` - the listener to add
      Returns:
        this ClientSessionFactory

    - #### removeFailoverListener

          boolean removeFailoverListener​(FailoverEventListener listener)

      Removes a FailoverEventListener to the session.
      Parameters:
        `listener` - the listener to remove
      Returns:
        `true` if the listener was removed, `false` else

    - #### cleanup

          void cleanup()

      Opposed to close, will call cleanup only on every created session and children objects.

    - #### getServerLocator

          ServerLocator getServerLocator()

      Returns:
        the server locator associated with this session factory

    - #### getConnection

          RemotingConnection getConnection()

      Returns the code connection used by this session factory.
      Returns:
        the core connection

    - #### getConnectorConfiguration

          TransportConfiguration getConnectorConfiguration()

      Return the configuration used
      Returns: