Author: jmesnil Date: 2009-12-08 10:37:42 -0500 (Tue, 08 Dec 2009) New Revision: 8620 Modified: trunk/src/main/org/hornetq/core/client/ClientSessionFactory.java Log: HORNETQ-186: fill in Javadocs for core API * documented ClientSessionFactory API Modified: trunk/src/main/org/hornetq/core/client/ClientSessionFactory.java =================================================================== --- trunk/src/main/org/hornetq/core/client/ClientSessionFactory.java 2009-12-08 14:12:26 UTC (rev 8619) +++ trunk/src/main/org/hornetq/core/client/ClientSessionFactory.java 2009-12-08 15:37:42 UTC (rev 8620) @@ -17,30 +17,115 @@ import org.hornetq.core.config.TransportConfiguration; import org.hornetq.core.exception.HornetQException; +import org.hornetq.core.message.impl.MessageImpl; import org.hornetq.core.remoting.Interceptor; import org.hornetq.utils.Pair; /** - * A ClientSessionFactory + * A ClientSessionFactory is the entry point to create and configure HornetQ resources to produce and consume messages. * * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a> */ public interface ClientSessionFactory { + /** + * Create a session with XA transaction semantics. + * + * @return a ClientSession with XA transaction semantics + * + * @throws HornetQException if an exception occurs while creating the session + */ ClientSession createXASession() throws HornetQException; + /** + * Create a <em>transacted</em> session. + * + * It is up to the client to commit when sending and acknowledging messages. + + * @return a transacted ClientSession + * @throws HornetQException if an exception occurs while creating the session + * + * @see ClientSession#commit() + */ ClientSession createTransactedSession() throws HornetQException; + + /** + * Create a <em>non-transacted</em> session. + * + * Message sends and acknowledgments are automatically committed by the session. <em>This does not + * mean that messages are automatically acknowledged</em>, only that when messages are acknowledged, + * the session will automatically commit the transaction containing the acknowledgments. + + * @return a non-transacted ClientSession + * @throws HornetQException if an exception occurs while creating the session + */ ClientSession createSession() throws HornetQException; + /** + * Create a session. + * + * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually + * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually + * @return a ClientSession + * @throws HornetQException if an exception occurs while creating the session + */ ClientSession createSession(boolean autoCommitSends, boolean autoCommitAcks) throws HornetQException; + /** + * Create a session. + * + * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually + * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually + * @param ackBatchSize the batch size of the acknowledgements + * @return a ClientSession + * @throws HornetQException if an exception occurs while creating the session + */ ClientSession createSession(boolean autoCommitSends, boolean autoCommitAcks, int ackBatchSize) throws HornetQException; + /** + * Create a session. + * + * @param xa wether the session support XA transaction semantic or not + * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually + * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually + * @return a ClientSession + * @throws HornetQException if an exception occurs while creating the session + */ ClientSession createSession(boolean xa, boolean autoCommitSends, boolean autoCommitAcks) throws HornetQException; + /** + * Create a session. + * + * It is possible to <em>pre-acknowledge messages on the server</em> 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 wether the session support XA transaction semantic or not + * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually + * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually + * @param preAcknowledge <code>true</code> to pre-acknowledge messages on the server, <code>false</code> to let the client acknowledge the messages + * @return a ClientSession + * @throws HornetQException if an exception occurs while creating the session + */ ClientSession createSession(boolean xa, boolean autoCommitSends, boolean autoCommitAcks, boolean preAcknowledge) throws HornetQException; + /** + * Create an <em>authenticated</em> session. + * + * It is possible to <em>pre-acknowledge messages on the server</em> 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 <code>true</code> to automatically commit message sends, <code>false</code> to commit manually + * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually + * @param preAcknowledge <code>true</code> to pre-acknowledge messages on the server, <code>false</code> to let the client acknowledge the messages + * @return a ClientSession + * @throws HornetQException if an exception occurs while creating the session + */ ClientSession createSession(String username, String password, boolean xa, @@ -49,64 +134,289 @@ boolean preAcknowledge, int ackBatchSize) throws HornetQException; + /** + * Return the list of <em>live - backup</em> connectors pairs configured + * that sessions created by this factory will use to connect + * to HornetQ servers or <code>null</code> if the factory is using discovery group. + * + * The backup configuration (returned by {@link org.hornetq.utils.Pair#b}) can be <code>null</code> if there is no + * backup for the corresponding live configuration (returned by {@link org.hornetq.utils.Pair#a}) + * + * @return a list of pair of TransportConfiguration corresponding to the live - backup nodes + */ List<Pair<TransportConfiguration, TransportConfiguration>> getStaticConnectors(); + /** + * Set the static list of live - backup connectors pairs that sessions created by this factory will use to connect + * to HornetQ servers. + * + * The backup configuration (returned by {@link Pair#b}) can be <code>null</code> if there is no + * backup for the corresponding live configuration (returned by {@link Pair#a}) + * + * @param staticConnectors a list of pair of TransportConfiguration corresponding to the live - backup nodes + */ void setStaticConnectors(List<Pair<TransportConfiguration, TransportConfiguration>> staticConnectors); + /** + * Return the period used to check if a client has failed to receive pings from the server. + * + * Period is in milliseconds, default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_CLIENT_FAILURE_CHECK_PERIOD}. + * + * @return the period used to check if a client has failed to receive pings from the server + */ long getClientFailureCheckPeriod(); + /** + * Set the period (in milliseconds) used to check if a client has failed to receive pings from the server. + * + * Value must be -1 (to disable) or greater than 0. + * + * @param clientFailureCheckPeriod the period to check failure + */ void setClientFailureCheckPeriod(long clientFailureCheckPeriod); + /** + * When <code>true</code>, consumers created through this factory will create temporary files to cache large messages. + * + * There is 1 temporary file created for each large message. + * + * Default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_CACHE_LARGE_MESSAGE_CLIENT}. + * + * @return <code>true</code> if consumers created through this factory will cache large messages in temporary files, <code>false</code> else. + */ boolean isCacheLargeMessagesClient(); + /** + * Set wether large messages received by consumers created through this factory will be cached in temporary files or not. + * + * @param cached <code>true</code> to cache large messages in temporary files, <code>false</code> else + */ void setCacheLargeMessagesClient(boolean cached); + /** + * Return the connection <em>time-to-live</em>. + * This TTL determines how long the server will keep a connection alive in the absence of any data arriving from the client. + * + * Value is in milliseconds, default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_CONNECTION_TTL}. + * + * @return the connection time-to-live in milliseconds + */ long getConnectionTTL(); + /** + * Set this factory's connections <em>time-to-live</em>. + * + * Value must be -1 (to disable) or greater or equals to 0. + * + * @param connectionTTL period in milliseconds + */ void setConnectionTTL(long connectionTTL); + /** + * Returns the blocking calls timeout. + * + * If client's blocking calls to the server take more than this timeout, the call will throw a {@link HornetQException} with the code {@link HornetQException#CONNECTION_TIMEDOUT}. + * Value is in milliseconds, default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_CALL_TIMEOUT}. + * + * @return the blocking calls timeout + */ long getCallTimeout(); + /** + * Set the blocking call timeout. + * + * Value must be greater or equals to 0 + * + * @param callTimeout blocking call timeout in milliseconds + */ void setCallTimeout(long callTimeout); + /** + * Return the large message size threshold. + * + * Messages whose size is if greater than this value will be handled as <em>large messages</em>. + * + * Value is in bytes, default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_MIN_LARGE_MESSAGE_SIZE}. + * + * @return the message size threshold to treat messages as large messages. + */ int getMinLargeMessageSize(); + /** + * Set the large message size threshold. + * + * Value must be greater than 0. + * + * @param minLargeMessageSize large message size threshold in bytes + */ void setMinLargeMessageSize(int minLargeMessageSize); + /** + * Return the window size for flow control of the consumers created through this factory. + * + * Value is in bytes, default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_CONSUMER_WINDOW_SIZE}. + * + * @return the window size used for consumer flow control + */ int getConsumerWindowSize(); + /** + * Set the window size for flow control of the consumers created through this factory. + * + * Value must be -1 (to disable flow control), 0 (to not buffer any messages) or greater than 0 (to set the maximum size of the buffer) + * + * @param consumerWindowSize window size (in bytes) used for consumer flow control + */ void setConsumerWindowSize(int consumerWindowSize); + /** + * Return the maximum rate of message consumption for consumers created through this factory. + * + * This value controls the rate at which a consumer can consume messages. A consumer will never consume messages at a rate faster than the rate specified. + * + * Value is -1 (to disable) or a positive integer corresponding to the maximum desired message consumption rate specified in units of messages per second. + * Default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_CONSUMER_MAX_RATE}. + * + * @return the consumer max rate + */ int getConsumerMaxRate(); + /** + * Set the maximum rate of message consumption for consumers created through this factory. + * + * Value must -1 (to disable) or a positive integer corresponding to the maximum desired message consumption rate specified in units of messages per second. + * + * @param consumerMaxRate maximum rate of message consumption (in messages per seconds) + */ void setConsumerMaxRate(int consumerMaxRate); + /** + * Return the size for the confirmation window of clients using this factory. + * + * Value is in bytes or -1 (to disable the window). Default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_CONFIRMATION_WINDOW_SIZE}. + * + * @return the size for the confirmation window of clients using this factory + */ int getConfirmationWindowSize(); + /** + * Set the size for the confirmation window buffer of clients using this factory. + * + * Value must be -1 (to disable the window) or greater than 0. + + * @param confirmationWindowSize size of the confirmation window (in bytes) + */ void setConfirmationWindowSize(int confirmationWindowSize); + /** + * Return the window size for flow control of the producers created through this factory. + * + * Value must be -1 (to disable flow control) or greater than 0 to determine the maximum amount of bytes at any give time (to prevent overloading the connection). + * Default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_PRODUCER_WINDOW_SIZE}. + * + * @return the window size for flow control of the producers created through this factory. + */ int getProducerWindowSize(); + /** + * Return the window size for flow control of the producers created through this factory. + * + * Value must be -1 (to disable flow control) or greater than 0. + * + * @param producerWindowSize window size (in bytest) for flow control of the producers created through this factory. + */ void setProducerWindowSize(int producerWindowSize); + /** + * Return the maximum rate of message production for producers created through this factory. + * + * This value controls the rate at which a producer can produce messages. A producer will never produce messages at a rate faster than the rate specified. + * + * Value is -1 (to disable) or a positive integer corresponding to the maximum desired message production rate specified in units of messages per second. + * Default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_PRODUCER_MAX_RATE}. + * + * @return maximum rate of message production (in messages per seconds) + */ int getProducerMaxRate(); + /** + * Set the maximum rate of message production for producers created through this factory. + * + * Value must -1 (to disable) or a positive integer corresponding to the maximum desired message production rate specified in units of messages per second. + * + * @param producerMaxRate maximum rate of message production (in messages per seconds) + */ void setProducerMaxRate(int producerMaxRate); + /** + * Return whether consumers created through this factory will block while sending message acknowledgements or do it asynchronously. + * + * If the consumer are configured to send message acknowledgement asynchronously, you can set a SendAcknowledgementHandler on the ClientSession + * to be notified once the acknowledgement has been handled by the server. + * + * Default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_BLOCK_ON_ACKNOWLEDGE}. + * + * @return whether consumers will block while sending message acknowledgements or do it asynchronously + */ boolean isBlockOnAcknowledge(); + /** + * Set whether consumers created through this factory will block while sending message acknowledgements or do it asynchronously. + * + * @param blockOnAcknowledge <code>true</code> to block when sending message acknowledgements or <code>false</code> to send them asynchronously + */ void setBlockOnAcknowledge(boolean blockOnAcknowledge); + /** + * Return whether producers created through this factory will block while sending <em>persistent</em> messages or do it asynchronously. + * + * Default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_BLOCK_ON_PERSISTENT_SEND}. + * + * @return whether producers will block while sending persistent messages or do it asynchronously + */ boolean isBlockOnPersistentSend(); + /** + * Set whether producers created through this factory will block while sending <em>persistent</em> messages or do it asynchronously. + * + * @param blockOnPersistentSend <code>true</code> to block when sending persistent messages or <code>false</code> to send them asynchronously + */ void setBlockOnPersistentSend(boolean blockOnPersistentSend); + /** + * Return whether producers created through this factory will block while sending <em>non-persistent</em> messages or do it asynchronously. + * + * Default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_BLOCK_ON_NON_PERSISTENT_SEND}. + * + * @return whether producers will block while sending non-persistent messages or do it asynchronously + */ boolean isBlockOnNonPersistentSend(); + /** + * Set whether producers created through this factory will block while sending <em>non-persistent</em> messages or do it asynchronously. + * + * @param blockOnNonPersistentSend <code>true</code> to block when sending non-persistent messages or <code>false</code> to send them asynchronously + */ void setBlockOnNonPersistentSend(boolean blockOnNonPersistentSend); + /** + * Return whether producers created through this factory will automatically + * assign a group ID to the messages they sent. + * + * if <code>true</code>, the random unique group ID is created set on each message for the property + * {@value MessageImpl#HDR_GROUP_ID}. + * Default value is {@value org.hornetq.core.client.impl.ClientSessionFactoryImpl#DEFAULT_AUTO_GROUP}. + * + * @return whether producers will automatically assign a group ID to their messages + */ boolean isAutoGroup(); + /** + * Set whether producers created through this factory will automatically + * assign a group ID to the messages they sent. + * + * @param autoGroup <code>true</code> to automatically assign a group ID to each messages sent through this factory, <code>false</code> else + */ void setAutoGroup(boolean autoGroup); boolean isPreAcknowledge();