/***
    * Redistribution and use of this software and associated documentation
    * ("Software"), with or without modification, are permitted provided
    * that the following conditions are met:
    *
    * 1. Redistributions of source code must retain copyright
    *    statements and notices.  Redistributions must also contain a
    *    copy of this document.
    *
   * 2. Redistributions in binary form must reproduce the
   *    above copyright notice, this list of conditions and the
   *    following disclaimer in the documentation and/or other
   *    materials provided with the distribution.
   *
   * 3. The name "Exolab" must not be used to endorse or promote
   *    products derived from this Software without prior written
   *    permission of Exoffice Technologies.  For written permission,
   *    please contact info@exolab.org.
   *
   * 4. Products derived from this Software may not be called "Exolab"
   *    nor may "Exolab" appear in their names without prior written
   *    permission of Exoffice Technologies. Exolab is a registered
   *    trademark of Exoffice Technologies.
   *
   * 5. Due credit should be given to the Exolab Project
   *    (http://www.exolab.org/).
   *
   * THIS SOFTWARE IS PROVIDED BY EXOFFICE TECHNOLOGIES AND CONTRIBUTORS
   * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
   * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
   * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
   * EXOFFICE TECHNOLOGIES OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
   * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
   * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
   * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
   * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
   * OF THE POSSIBILITY OF SUCH DAMAGE.
   *
   * Copyright 2000-2004 (C) Exoffice Technologies Inc. All Rights Reserved.
   *
   * $Id: JmsConnection.java,v 1.26 2004/01/11 02:33:44 tanderson Exp $
   *
   * Date         Author  Changes
   * 3/21/2000    jima    Created
   */
  package org.exolab.jms.client;
  
  
  import java.util.Enumeration;
  import java.util.Vector;
  
  import javax.jms.Connection;
  import javax.jms.ConnectionMetaData;
  import javax.jms.ExceptionListener;
  import javax.jms.IllegalStateException;
  import javax.jms.JMSException;
  
  import org.apache.commons.logging.Log;
  import org.apache.commons.logging.LogFactory;
  
  import org.exolab.core.service.ServiceException;
  import org.exolab.jms.events.BasicEventManager;
  
  
  /***
   * Client side implementation of the <code>javax.jms.Connection</code>
   * interface.
   *
   * @version     $Revision: 1.26 $ $Date: 2004/01/11 02:33:44 $
   * @author      <a href="mailto:jima@exoffice.com">Jim Alateras</a>
   * @author      <a href="mailto:tma@netspace.net.au">Tim Anderson</a>
   */
  abstract class JmsConnection implements Connection {
  
      /***
       * This flag indicates whether or not the connection is closed. It
       * is set to false on creation
       */
      private boolean _closed = false;
  
      /***
       * This flag indicates whether the connection is in the start or
       * stopped state
       */
      private boolean _stopped = true;
  
      /***
       * This flag indicates whether the connection has been modified.
       * If so, subsequent attempts to invoke {@link #setClientID} will
       * cause an <code>IllegalStateException</code> being thrown
       */
      private boolean _modified = false;
  
      /***
       * This is the identity associated with the client. The identity is
       * generated and assigned by the connection factory
       */
     private String _clientId = null;
 
     /***
      * Gates the setting of the clientId more than once
      */
     private boolean _clientIdSet = false;
 
     /***
      * A connection can maintain one and only one exception listener, The
      * listener will be informed of unusual and exception events
      */
     private ExceptionListener _exceptionListener = null;
 
     /***
      * Manage the list of activated and registered sessions. Everytime a
      * session is created through this connection it is registered.
      */
     private Vector _sessions = new Vector();
 
     /***
      * This is a back pointer to the connection factory which created this
      * connection. It is assigned during object construction
      */
     private JmsConnectionFactory _factory = null;
 
     /***
      * This is a stub to a remote object on the JMSSever. This abstraction
      * allows us to use different underlying ORBS.
      */
     private JmsConnectionStubIfc _stub = null;
 
     /***
      * The id is generated by the server and is unique for each connection
      * created. This id is then used to generate other ids
      */
     private String _connectionId = null;
 
     /***
      * The number of connections created
      */
     private static volatile int _activeConnections = 0;
 
     /***
      * The connection data is immutable at this stage. This enables us to cache
      * a single copy in memory
      */
     private static final JmsConnectionMetaData _metaData =
         new JmsConnectionMetaData();
 
     /***
      * The logger
      */
     private static final Log _log = LogFactory.getLog(JmsConnection.class);
 
 
     /***
      * Construct a new <code>JmsConnection</code>
      * <p>
      * This attempts to establish a connection to the JMS server
      *
      * @param factory the connection factory responsible for creating this
      * @param id the client identity
      * @param username the client username
      * @param password the client password
      * @throws JMSException if a connection cannot be established
      */
     protected JmsConnection(JmsConnectionFactory factory, String id, 
                             String username, String password)
         throws JMSException {
 
         if (factory == null) {
             throw new IllegalArgumentException("Argument 'factory' is null");
         }
         if (id == null) {
             throw new IllegalArgumentException("Argument 'id' is null");
         }
         if (id.trim().length() == 0) {
             throw new IllegalArgumentException("Argument 'id' is invalid: '"
                                                + id + "'");
         }
 
         _factory = factory;
         _clientId = id;
 
         _stopped = true;
 
         // use the factory object to retrieve the proxy that
         // will be used to get a JmsConnectionStubIfc instance
         // and cache its identity locally
         _stub = factory.getProxy().createConnection(_clientId, username,
                                                     password);
         _connectionId = _stub.getConnectionId();
 
         // start the event manager
         startEventManager();
     }
 
     // implementation of Connection.getClientID
     public String getClientID() throws JMSException {
         ensureOpen();
         setModified();
 
         return _clientId;
     }
 
 
     // implementation of Connection.setClientID
     public void setClientID(String id) throws JMSException {
         ensureOpen();
 
         // check if the client id has already been set
         if (_clientIdSet) {
             throw new IllegalStateException(
                 "The client id has already been set");
         }
 
         if (_modified) {
             throw new IllegalStateException(
                 "The client identifier must be set before any other operation "
                 + "is performed");
         }
 
         // gate the client id from being set more than once.
         _clientId = id;
         _clientIdSet = true;
     }
 
 
     // implementation of Connection.getMetaData
     public ConnectionMetaData getMetaData() throws JMSException {
         ensureOpen();
         setModified();
         return _metaData;
     }
 
     // implementation of Connection.getExceptionListener
     public ExceptionListener getExceptionListener() throws JMSException {
         ensureOpen();
         setModified();
         return _exceptionListener;
     }
 
 
     // implementation of Connection.setExceptionListener
     public void setExceptionListener(ExceptionListener listener)
         throws JMSException {
         ensureOpen();
         setModified();
         _exceptionListener = listener;
     }
 
     /***
      * Notify the exception listener of a JMSException. If the exception
      * listener is not set then ignore it
      *
      * @param message message to deliver
      */
     public void notifyExceptionListener(JMSException message) {
         // check the error code
         if (message.getErrorCode() != null &&
             message.getErrorCode().equals(
                 JmsErrorCodes.CONNECTION_TO_SERVER_DROPPED)) {
             // the connection to the server has been dropped so we need to
             // release all local resources.
             try {
                 destroy();
             } catch (JMSException exception) {
                 _log.error(exception.getMessage(), exception);
             }
         }
 
         // finally notify registered exception listener
         if (_exceptionListener != null) {
             _exceptionListener.onException(message);
         }
     }
 
     // implementation of Connection.start
     public synchronized void start() throws JMSException {
         ensureOpen();
         setModified();
 
         try {
             if (_stopped) {
                 // propagate the start to all the associated sessions. When
                 // that is complete transition the state of the connection to
                 // RUNNING
                 Enumeration sessions = _sessions.elements();
                 while (sessions.hasMoreElements()) {
                     JmsSession session = (JmsSession) sessions.nextElement();
                     session.start();
                 }
                 // set the  state of the connection to start
                 _stopped = false;
             }
         } catch (JMSException exception) {
             // do we need to change _stopped to true if the any of the
             // sessions fail to start
             throw exception;
         }
     }
 
     // implementation of Connection.stop
     public synchronized void stop() throws JMSException {
         ensureOpen();
         setModified();
 
         if (!_stopped) {
             // propagate the stop to all the encapsulated sessions before
             // changing the state of the connection. Only when all the
             // sessions have successfully transitioned, without exception,
             // do we change the state of the connection
             Enumeration sessions = _sessions.elements();
             while (sessions.hasMoreElements()) {
                 JmsSession session = (JmsSession) sessions.nextElement();
                 session.stop();
             }
 
             // set the state of the connection to stopped before stopping
             // all the enclosed sessions
             _stopped = true;
         }
     }
 
     // implementation of Connection.close
     public synchronized void close() throws JMSException {
         if (!_closed) {
             try {
                 // before we close we should stop the connection and any
                 // associated sessions
                 stop();
 
                 // propagate the close to all the encapsulated sessions before
                 // changing the state of the connection. Only when all the
                 // sessions have successfully transitioned, without exception,
                 // do we change the state of the connection. All the sessions
                 // are removed from the connection.
                 Object sessions[] = _sessions.toArray();
                 for (int i = 0; i < sessions.length; ++i) {
                     JmsSession session = (JmsSession) sessions[i];
                     session.close();
                     // the session deregisters itself with the connection via
                     // removeSession()
                 }
 
                 // send a close to the stub and then null the stub
                 getJmsConnectionStub().close();
                 _stub = null;
 
                 // remove yourself from the list of connections managed by the
                 // connection factory and then null the factory.
                 _factory.removeConnection(this);
                 _factory = null;
 
                 // set the closed flag so calling it multiple times is
                 // cool
                 _closed = true;
             } finally {
                 stopEventManager();
             }
         }
     }
 
     /***
      * Release all resources used by this connection, including supporting
      * sessions
      *
      * @throws JMSException - error completing this request
      */
     public synchronized void destroy() throws JMSException {
         if (!_closed) {
             try {
                 // propagate the close to all the encapsulated sessions before
                 // changing the state of the connection. Only when all the
                 // sessions have successfully transitioned, without exception,
                 // do we change the state of the connection. All the sessions
                 // are removed from the connection.
                 Object sessions[] = _sessions.toArray();
                 for (int i = 0; i < sessions.length; ++i) {
                     JmsSession session = (JmsSession) sessions[i];
                     session.destroy();
                 }
 
                 // send a close to the stub and then null the stub
                 getJmsConnectionStub().destroy();
                 _stub = null;
 
                 // remove yourself from the list of connections managed by the
                 // connection factory and then null the factory.
                 _factory.removeConnection(this);
                 _factory = null;
 
                 // set the closed flag so calling it multiple times is
                 // cool
                 _closed = true;
             } finally {
                 stopEventManager();
             }
         }
     }
 
     /***
      * Return the identity of this connection. An identity is created by the
      * server and is unique within that servers environment
      *
      * @return      String
      */
     public String getConnectionId() {
         return _connectionId;
     }
 
     /***
      * Return an instance of the remote server connection. If one has not
      * been assigned then throw the JMSException exception
      *
      * @return      JmsConnectionStub   connection to the server
      * @throws   JMSException
      */
     JmsConnectionStubIfc getJmsConnectionStub() throws JMSException {
         if (_stub == null) {
             throw new JMSException("The connectionstub is set to null");
         }
 
         return _stub;
     }
 
     /***
      * Add the specified session to the list of managed sessions
      *
      * @param       session         session to register
      */
     protected void addSession(JmsSession session) {
         _sessions.addElement(session);
     }
 
     /***
      * Remove the specified session from the list of managed sessions.
      * If it doesn't exist then fail silently
      *
      * @param       session         session to remove
      */
     protected void removeSession(JmsSession session) {
         _sessions.removeElement(session);
     }
 
     /***
      * Test whether the specified session is managed by this connection
      *
      * @param       session         session to test against
      * @return      boolean         true if managed
      */
     protected boolean isManaged(JmsSession session) {
         return _sessions.contains(session);
     }
 
     /***
      * Returns an enumeration of all sessions managed by this connection
      *
      * @return an enumeration of all sessions managed by this connection
      */
     protected Enumeration getSessions() {
         return _sessions.elements();
     }
 
     /***
      * Return the running state of the connection
      *
      * @return <code>true</code> if stopped
      */
     protected boolean isStopped() {
         return _stopped;
     }
 
     /***
      * Flags this connection as being modified. Subsequent attempts
      * to invoke {@link #setClientID} will result in an
      * <code>IllegalStateException</code> being thrown
      */
     protected void setModified() {
         _modified = true;
     }
 
     /***
      * Delete the temporary destination and all the registered sessions
      * consumers waiting to receive messages from this destination will
      * be stopped.
      * <p>
      * It will throw a JMSException if the specified destination is not
      * temporary or if the destination is null or if the destination is
      * not owned by this connection
      *
      * @param       destination         temporary destination to delete
      * @throws   JMSException
      */
     synchronized void deleteTemporaryDestination(JmsDestination destination)
         throws JMSException {
         if ((destination != null) &&
             (destination instanceof JmsTemporaryDestination)) {
             JmsTemporaryDestination temp_dest =
                 (JmsTemporaryDestination) destination;
 
             // check to see that this destination was actually created by
             // this connection
             if (temp_dest.getOwningConnection() == this) {
                 // this is currently a no-op but we probably need a way to
                 // clean up on the server side
             } else {
                 throw new JMSException("The temp destination cannot be " +
                     "used outside the scope of the connection creating it");
             }
         } else {
             throw new JMSException("The destination is not temporary");
         }
     }
 
     /***
      * Verifies that the connection is open
      *
      * @throws IllegalStateException if the connection is closed
      */
     protected void ensureOpen() throws IllegalStateException {
         if (_closed) {
             throw new IllegalStateException(
                 "Cannot perform operation - session has been closed");
         }
     }
 
     /***
      * This method will start the event manager service on the first connection
      * that is created
      */
     private static void startEventManager() {
         try {
             if (_activeConnections++ == 0) {
                 try {
                     BasicEventManager.instance().start();
                 } catch (ServiceException exception) {
                     // ignore
                 }
             }
         } catch (Exception exception) {
             _log.error(exception.getMessage(), exception);
         }
     }
 
     /***
      * This method will terminate the event manager service when the last
      * connection has been closed
      */
     private static void stopEventManager() {
         try {
             if (--_activeConnections == 0) {
                 BasicEventManager.instance().stop();
             }
         } catch (Exception exception) {
             exception.printStackTrace();
         }
     }
 
 } //-- JmsConnection