001 /*
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements. See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership. The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License. You may obtain a copy of the License at
010 *
011 * http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied. See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 *
020 */
021 package org.apache.qpid.transport.codec;
022
023 import java.util.List;
024 import java.util.Map;
025 import java.util.UUID;
026
027 import org.apache.qpid.transport.RangeSet;
028 import org.apache.qpid.transport.Struct;
029
030
031 /**
032 * Encoder interface.
033 * Each concrete implementor must specify how to encode given values.
034 *
035 * @author Rafael H. Schloming
036 */
037 public interface Encoder
038 {
039 /**
040 * The uint8 type is an 8-bit unsigned integral value.
041 *
042 * @param b the unsigned integer to be encoded.
043 */
044 void writeUint8(short b);
045
046 /**
047 *The uint16 type is a 16-bit unsigned integral value encoded in network byte order.
048 *
049 * @param s the unsigned integer to be encoded.
050 */
051 void writeUint16(int s);
052
053 /**
054 *The uint32 type is a 32-bit unsigned integral value encoded in network byte order.
055 *
056 * @param i the unsigned integer to be encoded.
057 */
058 void writeUint32(long i);
059
060 /**
061 * The uint64 type is a 64-bit unsigned integral value encoded in network byte order.
062 *
063 * @param b the unsigned integer to be encoded.
064 */
065 void writeUint64(long l);
066
067 /**
068 * The datetime type encodes a date and time using the 64 bit POSIX time_t format.
069 *
070 * @param l the datetime (as long) to be encoded.
071 */
072 void writeDatetime(long l);
073
074 /**
075 * The uuid type encodes a universally unique id as defined by RFC-4122.
076 * The format and operations for this type can be found in section 4.1.2 of RFC-4122.
077 *
078 * @param uuid the uuid to be encoded.
079 */
080 void writeUuid(UUID uuid);
081
082 /**
083 *The sequence-no type encodes, in network byte order, a serial number as defined in RFC-1982.
084 *
085 * @param s the sequence number to be encoded.
086 */
087 void writeSequenceNo(int s);
088
089 void writeSequenceSet(RangeSet ranges); // XXX
090 void writeByteRanges(RangeSet ranges); // XXX
091
092 /**
093 * The str8 type encodes up to 255 octets worth of UTF-8 unicode.
094 * The number of octets of unicode is first encoded as an 8-bit unsigned integral value.
095 * This is followed by the actual UTF-8 unicode.
096 * Note that the encoded size refers to the number of octets of unicode, not necessarily the number of characters since
097 * the UTF-8 unicode may include multi-byte character sequences.
098 *
099 * @param s the string to be encoded.
100 */
101 void writeStr8(String s);
102
103 /**
104 * The str16 type encodes up to 65535 octets worth of UTF-8 unicode.
105 * The number of octets is first encoded as a 16-bit unsigned integral value in network byte order.
106 * This is followed by the actual UTF-8 unicode.
107 * Note that the encoded size refers to the number of octets of unicode, not necessarily the number of unicode
108 * characters since the UTF-8 unicode may include multi-byte character sequences.
109 *
110 * @param s the string to be encoded.
111 */
112 void writeStr16(String s);
113
114 /**
115 * The vbin8 type encodes up to 255 octets of opaque binary data.
116 * The number of octets is first encoded as an 8-bit unsigned integral value.
117 * This is followed by the actual data.
118 *
119 * @param bytes the byte array to be encoded.
120 */
121 void writeVbin8(byte[] bytes);
122
123 /**
124 * The vbin16 type encodes up to 65535 octets of opaque binary data.
125 * The number of octets is first encoded as a 16-bit unsigned integral value in network byte order.
126 * This is followed by the actual data.
127 *
128 * @param bytes the byte array to be encoded.
129 */
130 void writeVbin16(byte[] bytes);
131
132 /**
133 * The vbin32 type encodes up to 4294967295 octets of opaque binary data.
134 * The number of octets is first encoded as a 32-bit unsigned integral value in network byte order.
135 * This is followed by the actual data.
136 *
137 * @param bytes the byte array to be encoded.
138 */
139 void writeVbin32(byte[] bytes);
140
141 /**
142 * The struct32 type describes any coded struct with a 32-bit (4 octet) size.
143 * The type is restricted to be only coded structs with a 32-bit size, consequently the first six octets of any encoded
144 * value for this type MUST always contain the size, class-code, and struct-code in that order.
145 * The size is encoded as a 32-bit unsigned integral value in network byte order that is equal to the size of the
146 * encoded field-data, packing-flags, class-code, and struct-code. The class-code is a single octet that may be set to any
147 * valid class code.
148 * The struct-code is a single octet that may be set to any valid struct code within the given class-code.
149 * The first six octets are then followed by the packing flags and encoded field data.
150 * The presence and quantity of packingflags, as well as the specific fields are determined by the struct definition
151 * identified with the encoded class-code and struct-code.
152 *
153 * @param struct the struct to be encoded.
154 */
155 void writeStruct32(Struct struct);
156
157 /**
158 * A map is a set of distinct keys where each key has an associated (type,value) pair.
159 * The triple of the key, type, and value, form an entry within a map. Each entry within a given map MUST have a
160 * distinct key.
161 * A map is encoded as a size in octets, a count of the number of entries, followed by the encoded entries themselves.
162 * An encoded map may contain up to (4294967295 - 4) octets worth of encoded entries.
163 * The size is encoded as a 32-bit unsigned integral value in network byte order equal to the number of octets worth of
164 * encoded entries plus 4. (The extra 4 octets is added for the entry count.)
165 * The size is then followed by the number of entries encoded as a 32-bit unsigned integral value in network byte order.
166 * Finally the entries are encoded sequentially.
167 * An entry is encoded as the key, followed by the type, and then the value. The key is always a string encoded as a str8.
168 * The type is a single octet that may contain any valid AMQP type code.
169 * The value is encoded according to the rules defined by the type code for that entry.
170 *
171 * @param map the map to be encoded.
172 */
173 void writeMap(Map<String,Object> map);
174
175 /**
176 * A list is an ordered sequence of (type, value) pairs. The (type, value) pair forms an item within the list.
177 * The list may contain items of many distinct types. A list is encoded as a size in octets, followed by a count of the
178 * number of items, followed by the items themselves encoded in their defined order.
179 * An encoded list may contain up to (4294967295 - 4) octets worth of encoded items.
180 * The size is encoded as a 32-bit unsigned integral value in network byte order equal to the number of octets worth
181 * of encoded items plus 4. (The extra4 octets is added for the item count.)
182 * The size is then followed by the number of items encoded as a 32-bit unsigned integral value in network byte order.
183 * Finally the items are encoded sequentially in their defined order.
184 * An item is encoded as the type followed by the value. The type is a single octet that may contain any valid AMQP type
185 * code.
186 * The value is encoded according to the rules defined by the type code for that item.
187 *
188 * @param list the list to be encoded.
189 */
190 void writeList(List<Object> list);
191
192 /**
193 * An array is an ordered sequence of values of the same type.
194 * The array is encoded in as a size in octets, followed by a type code, then a count of the number values in the array,
195 * and finally the values encoded in their defined order.
196 * An encoded array may contain up to (4294967295 - 5) octets worth of encoded values.
197 * The size is encoded as a 32-bit unsigned integral value in network byte order equal to the number of octets worth of
198 * encoded values plus 5. (The extra 5 octets consist of 4 octets for the count of the number of values, and one octet to
199 * hold the type code for the items inthe array.)
200 * The size is then followed by a single octet that may contain any valid AMQP type code.
201 * The type code is then followed by the number of values encoded as a 32-bit unsigned integral value in network byte
202 * order.
203 * Finally the values are encoded sequentially in their defined order according to the rules defined by the type code for
204 * the array.
205 *
206 * @param array the array to be encoded.
207 */
208 void writeArray(List<Object> array);
209
210 /**
211 * The struct32 type describes any coded struct with a 32-bit (4 octet) size.
212 * The type is restricted to be only coded structs with a 32-bit size, consequently the first six octets of any encoded
213 * value for this type MUST always contain the size, class-code, and struct-code in that order.
214 * The size is encoded as a 32-bit unsigned integral value in network byte order that is equal to the size of the
215 * encoded field-data, packing-flags, class-code, and struct-code. The class-code is a single octet that may be set to any
216 * valid class code.
217 * The struct-code is a single octet that may be set to any valid struct code within the given class-code.
218 * The first six octets are then followed by the packing flags and encoded field data.
219 * The presence and quantity of packingflags, as well as the specific fields are determined by the struct definition
220 * identified with the encoded class-code and struct-code.
221 *
222 * @param type the type of the struct.
223 * @param struct the struct to be encoded.
224 */
225 void writeStruct(int type, Struct struct);
226
227 /**
228 * The float type encodes a single precision 32-bit floating point number.
229 * The format and operations are defined by the IEEE 754 standard for 32-bit single precision floating point numbers.
230 *
231 * @param aFloat the float to be encoded.
232 */
233 void writeFloat(float aFloat);
234
235 /**
236 * The double type encodes a double precision 64-bit floating point number.
237 * The format and operations are defined by the IEEE 754 standard for 64-bit double precision floating point numbers.
238 *
239 * @param aDouble the double to be encoded.
240 */
241 void writeDouble(double aDouble);
242
243 /**
244 * The int8 type is a signed integral value encoded using an 8-bit two's complement representation.
245 *
246 * @param aByte the integer to be encoded.
247 */
248 void writeInt8(byte aByte);
249
250 /**
251 * The int16 type is a signed integral value encoded using a 16-bit two's complement representation in network byte order.
252 *
253 * @param aShort the integer to be encoded.
254 */
255 void writeInt16(short aShort);
256
257 /**
258 * The int32 type is a signed integral value encoded using a 32-bit two's complement representation in network byte order.
259 *
260 * @param anInt the integer to be encoded.
261 */
262 void writeInt32(int anInt);
263
264 /**
265 * The int64 type is a signed integral value encoded using a 64-bit two's complement representation in network byte order.
266 *
267 * @param aLong the integer to be encoded.
268 */
269 void writeInt64(long aLong);
270
271 /**
272 * The bin128 type consists of 16 consecutive octets of opaque binary data.
273 *
274 * @param bytes the bytes array to be encoded.
275 */
276 void writeBin128(byte [] bytes);
277
278 /**
279 * Encodes the AMQP magic number.
280 */
281 void writeMagicNumber();
282 }
|