    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    }