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 */
25
26package com.sun.xml.internal.bind.api;
27
28import java.io.InputStream;
29import java.io.OutputStream;
30
31import javax.xml.bind.JAXBException;
32import javax.xml.bind.Marshaller;
33import javax.xml.bind.Unmarshaller;
34import javax.xml.bind.attachment.AttachmentMarshaller;
35import javax.xml.bind.attachment.AttachmentUnmarshaller;
36import javax.xml.namespace.NamespaceContext;
37import javax.xml.stream.XMLStreamReader;
38import javax.xml.stream.XMLStreamWriter;
39import javax.xml.transform.Result;
40import javax.xml.transform.Source;
41
42import com.sun.istack.internal.NotNull;
43import com.sun.istack.internal.Nullable;
44import com.sun.xml.internal.bind.v2.runtime.BridgeContextImpl;
45import com.sun.xml.internal.bind.v2.runtime.JAXBContextImpl;
46
47import org.w3c.dom.Node;
48import org.xml.sax.ContentHandler;
49
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 */
67public abstract class Bridge<T> {
68    protected Bridge(JAXBContextImpl context) {
69        this.context = context;
70    }
71
72    protected final JAXBContextImpl context;
73
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    }
82
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    }
100
101    public final void marshal(@NotNull BridgeContext context,T object,XMLStreamWriter output) throws JAXBException {
102        marshal( ((BridgeContextImpl)context).marshaller, object, output );
103    }
104
105    public abstract void marshal(@NotNull Marshaller m,T object,XMLStreamWriter output) throws JAXBException;
106
107
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    }
134
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    }
138
139    public abstract void marshal(@NotNull Marshaller m,T object,OutputStream output, NamespaceContext nsContext) throws JAXBException;
140
141
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    }
147
148    public final void marshal(@NotNull BridgeContext context,T object,Node output) throws JAXBException {
149        marshal( ((BridgeContextImpl)context).marshaller, object, output );
150    }
151
152    public abstract void marshal(@NotNull Marshaller m,T object,Node output) throws JAXBException;
153
154
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;
175
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;
188
189
190
191    private T exit(T r, Unmarshaller u) {
192        u.setAttachmentUnmarshaller(null);
193        context.unmarshallerPool.recycle(u);
194        return r;
195    }
196
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;
228
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;
260
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;
285
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;
315
316    /**
317     * Gets the {@link TypeReference} from which this bridge was created.
318     */
319    public abstract TypeReference getTypeReference();
320}
321