/** 
 * 
 * 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 javax.security.auth.Subject;

import org.codehaus.activemq.message.ActiveMQMessage;
import org.codehaus.activemq.service.Service;
import org.codehaus.activemq.transport.TransportChannel;

/**
 * A Broker side proxy representing mostly outbound JMS Connnection
 */

public interface BrokerClient extends Service {


    /**
     * Initialize the Brokerclient
     *
     * @param brokerConnector
     * @param channel
     */
    public void initialize(BrokerConnector brokerConnector, TransportChannel channel);

    /**
     * Dispatch an ActiveMQMessage to the end client
     *
     * @param message
     */
    public void dispatch(ActiveMQMessage message);

    /**
     * @return true if the peer for this Client is itself another Broker
     */
    public boolean isBrokerConnection();
    
    /**
     * @return true id this client is part of a cluster 
     */
    public boolean isClusteredConnection();


    /**
     * Get the Capacity for in-progress messages at the peer (probably a JMSConnection)
     * Legimate values between 0-100. 0 capacity representing that the peer cannot process
     * any more messages at the current time
     *
     * @return
     */
    public int getCapacity();


    /**
     * Get an indication if the peer should be considered as a slow consumer
     *
     * @return true id the peer should be considered as a slow consumer
     */
    public boolean isSlowConsumer();

    /**
     * Update the peer Connection about the Broker's capacity for messages
     *
     * @param capacity
     */
    public void updateBrokerCapacity(int capacity);

    /**
     * @return the client ID for this client if the client has been initialised
     */
    public String getClientID();

    /**
     * Called when the transport has been terminated, so do our best to
     * shut down any resources and deregister from any subscriptions etc
     */
    public void cleanUp();

    /**
     * @return the TransportChannel
     */
    TransportChannel getChannel();
    
    /**
     * @return the BrokerConnector this client is associated with
     */
    public BrokerConnector getBrokerConnector();
    
    /**
     * Associcates a subject with BrokerClient.
     */
    public void setSubject(Subject subject);

    /**
     * @return the Subject associcates with the BrokerClient.
     */
    public Subject getSubject();
    
}
