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 }