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, 2011, 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.bind.api;
28 import java.io.InputStream;
29 import java.io.OutputStream;
31 import javax.xml.bind.JAXBException;
32 import javax.xml.bind.Marshaller;
33 import javax.xml.bind.Unmarshaller;
34 import javax.xml.bind.attachment.AttachmentMarshaller;
35 import javax.xml.bind.attachment.AttachmentUnmarshaller;
36 import javax.xml.namespace.NamespaceContext;
37 import javax.xml.stream.XMLStreamReader;
38 import javax.xml.stream.XMLStreamWriter;
39 import javax.xml.transform.Result;
40 import javax.xml.transform.Source;
42 import com.sun.istack.internal.NotNull;
43 import com.sun.istack.internal.Nullable;
44 import com.sun.xml.internal.bind.v2.runtime.BridgeContextImpl;
45 import com.sun.xml.internal.bind.v2.runtime.JAXBContextImpl;
47 import org.w3c.dom.Node;
48 import org.xml.sax.ContentHandler;
50 /**
51 * Mini-marshaller/unmarshaller that is specialized for a particular
52 * element name and a type.
53 *
54 * <p>
55 * Instances of this class is stateless and multi-thread safe.
56 * They are reentrant.
57 *
58 * <p>
59 * All the marshal operation generates fragments.
60 *
61 * <p>
62 * <b>Subject to change without notice</b>.
63 *
64 * @since JAXB 2.0 EA1
65 * @author Kohsuke Kawaguchi
66 */
67 public abstract class Bridge<T> {
68 protected Bridge(JAXBContextImpl context) {
69 this.context = context;
70 }
72 protected final JAXBContextImpl context;
74 /**
75 * Gets the {@link JAXBRIContext} to which this object belongs.
76 *
77 * @since 2.1
78 */
79 public @NotNull JAXBRIContext getContext() {
80 return context;
81 }
83 /**
84 *
85 * @throws JAXBException
86 * if there was an error while marshalling.
87 *
88 * @since 2.0 EA1
89 */
90 public final void marshal(T object,XMLStreamWriter output) throws JAXBException {
91 marshal(object,output,null);
92 }
93 public final void marshal(T object,XMLStreamWriter output, AttachmentMarshaller am) throws JAXBException {
94 Marshaller m = context.marshallerPool.take();
95 m.setAttachmentMarshaller(am);
96 marshal(m,object,output);
97 m.setAttachmentMarshaller(null);
98 context.marshallerPool.recycle(m);
99 }
101 public final void marshal(@NotNull BridgeContext context,T object,XMLStreamWriter output) throws JAXBException {
102 marshal( ((BridgeContextImpl)context).marshaller, object, output );
103 }
105 public abstract void marshal(@NotNull Marshaller m,T object,XMLStreamWriter output) throws JAXBException;
108 /**
109 * Marshals the specified type object with the implicit element name
110 * associated with this instance of {@link Bridge}.
111 *
112 * @param nsContext
113 * if this marshalling is done to marshal a subelement, this {@link NamespaceContext}
114 * represents in-scope namespace bindings available for that element. Can be null,
115 * in which case JAXB assumes no in-scope namespaces.
116 * @throws JAXBException
117 * if there was an error while marshalling.
118 *
119 * @since 2.0 EA1
120 */
121 public void marshal(T object,OutputStream output, NamespaceContext nsContext) throws JAXBException {
122 marshal(object,output,nsContext,null);
123 }
124 /**
125 * @since 2.0.2
126 */
127 public void marshal(T object,OutputStream output, NamespaceContext nsContext, AttachmentMarshaller am) throws JAXBException {
128 Marshaller m = context.marshallerPool.take();
129 m.setAttachmentMarshaller(am);
130 marshal(m,object,output,nsContext);
131 m.setAttachmentMarshaller(null);
132 context.marshallerPool.recycle(m);
133 }
135 public final void marshal(@NotNull BridgeContext context,T object,OutputStream output, NamespaceContext nsContext) throws JAXBException {
136 marshal( ((BridgeContextImpl)context).marshaller, object, output, nsContext );
137 }
139 public abstract void marshal(@NotNull Marshaller m,T object,OutputStream output, NamespaceContext nsContext) throws JAXBException;
142 public final void marshal(T object,Node output) throws JAXBException {
143 Marshaller m = context.marshallerPool.take();
144 marshal(m,object,output);
145 context.marshallerPool.recycle(m);
146 }
148 public final void marshal(@NotNull BridgeContext context,T object,Node output) throws JAXBException {
149 marshal( ((BridgeContextImpl)context).marshaller, object, output );
150 }
152 public abstract void marshal(@NotNull Marshaller m,T object,Node output) throws JAXBException;
155 /**
156 * @since 2.0 EA4
157 */
158 public final void marshal(T object, ContentHandler contentHandler) throws JAXBException {
159 marshal(object,contentHandler,null);
160 }
161 /**
162 * @since 2.0.2
163 */
164 public final void marshal(T object, ContentHandler contentHandler, AttachmentMarshaller am) throws JAXBException {
165 Marshaller m = context.marshallerPool.take();
166 m.setAttachmentMarshaller(am);
167 marshal(m,object,contentHandler);
168 m.setAttachmentMarshaller(null);
169 context.marshallerPool.recycle(m);
170 }
171 public final void marshal(@NotNull BridgeContext context,T object, ContentHandler contentHandler) throws JAXBException {
172 marshal( ((BridgeContextImpl)context).marshaller, object, contentHandler );
173 }
174 public abstract void marshal(@NotNull Marshaller m,T object, ContentHandler contentHandler) throws JAXBException;
176 /**
177 * @since 2.0 EA4
178 */
179 public final void marshal(T object, Result result) throws JAXBException {
180 Marshaller m = context.marshallerPool.take();
181 marshal(m,object,result);
182 context.marshallerPool.recycle(m);
183 }
184 public final void marshal(@NotNull BridgeContext context,T object, Result result) throws JAXBException {
185 marshal( ((BridgeContextImpl)context).marshaller, object, result );
186 }
187 public abstract void marshal(@NotNull Marshaller m,T object, Result result) throws JAXBException;
191 private T exit(T r, Unmarshaller u) {
192 u.setAttachmentUnmarshaller(null);
193 context.unmarshallerPool.recycle(u);
194 return r;
195 }
197 /**
198 * Unmarshals the specified type object.
199 *
200 * @param in
201 * the parser must be pointing at a start tag
202 * that encloses the XML type that this {@link Bridge} is
203 * instanciated for.
204 *
205 * @return
206 * never null.
207 *
208 * @throws JAXBException
209 * if there was an error while unmarshalling.
210 *
211 * @since 2.0 EA1
212 */
213 public final @NotNull T unmarshal(@NotNull XMLStreamReader in) throws JAXBException {
214 return unmarshal(in,null);
215 }
216 /**
217 * @since 2.0.3
218 */
219 public final @NotNull T unmarshal(@NotNull XMLStreamReader in, @Nullable AttachmentUnmarshaller au) throws JAXBException {
220 Unmarshaller u = context.unmarshallerPool.take();
221 u.setAttachmentUnmarshaller(au);
222 return exit(unmarshal(u,in),u);
223 }
224 public final @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull XMLStreamReader in) throws JAXBException {
225 return unmarshal( ((BridgeContextImpl)context).unmarshaller, in );
226 }
227 public abstract @NotNull T unmarshal(@NotNull Unmarshaller u, @NotNull XMLStreamReader in) throws JAXBException;
229 /**
230 * Unmarshals the specified type object.
231 *
232 * @param in
233 * the parser must be pointing at a start tag
234 * that encloses the XML type that this {@link Bridge} is
235 * instanciated for.
236 *
237 * @return
238 * never null.
239 *
240 * @throws JAXBException
241 * if there was an error while unmarshalling.
242 *
243 * @since 2.0 EA1
244 */
245 public final @NotNull T unmarshal(@NotNull Source in) throws JAXBException {
246 return unmarshal(in,null);
247 }
248 /**
249 * @since 2.0.3
250 */
251 public final @NotNull T unmarshal(@NotNull Source in, @Nullable AttachmentUnmarshaller au) throws JAXBException {
252 Unmarshaller u = context.unmarshallerPool.take();
253 u.setAttachmentUnmarshaller(au);
254 return exit(unmarshal(u,in),u);
255 }
256 public final @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull Source in) throws JAXBException {
257 return unmarshal( ((BridgeContextImpl)context).unmarshaller, in );
258 }
259 public abstract @NotNull T unmarshal(@NotNull Unmarshaller u, @NotNull Source in) throws JAXBException;
261 /**
262 * Unmarshals the specified type object.
263 *
264 * @param in
265 * the parser must be pointing at a start tag
266 * that encloses the XML type that this {@link Bridge} is
267 * instanciated for.
268 *
269 * @return
270 * never null.
271 *
272 * @throws JAXBException
273 * if there was an error while unmarshalling.
274 *
275 * @since 2.0 EA1
276 */
277 public final @NotNull T unmarshal(@NotNull InputStream in) throws JAXBException {
278 Unmarshaller u = context.unmarshallerPool.take();
279 return exit(unmarshal(u,in),u);
280 }
281 public final @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull InputStream in) throws JAXBException {
282 return unmarshal( ((BridgeContextImpl)context).unmarshaller, in );
283 }
284 public abstract @NotNull T unmarshal(@NotNull Unmarshaller u, @NotNull InputStream in) throws JAXBException;
286 /**
287 * Unmarshals the specified type object.
288 *
289 * @param n
290 * Node to be unmarshalled.
291 *
292 * @return
293 * never null.
294 *
295 * @throws JAXBException
296 * if there was an error while unmarshalling.
297 *
298 * @since 2.0 FCS
299 */
300 public final @NotNull T unmarshal(@NotNull Node n) throws JAXBException {
301 return unmarshal(n,null);
302 }
303 /**
304 * @since 2.0.3
305 */
306 public final @NotNull T unmarshal(@NotNull Node n, @Nullable AttachmentUnmarshaller au) throws JAXBException {
307 Unmarshaller u = context.unmarshallerPool.take();
308 u.setAttachmentUnmarshaller(au);
309 return exit(unmarshal(u,n),u);
310 }
311 public final @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull Node n) throws JAXBException {
312 return unmarshal( ((BridgeContextImpl)context).unmarshaller, n );
313 }
314 public abstract @NotNull T unmarshal(@NotNull Unmarshaller context, @NotNull Node n) throws JAXBException;
316 /**
317 * Gets the {@link TypeReference} from which this bridge was created.
318 */
319 public abstract TypeReference getTypeReference();
320 }