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    
014    package org.hornetq.api.core.client;
015    
016    import org.hornetq.api.core.HornetQException;
017    import 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     */
028    public 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    }