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_SCHEDULED_DELIVERY_TIME = new SimpleString("_HQ_SCHED_DELIVERY");
070    
071       public static final SimpleString HDR_DUPLICATE_DETECTION_ID = new SimpleString("_HQ_DUPL_ID");
072    
073       public static final SimpleString HDR_LAST_VALUE_NAME = new SimpleString("_HQ_LVQ_NAME");
074    
075       public static final byte DEFAULT_TYPE = 0;
076    
077       public static final byte OBJECT_TYPE = 2;
078    
079       public static final byte TEXT_TYPE = 3;
080    
081       public static final byte BYTES_TYPE = 4;
082    
083       public static final byte MAP_TYPE = 5;
084    
085       public static final byte STREAM_TYPE = 6;
086       
087       /**
088        * Returns the messageID.
089        * <br>
090        * The messageID is set when the message is handled by the server.
091        */
092       long getMessageID();
093       
094       /**
095        * Returns the userID - this is an optional user specified UUID that can be set to identify the message
096        * and will be passed around with the message
097        * @return the user id
098        */
099       UUID getUserID();
100       
101       /**
102        * Sets the user ID
103        * @param userID
104        */
105       void setUserID(UUID userID);
106    
107       /**
108        * Returns the address this message is sent to.
109        */
110       SimpleString getAddress();
111    
112       /**
113        * Sets the address to send this message to.
114        * 
115        * @param address address to send the message to
116        */
117       void setAddress(SimpleString address);
118    
119       /**
120        * Returns this message type.
121        */
122       byte getType();
123    
124       /**
125        * Returns whether this message is durable or not.
126        */
127       boolean isDurable();
128    
129       /**
130        * Sets whether this message is durable or not.
131        * 
132        * @param durable {@code true} to flag this message as durable, {@code false} else
133        */
134       void setDurable(boolean durable);
135    
136       /**
137        * Returns the expiration time of this message.
138        */
139       long getExpiration();
140    
141       /**
142        * Returns whether this message is expired or not.
143        */
144       boolean isExpired();
145    
146       /**
147        * Sets the expiration of this message.
148        * 
149        * @param expiration expiration time
150        */
151       void setExpiration(long expiration);
152    
153       /**
154        * Returns the message timestamp.
155        * <br>
156        * The timestamp corresponds to the time this message
157        * was handled by a HornetQ server.
158        */
159       long getTimestamp();
160    
161       /**
162        * Sets the message timestamp.
163        * 
164        * @param timestamp timestamp
165        */
166       void setTimestamp(long timestamp);
167    
168       /**
169        * Returns the message priority.
170        * 
171        * Values range from 0 (less priority) to 9 (more priority) inclusive.
172        */
173       byte getPriority();
174    
175       /**
176        * Sets the message priority.
177        * 
178        * Value must be between 0 and 9 inclusive.
179        * 
180        * @param priority the new message priority
181        */
182       void setPriority(byte priority);
183    
184       /**
185        * Returns the size of the <em>encoded</em> message.
186        */
187       int getEncodeSize();
188    
189       /**
190        * Returns whether this message is a <em>large message</em> or a regular message.
191        */
192       boolean isLargeMessage();
193    
194       /**
195        * Returns the message body as a HornetQBuffer
196        */
197       HornetQBuffer getBodyBuffer();
198    
199       // Properties
200       // -----------------------------------------------------------------
201    
202       /**
203        * Puts a boolean property in this message.
204        * 
205        * @param key property name
206        * @param value property value
207        */
208       void putBooleanProperty(SimpleString key, boolean value);
209    
210       /**
211        * @see #putBooleanProperty(SimpleString, boolean)
212        */
213       void putBooleanProperty(String key, boolean value);
214    
215       /**
216        * Puts a byte property in this message.
217        * 
218        * @param key property name
219        * @param value property value
220        */
221       void putByteProperty(SimpleString key, byte value);
222    
223       /**
224        * @see #putByteProperty(SimpleString, byte)
225        */
226       void putByteProperty(String key, byte value);
227    
228       /**
229        * Puts a byte[] property in this message.
230        * 
231        * @param key property name
232        * @param value property value
233        */
234       void putBytesProperty(SimpleString key, byte[] value);
235    
236       /**
237        * @see #putBytesProperty(SimpleString, byte[])
238        */
239       void putBytesProperty(String key, byte[] value);
240    
241       /**
242        * Puts a short property in this message.
243        * 
244        * @param key property name
245        * @param value property value
246        */
247       void putShortProperty(SimpleString key, short value);
248    
249       /**
250        * @see #putShortProperty(SimpleString, short)
251        */
252       void putShortProperty(String key, short value);
253    
254       /**
255        * Puts a int property in this message.
256        * 
257        * @param key property name
258        * @param value property value
259        */
260       void putIntProperty(SimpleString key, int value);
261    
262       /**
263        * @see #putIntProperty(SimpleString, int)
264        */
265       void putIntProperty(String key, int value);
266    
267       /**
268        * Puts a long property in this message.
269        * 
270        * @param key property name
271        * @param value property value
272        */
273       void putLongProperty(SimpleString key, long value);
274    
275       /**
276        * @see #putLongProperty(SimpleString, long)
277        */
278       void putLongProperty(String key, long value);
279    
280       /**
281        * Puts a float property in this message.
282        * 
283        * @param key property name
284        * @param value property value
285        */
286       void putFloatProperty(SimpleString key, float value);
287    
288       /**
289        * @see #putFloatProperty(SimpleString, float)
290        */
291       void putFloatProperty(String key, float value);
292    
293       /**
294        * Puts a double property in this message.
295        * 
296        * @param key property name
297        * @param value property value
298        */
299       void putDoubleProperty(SimpleString key, double value);
300    
301       /**
302        * @see #putDoubleProperty(SimpleString, double)
303        */
304       void putDoubleProperty(String key, double value);
305    
306       /**
307        * Puts a SimpleString property in this message.
308        * 
309        * @param key property name
310        * @param value property value
311        */
312       void putStringProperty(SimpleString key, SimpleString value);
313    
314       /**
315        * Puts a String property in this message.
316        * 
317        * @param key property name
318        * @param value property value
319        */
320       void putStringProperty(String key, String value);
321       
322       /**
323        * Puts an Object property in this message.
324        * <br>
325        * Accepted types are:
326        * <ul>
327        *   <li>Boolean</li>
328        *   <li>Byte</li>
329        *   <li>Short</li>
330        *   <li>Integer</li>
331        *   <li>Long</li>
332        *   <li>Float</li>
333        *   <li>Double</li>
334        *   <li>String</li>
335        *   <li>SimpleString</li>
336        * </ul>
337        * 
338        * Using any other type will throw a PropertyConversionException.
339        * 
340        * @param key property name
341        * @param value property value
342        * 
343        * @throws PropertyConversionException if the value is not one of the accepted property types.
344        */
345       void putObjectProperty(SimpleString key, Object value) throws PropertyConversionException;
346    
347       /**
348        * @see #putObjectProperty(SimpleString, Object)
349        */
350       void putObjectProperty(String key, Object value) throws PropertyConversionException;
351    
352       /**
353        * Removes the property corresponding to the specified key.
354        * @param key property name
355        * @return the value corresponding to the specified key or @{code null}
356        */
357       Object removeProperty(SimpleString key);
358    
359       
360       /**
361        * @see #removeProperty(SimpleString)
362        */
363       Object removeProperty(String key);
364    
365       /**
366        * Returns {@code true} if this message contains a property with the given key, {@code false} else.
367        * 
368        * @param key property name
369        */
370       boolean containsProperty(SimpleString key);
371       
372       /**
373        * @see #containsProperty(SimpleString)
374        */
375       boolean containsProperty(String key);
376    
377       /**
378        * Returns the property corresponding to the specified key as a Boolean.
379        * 
380        * @throws PropertyConversionException if the value can not be converted to a Boolean
381        */
382       Boolean getBooleanProperty(SimpleString key) throws PropertyConversionException;
383    
384       /**
385        * @see #getBooleanProperty(SimpleString)
386        */
387       Boolean getBooleanProperty(String key) throws PropertyConversionException;
388    
389       /**
390        * Returns the property corresponding to the specified key as a Byte.
391        * 
392        * @throws PropertyConversionException if the value can not be converted to a Byte
393        */
394       Byte getByteProperty(SimpleString key) throws PropertyConversionException;
395    
396       /**
397        * @see #getByteProperty(SimpleString)
398        */
399       Byte getByteProperty(String key) throws PropertyConversionException;
400    
401       /**
402        * Returns the property corresponding to the specified key as a Double.
403        * 
404        * @throws PropertyConversionException if the value can not be converted to a Double
405        */
406       Double getDoubleProperty(SimpleString key) throws PropertyConversionException;
407    
408       /**
409        * @see #getDoubleProperty(SimpleString)
410        */
411       Double getDoubleProperty(String key) throws PropertyConversionException;
412    
413       /**
414        * Returns the property corresponding to the specified key as an Integer.
415        * 
416        * @throws PropertyConversionException if the value can not be converted to an Integer
417        */
418       Integer getIntProperty(SimpleString key) throws PropertyConversionException;
419    
420       /**
421        * @see #getIntProperty(SimpleString)
422        */
423       Integer getIntProperty(String key) throws PropertyConversionException;
424    
425       /**
426        * Returns the property corresponding to the specified key as a Long.
427        * 
428        * @throws PropertyConversionException if the value can not be converted to a Long
429        */
430       Long getLongProperty(SimpleString key) throws PropertyConversionException;
431    
432       /**
433        * @see #getLongProperty(SimpleString)
434        */
435       Long getLongProperty(String key) throws PropertyConversionException;
436    
437       /**
438        * Returns the property corresponding to the specified key
439        */
440       Object getObjectProperty(SimpleString key);
441    
442       /**
443        * @see #getBooleanProperty(SimpleString)
444        */
445       Object getObjectProperty(String key);
446    
447       /**
448        * Returns the property corresponding to the specified key as a Short.
449        * 
450        * @throws PropertyConversionException if the value can not be converted to a Short
451        */
452       Short getShortProperty(SimpleString key) throws PropertyConversionException;
453    
454       /**
455        * @see #getShortProperty(SimpleString)
456        */
457       Short getShortProperty(String key) throws PropertyConversionException;
458    
459       /**
460        * Returns the property corresponding to the specified key as a Float.
461        * 
462        * @throws PropertyConversionException if the value can not be converted to a Float
463        */
464       Float getFloatProperty(SimpleString key) throws PropertyConversionException;
465    
466       /**
467        * @see #getFloatProperty(SimpleString)
468        */
469       Float getFloatProperty(String key) throws PropertyConversionException;
470    
471       /**
472        * Returns the property corresponding to the specified key as a String.
473        * 
474        * @throws PropertyConversionException if the value can not be converted to a String
475        */
476       String getStringProperty(SimpleString key) throws PropertyConversionException;
477    
478       /**
479        * @see #getStringProperty(SimpleString)
480        */
481       String getStringProperty(String key) throws PropertyConversionException;
482    
483       /**
484        * Returns the property corresponding to the specified key as a SimpleString.
485        * 
486        * @throws PropertyConversionException if the value can not be converted to a SimpleString
487        */
488       SimpleString getSimpleStringProperty(SimpleString key) throws PropertyConversionException;
489    
490       /**
491        * @see #getSimpleStringProperty(SimpleString)
492        */
493       SimpleString getSimpleStringProperty(String key) throws PropertyConversionException;
494    
495       /**
496        * Returns the property corresponding to the specified key as a byte[].
497        * 
498        * @throws PropertyConversionException if the value can not be converted to a byte[]
499        */
500       byte[] getBytesProperty(SimpleString key) throws PropertyConversionException;
501    
502       /**
503        * @see #getBytesProperty(SimpleString)
504        */
505       byte[] getBytesProperty(String key) throws PropertyConversionException;
506    
507       /**
508        * Returns all the names of the properties for this message.
509        */
510       Set<SimpleString> getPropertyNames();
511    
512       /**
513        * @return Returns the message in Map form, useful when encoding to JSON
514        */
515       Map<String, Object> toMap();  
516    }