01: /*
02: * JBoss, Home of Professional Open Source.
03: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
04: * as indicated by the @author tags. See the copyright.txt file in the
05: * distribution for a full listing of individual contributors.
06: *
07: * This is free software; you can redistribute it and/or modify it
08: * under the terms of the GNU Lesser General Public License as
09: * published by the Free Software Foundation; either version 2.1 of
10: * the License, or (at your option) any later version.
11: *
12: * This software is distributed in the hope that it will be useful,
13: * but WITHOUT ANY WARRANTY; without even the implied warranty of
14: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15: * Lesser General Public License for more details.
16: *
17: * You should have received a copy of the GNU Lesser General Public
18: * License along with this software; if not, write to the Free
19: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21: */
22: package javax.jms;
23:
24: import java.io.Serializable;
25:
26: /** An <CODE>ObjectMessage</CODE> object is used to send a message that contains
27: * a serializable object in the Java programming language ("Java object").
28: * It inherits from the <CODE>Message</CODE> interface and adds a body
29: * containing a single reference to an object. Only <CODE>Serializable</CODE>
30: * Java objects can be used.
31: *
32: * <P>If a collection of Java objects must be sent, one of the
33: * <CODE>Collection</CODE> classes provided since JDK 1.2 can be used.
34: *
35: * <P>When a client receives an <CODE>ObjectMessage</CODE>, it is in read-only
36: * mode. If a client attempts to write to the message at this point, a
37: * <CODE>MessageNotWriteableException</CODE> is thrown. If
38: * <CODE>clearBody</CODE> is called, the message can now be both read from and
39: * written to.
40: *
41: * @see javax.jms.Session#createObjectMessage()
42: * @see javax.jms.Session#createObjectMessage(Serializable)
43: * @see javax.jms.BytesMessage
44: * @see javax.jms.MapMessage
45: * @see javax.jms.Message
46: * @see javax.jms.StreamMessage
47: * @see javax.jms.TextMessage
48: */
49:
50: public interface ObjectMessage extends Message {
51:
52: /** Sets the serializable object containing this message's data.
53: * It is important to note that an <CODE>ObjectMessage</CODE>
54: * contains a snapshot of the object at the time <CODE>setObject()</CODE>
55: * is called; subsequent modifications of the object will have no
56: * effect on the <CODE>ObjectMessage</CODE> body.
57: *
58: * @param object the message's data
59: *
60: * @exception JMSException if the JMS provider fails to set the object
61: * due to some internal error.
62: * @exception MessageFormatException if object serialization fails.
63: * @exception MessageNotWriteableException if the message is in read-only
64: * mode.
65: */
66:
67: void setObject(Serializable object) throws JMSException;
68:
69: /** Gets the serializable object containing this message's data. The
70: * default value is null.
71: *
72: * @return the serializable object containing this message's data
73: *
74: * @exception JMSException if the JMS provider fails to get the object
75: * due to some internal error.
76: * @exception MessageFormatException if object deserialization fails.
77: */
78:
79: Serializable getObject() throws JMSException;
80: }
|