001/*
002 * Copyright 2009 Red Hat, Inc.
003 * Red Hat licenses this file to you under the Apache License, version
004 * 2.0 (the "License"); you may not use this file except in compliance
005 * with the License.  You may obtain a copy of the License at
006 *    http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
010 * implied.  See the License for the specific language governing
011 * permissions and limitations under the License.
012 */
013
014package org.hornetq.api.core.client;
015
016import org.hornetq.api.core.HornetQException;
017import org.hornetq.core.protocol.core.CoreRemotingConnection;
018
019
020/**
021 * A ClientSessionFactory is the entry point to create and configure HornetQ resources to produce and consume messages.
022 * <br>
023 * It is possible to configure a factory using the setter methods only if no session has been created.
024 * Once a session is created, the configuration is fixed and any call to a setter method will throw a IllegalStateException.
025 * 
026 * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
027 */
028public interface ClientSessionFactory
029{
030   /**
031    * Creates a session with XA transaction semantics.
032    * 
033    * @return a ClientSession with XA transaction semantics
034    * 
035    * @throws HornetQException if an exception occurs while creating the session
036    */
037   ClientSession createXASession() throws HornetQException;
038
039   /**
040    * Creates a <em>transacted</em> session.
041    * 
042    * It is up to the client to commit when sending and acknowledging messages.
043
044    * @return a transacted ClientSession
045    * @throws HornetQException if an exception occurs while creating the session
046    * 
047    * @see ClientSession#commit()
048    */
049   ClientSession createTransactedSession() throws HornetQException;
050
051
052   /**
053    * Creates a <em>non-transacted</em> session.
054    * Message sends and acknowledgements are automatically committed by the session. <em>This does not
055    * mean that messages are automatically acknowledged</em>, only that when messages are acknowledged, 
056    * the session will automatically commit the transaction containing the acknowledgements.
057
058    * @return a non-transacted ClientSession
059    * @throws HornetQException if an exception occurs while creating the session
060    */
061   ClientSession createSession() throws HornetQException;
062
063   /**
064    * Creates a session.
065    * 
066    * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
067    * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
068    * @return a ClientSession
069    * @throws HornetQException if an exception occurs while creating the session
070    */
071   ClientSession createSession(boolean autoCommitSends, boolean autoCommitAcks) throws HornetQException;
072
073   /**
074    * Creates a session.
075    * 
076    * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
077    * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
078    * @param ackBatchSize the batch size of the acknowledgements
079    * @return a ClientSession
080    * @throws HornetQException if an exception occurs while creating the session
081    */
082   ClientSession createSession(boolean autoCommitSends, boolean autoCommitAcks, int ackBatchSize) throws HornetQException;
083
084   /**
085    * Creates a session.
086    * 
087    * @param xa whether the session support XA transaction semantic or not
088    * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
089    * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
090    * @return a ClientSession
091    * @throws HornetQException if an exception occurs while creating the session
092    */
093   ClientSession createSession(boolean xa, boolean autoCommitSends, boolean autoCommitAcks) throws HornetQException;
094
095   /**
096    * Creates a session.
097    * 
098    * It is possible to <em>pre-acknowledge messages on the server</em> so that the client can avoid additional network trip
099    * to the server to acknowledge messages. While this increase performance, this does not guarantee delivery (as messages
100    * can be lost after being pre-acknowledged on the server). Use with caution if your application design permits it.
101    * 
102    * @param xa whether the session support XA transaction semantic or not
103    * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
104    * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
105    * @param preAcknowledge <code>true</code> to pre-acknowledge messages on the server, <code>false</code> to let the client acknowledge the messages
106    * @return a ClientSession
107    * @throws HornetQException if an exception occurs while creating the session
108    */
109   ClientSession createSession(boolean xa, boolean autoCommitSends, boolean autoCommitAcks, boolean preAcknowledge) throws HornetQException;
110
111   /**
112    * Creates an <em>authenticated</em> session.
113    * 
114    * It is possible to <em>pre-acknowledge messages on the server</em> so that the client can avoid additional network trip
115    * to the server to acknowledge messages. While this increase performance, this does not guarantee delivery (as messages
116    * can be lost after being pre-acknowledged on the server). Use with caution if your application design permits it.
117    * 
118    * @param username the user name
119    * @param password the user password
120    * @param xa whether the session support XA transaction semantic or not
121    * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
122    * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
123    * @param preAcknowledge <code>true</code> to pre-acknowledge messages on the server, <code>false</code> to let the client acknowledge the messages
124    * @return a ClientSession
125    * @throws HornetQException if an exception occurs while creating the session
126    */
127   ClientSession createSession(String username,
128                               String password,
129                               boolean xa,
130                               boolean autoCommitSends,
131                               boolean autoCommitAcks,
132                               boolean preAcknowledge,
133                               int ackBatchSize) throws HornetQException;
134
135   void close();
136
137   /**
138    * Opposed to close, will call cleanup only on every created session and children objects.
139    */
140   void cleanup();
141   
142   ServerLocator getServerLocator();
143   
144   CoreRemotingConnection getConnection();
145
146    boolean isClosed();
147
148}