001    /** 
002     * 
003     * Copyright 2004 Protique Ltd
004     * 
005     * Licensed under the Apache License, Version 2.0 (the "License"); 
006     * you may not use this file except in compliance with the License. 
007     * You may obtain a copy of the License at 
008     * 
009     * http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS, 
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
014     * See the License for the specific language governing permissions and 
015     * limitations under the License. 
016     * 
017     **/
018    
019    package org.activemq.broker;
020    
021    import org.activemq.message.ActiveMQMessage;
022    import org.activemq.message.ConnectionInfo;
023    import org.activemq.service.Service;
024    import org.activemq.transport.TransportChannel;
025    
026    import javax.jms.JMSException;
027    import javax.security.auth.Subject;
028    
029    /**
030     * A Broker side proxy representing mostly outbound JMS Connnection
031     */
032    
033    public interface BrokerClient extends Service {
034    
035    
036        /**
037         * Initialize the Brokerclient
038         *
039         * @param brokerConnector
040         * @param channel
041         */
042        public void initialize(BrokerConnector brokerConnector, TransportChannel channel);
043    
044        /**
045         * Dispatch an ActiveMQMessage to the end client
046         *
047         * @param message
048         */
049        public void dispatch(ActiveMQMessage message);
050    
051        /**
052         * @return true if the peer for this Client is itself another Broker
053         */
054        public boolean isBrokerConnection();
055    
056        /**
057         * @return true id this client is part of a cluster
058         */
059        public boolean isClusteredConnection();
060    
061    
062        /**
063         * Get the Capacity for in-progress messages at the peer (probably a JMSConnection)
064         * Legimate values between 0-100. 0 capacity representing that the peer cannot process
065         * any more messages at the current time
066         *
067         * @return
068         */
069        public int getCapacity();
070    
071    
072        /**
073         * Get an indication if the peer should be considered as a slow consumer
074         *
075         * @return true id the peer should be considered as a slow consumer
076         */
077        public boolean isSlowConsumer();
078    
079        /**
080         * Update the peer Connection about the Broker's capacity for messages
081         *
082         * @param capacity
083         */
084        public void updateBrokerCapacity(int capacity);
085    
086        /**
087         * @return the client ID for this client if the client has been initialised
088         */
089        public String getClientID();
090    
091        /**
092         * Called when the transport has been terminated, so do our best to
093         * shut down any resources and deregister from any subscriptions etc
094         */
095        public void cleanUp();
096    
097        /**
098         * @return the TransportChannel
099         */
100        TransportChannel getChannel();
101    
102        /**
103         * @return the BrokerConnector this client is associated with
104         */
105        public BrokerConnector getBrokerConnector();
106    
107        /**
108         * Associcates a subject with BrokerClient.
109         */
110        public void setSubject(Subject subject);
111    
112        /**
113         * @return the Subject associcates with the BrokerClient.
114         */
115        public Subject getSubject();
116    
117        /**
118         * Tests the connection to assert that it in fact is alive by asserting that
119         * a full round-trip to the client is possible.
120         *
121         * @param timeout the number of millisecods to wait before the connection is declared invalid
122         * @throws JMSException if the connection is invalid
123         */
124        public void validateConnection(int timeout) throws JMSException;
125    
126        /**
127         * @return the connection information for this client
128         */
129        public ConnectionInfo getConnectionInfo();
130    }