Source code: org/activemq/io/WireFormat.java
1 /**
2 *
3 * Copyright 2004 Protique Ltd
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 **/
18
19 package org.activemq.io;
20 import java.io.DataInput;
21 import java.io.DataInputStream;
22 import java.io.DataOutput;
23 import java.io.DataOutputStream;
24 import java.io.IOException;
25 import java.net.DatagramPacket;
26 import javax.jms.JMSException;
27 import org.activemq.message.Packet;
28
29 /**
30 * Represents a strategy of encoding packets on the wire or on disk
31 * using some kind of serialization or wire format.
32 * <p/>
33 * We use a default efficient format
34 * for Java to Java communication but other formats to other systems
35 * can be used, such as using simple text
36 * strings when talking to JavaScript or coming up with other formats for
37 * talking to C / C# languages or proprietary messaging systems
38 * we wish to interface with at the wire level etc.
39 *
40 * @version $Revision: 1.1.1.1 $
41 */
42 public interface WireFormat {
43 /**
44 * The maximum message size supported by the transport
45 * If the message is bigger than this size, then the message
46 * will be 'chunked' into separate pieces and re-assembled
47 * on the consumer
48 */
49 public static final int DEFAULT_MAXIMUM_MESSAGE_SIZE = 64 * 1024;
50
51 /**
52 * Reads a packet from the given input stream
53 *
54 * @param in
55 * @return
56 * @throws IOException
57 */
58 public Packet readPacket(DataInput in) throws IOException;
59
60 /**
61 * A helper method for working with sockets where the first byte is read
62 * first, then the rest of the message is read.
63 * <p/>
64 * Its common when dealing with sockets to have different timeout semantics
65 * until the first non-zero byte is read of a message, after which
66 * time a zero timeout is used.
67 *
68 * @param firstByte the first byte of the packet
69 * @param in the rest of the packet
70 * @return
71 * @throws IOException
72 */
73 public Packet readPacket(int firstByte, DataInput in) throws IOException;
74
75
76 /**
77 * Read a packet from a Datagram packet from the given channelID. If the
78 * packet is from the same channel ID as it was sent then we have a
79 * loop-back so discard the packet
80 *
81 * @param channelID is the unique channel ID
82 * @param dpacket
83 * @return the packet read from the datagram or null if it should be
84 * discarded
85 * @throws IOException
86 */
87 public Packet readPacket(String channelID, DatagramPacket dpacket) throws IOException;
88
89 /**
90 * Writes the packet to the given output stream
91 *
92 * @param packet
93 * @param out
94 * @return a response packet - or null
95 * @throws IOException
96 * @throws JMSException
97 */
98 public Packet writePacket(Packet packet, DataOutput out) throws IOException, JMSException;
99
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 }