01: /*
02: * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
03: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
04: */
05:
06: package javax.xml.ws;
07:
08: import javax.xml.transform.Source;
09: import javax.xml.bind.JAXBContext;
10:
11: /** The <code>LogicalMessage</code> interface represents a
12: * protocol agnostic XML message and contains methods that
13: * provide access to the payload of the message.
14: *
15: * @since JAX-WS 2.0
16: **/
17: public interface LogicalMessage {
18:
19: /** Gets the message payload as an XML source, may be called
20: * multiple times on the same LogicalMessage instance, always
21: * returns a new <code>Source</code> that may be used to retrieve the entire
22: * message payload.
23: *
24: * <p>If the returned <code>Source</code> is an instance of
25: * <code>DOMSource</code>, then
26: * modifications to the encapsulated DOM tree change the message
27: * payload in-place, there is no need to susequently call
28: * <code>setPayload</code>. Other types of <code>Source</code> provide only
29: * read access to the message payload.
30: *
31: * @return The contained message payload; returns <code>null</code> if no
32: * payload is present in this message.
33: **/
34: public Source getPayload();
35:
36: /** Sets the message payload
37: *
38: * @param payload message payload
39: * @throws WebServiceException If any error during the setting
40: * of the payload in this message
41: * @throws java.lang.UnsupportedOperationException If this
42: * operation is not supported
43: **/
44: public void setPayload(Source payload);
45:
46: /** Gets the message payload as a JAXB object. Note that there is no
47: * connection between the returned object and the message payload,
48: * changes to the payload require calling <code>setPayload</code>.
49: *
50: * @param context The JAXBContext that should be used to unmarshall
51: * the message payload
52: * @return The contained message payload; returns <code>null</code> if no
53: * payload is present in this message
54: * @throws WebServiceException If an error occurs when using a supplied
55: * JAXBContext to unmarshall the payload. The cause of
56: * the WebServiceException is the original JAXBException.
57: **/
58: public Object getPayload(JAXBContext context);
59:
60: /** Sets the message payload
61: *
62: * @param payload message payload
63: * @param context The JAXBContext that should be used to marshall
64: * the payload
65: * @throws java.lang.UnsupportedOperationException If this
66: * operation is not supported
67: * @throws WebServiceException If an error occurs when using the supplied
68: * JAXBContext to marshall the payload. The cause of
69: * the WebServiceException is the original JAXBException.
70: **/
71: public void setPayload(Object payload, JAXBContext context);
72: }
|