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 ServerLocator getServerLocator();
138
139 CoreRemotingConnection getConnection();
140 }