1. /*
  2. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  3. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  4. */
  5. package javax.jms;
  6. import java.io.Serializable;
  7. /** An <CODE>ObjectMessage</CODE> object is used to send a message that contains
  8. * a serializable object in the Java programming language ("Java object").
  9. * It inherits from the <CODE>Message</CODE> interface and adds a body
  10. * containing a single reference to an object. Only <CODE>Serializable</CODE>
  11. * Java objects can be used.
  12. *
  13. * <P>If a collection of Java objects must be sent, one of the
  14. * <CODE>Collection</CODE> classes provided since JDK 1.2 can be used.
  15. *
  16. * <P>When a client receives an <CODE>ObjectMessage</CODE>, it is in read-only
  17. * mode. If a client attempts to write to the message at this point, a
  18. * <CODE>MessageNotWriteableException</CODE> is thrown. If
  19. * <CODE>clearBody</CODE> is called, the message can now be both read from and
  20. * written to.
  21. *
  22. * @version 1.0 - 6 August 1998
  23. * @author Mark Hapner
  24. * @author Rich Burridge
  25. *
  26. * @see javax.jms.Session#createObjectMessage()
  27. * @see javax.jms.Session#createObjectMessage(Serializable)
  28. * @see javax.jms.BytesMessage
  29. * @see javax.jms.MapMessage
  30. * @see javax.jms.Message
  31. * @see javax.jms.StreamMessage
  32. * @see javax.jms.TextMessage
  33. */
  34. public interface ObjectMessage extends Message {
  35. /** Sets the serializable object containing this message's data.
  36. * It is important to note that an <CODE>ObjectMessage</CODE>
  37. * contains a snapshot of the object at the time <CODE>setObject()</CODE>
  38. * is called; subsequent modifications of the object will have no
  39. * effect on the <CODE>ObjectMessage</CODE> body.
  40. *
  41. * @param object the message's data
  42. *
  43. * @exception JMSException if the JMS provider fails to set the object
  44. * due to some internal error.
  45. * @exception MessageFormatException if object serialization fails.
  46. * @exception MessageNotWriteableException if the message is in read-only
  47. * mode.
  48. */
  49. void
  50. setObject(Serializable object) throws JMSException;
  51. /** Gets the serializable object containing this message's data. The
  52. * default value is null.
  53. *
  54. * @return the serializable object containing this message's data
  55. *
  56. * @exception JMSException if the JMS provider fails to get the object
  57. * due to some internal error.
  58. * @exception MessageFormatException if object deserialization fails.
  59. */
  60. Serializable
  61. getObject() throws JMSException;
  62. }