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 014package org.hornetq.api.core; 015 016import java.util.Map; 017import java.util.Set; 018 019import 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 */ 059public 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}