/** 
 * 
 * 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.message.ActiveMQMessage;
import org.codehaus.activemq.message.ActiveMQXid;
import org.codehaus.activemq.message.BrokerInfo;
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.service.Service;
import org.codehaus.activemq.transport.TransportServerChannel;

import javax.jms.JMSException;
import javax.jms.JMSSecurityException;
import javax.transaction.xa.XAException;

/**
 * The Broker is the client side interface to the JMS server
 *
 * @version $Revision: 1.1 $
 */
public interface BrokerConnector extends Service {

    /**
     * @return infomation about the Broker
     */
    public BrokerInfo getBrokerInfo();

    /**
     * @return the transport channel this broker is using
     */
    public TransportServerChannel getServerChannel();

    /**
     * Get a hint about the broker capacity for more messages
     *
     * @return percentage value (0-100) about how much capacity the
     *         broker has
     */
    public int getBrokerCapacity();

    /**
     * Register a Broker Client
     *
     * @param client
     * @param info   contains infomation about the Connection this Client
     *               represents
     * @throws JMSException
     * @throws javax.jms.InvalidClientIDException
     *                              if the JMS client specifies an invalid or duplicate client
     *                              ID.
     * @throws JMSSecurityException if client authentication fails due to an invalid user name or
     *                              password.
     */
    public void registerClient(BrokerClient client, ConnectionInfo info) throws JMSException;

    /**
     * Deregister a Broker Client
     *
     * @param client
     * @param info
     * @throws JMSException if some internal error occurs
     */

    public void deregisterClient(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;


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

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

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

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

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

    /**
     * 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;

    /**
     * Gets the unique id of the resource manager used for managing xa
     * transactions.
     *
     * @param client
     * @return the id
     */
    public String getResourceManagerId(BrokerClient client);

    /**
     * @return the BrokerContainer for this Connector
     */
    public BrokerContainer getBrokerContainer();


}