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 * Decoder interface.
033 * Each concrete implementor must specify how to decode given values.
034 *
035 * @author Rafael H. Schloming
036 */
037 public interface Decoder
038 {
039 /**
040 * Tells whether there are any remaining byte(s) to be read.
041 *
042 * @return true if there are remaining bytes, false otherwise.
043 */
044 boolean hasRemaining();
045
046 /**
047 * The uint8 type is an 8-bit unsigned integral value.
048 *
049 * @return an 8-bit unsigned integral value.
050 */
051 short readUint8();
052
053 /**
054 *The uint16 type is a 16-bit unsigned integral value encoded in network byte order.
055 *
056 * @return a 16-bit unsigned integral value encoded in network byte order.
057 */
058 int readUint16();
059
060 /**
061 *The uint32 type is a 32-bit unsigned integral value encoded in network byte order.
062 *
063 * @return a 32-bit unsigned integral value encoded in network byte order.
064 */
065 long readUint32();
066
067 /**
068 * The uint64 type is a 64-bit unsigned integral value encoded in network byte order.
069 *
070 * @return a 64-bit unsigned integral value encoded in network byte order.
071 */
072 long readUint64();
073
074 /**
075 * The datetime type encodes a date and time using the 64 bit POSIX time_t format.
076 *
077 * @return a date and time using the 64 bit POSIX time_t format.
078 */
079 long readDatetime();
080
081 /**
082 * The uuid type encodes a universally unique id as defined by RFC-4122.
083 * The format and operations for this type can be found in section 4.1.2 of RFC-4122.
084 *
085 * return a universally unique id as defined by RFC-4122.
086 */
087 UUID readUuid();
088
089 /**
090 // *The sequence-no type encodes, in network byte order, a serial number as defined in RFC-1982.
091 *
092 * @return a serial number as defined in RFC-1982.
093 */
094 int readSequenceNo();
095
096 RangeSet readSequenceSet(); // XXX
097 RangeSet readByteRanges(); // XXX
098
099 /**
100 * The str8 type encodes up to 255 octets worth of UTF-8 unicode.
101 * The number of octets of unicode is first encoded as an 8-bit unsigned integral value.
102 * This is followed by the actual UTF-8 unicode.
103 * Note that the encoded size refers to the number of octets of unicode, not necessarily the number of characters since
104 * the UTF-8 unicode may include multi-byte character sequences.
105 *
106 * @return a string.
107 */
108 String readStr8();
109
110 /**
111 * The str16 type encodes up to 65535 octets worth of UTF-8 unicode.
112 * The number of octets is first encoded as a 16-bit unsigned integral value in network byte order.
113 * This is followed by the actual UTF-8 unicode.
114 * Note that the encoded size refers to the number of octets of unicode, not necessarily the number of unicode
115 * characters since the UTF-8 unicode may include multi-byte character sequences.
116 *
117 * return a string.
118 */
119 String readStr16();
120
121 /**
122 * The vbin8 type encodes up to 255 octets of opaque binary data.
123 *
124 * return a byte array.
125 */
126 byte[] readVbin8();
127
128 /**
129 * The vbin16 type encodes up to 65535 octets of opaque binary data.
130 *
131 * @return the corresponding byte array.
132 */
133 byte[] readVbin16();
134
135 /**
136 * The vbin32 type encodes up to 4294967295 octets of opaque binary data.
137 *
138 * @return the corresponding byte array.
139 */
140 byte[] readVbin32();
141
142 /**
143 * The struct32 type describes any coded struct with a 32-bit (4 octet) size.
144 * The type is restricted to be only coded structs with a 32-bit size, consequently the first six octets of any encoded
145 * value for this type MUST always contain the size, class-code, and struct-code in that order.
146 * The size is encoded as a 32-bit unsigned integral value in network byte order that is equal to the size of the
147 * encoded field-data, packing-flags, class-code, and struct-code. The class-code is a single octet that may be set to any
148 * valid class code.
149 * The struct-code is a single octet that may be set to any valid struct code within the given class-code.
150 * The first six octets are then followed by the packing flags and encoded field data.
151 * The presence and quantity of packingflags, as well as the specific fields are determined by the struct definition
152 * identified with the encoded class-code and struct-code.
153 *
154 * @return the decoded struct.
155 */
156 Struct readStruct32();
157
158 /**
159 * A map is a set of distinct keys where each key has an associated (type,value) pair.
160 * The triple of the key, type, and value, form an entry within a map. Each entry within a given map MUST have a
161 * distinct key.
162 * A map is encoded as a size in octets, a count of the number of entries, followed by the encoded entries themselves.
163 * An encoded map may contain up to (4294967295 - 4) octets worth of encoded entries.
164 * The size is encoded as a 32-bit unsigned integral value in network byte order equal to the number of octets worth of
165 * encoded entries plus 4. (The extra 4 octets is added for the entry count.)
166 * The size is then followed by the number of entries encoded as a 32-bit unsigned integral value in network byte order.
167 * Finally the entries are encoded sequentially.
168 * 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.
169 * The type is a single octet that may contain any valid AMQP type code.
170 * The value is encoded according to the rules defined by the type code for that entry.
171 *
172 * @return the decoded map.
173 */
174 Map<String,Object> readMap();
175
176 /**
177 * A list is an ordered sequence of (type, value) pairs. The (type, value) pair forms an item within the list.
178 * The list may contain items of many distinct types. A list is encoded as a size in octets, followed by a count of the
179 * number of items, followed by the items themselves encoded in their defined order.
180 * An encoded list may contain up to (4294967295 - 4) octets worth of encoded items.
181 * The size is encoded as a 32-bit unsigned integral value in network byte order equal to the number of octets worth
182 * of encoded items plus 4. (The extra4 octets is added for the item count.)
183 * The size is then followed by the number of items encoded as a 32-bit unsigned integral value in network byte order.
184 * Finally the items are encoded sequentially in their defined order.
185 * An item is encoded as the type followed by the value. The type is a single octet that may contain any valid AMQP type
186 * code.
187 * The value is encoded according to the rules defined by the type code for that item.
188 *
189 * @return the decoded list.
190 */
191 List<Object> readList();
192
193 /**
194 * An array is an ordered sequence of values of the same type.
195 * 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,
196 * and finally the values encoded in their defined order.
197 * An encoded array may contain up to (4294967295 - 5) octets worth of encoded values.
198 * The size is encoded as a 32-bit unsigned integral value in network byte order equal to the number of octets worth of
199 * encoded values plus 5. (The extra 5 octets consist of 4 octets for the count of the number of values, and one octet to
200 * hold the type code for the items inthe array.)
201 * The size is then followed by a single octet that may contain any valid AMQP type code.
202 * The type code is then followed by the number of values encoded as a 32-bit unsigned integral value in network byte
203 * order.
204 * Finally the values are encoded sequentially in their defined order according to the rules defined by the type code for
205 * the array.
206 *
207 * @return the decoded array.
208 */
209 List<Object> readArray();
210
211 /**
212 *
213 * @param type the type of the struct.
214 * @return the decoded struct.
215 */
216 Struct readStruct(int type);
217
218 /**
219 * The float type encodes a single precision 32-bit floating point number.
220 * The format and operations are defined by the IEEE 754 standard for 32-bit single precision floating point numbers.
221 *
222 * @return the decoded float.
223 */
224 float readFloat();
225
226 /**
227 * The double type encodes a double precision 64-bit floating point number.
228 * The format and operations are defined by the IEEE 754 standard for 64-bit double precision floating point numbers.
229 *
230 * @return the decoded double
231 */
232 double readDouble();
233
234 /**
235 * The int8 type is a signed integral value encoded using an 8-bit two's complement representation.
236 *
237 * @return the decoded integer.
238 */
239 byte readInt8();
240
241 /**
242 * The int16 type is a signed integral value encoded using a 16-bit two's complement representation in network byte order.
243 *
244 * @return the decoded integer.
245 */
246 short readInt16();
247
248 /**
249 * The int32 type is a signed integral value encoded using a 32-bit two's complement representation in network byte order.
250 *
251 * @return the decoded integer.
252 */
253 int readInt32();
254
255 /**
256 * The int64 type is a signed integral value encoded using a 64-bit two's complement representation in network byte order.
257 *
258 * @return the decoded integer (as long).
259 */
260 long readInt64();
261
262 /**
263 * The bin128 type consists of 16 consecutive octets of opaque binary data.
264 *
265 * @return the decoded byte array.
266 */
267 byte [] readBin128();
268
269 /**
270 * Reads the remaining bytes on the underlying buffer.
271 *
272 * @return the remaining bytes on the underlying buffer.
273 */
274 byte[] readReaminingBytes ();
275
276 /**
277 * Reads the given number of bytes.
278 *
279 * @param howManyBytes how many bytes need to be read?
280 * @return a byte array containing the requested data.
281 */
282 byte[] readBytes (int howManyBytes);
283 }
|