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.io;
020 import java.io.DataInput;
021 import java.io.DataInputStream;
022 import java.io.DataOutput;
023 import java.io.DataOutputStream;
024 import java.io.IOException;
025 import java.net.DatagramPacket;
026 import javax.jms.JMSException;
027 import org.activemq.message.Packet;
028
029 /**
030 * Represents a strategy of encoding packets on the wire or on disk
031 * using some kind of serialization or wire format.
032 * <p/>
033 * We use a default efficient format
034 * for Java to Java communication but other formats to other systems
035 * can be used, such as using simple text
036 * strings when talking to JavaScript or coming up with other formats for
037 * talking to C / C# languages or proprietary messaging systems
038 * we wish to interface with at the wire level etc.
039 *
040 * @version $Revision: 1.1.1.1 $
041 */
042 public interface WireFormat {
043 /**
044 * The maximum message size supported by the transport
045 * If the message is bigger than this size, then the message
046 * will be 'chunked' into separate pieces and re-assembled
047 * on the consumer
048 */
049 public static final int DEFAULT_MAXIMUM_MESSAGE_SIZE = 64 * 1024;
050
051 /**
052 * Reads a packet from the given input stream
053 *
054 * @param in
055 * @return
056 * @throws IOException
057 */
058 public Packet readPacket(DataInput in) throws IOException;
059
060 /**
061 * A helper method for working with sockets where the first byte is read
062 * first, then the rest of the message is read.
063 * <p/>
064 * Its common when dealing with sockets to have different timeout semantics
065 * until the first non-zero byte is read of a message, after which
066 * time a zero timeout is used.
067 *
068 * @param firstByte the first byte of the packet
069 * @param in the rest of the packet
070 * @return
071 * @throws IOException
072 */
073 public Packet readPacket(int firstByte, DataInput in) throws IOException;
074
075
076 /**
077 * Read a packet from a Datagram packet from the given channelID. If the
078 * packet is from the same channel ID as it was sent then we have a
079 * loop-back so discard the packet
080 *
081 * @param channelID is the unique channel ID
082 * @param dpacket
083 * @return the packet read from the datagram or null if it should be
084 * discarded
085 * @throws IOException
086 */
087 public Packet readPacket(String channelID, DatagramPacket dpacket) throws IOException;
088
089 /**
090 * Writes the packet to the given output stream
091 *
092 * @param packet
093 * @param out
094 * @return a response packet - or null
095 * @throws IOException
096 * @throws JMSException
097 */
098 public Packet writePacket(Packet packet, DataOutput out) throws IOException, JMSException;
099
100 /**
101 * Writes the given package to a new datagram
102 *
103 * @param channelID is the unique channel ID
104 * @param packet is the packet to write
105 * @return
106 * @throws IOException
107 * @throws JMSException
108 */
109 public DatagramPacket writePacket(String channelID, Packet packet) throws IOException, JMSException;
110
111 /**
112 * Reads the packet from the given byte[]
113 * @param bytes
114 * @param offset
115 * @param length
116 * @return
117 * @throws IOException
118 */
119 public Packet fromBytes(byte[] bytes, int offset, int length) throws IOException;
120
121 /**
122 * Reads the packet from the given byte[]
123 * @param bytes
124 * @return
125 * @throws IOException
126 */
127 public Packet fromBytes(byte[] bytes) throws IOException;
128
129 /**
130 * A helper method which converts a packet into a byte array
131 *
132 * @param packet
133 * @return a byte array representing the packet using some wire protocol
134 * @throws IOException
135 * @throws JMSException
136 */
137 public byte[] toBytes(Packet packet) throws IOException, JMSException;
138
139 /**
140 * Creates a new copy of this wire format so it can be used in another thread/context
141 *
142 * @return
143 */
144 public WireFormat copy();
145
146 /**
147 * Can this wireformat process packets of this version
148 * @param version the version number to test
149 * @return true if can accept the version
150 */
151 public boolean canProcessWireFormatVersion(int version);
152
153 /**
154 * @return the current version of this wire format
155 */
156 public int getCurrentWireFormatVersion();
157
158 /**
159 * some transports may register their streams (e.g. Tcp)
160 * @param dataOut
161 * @param dataIn
162 */
163 public void registerTransportStreams(DataOutputStream dataOut, DataInputStream dataIn);
164
165 /**
166 * Some wire formats require a handshake at start-up
167 * @throws IOException
168 */
169 public void initiateClientSideProtocol() throws IOException;
170
171
172 /**
173 * Some wire formats require a handshake at start-up
174 * @throws IOException
175 */
176 public void initiateServerSideProtocol() throws IOException;
177
178
179 /**
180 * @return Returns the enableCaching.
181 */
182 public boolean isCachingEnabled();
183
184 /**
185 * @param enableCaching The enableCaching to set.
186 */
187 public void setCachingEnabled(boolean enableCaching);
188
189 /**
190 * some wire formats will implement their own fragementation
191 * @return true unless a wire format supports it's own fragmentation
192 */
193 public boolean doesSupportMessageFragmentation();
194
195
196 /**
197 * Some wire formats will not be able to understand compressed messages
198 * @return true unless a wire format cannot understand compression
199 */
200 public boolean doesSupportMessageCompression();
201
202 }