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