    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    }