Fri, 24 Oct 2014 15:02:28 +0200
8054367: More references for endpoints
Summary: fix also reviewed by Iaroslav.Savytskyi@oracle.com, Alexander.Fomin@oracle.com
Reviewed-by: mullan, skoivu
1 /*
2 * Copyright (c) 1997, 2012, 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 */
26 package com.sun.xml.internal.ws.spi.db;
28 import java.io.InputStream;
29 import java.io.OutputStream;
31 import javax.xml.bind.JAXBException;
32 import javax.xml.bind.attachment.AttachmentMarshaller;
33 import javax.xml.bind.attachment.AttachmentUnmarshaller;
34 import javax.xml.namespace.NamespaceContext;
35 import javax.xml.stream.XMLStreamReader;
36 import javax.xml.stream.XMLStreamWriter;
37 import javax.xml.transform.Result;
38 import javax.xml.transform.Source;
40 import com.sun.istack.internal.NotNull;
41 import com.sun.istack.internal.Nullable;
42 import org.w3c.dom.Node;
43 import org.xml.sax.ContentHandler;
45 /**
46 * The XMLBridge is a Glassfish JAXWS side of Glassfish JAXB Bridge.
47 *
48 * Mini-marshaller/unmarshaller that is specialized for a particular
49 * element name and a type.
50 *
51 * <p>
52 * Instances of this class is stateless and multi-thread safe.
53 * They are reentrant.
54 *
55 * <p>
56 * All the marshal operation generates fragments.
57 *
58 * <p>
59 * <b>Subject to change without notice</b>.
60 *
61 * @since JAXB 2.0 EA1
62 * @author Kohsuke Kawaguchi
63 * @author shih-chang.chen@oracle.com
64 */
65 public interface XMLBridge<T> {
66 /**
67 * Gets the {@link BindingContext} to which this object belongs.
68 *
69 * @since 2.1
70 */
71 public @NotNull BindingContext context();
73 /**
74 *
75 * @throws JAXBException
76 * if there was an error while marshalling.
77 *
78 * @since 2.0 EA1
79 */
80 // public void marshal(T object,XMLStreamWriter output) throws JAXBException;
82 public void marshal(T object,XMLStreamWriter output, AttachmentMarshaller am) throws JAXBException;
84 /**
85 * Marshals the specified type object with the implicit element name
86 * associated with this instance of {@link Bond}.
87 *
88 * @param nsContext
89 * if this marshalling is done to marshal a subelement, this {@link NamespaceContext}
90 * represents in-scope namespace bindings available for that element. Can be null,
91 * in which case JAXB assumes no in-scope namespaces.
92 * @throws JAXBException
93 * if there was an error while marshalling.
94 *
95 * @since 2.0 EA1
96 */
97 // public void marshal(T object,OutputStream output, NamespaceContext nsContext) throws JAXBException;
99 /**
100 * @since 2.0.2
101 */
102 public void marshal(T object,OutputStream output, NamespaceContext nsContext, AttachmentMarshaller am) throws JAXBException ;
103 //
104 //// public void marshal(@NotNull BridgeContext context,T object,OutputStream output, NamespaceContext nsContext) throws JAXBException;
105 //
106 // public void marshal(@NotNull Marshaller m,T object,OutputStream output, NamespaceContext nsContext) throws JAXBException;
109 public void marshal(T object,Node output) throws JAXBException ;
110 //
111 //// public void marshal(@NotNull BridgeContext context,T object,Node output) throws JAXBException ;
112 //
113 // public void marshal(@NotNull Marshaller m,T object,Node output) throws JAXBException;
116 /**
117 * @since 2.0 EA4
118 */
119 // public void marshal(T object, ContentHandler contentHandler) throws JAXBException;
120 /**
121 * @since 2.0.2
122 */
123 public void marshal(T object, ContentHandler contentHandler, AttachmentMarshaller am) throws JAXBException ;
125 //// public void marshal(@NotNull BridgeContext context,T object, ContentHandler contentHandler) throws JAXBException;
126 //
127 // public void marshal(@NotNull Marshaller m,T object, ContentHandler contentHandler) throws JAXBException;
129 /**
130 * @since 2.0 EA4
131 */
132 public void marshal(T object, Result result) throws JAXBException;
134 //// public void marshal(@NotNull BridgeContext context,T object, Result result) throws JAXBException;
135 // public void marshal(@NotNull Marshaller m,T object, Result result) throws JAXBException;
139 /**
140 * Unmarshals the specified type object.
141 *
142 * @param in
143 * the parser must be pointing at a start tag
144 * that encloses the XML type that this {@link Bond} is
145 * instanciated for.
146 *
147 * @return
148 * never null.
149 *
150 * @throws JAXBException
151 * if there was an error while unmarshalling.
152 *
153 * @since 2.0 EA1
154 */
155 // public @NotNull T unmarshal(@NotNull XMLStreamReader in) throws JAXBException ;
156 /**
157 * @since 2.0.3
158 */
159 public @NotNull T unmarshal(@NotNull XMLStreamReader in, @Nullable AttachmentUnmarshaller au) throws JAXBException;
160 // public @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull XMLStreamReader in) throws JAXBException ;
161 // public @NotNull T unmarshal(@NotNull Unmarshaller u, @NotNull XMLStreamReader in) throws JAXBException;
163 /**
164 * Unmarshals the specified type object.
165 *
166 * @param in
167 * the parser must be pointing at a start tag
168 * that encloses the XML type that this {@link Bond} is
169 * instanciated for.
170 *
171 * @return
172 * never null.
173 *
174 * @throws JAXBException
175 * if there was an error while unmarshalling.
176 *
177 * @since 2.0 EA1
178 */
179 // public @NotNull T unmarshal(@NotNull Source in) throws JAXBException ;
180 /**
181 * @since 2.0.3
182 */
183 public @NotNull T unmarshal(@NotNull Source in, @Nullable AttachmentUnmarshaller au) throws JAXBException;
184 // public @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull Source in) throws JAXBException;
185 // public @NotNull T unmarshal(@NotNull Unmarshaller u, @NotNull Source in) throws JAXBException;
187 /**
188 * Unmarshals the specified type object.
189 *
190 * @param in
191 * the parser must be pointing at a start tag
192 * that encloses the XML type that this {@link XMLBridge} is
193 * instanciated for.
194 *
195 * @return
196 * never null.
197 *
198 * @throws JAXBException
199 * if there was an error while unmarshalling.
200 *
201 * @since 2.0 EA1
202 */
203 public @NotNull T unmarshal(@NotNull InputStream in) throws JAXBException ;
205 // public @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull InputStream in) throws JAXBException ;
207 // public @NotNull T unmarshal(@NotNull Unmarshaller u, @NotNull InputStream in) throws JAXBException;
209 /**
210 * Unmarshals the specified type object.
211 *
212 * @param n
213 * Node to be unmarshalled.
214 *
215 * @return
216 * never null.
217 *
218 * @throws JAXBException
219 * if there was an error while unmarshalling.
220 *
221 * @since 2.0 FCS
222 */
223 // public @NotNull T unmarshal(@NotNull Node n) throws JAXBException ;
224 /**
225 * @since 2.0.3
226 */
227 public @NotNull T unmarshal(@NotNull Node n, @Nullable AttachmentUnmarshaller au) throws JAXBException;
228 // public @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull Node n) throws JAXBException;
229 // public @NotNull T unmarshal(@NotNull Unmarshaller context, @NotNull Node n) throws JAXBException;
231 /**
232 * Gets the {@link TypeInfo} from which this bridge was created.
233 */
234 public TypeInfo getTypeInfo();
236 /**
237 * This can be used to determine whether XMLStreamWriter or OutputStream is
238 * prefered by the implementation.
239 *
240 * @return true if marshall to OutputStream is supported in the
241 * implementation.
242 */
243 public boolean supportOutputStream();
244 }