/** 
 * 
 * Copyright 2004 Protique Ltd
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); 
 * you may not use this file except in compliance with the License. 
 * You may obtain a copy of the License at 
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, 
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 * See the License for the specific language governing permissions and 
 * limitations under the License. 
 * 
 **/

package org.codehaus.activemq.broker;

import org.codehaus.activemq.io.WireFormat;
import org.codehaus.activemq.message.ActiveMQMessage;
import org.codehaus.activemq.message.ActiveMQXid;
import org.codehaus.activemq.message.ConnectionInfo;
import org.codehaus.activemq.message.ConsumerInfo;
import org.codehaus.activemq.message.DurableUnsubscribe;
import org.codehaus.activemq.message.MessageAck;
import org.codehaus.activemq.message.ProducerInfo;
import org.codehaus.activemq.message.SessionInfo;
import org.codehaus.activemq.security.SecurityAdapter;
import org.codehaus.activemq.service.Service;
import org.codehaus.activemq.store.PersistenceAdapter;
import org.codehaus.activemq.transport.DiscoveryAgent;
import org.codehaus.activemq.transport.NetworkConnector;
import org.codehaus.activemq.transport.TransportServerChannel;

import javax.jms.InvalidClientIDException;
import javax.jms.JMSException;
import javax.jms.JMSSecurityException;
import javax.transaction.xa.XAException;
import java.util.List;

/**
 * The ActiveMQ JMS Broker Container which contains a {@link Broker} and one or more
 * {@ BrokerConnector} instances talking over some {@link org.codehaus.activemq.transport.TransportChannel}
 * <p/>
 * <b>Note</b> that  once a broker container has been stopped it should be discarded and a new service
 * instance created again. Calling start() on a stopped broker will not usually work.
 *
 * @version $Revision: 1.2 $
 */
public interface BrokerContainer extends Service {

    /**
     * registers a new Connection
     *
     * @param client
     * @param info   infomation about the client-side Connection
     * @throws InvalidClientIDException if the ClientID of the Connection is a duplicate
     */
    public void registerConnection(BrokerClient client, ConnectionInfo info) throws JMSException;

    /**
     * un-registers a Connection
     *
     * @param client
     * @param info   infomation about the client-side Connection
     * @throws JMSException
     */
    public void deregisterConnection(BrokerClient client, ConnectionInfo info) throws JMSException;

    /**
     * Registers a MessageConsumer
     *
     * @param client
     * @param info
     * @throws JMSException
     * @throws JMSSecurityException if client authentication fails for the Destination the
     *                              Consumer applies for
     */
    public void registerMessageConsumer(BrokerClient client, ConsumerInfo info) throws JMSException;

    /**
     * De-register a MessageConsumer from the Broker
     *
     * @param client
     * @param info
     * @throws JMSException
     */
    public void deregisterMessageConsumer(BrokerClient client, ConsumerInfo info) throws JMSException;

    /**
     * Registers a MessageProducer
     *
     * @param client
     * @param info
     * @throws JMSException
     * @throws JMSSecurityException if client authentication fails for the Destination the
     *                              Consumer applies for
     */

    public void registerMessageProducer(BrokerClient client, ProducerInfo info) throws JMSException;

    /**
     * De-register a MessageProducer from the Broker
     *
     * @param client
     * @param info
     * @throws JMSException
     */
    public void deregisterMessageProducer(BrokerClient client, ProducerInfo info) throws JMSException;

    /**
     * Register a client-side Session (used for Monitoring)
     *
     * @param client
     * @param info
     * @throws JMSException
     */

    public void registerSession(BrokerClient client, SessionInfo info) throws JMSException;

    /**
     * De-register a client-side Session from the Broker (used for monitoring)
     *
     * @param client
     * @param info
     * @throws JMSException
     */
    public void deregisterSession(BrokerClient client, SessionInfo info) throws JMSException;

    /**
     * Start a transaction from the Client session
     *
     * @param client
     * @param transactionId
     * @throws JMSException
     */
    public void startTransaction(BrokerClient client, String transactionId) throws JMSException;

    /**
     * Rollback a transacton
     *
     * @param client
     * @param transactionId
     * @throws JMSException
     */
    public void rollbackTransaction(BrokerClient client, String transactionId) throws JMSException;

    /**
     * Commit a transaction
     *
     * @param client
     * @param transactionId
     * @throws JMSException
     */
    public void commitTransaction(BrokerClient client, String transactionId) throws JMSException;

    /**
     * send message with a transaction context
     *
     * @param client
     * @param transactionId
     * @param message
     * @throws JMSException
     */
    public void sendTransactedMessage(BrokerClient client, String transactionId, ActiveMQMessage message)
            throws JMSException;

    /**
     * Acknowledge receipt of a message within a transaction context
     *
     * @param client
     * @param transactionId
     * @param ack
     * @throws JMSException
     */
    public void acknowledgeTransactedMessage(BrokerClient client, String transactionId, MessageAck ack)
            throws JMSException;

    /**
     * Send a non-transacted message to the Broker
     *
     * @param client
     * @param message
     * @throws JMSException
     */

    public void sendMessage(BrokerClient client, ActiveMQMessage message) throws JMSException;

    /**
     * Acknowledge reciept of a message
     *
     * @param client
     * @param ack
     * @throws JMSException
     */
    public void acknowledgeMessage(BrokerClient client, MessageAck ack) throws JMSException;

    /**
     * Command to delete a durable topic subscription
     *
     * @param client
     * @param ds
     * @throws JMSException
     */

    public void durableUnsubscribe(BrokerClient client, DurableUnsubscribe ds) throws JMSException;

    /**
     * Start an XA transaction.
     *
     * @param client
     * @param xid
     */
    public void startTransaction(BrokerClient client, ActiveMQXid xid) throws XAException;

    /**
     * Gets the prepared XA transactions.
     *
     * @param client
     * @return
     */
    public ActiveMQXid[] getPreparedTransactions(BrokerClient client) throws XAException;

    /**
     * Prepare an XA transaction.
     *
     * @param client
     * @param xid
     */
    public int prepareTransaction(BrokerClient client, ActiveMQXid xid) throws XAException;

    /**
     * Rollback an XA transaction.
     *
     * @param client
     * @param xid
     */
    public void rollbackTransaction(BrokerClient client, ActiveMQXid xid) throws XAException;

    /**
     * Commit an XA transaction.
     *
     * @param client
     * @param xid
     * @param onePhase
     */
    public void commitTransaction(BrokerClient client, ActiveMQXid xid, boolean onePhase) throws XAException;

    /**
     * Called when a new connector is added to this container
     *
     * @param connector
     */
    public void addConnector(BrokerConnector connector);

    /**
     * Called when a connector is removed to this container
     *
     * @param connector
     */
    public void removeConnector(BrokerConnector connector);


    /**
     * @return the Broker for the Container
     */
    public Broker getBroker();

    /**
     * Returns the transport connectors used to communicate with
     * clients
     */
    public List getTransportConnectors();

    public void setTransportConnectors(List transportConnectors);

    /**
     * Returns a list of {@link org.codehaus.activemq.transport.NetworkConnector}
     * instances used to communicate with the network of {@link Broker} instances
     */
    public List getNetworkConnectors();

    public void setNetworkConnectors(List networkConnectors);


    /**
     * Returns the persistence adapter
     */
    public PersistenceAdapter getPersistenceAdapter();

    public void setPersistenceAdapter(PersistenceAdapter persistenceAdapter);

    /**
     * Returns the discovery agent if one is available or null if discovery is not
     * enabled
     */
    public DiscoveryAgent getDiscoveryAgent();

    public void setDiscoveryAgent(DiscoveryAgent discoveryAgent);

    /**
     * Returns the security adapter used to authenticate and authorize access to JMS resources
     */
    public SecurityAdapter getSecurityAdapter();

    /**
     * Sets the security adapter used to authenticate and authorize access to JMS resources
     */
    public void setSecurityAdapter(SecurityAdapter securityAdapter);

    /**
     * Adds a new network connector for the given URI
     */
    NetworkConnector addNetworkConnector(String uri);

    /**
     * Adds a new network connector
     *
     * @return the newly created network connector
     */
    NetworkConnector addNetworkConnector();

    /**
     * Adds a new network connector
     */
    void addNetworkConnector(NetworkConnector connector);

    /**
     * Removes the given network connector
     */
    void removeNetworkConnector(NetworkConnector connector);

    /**
     * Adds a new transport connector for the given bind address
     */
    void addConnector(String bindAddress) throws JMSException;

    /**
     * Adds a new transport connector for the given bind address and wire format
     */
    void addConnector(String bindAddress, WireFormat wireFormat) throws JMSException;

    /**
     * Adds a new transport connector for the given transportConnector
     */
    void addConnector(TransportServerChannel transportConnector);
}