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    }