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
014package org.hornetq.api.core;
015
016import java.util.Map;
017import java.util.Set;
018
019import 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 */
059public 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}