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}