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       /**
204        * Returns a <em>copy</em> of the message body as a HornetQBuffer. Any modification
205        * of this buffer should not impact the underlying buffer.
206        */
207       HornetQBuffer getBodyBufferCopy();
208    
209       // Properties
210       // -----------------------------------------------------------------
211    
212       /**
213        * Puts a boolean property in this message.
214        *
215        * @param key property name
216        * @param value property value
217        */
218       void putBooleanProperty(SimpleString key, boolean value);
219    
220       /**
221        * @see #putBooleanProperty(SimpleString, boolean)
222        */
223       void putBooleanProperty(String key, boolean value);
224    
225       /**
226        * Puts a byte property in this message.
227        *
228        * @param key property name
229        * @param value property value
230        */
231       void putByteProperty(SimpleString key, byte value);
232    
233       /**
234        * @see #putByteProperty(SimpleString, byte)
235        */
236       void putByteProperty(String key, byte value);
237    
238       /**
239        * Puts a byte[] property in this message.
240        *
241        * @param key property name
242        * @param value property value
243        */
244       void putBytesProperty(SimpleString key, byte[] value);
245    
246       /**
247        * @see #putBytesProperty(SimpleString, byte[])
248        */
249       void putBytesProperty(String key, byte[] value);
250    
251       /**
252        * Puts a short property in this message.
253        *
254        * @param key property name
255        * @param value property value
256        */
257       void putShortProperty(SimpleString key, short value);
258    
259       /**
260        * @see #putShortProperty(SimpleString, short)
261        */
262       void putShortProperty(String key, short value);
263    
264       /**
265        * Puts a int property in this message.
266        *
267        * @param key property name
268        * @param value property value
269        */
270       void putIntProperty(SimpleString key, int value);
271    
272       /**
273        * @see #putIntProperty(SimpleString, int)
274        */
275       void putIntProperty(String key, int value);
276    
277       /**
278        * Puts a long property in this message.
279        *
280        * @param key property name
281        * @param value property value
282        */
283       void putLongProperty(SimpleString key, long value);
284    
285       /**
286        * @see #putLongProperty(SimpleString, long)
287        */
288       void putLongProperty(String key, long value);
289    
290       /**
291        * Puts a float property in this message.
292        *
293        * @param key property name
294        * @param value property value
295        */
296       void putFloatProperty(SimpleString key, float value);
297    
298       /**
299        * @see #putFloatProperty(SimpleString, float)
300        */
301       void putFloatProperty(String key, float value);
302    
303       /**
304        * Puts a double property in this message.
305        *
306        * @param key property name
307        * @param value property value
308        */
309       void putDoubleProperty(SimpleString key, double value);
310    
311       /**
312        * @see #putDoubleProperty(SimpleString, double)
313        */
314       void putDoubleProperty(String key, double value);
315    
316       /**
317        * Puts a SimpleString property in this message.
318        *
319        * @param key property name
320        * @param value property value
321        */
322       void putStringProperty(SimpleString key, SimpleString value);
323    
324       /**
325        * Puts a String property in this message.
326        *
327        * @param key property name
328        * @param value property value
329        */
330       void putStringProperty(String key, String value);
331    
332       /**
333        * Puts an Object property in this message.
334        * <br>
335        * Accepted types are:
336        * <ul>
337        *   <li>Boolean</li>
338        *   <li>Byte</li>
339        *   <li>Short</li>
340        *   <li>Integer</li>
341        *   <li>Long</li>
342        *   <li>Float</li>
343        *   <li>Double</li>
344        *   <li>String</li>
345        *   <li>SimpleString</li>
346        * </ul>
347        *
348        * Using any other type will throw a PropertyConversionException.
349        *
350        * @param key property name
351        * @param value property value
352        *
353        * @throws PropertyConversionException if the value is not one of the accepted property types.
354        */
355       void putObjectProperty(SimpleString key, Object value) throws PropertyConversionException;
356    
357       /**
358        * @see #putObjectProperty(SimpleString, Object)
359        */
360       void putObjectProperty(String key, Object value) throws PropertyConversionException;
361    
362       /**
363        * Removes the property corresponding to the specified key.
364        * @param key property name
365        * @return the value corresponding to the specified key or @{code null}
366        */
367       Object removeProperty(SimpleString key);
368    
369    
370       /**
371        * @see #removeProperty(SimpleString)
372        */
373       Object removeProperty(String key);
374    
375       /**
376        * Returns {@code true} if this message contains a property with the given key, {@code false} else.
377        *
378        * @param key property name
379        */
380       boolean containsProperty(SimpleString key);
381    
382       /**
383        * @see #containsProperty(SimpleString)
384        */
385       boolean containsProperty(String key);
386    
387       /**
388        * Returns the property corresponding to the specified key as a Boolean.
389        *
390        * @throws PropertyConversionException if the value can not be converted to a Boolean
391        */
392       Boolean getBooleanProperty(SimpleString key) throws PropertyConversionException;
393    
394       /**
395        * @see #getBooleanProperty(SimpleString)
396        */
397       Boolean getBooleanProperty(String key) throws PropertyConversionException;
398    
399       /**
400        * Returns the property corresponding to the specified key as a Byte.
401        *
402        * @throws PropertyConversionException if the value can not be converted to a Byte
403        */
404       Byte getByteProperty(SimpleString key) throws PropertyConversionException;
405    
406       /**
407        * @see #getByteProperty(SimpleString)
408        */
409       Byte getByteProperty(String key) throws PropertyConversionException;
410    
411       /**
412        * Returns the property corresponding to the specified key as a Double.
413        *
414        * @throws PropertyConversionException if the value can not be converted to a Double
415        */
416       Double getDoubleProperty(SimpleString key) throws PropertyConversionException;
417    
418       /**
419        * @see #getDoubleProperty(SimpleString)
420        */
421       Double getDoubleProperty(String key) throws PropertyConversionException;
422    
423       /**
424        * Returns the property corresponding to the specified key as an Integer.
425        *
426        * @throws PropertyConversionException if the value can not be converted to an Integer
427        */
428       Integer getIntProperty(SimpleString key) throws PropertyConversionException;
429    
430       /**
431        * @see #getIntProperty(SimpleString)
432        */
433       Integer getIntProperty(String key) throws PropertyConversionException;
434    
435       /**
436        * Returns the property corresponding to the specified key as a Long.
437        *
438        * @throws PropertyConversionException if the value can not be converted to a Long
439        */
440       Long getLongProperty(SimpleString key) throws PropertyConversionException;
441    
442       /**
443        * @see #getLongProperty(SimpleString)
444        */
445       Long getLongProperty(String key) throws PropertyConversionException;
446    
447       /**
448        * Returns the property corresponding to the specified key
449        */
450       Object getObjectProperty(SimpleString key);
451    
452       /**
453        * @see #getBooleanProperty(SimpleString)
454        */
455       Object getObjectProperty(String key);
456    
457       /**
458        * Returns the property corresponding to the specified key as a Short.
459        *
460        * @throws PropertyConversionException if the value can not be converted to a Short
461        */
462       Short getShortProperty(SimpleString key) throws PropertyConversionException;
463    
464       /**
465        * @see #getShortProperty(SimpleString)
466        */
467       Short getShortProperty(String key) throws PropertyConversionException;
468    
469       /**
470        * Returns the property corresponding to the specified key as a Float.
471        *
472        * @throws PropertyConversionException if the value can not be converted to a Float
473        */
474       Float getFloatProperty(SimpleString key) throws PropertyConversionException;
475    
476       /**
477        * @see #getFloatProperty(SimpleString)
478        */
479       Float getFloatProperty(String key) throws PropertyConversionException;
480    
481       /**
482        * Returns the property corresponding to the specified key as a String.
483        *
484        * @throws PropertyConversionException if the value can not be converted to a String
485        */
486       String getStringProperty(SimpleString key) throws PropertyConversionException;
487    
488       /**
489        * @see #getStringProperty(SimpleString)
490        */
491       String getStringProperty(String key) throws PropertyConversionException;
492    
493       /**
494        * Returns the property corresponding to the specified key as a SimpleString.
495        *
496        * @throws PropertyConversionException if the value can not be converted to a SimpleString
497        */
498       SimpleString getSimpleStringProperty(SimpleString key) throws PropertyConversionException;
499    
500       /**
501        * @see #getSimpleStringProperty(SimpleString)
502        */
503       SimpleString getSimpleStringProperty(String key) throws PropertyConversionException;
504    
505       /**
506        * Returns the property corresponding to the specified key as a byte[].
507        *
508        * @throws PropertyConversionException if the value can not be converted to a byte[]
509        */
510       byte[] getBytesProperty(SimpleString key) throws PropertyConversionException;
511    
512       /**
513        * @see #getBytesProperty(SimpleString)
514        */
515       byte[] getBytesProperty(String key) throws PropertyConversionException;
516    
517       /**
518        * Returns all the names of the properties for this message.
519        */
520       Set<SimpleString> getPropertyNames();
521    
522       /**
523        * @return Returns the message in Map form, useful when encoding to JSON
524        */
525       Map<String, Object> toMap();
526    }