org.apache.activemq.artemis.api.core.client.ClientSessionFactory Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.activemq.artemis.api.core.client;
import org.apache.activemq.artemis.api.core.ActiveMQException;
import org.apache.activemq.artemis.api.core.TransportConfiguration;
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection;
/**
* 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.
*/
public interface ClientSessionFactory extends AutoCloseable {
/**
* Creates a session with XA transaction semantics.
*
* @return a ClientSession with XA transaction semantics
* @throws ActiveMQException if an exception occurs while creating the session
*/
ClientSession createXASession() throws ActiveMQException;
/**
* Creates a transacted session.
*
* It is up to the client to commit when sending and acknowledging messages.
*
* @return a transacted ClientSession
* @throws ActiveMQException if an exception occurs while creating the session
* @see ClientSession#commit()
*/
ClientSession createTransactedSession() throws 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.
*
* @return a non-transacted ClientSession
* @throws ActiveMQException if an exception occurs while creating the session
*/
ClientSession createSession() throws ActiveMQException;
/**
* Creates a session.
*
* @param autoCommitSends true to automatically commit message sends, false to commit manually
* @param autoCommitAcks true to automatically commit message acknowledgement, false to commit manually
* @return a ClientSession
* @throws ActiveMQException if an exception occurs while creating the session
*/
ClientSession createSession(boolean autoCommitSends, boolean autoCommitAcks) throws ActiveMQException;
/**
* Creates a session.
*
* @param autoCommitSends true to automatically commit message sends, false to commit manually
* @param autoCommitAcks true to automatically commit message acknowledgement, false to commit manually
* @param ackBatchSize the batch size of the acknowledgements
* @return a ClientSession
* @throws ActiveMQException if an exception occurs while creating the session
*/
ClientSession createSession(boolean autoCommitSends,
boolean autoCommitAcks,
int ackBatchSize) throws ActiveMQException;
/**
* Creates a session.
*
* @param xa whether the session support XA transaction semantic or not
* @param autoCommitSends true to automatically commit message sends, false to commit manually
* @param autoCommitAcks true to automatically commit message acknowledgement, false to commit manually
* @return a ClientSession
* @throws ActiveMQException if an exception occurs while creating the session
*/
ClientSession createSession(boolean xa, boolean autoCommitSends, boolean autoCommitAcks) throws 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.
*
* @param xa whether the session support XA transaction semantic or not
* @param autoCommitSends true to automatically commit message sends, false to commit manually
* @param autoCommitAcks true to automatically commit message acknowledgement, false to commit manually
* @param preAcknowledge true to pre-acknowledge messages on the server, false to let the client acknowledge the messages
* @return a ClientSession
* @throws ActiveMQException if an exception occurs while creating the session
*/
ClientSession createSession(boolean xa,
boolean autoCommitSends,
boolean autoCommitAcks,
boolean preAcknowledge) throws 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.
*
* @param username the user name
* @param password the user password
* @param xa whether the session support XA transaction semantic or not
* @param autoCommitSends true to automatically commit message sends, false to commit manually
* @param autoCommitAcks true to automatically commit message acknowledgement, false to commit manually
* @param preAcknowledge true to pre-acknowledge messages on the server, false to let the client acknowledge the messages
* @return a ClientSession
* @throws ActiveMQException if an exception occurs while creating the session
*/
ClientSession createSession(String username,
String password,
boolean xa,
boolean autoCommitSends,
boolean autoCommitAcks,
boolean preAcknowledge,
int ackBatchSize) throws 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.
*
* @param username the user name
* @param password the user password
* @param xa whether the session support XA transaction semantic or not
* @param autoCommitSends true to automatically commit message sends, false to commit manually
* @param autoCommitAcks true to automatically commit message acknowledgement, false to commit manually
* @param preAcknowledge true to pre-acknowledge messages on the server, false to let the client acknowledge the messages
* @param clientID the session clientID
* @return a ClientSession
* @throws ActiveMQException if an exception occurs while creating the session
*/
ClientSession createSession(String username,
String password,
boolean xa,
boolean autoCommitSends,
boolean autoCommitAcks,
boolean preAcknowledge,
int ackBatchSize,
String clientID) throws ActiveMQException;
/**
* Closes this factory and any session created by it.
*/
@Override
void close();
/**
* @return {@code true} if the factory is closed, {@code false} otherwise.
*/
boolean isClosed();
/**
* Adds a FailoverEventListener to the session which is notified if a failover event occurs on the session.
*
* @param listener the listener to add
* @return this ClientSessionFactory
*/
ClientSessionFactory addFailoverListener(FailoverEventListener listener);
/**
* Removes a FailoverEventListener to the session.
*
* @param listener the listener to remove
* @return true if the listener was removed, false else
*/
boolean removeFailoverListener(FailoverEventListener listener);
/**
* Opposed to close, will call cleanup only on every created session and children objects.
*/
void cleanup();
/**
* @return the server locator associated with this session factory
*/
ServerLocator getServerLocator();
/**
* Returns the code connection used by this session factory.
*
* @return the core connection
*/
RemotingConnection getConnection();
/**
* Return the configuration used
*
* @return
*/
TransportConfiguration getConnectorConfiguration();
}