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 }