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.transport;
020    
021    import org.activemq.broker.BrokerConnector;
022    import org.activemq.io.WireFormat;
023    import org.activemq.message.Packet;
024    import org.activemq.message.PacketListener;
025    import org.activemq.message.Receipt;
026    import org.activemq.message.ReceiptHolder;
027    import org.activemq.service.Service;
028    
029    import javax.jms.ExceptionListener;
030    import javax.jms.JMSException;
031    
032    /**
033     * A TransportChannel is used for tranporting packets between nodes
034     * e.g. a ActiveMQ JMS Connection and Broker.
035     * The TransportChannel supports synchronous and asynchronous send operations
036     * as well as sync or async reading of packets. A TransportChannel implementation
037     * could use a dedicated thread using blocking IO to read from a socket or
038     * could use NIO or poll some file system or database etc.
039     * On receipt of a Packet the TransportChannel should invoke the PacketListener
040     *
041     * @version $Revision: 1.1.1.1 $
042     */
043    public interface TransportChannel extends Service {
044    
045        
046        
047        /**
048         * Give the TransportChannel a hint it's about to stop
049         * @param pendingStop
050         *
051         */
052        public void setPendingStop(boolean pendingStop);
053        
054        /**
055         * @return true if the channel is about to stop
056         */
057        public boolean isPendingStop();
058    
059        /**
060         * close the channel
061         */
062        public void stop();
063    
064        /**
065         * start listeneing for events
066         *
067         * @throws JMSException if an error occurs
068         */
069        public void start() throws JMSException;
070    
071        /**
072         * Forces an immediate transport-level disconnect which will be asynchronously reported 
073         * as an exception to the exceptionListener. If the channel isn't connected, the call will
074         * be ignored.
075         */
076        public void forceDisconnect();
077        
078        /**
079         * Gets the timestamp of the last received receipt packet.
080         * 
081         * @return the timestamp in milliseconds
082         */
083        public long getLastReceiptTimestamp();
084        
085        /**
086         * synchronously send a Packet
087         *
088         * @param packet
089         * @return a Receipt
090         * @throws JMSException
091         */
092    
093        public Receipt send(Packet packet) throws JMSException;
094    
095        /**
096         * Synchrnously send a Packet
097         *
098         * @param packet  packet to send
099         * @param timeout amount of time to wait for a receipt
100         * @return the Receipt
101         * @throws JMSException
102         */
103    
104        public Receipt send(Packet packet, int timeout) throws JMSException;
105    
106        /**
107         * Asynchronously send a Packet
108         *
109         * @param packet the packet to send
110         * @throws JMSException
111         */
112    
113        public void asyncSend(Packet packet) throws JMSException;
114        
115        /**
116         * Asynchronously send a Packet with receipt.
117         * 
118         * @param packet the packet to send
119         * @return a ReceiptHolder for the packet
120         * @throws JMSException
121         */
122        public ReceiptHolder asyncSendWithReceipt(Packet packet) throws JMSException;
123    
124        /**
125         * Set a listener for Packets
126         *
127         * @param l
128         */
129        public void setPacketListener(PacketListener l);
130    
131    
132        /**
133         * Set an exception listener to listen for asynchronously generated exceptions
134         *
135         * @param listener
136         */
137        public void setExceptionListener(ExceptionListener listener);
138    
139        /**
140         * @return true if this transport is multicast based (i.e. broadcasts to multiple nodes)
141         */
142        public boolean isMulticast();
143    
144        /**
145         * Add a listener for changes in a channels status
146         *
147         * @param listener
148         */
149        public void addTransportStatusEventListener(TransportStatusEventListener listener);
150    
151        /**
152         * Remove a listener for changes in a channels status
153         *
154         * @param listener
155         */
156        public void removeTransportStatusEventListener(TransportStatusEventListener listener);
157    
158        /**
159         * Provides a way to specify the client ID that this channel is using
160         *
161         * @param clientID
162         */
163        public void setClientID(String clientID);
164    
165        /**
166         * @return the client ID that this channel is being used for
167         */
168        public String getClientID();
169    
170        /**
171         * A listener to be notified when the channel is removed
172         *
173         * @param listener
174         */
175        public void setTransportChannelListener(TransportChannelListener listener);
176    
177        /**
178         * @return true if this transport is used by the broker to
179         * communicate with a client, or false if this is a client side
180         * transport
181         */
182        public boolean isServerSide();
183    
184        /**
185         * set the server flag
186         * @param serverSide
187         */
188        public void setServerSide(boolean serverSide);
189        
190        /**
191         * Can this wireformat process packets of this version
192         * @param version the version number to test
193         * @return true if can accept the version
194         */
195        public boolean canProcessWireFormatVersion(int version);
196        
197        /**
198         * @return the current version of this wire format
199         */
200        public int getCurrentWireFormatVersion();
201        
202        /**
203         * @return true if the transport channel is active,
204         * this value will be false through reconnecting
205         */
206        public boolean isTransportConnected();
207        
208        /**
209         * Some transports rely on an embedded broker (peer based protocols)
210         * @return true if an embedded broker required
211         */
212        public boolean requiresEmbeddedBroker();
213        
214        /**
215         * Some transports that rely on an embedded broker need to
216         * create the connector used by the broker
217         * @return the BrokerConnector or null if not applicable
218         * @throws JMSException
219         */
220        public BrokerConnector getEmbeddedBrokerConnector() throws JMSException;
221        
222        /**
223         * set the wire format to be used by this channel
224         * @param wireformat
225         */
226        public void setWireFormat(WireFormat wireformat);
227        
228        /**
229         * Get the current wireformat used by this channel
230         * @return the current wire format, or null if not set
231         */
232        public WireFormat getWireFormat();
233        
234        /**
235         * Does the transport support wire format version info
236         * @return true if it odes
237         */
238        public boolean doesSupportWireFormatVersioning();
239        
240        
241        /**
242         * some transports/wire formats will implement their own fragementation
243         * @return true unless a transport/wire format supports it's own fragmentation
244         */
245        public boolean doesSupportMessageFragmentation();
246        
247        
248        /**
249         * Some transports/wireformats will not be able to understand compressed messages
250         * @return true unless a transport/wire format cannot understand compression
251         */
252        public boolean doesSupportMessageCompression();
253        
254       
255        /**
256         * @return Returns the cachingEnabled.
257         */
258        public boolean isCachingEnabled();
259        /**
260         * @param cachingEnabled The cachingEnabled to set.
261         */
262        public void setCachingEnabled(boolean cachingEnabled);
263        
264        /**
265         * Inform Transport to send messages as quickly
266         * as possible - for Tcp - this means disabling Nagles,
267         * which on OSX may provide better performance for sync
268         * sends
269         * @return Returns the noDelay.
270         */
271        public boolean isNoDelay();
272        /**
273         * @param noDelay The noDelay to set.
274         */
275        public void setNoDelay(boolean noDelay);
276        
277        /**
278         * @return Returns the usedInternally.
279         */
280        public boolean isUsedInternally();
281        /**
282         * @param usedInternally The usedInternally to set.
283         */
284        public void setUsedInternally(boolean usedInternally);
285        
286    }