    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    }