001 /*
002 * Copyright 2009 Red Hat, Inc.
003 * Red Hat licenses this file to you under the Apache License, version
004 * 2.0 (the "License"); you may not use this file except in compliance
005 * with the License. You may obtain a copy of the License at
006 * http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
010 * implied. See the License for the specific language governing
011 * permissions and limitations under the License.
012 */
013
014 package org.hornetq.api.core;
015
016 import java.util.Map;
017 import java.util.Set;
018
019 import org.hornetq.utils.UUID;
020
021
022 /**
023 * A Message is a routable instance that has a payload.
024 * <br/>
025 * The payload (the "body") is opaque to the messaging system.
026 * A Message also has a fixed set of headers (required by the messaging system)
027 * and properties (defined by the users) that can be used by the messaging system
028 * to route the message (e.g. to ensure it matches a queue filter).
029 * <br>
030 * <h2>Message Properties</h2>
031 *
032 * Message can contain properties specified by the users.
033 * It is possible to convert from some types to other types as specified
034 * by the following table:
035 * <pre>
036 * | | boolean byte short int long float double String byte[]
037 * |----------------------------------------------------------------
038 * |boolean | X X
039 * |byte | X X X X X
040 * |short | X X X X
041 * |int | X X X
042 * |long | X X
043 * |float | X X X
044 * |double | X X
045 * |String | X X X X X X X X
046 * |byte[] | X
047 * |-----------------------------------------------------------------
048 * </pre>
049 * <br>
050 * If conversion is not allowed (for example calling {@code getFloatProperty} on a property set a {@code boolean}),
051 * a PropertyConversionException will be thrown.
052 *
053 * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
054 * @author <a href="mailto:clebert.suconic@jboss.com">ClebertSuconic</a>
055 * @version <tt>$Revision: 3341 $</tt>
056 *
057 * $Id: Message.java 3341 2007-11-19 14:34:57Z timfox $
058 */
059 public interface Message
060 {
061 public static final SimpleString HDR_ACTUAL_EXPIRY_TIME = new SimpleString("_HQ_ACTUAL_EXPIRY");
062
063 public static final SimpleString HDR_ORIGINAL_ADDRESS = new SimpleString("_HQ_ORIG_ADDRESS");
064
065 public static final SimpleString HDR_ORIG_MESSAGE_ID = new SimpleString("_HQ_ORIG_MESSAGE_ID");
066
067 public static final SimpleString HDR_GROUP_ID = new SimpleString("_HQ_GROUP_ID");
068
069 public static final SimpleString HDR_LARGE_COMPRESSED = new SimpleString("_HQ_LARGE_COMPRESSED");
070
071 public static final SimpleString HDR_LARGE_BODY_SIZE = new SimpleString("_HQ_LARGE_SIZE");
072
073 public static final SimpleString HDR_SCHEDULED_DELIVERY_TIME = new SimpleString("_HQ_SCHED_DELIVERY");
074
075 public static final SimpleString HDR_DUPLICATE_DETECTION_ID = new SimpleString("_HQ_DUPL_ID");
076
077 public static final SimpleString HDR_LAST_VALUE_NAME = new SimpleString("_HQ_LVQ_NAME");
078
079 public static final byte DEFAULT_TYPE = 0;
080
081 public static final byte OBJECT_TYPE = 2;
082
083 public static final byte TEXT_TYPE = 3;
084
085 public static final byte BYTES_TYPE = 4;
086
087 public static final byte MAP_TYPE = 5;
088
089 public static final byte STREAM_TYPE = 6;
090
091 /**
092 * Returns the messageID.
093 * <br>
094 * The messageID is set when the message is handled by the server.
095 */
096 long getMessageID();
097
098 /**
099 * Returns the userID - this is an optional user specified UUID that can be set to identify the message
100 * and will be passed around with the message
101 * @return the user id
102 */
103 UUID getUserID();
104
105 /**
106 * Sets the user ID
107 * @param userID
108 */
109 void setUserID(UUID userID);
110
111 /**
112 * Returns the address this message is sent to.
113 */
114 SimpleString getAddress();
115
116 /**
117 * Sets the address to send this message to.
118 *
119 * @param address address to send the message to
120 */
121 void setAddress(SimpleString address);
122
123 /**
124 * Returns this message type.
125 */
126 byte getType();
127
128 /**
129 * Returns whether this message is durable or not.
130 */
131 boolean isDurable();
132
133 /**
134 * Sets whether this message is durable or not.
135 *
136 * @param durable {@code true} to flag this message as durable, {@code false} else
137 */
138 void setDurable(boolean durable);
139
140 /**
141 * Returns the expiration time of this message.
142 */
143 long getExpiration();
144
145 /**
146 * Returns whether this message is expired or not.
147 */
148 boolean isExpired();
149
150 /**
151 * Sets the expiration of this message.
152 *
153 * @param expiration expiration time
154 */
155 void setExpiration(long expiration);
156
157 /**
158 * Returns the message timestamp.
159 * <br>
160 * The timestamp corresponds to the time this message
161 * was handled by a HornetQ server.
162 */
163 long getTimestamp();
164
165 /**
166 * Sets the message timestamp.
167 *
168 * @param timestamp timestamp
169 */
170 void setTimestamp(long timestamp);
171
172 /**
173 * Returns the message priority.
174 *
175 * Values range from 0 (less priority) to 9 (more priority) inclusive.
176 */
177 byte getPriority();
178
179 /**
180 * Sets the message priority.
181 *
182 * Value must be between 0 and 9 inclusive.
183 *
184 * @param priority the new message priority
185 */
186 void setPriority(byte priority);
187
188 /**
189 * Returns the size of the <em>encoded</em> message.
190 */
191 int getEncodeSize();
192
193 /**
194 * Returns whether this message is a <em>large message</em> or a regular message.
195 */
196 boolean isLargeMessage();
197
198 /**
199 * Returns the message body as a HornetQBuffer
200 */
201 HornetQBuffer getBodyBuffer();
202
203 // Properties
204 // -----------------------------------------------------------------
205
206 /**
207 * Puts a boolean property in this message.
208 *
209 * @param key property name
210 * @param value property value
211 */
212 void putBooleanProperty(SimpleString key, boolean value);
213
214 /**
215 * @see #putBooleanProperty(SimpleString, boolean)
216 */
217 void putBooleanProperty(String key, boolean value);
218
219 /**
220 * Puts a byte property in this message.
221 *
222 * @param key property name
223 * @param value property value
224 */
225 void putByteProperty(SimpleString key, byte value);
226
227 /**
228 * @see #putByteProperty(SimpleString, byte)
229 */
230 void putByteProperty(String key, byte value);
231
232 /**
233 * Puts a byte[] property in this message.
234 *
235 * @param key property name
236 * @param value property value
237 */
238 void putBytesProperty(SimpleString key, byte[] value);
239
240 /**
241 * @see #putBytesProperty(SimpleString, byte[])
242 */
243 void putBytesProperty(String key, byte[] value);
244
245 /**
246 * Puts a short property in this message.
247 *
248 * @param key property name
249 * @param value property value
250 */
251 void putShortProperty(SimpleString key, short value);
252
253 /**
254 * @see #putShortProperty(SimpleString, short)
255 */
256 void putShortProperty(String key, short value);
257
258 /**
259 * Puts a int property in this message.
260 *
261 * @param key property name
262 * @param value property value
263 */
264 void putIntProperty(SimpleString key, int value);
265
266 /**
267 * @see #putIntProperty(SimpleString, int)
268 */
269 void putIntProperty(String key, int value);
270
271 /**
272 * Puts a long property in this message.
273 *
274 * @param key property name
275 * @param value property value
276 */
277 void putLongProperty(SimpleString key, long value);
278
279 /**
280 * @see #putLongProperty(SimpleString, long)
281 */
282 void putLongProperty(String key, long value);
283
284 /**
285 * Puts a float property in this message.
286 *
287 * @param key property name
288 * @param value property value
289 */
290 void putFloatProperty(SimpleString key, float value);
291
292 /**
293 * @see #putFloatProperty(SimpleString, float)
294 */
295 void putFloatProperty(String key, float value);
296
297 /**
298 * Puts a double property in this message.
299 *
300 * @param key property name
301 * @param value property value
302 */
303 void putDoubleProperty(SimpleString key, double value);
304
305 /**
306 * @see #putDoubleProperty(SimpleString, double)
307 */
308 void putDoubleProperty(String key, double value);
309
310 /**
311 * Puts a SimpleString property in this message.
312 *
313 * @param key property name
314 * @param value property value
315 */
316 void putStringProperty(SimpleString key, SimpleString value);
317
318 /**
319 * Puts a String property in this message.
320 *
321 * @param key property name
322 * @param value property value
323 */
324 void putStringProperty(String key, String value);
325
326 /**
327 * Puts an Object property in this message.
328 * <br>
329 * Accepted types are:
330 * <ul>
331 * <li>Boolean</li>
332 * <li>Byte</li>
333 * <li>Short</li>
334 * <li>Integer</li>
335 * <li>Long</li>
336 * <li>Float</li>
337 * <li>Double</li>
338 * <li>String</li>
339 * <li>SimpleString</li>
340 * </ul>
341 *
342 * Using any other type will throw a PropertyConversionException.
343 *
344 * @param key property name
345 * @param value property value
346 *
347 * @throws PropertyConversionException if the value is not one of the accepted property types.
348 */
349 void putObjectProperty(SimpleString key, Object value) throws PropertyConversionException;
350
351 /**
352 * @see #putObjectProperty(SimpleString, Object)
353 */
354 void putObjectProperty(String key, Object value) throws PropertyConversionException;
355
356 /**
357 * Removes the property corresponding to the specified key.
358 * @param key property name
359 * @return the value corresponding to the specified key or @{code null}
360 */
361 Object removeProperty(SimpleString key);
362
363
364 /**
365 * @see #removeProperty(SimpleString)
366 */
367 Object removeProperty(String key);
368
369 /**
370 * Returns {@code true} if this message contains a property with the given key, {@code false} else.
371 *
372 * @param key property name
373 */
374 boolean containsProperty(SimpleString key);
375
376 /**
377 * @see #containsProperty(SimpleString)
378 */
379 boolean containsProperty(String key);
380
381 /**
382 * Returns the property corresponding to the specified key as a Boolean.
383 *
384 * @throws PropertyConversionException if the value can not be converted to a Boolean
385 */
386 Boolean getBooleanProperty(SimpleString key) throws PropertyConversionException;
387
388 /**
389 * @see #getBooleanProperty(SimpleString)
390 */
391 Boolean getBooleanProperty(String key) throws PropertyConversionException;
392
393 /**
394 * Returns the property corresponding to the specified key as a Byte.
395 *
396 * @throws PropertyConversionException if the value can not be converted to a Byte
397 */
398 Byte getByteProperty(SimpleString key) throws PropertyConversionException;
399
400 /**
401 * @see #getByteProperty(SimpleString)
402 */
403 Byte getByteProperty(String key) throws PropertyConversionException;
404
405 /**
406 * Returns the property corresponding to the specified key as a Double.
407 *
408 * @throws PropertyConversionException if the value can not be converted to a Double
409 */
410 Double getDoubleProperty(SimpleString key) throws PropertyConversionException;
411
412 /**
413 * @see #getDoubleProperty(SimpleString)
414 */
415 Double getDoubleProperty(String key) throws PropertyConversionException;
416
417 /**
418 * Returns the property corresponding to the specified key as an Integer.
419 *
420 * @throws PropertyConversionException if the value can not be converted to an Integer
421 */
422 Integer getIntProperty(SimpleString key) throws PropertyConversionException;
423
424 /**
425 * @see #getIntProperty(SimpleString)
426 */
427 Integer getIntProperty(String key) throws PropertyConversionException;
428
429 /**
430 * Returns the property corresponding to the specified key as a Long.
431 *
432 * @throws PropertyConversionException if the value can not be converted to a Long
433 */
434 Long getLongProperty(SimpleString key) throws PropertyConversionException;
435
436 /**
437 * @see #getLongProperty(SimpleString)
438 */
439 Long getLongProperty(String key) throws PropertyConversionException;
440
441 /**
442 * Returns the property corresponding to the specified key
443 */
444 Object getObjectProperty(SimpleString key);
445
446 /**
447 * @see #getBooleanProperty(SimpleString)
448 */
449 Object getObjectProperty(String key);
450
451 /**
452 * Returns the property corresponding to the specified key as a Short.
453 *
454 * @throws PropertyConversionException if the value can not be converted to a Short
455 */
456 Short getShortProperty(SimpleString key) throws PropertyConversionException;
457
458 /**
459 * @see #getShortProperty(SimpleString)
460 */
461 Short getShortProperty(String key) throws PropertyConversionException;
462
463 /**
464 * Returns the property corresponding to the specified key as a Float.
465 *
466 * @throws PropertyConversionException if the value can not be converted to a Float
467 */
468 Float getFloatProperty(SimpleString key) throws PropertyConversionException;
469
470 /**
471 * @see #getFloatProperty(SimpleString)
472 */
473 Float getFloatProperty(String key) throws PropertyConversionException;
474
475 /**
476 * Returns the property corresponding to the specified key as a String.
477 *
478 * @throws PropertyConversionException if the value can not be converted to a String
479 */
480 String getStringProperty(SimpleString key) throws PropertyConversionException;
481
482 /**
483 * @see #getStringProperty(SimpleString)
484 */
485 String getStringProperty(String key) throws PropertyConversionException;
486
487 /**
488 * Returns the property corresponding to the specified key as a SimpleString.
489 *
490 * @throws PropertyConversionException if the value can not be converted to a SimpleString
491 */
492 SimpleString getSimpleStringProperty(SimpleString key) throws PropertyConversionException;
493
494 /**
495 * @see #getSimpleStringProperty(SimpleString)
496 */
497 SimpleString getSimpleStringProperty(String key) throws PropertyConversionException;
498
499 /**
500 * Returns the property corresponding to the specified key as a byte[].
501 *
502 * @throws PropertyConversionException if the value can not be converted to a byte[]
503 */
504 byte[] getBytesProperty(SimpleString key) throws PropertyConversionException;
505
506 /**
507 * @see #getBytesProperty(SimpleString)
508 */
509 byte[] getBytesProperty(String key) throws PropertyConversionException;
510
511 /**
512 * Returns all the names of the properties for this message.
513 */
514 Set<SimpleString> getPropertyNames();
515
516 /**
517 * @return Returns the message in Map form, useful when encoding to JSON
518 */
519 Map<String, Object> toMap();
520 }