1/*
2 * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package javax.xml.ws;
27
28import javax.xml.transform.Source;
29import javax.xml.bind.JAXBContext;
30
31/** The {@code LogicalMessage} interface represents a
32 *  protocol agnostic XML message and contains methods that
33 *  provide access to the payload of the message.
34 *
35 *  @since 1.6, JAX-WS 2.0
36**/
37public interface LogicalMessage {
38
39  /** Gets the message payload as an XML source, may be called
40   *  multiple times on the same LogicalMessage instance, always
41   *  returns a new {@code Source} that may be used to retrieve the entire
42   *  message payload.
43   *
44   *  <p>If the returned {@code Source} is an instance of
45   *  {@code DOMSource}, then
46   *  modifications to the encapsulated DOM tree change the message
47   *  payload in-place, there is no need to susequently call
48   *  {@code setPayload}. Other types of {@code Source} provide only
49   *  read access to the message payload.
50   *
51   *  @return The contained message payload; returns {@code null} if no
52   *          payload is present in this message.
53  **/
54  public Source getPayload();
55
56  /** Sets the message payload
57   *
58   *  @param  payload message payload
59   *  @throws WebServiceException If any error during the setting
60   *          of the payload in this message
61   *  @throws java.lang.UnsupportedOperationException If this
62   *          operation is not supported
63  **/
64  public void setPayload(Source payload);
65
66  /** Gets the message payload as a JAXB object. Note that there is no
67   *  connection between the returned object and the message payload,
68   *  changes to the payload require calling {@code setPayload}.
69   *
70   *  @param  context The JAXBContext that should be used to unmarshall
71   *          the message payload
72   *  @return The contained message payload; returns {@code null} if no
73   *          payload is present in this message
74   *  @throws WebServiceException If an error occurs when using a supplied
75   *     JAXBContext to unmarshall the payload. The cause of
76   *     the WebServiceException is the original JAXBException.
77  **/
78  public Object getPayload(JAXBContext context);
79
80  /** Sets the message payload
81   *
82   *  @param  payload message payload
83   *  @param  context The JAXBContext that should be used to marshall
84   *          the payload
85   *  @throws java.lang.UnsupportedOperationException If this
86   *          operation is not supported
87   *  @throws WebServiceException If an error occurs when using the supplied
88   *     JAXBContext to marshall the payload. The cause of
89   *     the WebServiceException is the original JAXBException.
90  **/
91  public void setPayload(Object payload, JAXBContext context);
92}
93