MessageHeader


1   /* JFox, the OpenSource J2EE Application Server
2    *
3    * Distributable under GNU LGPL license by gun.org
4    * more details please visit http://www.huihoo.org/jfox
5    */
6   
7   package org.jfox.jms.message;
8   
9   import java.io.Serializable  ;
10  import javax.jms.DeliveryMode  ;
11  import javax.jms.Destination  ;
12  import javax.jms.JMSException  ;
13  
14  /**
15   * <p/>
16   * This class implements message header fields for messages.
17   * </p>
18   *
19   * @author <a HREF="mailto:founder_chen@yahoo.com.cn">Peter.Cheng</a>
20   * @version Revision: 1.1 Date: 2002-11-10 20:02:32
21   */
22  
23  public class MessageHeader implements Serializable   {
24  
25      private Destination   destination = null;
26      private int deliveryMode = DeliveryMode.NON_PERSISTENT;
27      private String   messageID = null;
28      private long timestamp = 0;
29      private String   correlationID = "";
30      private Destination   replyTo = null;
31      private boolean redelivered = false;
32      private String   messageType = "";
33      private long expiration = 0;
34      private int priority = 0;
35  
36      public final static String   MESSAGEID_PREFIX = "ID:";
37  
38      /**
39       * Default Constructor without param
40       */
41      MessageHeader() {
42      }
43  
44      /**
45       * Store the destination associated with this message.
46       *
47       * @param destination The destination value to store (null is not valid).
48       * @throws javax.jms.JMSException if an error occurs while storing the value.
49       * @see javax.jms.Message
50       */
51      public void setJMSDestination(Destination   destination)
52              throws JMSException   {
53          if (destination instanceof Destination  ) {
54              this.destination = (Destination  ) destination;
55          } else {
56              throw new JMSException  ("Message Destination unKnown.");
57          }
58      }
59  
60      /**
61       * The destination field contains the destination to which the message is
62       * being sent.
63       *
64       * @return The destination which the message is being delivered to (after a
65       *         send) or has been received from (after a receive).
66       * @throws javax.jms.JMSException an error occurred while retreiving the data.
67       */
68      public Destination   getJMSDestination() throws JMSException   {
69          return this.destination;
70      }
71  
72      /**
73       * Store the delivery mode associated with this message. This value
74       * determines the persistence of a message and is set by a client prior to
75       * sending a message. This implements the javax.jms.Message function.
76       *
77       * @param deliveryMode The defaultDeliveryMode to store.
78       * @throws javax.jms.JMSException if an error occurs while storing the value.
79       * @see javax.jms.DeliveryMode
80       */
81      public void setJMSDeliveryMode(int deliveryMode) throws JMSException   {
82          if (deliveryMode != DeliveryMode.NON_PERSISTENT && deliveryMode != DeliveryMode.PERSISTENT) {
83              throw new JMSException  ("invalide Delivery Mode: " + deliveryMode);
84          }
85          this.deliveryMode = deliveryMode;
86      }
87  
88      /**
89       * Get the currently stored delivery mode.
90       *
91       * @return defaultDeliveryMode
92       * @throws javax.jms.JMSException if an error occurs while retrieve the value.
93       * @see javax.jms.DeliveryMode
94       */
95      public int getJMSDeliveryMode() throws JMSException   {
96          return deliveryMode;
97      }
98  
99      /**
100      * Sets the message ID.
101      * <p/>
102      * <P>
103      * JMS providers set this field when a message is sent. This method can be
104      * used to change the value for a message that has been received.
105      *
106      * @param id the ID of the message
107      * @throws javax.jms.JMSException if the JMS provider fails to set the message ID due to
108      *                                some internal error.
109      * @see javax.jms.Message#getJMSMessageID()
110      */
111     public void setJMSMessageID(String   id) throws JMSException   {
112         if (!id.startsWith(MESSAGEID_PREFIX)) {
113             throw new JMSException  ("The message id must start with ID:");
114         }
115         this.messageID = id;
116     }
117 
118     /**
119      * Gets the message ID.
120      * <p/>
121      * <P>
122      * The <CODE>JMSMessageID</CODE> header field contains a value that
123      * uniquely identifies each message sent by a provider.
124      * <p/>
125      * <P>
126      * When a message is sent, <CODE>JMSMessageID</CODE> can be ignored. When
127      * the <CODE>send</CODE> or <CODE>publish</CODE> method returns, it
128      * contains a provider-assigned value.
129      * <p/>
130      * <P>
131      * A <CODE>JMSMessageID</CODE> is a <CODE>String</CODE> value that
132      * should function as a nique key for identifying messages in a historical
133      * repository.
134      * <p/>
135      * <P>
136      * All <CODE>JMSMessageID</CODE> values must start with the prefix <CODE>
137      * 'ID:'</CODE>. Uniqueness of message ID values across different
138      * providers is not required.
139      *
140      * @return the message ID
141      * @throws javax.jms.JMSException if the JMS provider fails to get the message ID due to
142      *                                some internal error.
143      * @see javax.jms.Message#setJMSMessageID(String)
144      * @see javax.jms.MessageProducer#setDisableMessageID(boolean)
145      */
146     public String   getJMSMessageID() throws JMSException   {
147         return messageID;
148 /*
149         if(this.messageID != null) {
150             return this.messageID.getMessageID();
151         }
152         else {
153             throw new JMSException("Message ID not initialized");
154         }
155 */
156     }
157 
158     /**
159      * Sets the message timestamp.
160      * <p/>
161      * <P>
162      * JMS providers set this field when a message is sent. This method can be
163      * used to change the value for a message that has been received.
164      *
165      * @param timestamp the timestamp for this message
166      * @throws javax.jms.JMSException if the JMS provider fails to set the timestamp due to
167      *                                some internal error.
168      * @see javax.jms.Message#getJMSTimestamp()
169      */
170     public void setJMSTimestamp(long timestamp) throws JMSException   {
171         this.timestamp = timestamp;
172     }
173 
174     /**
175      * Gets the message timestamp.
176      * <p/>
177      * <P>
178      * The <CODE>JMSTimestamp</CODE> header field contains the time a message
179      * was handed off to a provider to be sent. It is not the time the message
180      * was actually transmitted, because the actual send may occur later due to
181      * transactions or other client-side queueing of messages.
182      *
183      * @return the message timestamp
184      * @throws javax.jms.JMSException if the JMS provider fails to get the timestamp due to
185      *                                some internal error.
186      * @see javax.jms.Message#setJMSTimestamp(long)
187      * @see javax.jms.MessageProducer#setDisableMessageTimestamp(boolean)
188      */
189     public long getJMSTimestamp() throws JMSException   {
190         return timestamp;
191     }
192 
193     /**
194      * Sets the correlation ID for the message.
195      * <p/>
196      * <P>
197      * A client can use the <CODE>JMSCorrelationID</CODE> header field to
198      * link one message with another. A typical use is to link a response
199      * message with its request message.
200      * <p/>
201      * <P>
202      * <CODE>JMSCorrelationID</CODE> can hold one of the following:
203      * <UL>
204      * <LI>A provider-specific message ID
205      * <LI>An application-specific <CODE>String</CODE>
206      * <LI>A provider-native <CODE>byte[]</CODE> value
207      * </UL>
208      * <p/>
209      * <P>
210      * Since each message sent by a JMS provider is assigned a message ID
211      * value, it is convenient to link messages via message ID. All message ID
212      * values must start with the <CODE>'ID:'</CODE> prefix.
213      * <p/>
214      * <P>
215      * In some cases, an application (made up of several clients) needs to use
216      * an application-specific value for linking messages. For instance, an
217      * application may use <CODE>JMSCorrelationID</CODE> to hold a value
218      * referencing some external information. Application-specified values must
219      * not start with the <CODE>'ID:'</CODE> prefix; this is reserved for
220      * provider-generated message ID values.
221      * <p/>
222      * <P>
223      * If a provider supports the native concept of correlation ID, a JMS
224      * client may need to assign specific <CODE>JMSCorrelationID</CODE>
225      * values to match those expected by clients that do not use the JMS API. A
226      * <CODE>byte[]</CODE> value is used for this purpose. JMS providers
227      * without native correlation ID values are not required to support <CODE>
228      * byte[]</CODE> values. The use of a <CODE>byte[]</CODE> value for
229      * <CODE>JMSCorrelationID</CODE> is non-portable.
230      *
231      * @param correlationID the message ID of a message being referred to
232      * @throws javax.jms.JMSException if the JMS provider fails to set the correlation ID due
233      *                                to some internal error.
234      * @see javax.jms.Message#getJMSCorrelationID()
235      * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
236      * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
237      */
238     public void setJMSCorrelationID(String   correlationID) throws JMSException   {
239         this.correlationID = correlationID;
240     }
241 
242     /**
243      * Gets the correlation ID for the message.
244      * <p/>
245      * <P>
246      * This method is used to return correlation ID values that are either
247      * provider-specific message IDs or application-specific <CODE>String
248      * </CODE> values.
249      *
250      * @return the correlation ID of a message as a <CODE>String</CODE>
251      * @throws javax.jms.JMSException if the JMS provider fails to get the correlation ID due
252      *                                to some internal error.
253      * @see javax.jms.Message#setJMSCorrelationID(String)
254      * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
255      * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
256      */
257     public String   getJMSCorrelationID() throws JMSException   {
258         return correlationID;
259     }
260 
261     /**
262      * Sets the correlation ID as an array of bytes for the message.
263      * <p/>
264      * <P>
265      * The array is copied before the method returns, so future modifications
266      * to the array will not alter this message header.
267      * <p/>
268      * <P>
269      * If a provider supports the native concept of correlation ID, a JMS
270      * client may need to assign specific <CODE>JMSCorrelationID</CODE>
271      * values to match those expected by native messaging clients. JMS
272      * providers without native correlation ID values are not required to
273      * support this method and its corresponding get method; their
274      * implementation may throw a <CODE>
275      * java.lang.UnsupportedOperationException</CODE>.
276      * <p/>
277      * <P>
278      * The use of a <CODE>byte[]</CODE> value for <CODE>JMSCorrelationID
279      * </CODE> is non-portable.
280      *
281      * @param correlationID the correlation ID value as an array of bytes
282      * @throws javax.jms.JMSException if the JMS provider fails to set the correlation ID due
283      *                                to some internal error.
284      * @see javax.jms.Message#setJMSCorrelationID(String)
285      * @see javax.jms.Message#getJMSCorrelationID()
286      * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
287      */
288     void setJMSCorrelationIDAsBytes(byte[] correlationID)
289             throws JMSException   {
290         this.correlationID = new String  (correlationID);
291     }
292 
293     /**
294      * Gets the correlation ID as an array of bytes for the message.
295      * <p/>
296      * <P>
297      * The use of a <CODE>byte[]</CODE> value for <CODE>JMSCorrelationID
298      * </CODE> is non-portable.
299      *
300      * @return the correlation ID of a message as an array of bytes
301      * @throws javax.jms.JMSException if the JMS provider fails to get the correlation ID due
302      *                                to some internal error.
303      * @see javax.jms.Message#setJMSCorrelationID(String)
304      * @see javax.jms.Message#getJMSCorrelationID()
305      * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
306      */
307     byte[] getJMSCorrelationIDAsBytes() throws JMSException   {
308         return correlationID.getBytes();
309     }
310 
311     /**
312      * Sets the <CODE>Destination</CODE> object to which a reply to this
313      * message should be sent.
314      * <p/>
315      * <P>
316      * The <CODE>JMSReplyTo</CODE> header field contains the destination
317      * where a reply to the current message should be sent. If it is null, no
318      * reply is expected. The destination may be either a <CODE>Queue</CODE>
319      * object or a <CODE>Topic</CODE> object.
320      * <p/>
321      * <P>
322      * Messages sent with a null <CODE>JMSReplyTo</CODE> value may be a
323      * notification of some event, or they may just be some data the sender
324      * thinks is of interest.
325      * <p/>
326      * <P>
327      * Messages with a <CODE>JMSReplyTo</CODE> value typically expect a
328      * response. A response is optional; it is up to the client to decide.
329      * These messages are called requests. A message sent in response to a
330      * request is called a reply.
331      * <p/>
332      * <P>
333      * In some cases a client may wish to match a request it sent earlier with
334      * a reply it has just received. The client can use the <CODE>
335      * JMSCorrelationID</CODE> header field for this purpose.
336      *
337      * @param replyTo <CODE>Destination</CODE> to which to send a response to
338      *                this message
339      * @throws javax.jms.JMSException if the JMS provider fails to set the <CODE>JMSReplyTo
340      *                                </CODE> destination due to some internal error.
341      * @see javax.jms.Message#getJMSReplyTo()
342      */
343     public void setJMSReplyTo(Destination   replyTo) throws JMSException   {
344         if (replyTo instanceof Destination  ) {
345             this.replyTo = (Destination  ) replyTo;
346         } else {
347             throw new JMSException  ("Illegal Destination Type.");
348         }
349     }
350 
351     /**
352      * Gets the <CODE>Destination</CODE> object to which a reply to this
353      * message should be sent.
354      *
355      * @return <CODE>Destination</CODE> to which to send a response to this
356      *         message
357      * @throws javax.jms.JMSException if the JMS provider fails to get the <CODE>JMSReplyTo
358      *                                </CODE> destination due to some internal error.
359      * @see javax.jms.Message#setJMSReplyTo(javax.jms.Destination)
360      */
361     public Destination   getJMSReplyTo() throws JMSException   {
362         return this.replyTo;
363     }
364 
365     /**
366      * Specifies whether this message is being redelivered.
367      * <p/>
368      * <P>
369      * This field is set at the time the message is delivered. This method can
370      * be used to change the value for a message that has been received.
371      *
372      * @param redelivered an indication of whether this message is being redelivered
373      * @throws javax.jms.JMSException if the JMS provider fails to set the redelivered state
374      *                                due to some internal error.
375      * @see javax.jms.Message#getJMSRedelivered()
376      */
377     public void setJMSRedelivered(boolean redelivered) throws JMSException   {
378         this.redelivered = redelivered;
379     }
380 
381     /**
382      * Gets an indication of whether this message is being redelivered.
383      * <p/>
384      * <P>
385      * If a client receives a message with the <CODE>JMSRedelivered</CODE>
386      * field set, it is likely, but not guaranteed, that this message was
387      * delivered earlier but that its receipt was not acknowledged at that
388      * time.
389      *
390      * @return true if this message is being redelivered
391      * @throws javax.jms.JMSException if the JMS provider fails to get the redelivered state
392      *                                due to some internal error.
393      * @see javax.jms.Message#setJMSRedelivered(boolean)
394      */
395     public boolean getJMSRedelivered() throws JMSException   {
396         return this.redelivered;
397     }
398 
399     /**
400      * Gets the message type identifier supplied by the client when the message
401      * was sent.
402      *
403      * @return the message type
404      * @throws javax.jms.JMSException if the JMS provider fails to get the message type due to
405      *                                some internal error.
406      * @see javax.jms.Message#setJMSType(String)
407      */
408     public String   getJMSType() throws JMSException   {
409         return messageType;
410     }
411 
412     /**
413      * Sets the message type.
414      * <p/>
415      * <P>
416      * The JMS API does not define a standard message definition repository,
417      * nor does it define a naming policy for the definitions it contains.
418      * <p/>
419      * <P>
420      * Some messaging systems require that a message type definition for each
421      * application message be created and that each message specify its type.
422      * In order to work with such JMS providers, JMS clients should assign a
423      * value to <CODE>JMSType</CODE>, whether the application makes use of
424      * it or not. This ensures that the field is properly set for those
425      * providers that require it.
426      * <p/>
427      * <P>
428      * To ensure portability, JMS clients should use symbolic values for <CODE>
429      * JMSType</CODE> that can be configured at installation time to the
430      * values defined in the current provider's message repository. If string
431      * literals are used, they may not be valid type names for some JMS
432      * providers.
433      *
434      * @param type the message type
435      * @throws javax.jms.JMSException if the JMS provider fails to set the message type due to
436      *                                some internal error.
437      * @see javax.jms.Message#getJMSType()
438      */
439     public void setJMSType(String   type) throws JMSException   {
440         this.messageType = type;
441     }
442 
443     /**
444      * Sets the message's expiration value.
445      *
446      * @param expiration the message's expiration time
447      * @throws javax.jms.JMSException if the JMS provider fails to set the message expiration
448      *                                due to some internal error.
449      * @see javax.jms.Message
450      */
451     public void setJMSExpiration(long expiration) throws JMSException   {
452         if (expiration >= 0) {
453             this.expiration = expiration;
454         } else {
455             throw new JMSException  ("Illegal Message Expiration.");
456         }
457 
458     }
459 
460     /**
461      * Gets the message's expiration value.
462      * <p/>
463      * <P>
464      * When a message is sent, the <CODE>JMSExpiration</CODE> header field is
465      * left unassigned. After completion of the <CODE>send</CODE> or <CODE>
466      * publish</CODE> method, it holds the expiration time of the message.
467      * This is the sum of the time-to-live value specified by the client and
468      * the GMT at the time of the <CODE>send</CODE> or <CODE>publish</CODE>.
469      * <p/>
470      * <P>
471      * If the time-to-live is specified as zero, <CODE>JMSExpiration</CODE>
472      * is set to zero to indicate that the message does not expire.
473      * <p/>
474      * <P>
475      * When a message's expiration time is reached, a provider should discard
476      * it. The JMS API does not define any form of notification of message
477      * expiration.
478      * <p/>
479      * <P>
480      * Clients should not receive messages that have expired; however, the JMS
481      * API does not guarantee that this will not happen.
482      *
483      * @return the time the message expires, which is the sum of the
484      *         time-to-live value specified by the client and the GMT at the
485      *         time of the send
486      * @throws javax.jms.JMSException if the JMS provider fails to get the message expiration
487      *                                due to some internal error.
488      * @see javax.jms.Message
489      */
490     public long getJMSExpiration() throws JMSException   {
491         return expiration;
492     }
493 
494     /**
495      * Sets the defaultPriority level for this message.
496      *
497      * @param priority the defaultPriority of this message
498      * @throws javax.jms.JMSException if the JMS provider fails to set the message
499      *                                defaultPriority due to some internal error.
500      * @see javax.jms.Message
501      */
502     public void setJMSPriority(int priority) throws JMSException   {
503         if (priority >= 0 && priority < 10) {
504             this.priority = priority;
505         } else {
506             throw new JMSException  ("Invalid message defaultPriority");
507         }
508     }
509 
510     /**
511      * Gets the message defaultPriority level.
512      * <p/>
513      * <P>
514      * The JMS API defines ten levels of defaultPriority value, with 0 as the
515      * lowest defaultPriority and 9 as the highest. In addition, clients should
516      * consider priorities 0-4 as gradations of normal defaultPriority and
517      * priorities 5-9 as gradations of expedited defaultPriority.
518      *
519      * @return the default message defaultPriority
520      * @throws javax.jms.JMSException if the JMS provider fails to get the message
521      *                                defaultPriority due to some internal error.
522      * @see javax.jms.Message
523      */
524     public int getJMSPriority() throws JMSException   {
525         return priority;
526     }
527 }
528
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags