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 }