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_SCHEDULED_DELIVERY_TIME = new SimpleString("_HQ_SCHED_DELIVERY"); 070 071 public static final SimpleString HDR_DUPLICATE_DETECTION_ID = new SimpleString("_HQ_DUPL_ID"); 072 073 public static final SimpleString HDR_LAST_VALUE_NAME = new SimpleString("_HQ_LVQ_NAME"); 074 075 public static final byte DEFAULT_TYPE = 0; 076 077 public static final byte OBJECT_TYPE = 2; 078 079 public static final byte TEXT_TYPE = 3; 080 081 public static final byte BYTES_TYPE = 4; 082 083 public static final byte MAP_TYPE = 5; 084 085 public static final byte STREAM_TYPE = 6; 086 087 /** 088 * Returns the messageID. 089 * <br> 090 * The messageID is set when the message is handled by the server. 091 */ 092 long getMessageID(); 093 094 /** 095 * Returns the userID - this is an optional user specified UUID that can be set to identify the message 096 * and will be passed around with the message 097 * @return the user id 098 */ 099 UUID getUserID(); 100 101 /** 102 * Sets the user ID 103 * @param userID 104 */ 105 void setUserID(UUID userID); 106 107 /** 108 * Returns the address this message is sent to. 109 */ 110 SimpleString getAddress(); 111 112 /** 113 * Sets the address to send this message to. 114 * 115 * @param address address to send the message to 116 */ 117 void setAddress(SimpleString address); 118 119 /** 120 * Returns this message type. 121 */ 122 byte getType(); 123 124 /** 125 * Returns whether this message is durable or not. 126 */ 127 boolean isDurable(); 128 129 /** 130 * Sets whether this message is durable or not. 131 * 132 * @param durable {@code true} to flag this message as durable, {@code false} else 133 */ 134 void setDurable(boolean durable); 135 136 /** 137 * Returns the expiration time of this message. 138 */ 139 long getExpiration(); 140 141 /** 142 * Returns whether this message is expired or not. 143 */ 144 boolean isExpired(); 145 146 /** 147 * Sets the expiration of this message. 148 * 149 * @param expiration expiration time 150 */ 151 void setExpiration(long expiration); 152 153 /** 154 * Returns the message timestamp. 155 * <br> 156 * The timestamp corresponds to the time this message 157 * was handled by a HornetQ server. 158 */ 159 long getTimestamp(); 160 161 /** 162 * Sets the message timestamp. 163 * 164 * @param timestamp timestamp 165 */ 166 void setTimestamp(long timestamp); 167 168 /** 169 * Returns the message priority. 170 * 171 * Values range from 0 (less priority) to 9 (more priority) inclusive. 172 */ 173 byte getPriority(); 174 175 /** 176 * Sets the message priority. 177 * 178 * Value must be between 0 and 9 inclusive. 179 * 180 * @param priority the new message priority 181 */ 182 void setPriority(byte priority); 183 184 /** 185 * Returns the size of the <em>encoded</em> message. 186 */ 187 int getEncodeSize(); 188 189 /** 190 * Returns whether this message is a <em>large message</em> or a regular message. 191 */ 192 boolean isLargeMessage(); 193 194 /** 195 * Returns the message body as a HornetQBuffer 196 */ 197 HornetQBuffer getBodyBuffer(); 198 199 // Properties 200 // ----------------------------------------------------------------- 201 202 /** 203 * Puts a boolean property in this message. 204 * 205 * @param key property name 206 * @param value property value 207 */ 208 void putBooleanProperty(SimpleString key, boolean value); 209 210 /** 211 * @see #putBooleanProperty(SimpleString, boolean) 212 */ 213 void putBooleanProperty(String key, boolean value); 214 215 /** 216 * Puts a byte property in this message. 217 * 218 * @param key property name 219 * @param value property value 220 */ 221 void putByteProperty(SimpleString key, byte value); 222 223 /** 224 * @see #putByteProperty(SimpleString, byte) 225 */ 226 void putByteProperty(String key, byte value); 227 228 /** 229 * Puts a byte[] property in this message. 230 * 231 * @param key property name 232 * @param value property value 233 */ 234 void putBytesProperty(SimpleString key, byte[] value); 235 236 /** 237 * @see #putBytesProperty(SimpleString, byte[]) 238 */ 239 void putBytesProperty(String key, byte[] value); 240 241 /** 242 * Puts a short property in this message. 243 * 244 * @param key property name 245 * @param value property value 246 */ 247 void putShortProperty(SimpleString key, short value); 248 249 /** 250 * @see #putShortProperty(SimpleString, short) 251 */ 252 void putShortProperty(String key, short value); 253 254 /** 255 * Puts a int property in this message. 256 * 257 * @param key property name 258 * @param value property value 259 */ 260 void putIntProperty(SimpleString key, int value); 261 262 /** 263 * @see #putIntProperty(SimpleString, int) 264 */ 265 void putIntProperty(String key, int value); 266 267 /** 268 * Puts a long property in this message. 269 * 270 * @param key property name 271 * @param value property value 272 */ 273 void putLongProperty(SimpleString key, long value); 274 275 /** 276 * @see #putLongProperty(SimpleString, long) 277 */ 278 void putLongProperty(String key, long value); 279 280 /** 281 * Puts a float property in this message. 282 * 283 * @param key property name 284 * @param value property value 285 */ 286 void putFloatProperty(SimpleString key, float value); 287 288 /** 289 * @see #putFloatProperty(SimpleString, float) 290 */ 291 void putFloatProperty(String key, float value); 292 293 /** 294 * Puts a double property in this message. 295 * 296 * @param key property name 297 * @param value property value 298 */ 299 void putDoubleProperty(SimpleString key, double value); 300 301 /** 302 * @see #putDoubleProperty(SimpleString, double) 303 */ 304 void putDoubleProperty(String key, double value); 305 306 /** 307 * Puts a SimpleString property in this message. 308 * 309 * @param key property name 310 * @param value property value 311 */ 312 void putStringProperty(SimpleString key, SimpleString value); 313 314 /** 315 * Puts a String property in this message. 316 * 317 * @param key property name 318 * @param value property value 319 */ 320 void putStringProperty(String key, String value); 321 322 /** 323 * Puts an Object property in this message. 324 * <br> 325 * Accepted types are: 326 * <ul> 327 * <li>Boolean</li> 328 * <li>Byte</li> 329 * <li>Short</li> 330 * <li>Integer</li> 331 * <li>Long</li> 332 * <li>Float</li> 333 * <li>Double</li> 334 * <li>String</li> 335 * <li>SimpleString</li> 336 * </ul> 337 * 338 * Using any other type will throw a PropertyConversionException. 339 * 340 * @param key property name 341 * @param value property value 342 * 343 * @throws PropertyConversionException if the value is not one of the accepted property types. 344 */ 345 void putObjectProperty(SimpleString key, Object value) throws PropertyConversionException; 346 347 /** 348 * @see #putObjectProperty(SimpleString, Object) 349 */ 350 void putObjectProperty(String key, Object value) throws PropertyConversionException; 351 352 /** 353 * Removes the property corresponding to the specified key. 354 * @param key property name 355 * @return the value corresponding to the specified key or @{code null} 356 */ 357 Object removeProperty(SimpleString key); 358 359 360 /** 361 * @see #removeProperty(SimpleString) 362 */ 363 Object removeProperty(String key); 364 365 /** 366 * Returns {@code true} if this message contains a property with the given key, {@code false} else. 367 * 368 * @param key property name 369 */ 370 boolean containsProperty(SimpleString key); 371 372 /** 373 * @see #containsProperty(SimpleString) 374 */ 375 boolean containsProperty(String key); 376 377 /** 378 * Returns the property corresponding to the specified key as a Boolean. 379 * 380 * @throws PropertyConversionException if the value can not be converted to a Boolean 381 */ 382 Boolean getBooleanProperty(SimpleString key) throws PropertyConversionException; 383 384 /** 385 * @see #getBooleanProperty(SimpleString) 386 */ 387 Boolean getBooleanProperty(String key) throws PropertyConversionException; 388 389 /** 390 * Returns the property corresponding to the specified key as a Byte. 391 * 392 * @throws PropertyConversionException if the value can not be converted to a Byte 393 */ 394 Byte getByteProperty(SimpleString key) throws PropertyConversionException; 395 396 /** 397 * @see #getByteProperty(SimpleString) 398 */ 399 Byte getByteProperty(String key) throws PropertyConversionException; 400 401 /** 402 * Returns the property corresponding to the specified key as a Double. 403 * 404 * @throws PropertyConversionException if the value can not be converted to a Double 405 */ 406 Double getDoubleProperty(SimpleString key) throws PropertyConversionException; 407 408 /** 409 * @see #getDoubleProperty(SimpleString) 410 */ 411 Double getDoubleProperty(String key) throws PropertyConversionException; 412 413 /** 414 * Returns the property corresponding to the specified key as an Integer. 415 * 416 * @throws PropertyConversionException if the value can not be converted to an Integer 417 */ 418 Integer getIntProperty(SimpleString key) throws PropertyConversionException; 419 420 /** 421 * @see #getIntProperty(SimpleString) 422 */ 423 Integer getIntProperty(String key) throws PropertyConversionException; 424 425 /** 426 * Returns the property corresponding to the specified key as a Long. 427 * 428 * @throws PropertyConversionException if the value can not be converted to a Long 429 */ 430 Long getLongProperty(SimpleString key) throws PropertyConversionException; 431 432 /** 433 * @see #getLongProperty(SimpleString) 434 */ 435 Long getLongProperty(String key) throws PropertyConversionException; 436 437 /** 438 * Returns the property corresponding to the specified key 439 */ 440 Object getObjectProperty(SimpleString key); 441 442 /** 443 * @see #getBooleanProperty(SimpleString) 444 */ 445 Object getObjectProperty(String key); 446 447 /** 448 * Returns the property corresponding to the specified key as a Short. 449 * 450 * @throws PropertyConversionException if the value can not be converted to a Short 451 */ 452 Short getShortProperty(SimpleString key) throws PropertyConversionException; 453 454 /** 455 * @see #getShortProperty(SimpleString) 456 */ 457 Short getShortProperty(String key) throws PropertyConversionException; 458 459 /** 460 * Returns the property corresponding to the specified key as a Float. 461 * 462 * @throws PropertyConversionException if the value can not be converted to a Float 463 */ 464 Float getFloatProperty(SimpleString key) throws PropertyConversionException; 465 466 /** 467 * @see #getFloatProperty(SimpleString) 468 */ 469 Float getFloatProperty(String key) throws PropertyConversionException; 470 471 /** 472 * Returns the property corresponding to the specified key as a String. 473 * 474 * @throws PropertyConversionException if the value can not be converted to a String 475 */ 476 String getStringProperty(SimpleString key) throws PropertyConversionException; 477 478 /** 479 * @see #getStringProperty(SimpleString) 480 */ 481 String getStringProperty(String key) throws PropertyConversionException; 482 483 /** 484 * Returns the property corresponding to the specified key as a SimpleString. 485 * 486 * @throws PropertyConversionException if the value can not be converted to a SimpleString 487 */ 488 SimpleString getSimpleStringProperty(SimpleString key) throws PropertyConversionException; 489 490 /** 491 * @see #getSimpleStringProperty(SimpleString) 492 */ 493 SimpleString getSimpleStringProperty(String key) throws PropertyConversionException; 494 495 /** 496 * Returns the property corresponding to the specified key as a byte[]. 497 * 498 * @throws PropertyConversionException if the value can not be converted to a byte[] 499 */ 500 byte[] getBytesProperty(SimpleString key) throws PropertyConversionException; 501 502 /** 503 * @see #getBytesProperty(SimpleString) 504 */ 505 byte[] getBytesProperty(String key) throws PropertyConversionException; 506 507 /** 508 * Returns all the names of the properties for this message. 509 */ 510 Set<SimpleString> getPropertyNames(); 511 512 /** 513 * @return Returns the message in Map form, useful when encoding to JSON 514 */ 515 Map<String, Object> toMap(); 516 }