001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package com.sun.xml.bind.api;
038:
039: import java.io.InputStream;
040: import java.io.OutputStream;
041:
042: import javax.xml.bind.JAXBException;
043: import javax.xml.bind.Marshaller;
044: import javax.xml.bind.Unmarshaller;
045: import javax.xml.bind.attachment.AttachmentMarshaller;
046: import javax.xml.bind.attachment.AttachmentUnmarshaller;
047: import javax.xml.namespace.NamespaceContext;
048: import javax.xml.stream.XMLStreamReader;
049: import javax.xml.stream.XMLStreamWriter;
050: import javax.xml.transform.Result;
051: import javax.xml.transform.Source;
052:
053: import com.sun.istack.NotNull;
054: import com.sun.istack.Nullable;
055: import com.sun.xml.bind.v2.runtime.BridgeContextImpl;
056: import com.sun.xml.bind.v2.runtime.JAXBContextImpl;
057:
058: import org.w3c.dom.Node;
059: import org.xml.sax.ContentHandler;
060:
061: /**
062: * Mini-marshaller/unmarshaller that is specialized for a particular
063: * element name and a type.
064: *
065: * <p>
066: * Instances of this class is stateless and multi-thread safe.
067: * They are reentrant.
068: *
069: * <p>
070: * All the marshal operation generates fragments.
071: *
072: * <p>
073: * <b>Subject to change without notice</b>.
074: *
075: * @since JAXB 2.0 EA1
076: * @author Kohsuke Kawaguchi
077: */
078: public abstract class Bridge<T> {
079: protected Bridge(JAXBContextImpl context) {
080: this .context = context;
081: }
082:
083: protected final JAXBContextImpl context;
084:
085: /**
086: * Gets the {@link JAXBRIContext} to which this object belongs.
087: *
088: * @since 2.1
089: */
090: public @NotNull
091: JAXBRIContext getContext() {
092: return context;
093: }
094:
095: /**
096: *
097: * @throws JAXBException
098: * if there was an error while marshalling.
099: *
100: * @since 2.0 EA1
101: */
102: public final void marshal(T object, XMLStreamWriter output)
103: throws JAXBException {
104: marshal(object, output, null);
105: }
106:
107: public final void marshal(T object, XMLStreamWriter output,
108: AttachmentMarshaller am) throws JAXBException {
109: Marshaller m = context.marshallerPool.take();
110: m.setAttachmentMarshaller(am);
111: marshal(m, object, output);
112: m.setAttachmentMarshaller(null);
113: context.marshallerPool.recycle(m);
114: }
115:
116: public final void marshal(@NotNull
117: BridgeContext context, T object, XMLStreamWriter output)
118: throws JAXBException {
119: marshal(((BridgeContextImpl) context).marshaller, object,
120: output);
121: }
122:
123: public abstract void marshal(@NotNull
124: Marshaller m, T object, XMLStreamWriter output)
125: throws JAXBException;
126:
127: /**
128: * Marshals the specified type object with the implicit element name
129: * associated with this instance of {@link Bridge}.
130: *
131: * @param nsContext
132: * if this marshalling is done to marshal a subelement, this {@link NamespaceContext}
133: * represents in-scope namespace bindings available for that element. Can be null,
134: * in which case JAXB assumes no in-scope namespaces.
135: * @throws JAXBException
136: * if there was an error while marshalling.
137: *
138: * @since 2.0 EA1
139: */
140: public void marshal(T object, OutputStream output,
141: NamespaceContext nsContext) throws JAXBException {
142: marshal(object, output, nsContext, null);
143: }
144:
145: /**
146: * @since 2.0.2
147: */
148: public void marshal(T object, OutputStream output,
149: NamespaceContext nsContext, AttachmentMarshaller am)
150: throws JAXBException {
151: Marshaller m = context.marshallerPool.take();
152: m.setAttachmentMarshaller(am);
153: marshal(m, object, output, nsContext);
154: m.setAttachmentMarshaller(null);
155: context.marshallerPool.recycle(m);
156: }
157:
158: public final void marshal(@NotNull
159: BridgeContext context, T object, OutputStream output,
160: NamespaceContext nsContext) throws JAXBException {
161: marshal(((BridgeContextImpl) context).marshaller, object,
162: output, nsContext);
163: }
164:
165: public abstract void marshal(@NotNull
166: Marshaller m, T object, OutputStream output,
167: NamespaceContext nsContext) throws JAXBException;
168:
169: public final void marshal(T object, Node output)
170: throws JAXBException {
171: Marshaller m = context.marshallerPool.take();
172: marshal(m, object, output);
173: context.marshallerPool.recycle(m);
174: }
175:
176: public final void marshal(@NotNull
177: BridgeContext context, T object, Node output) throws JAXBException {
178: marshal(((BridgeContextImpl) context).marshaller, object,
179: output);
180: }
181:
182: public abstract void marshal(@NotNull
183: Marshaller m, T object, Node output) throws JAXBException;
184:
185: /**
186: * @since 2.0 EA4
187: */
188: public final void marshal(T object, ContentHandler contentHandler)
189: throws JAXBException {
190: marshal(object, contentHandler, null);
191: }
192:
193: /**
194: * @since 2.0.2
195: */
196: public final void marshal(T object, ContentHandler contentHandler,
197: AttachmentMarshaller am) throws JAXBException {
198: Marshaller m = context.marshallerPool.take();
199: m.setAttachmentMarshaller(am);
200: marshal(m, object, contentHandler);
201: m.setAttachmentMarshaller(null);
202: context.marshallerPool.recycle(m);
203: }
204:
205: public final void marshal(@NotNull
206: BridgeContext context, T object, ContentHandler contentHandler)
207: throws JAXBException {
208: marshal(((BridgeContextImpl) context).marshaller, object,
209: contentHandler);
210: }
211:
212: public abstract void marshal(@NotNull
213: Marshaller m, T object, ContentHandler contentHandler)
214: throws JAXBException;
215:
216: /**
217: * @since 2.0 EA4
218: */
219: public final void marshal(T object, Result result)
220: throws JAXBException {
221: Marshaller m = context.marshallerPool.take();
222: marshal(m, object, result);
223: context.marshallerPool.recycle(m);
224: }
225:
226: public final void marshal(@NotNull
227: BridgeContext context, T object, Result result)
228: throws JAXBException {
229: marshal(((BridgeContextImpl) context).marshaller, object,
230: result);
231: }
232:
233: public abstract void marshal(@NotNull
234: Marshaller m, T object, Result result) throws JAXBException;
235:
236: private T exit(T r, Unmarshaller u) {
237: u.setAttachmentUnmarshaller(null);
238: context.unmarshallerPool.recycle(u);
239: return r;
240: }
241:
242: /**
243: * Unmarshals the specified type object.
244: *
245: * @param in
246: * the parser must be pointing at a start tag
247: * that encloses the XML type that this {@link Bridge} is
248: * instanciated for.
249: *
250: * @return
251: * never null.
252: *
253: * @throws JAXBException
254: * if there was an error while unmarshalling.
255: *
256: * @since 2.0 EA1
257: */
258: public final @NotNull
259: T unmarshal(@NotNull
260: XMLStreamReader in) throws JAXBException {
261: return unmarshal(in, null);
262: }
263:
264: /**
265: * @since 2.0.3
266: */
267: public final @NotNull
268: T unmarshal(@NotNull
269: XMLStreamReader in, @Nullable
270: AttachmentUnmarshaller au) throws JAXBException {
271: Unmarshaller u = context.unmarshallerPool.take();
272: u.setAttachmentUnmarshaller(au);
273: return exit(unmarshal(u, in), u);
274: }
275:
276: public final @NotNull
277: T unmarshal(@NotNull
278: BridgeContext context, @NotNull
279: XMLStreamReader in) throws JAXBException {
280: return unmarshal(((BridgeContextImpl) context).unmarshaller, in);
281: }
282:
283: public abstract @NotNull
284: T unmarshal(@NotNull
285: Unmarshaller u, @NotNull
286: XMLStreamReader in) throws JAXBException;
287:
288: /**
289: * Unmarshals the specified type object.
290: *
291: * @param in
292: * the parser must be pointing at a start tag
293: * that encloses the XML type that this {@link Bridge} is
294: * instanciated for.
295: *
296: * @return
297: * never null.
298: *
299: * @throws JAXBException
300: * if there was an error while unmarshalling.
301: *
302: * @since 2.0 EA1
303: */
304: public final @NotNull
305: T unmarshal(@NotNull
306: Source in) throws JAXBException {
307: return unmarshal(in, null);
308: }
309:
310: /**
311: * @since 2.0.3
312: */
313: public final @NotNull
314: T unmarshal(@NotNull
315: Source in, @Nullable
316: AttachmentUnmarshaller au) throws JAXBException {
317: Unmarshaller u = context.unmarshallerPool.take();
318: u.setAttachmentUnmarshaller(au);
319: return exit(unmarshal(u, in), u);
320: }
321:
322: public final @NotNull
323: T unmarshal(@NotNull
324: BridgeContext context, @NotNull
325: Source in) throws JAXBException {
326: return unmarshal(((BridgeContextImpl) context).unmarshaller, in);
327: }
328:
329: public abstract @NotNull
330: T unmarshal(@NotNull
331: Unmarshaller u, @NotNull
332: Source in) throws JAXBException;
333:
334: /**
335: * Unmarshals the specified type object.
336: *
337: * @param in
338: * the parser must be pointing at a start tag
339: * that encloses the XML type that this {@link Bridge} is
340: * instanciated for.
341: *
342: * @return
343: * never null.
344: *
345: * @throws JAXBException
346: * if there was an error while unmarshalling.
347: *
348: * @since 2.0 EA1
349: */
350: public final @NotNull
351: T unmarshal(@NotNull
352: InputStream in) throws JAXBException {
353: Unmarshaller u = context.unmarshallerPool.take();
354: return exit(unmarshal(u, in), u);
355: }
356:
357: public final @NotNull
358: T unmarshal(@NotNull
359: BridgeContext context, @NotNull
360: InputStream in) throws JAXBException {
361: return unmarshal(((BridgeContextImpl) context).unmarshaller, in);
362: }
363:
364: public abstract @NotNull
365: T unmarshal(@NotNull
366: Unmarshaller u, @NotNull
367: InputStream in) throws JAXBException;
368:
369: /**
370: * Unmarshals the specified type object.
371: *
372: * @param n
373: * Node to be unmarshalled.
374: *
375: * @return
376: * never null.
377: *
378: * @throws JAXBException
379: * if there was an error while unmarshalling.
380: *
381: * @since 2.0 FCS
382: */
383: public final @NotNull
384: T unmarshal(@NotNull
385: Node n) throws JAXBException {
386: return unmarshal(n, null);
387: }
388:
389: /**
390: * @since 2.0.3
391: */
392: public final @NotNull
393: T unmarshal(@NotNull
394: Node n, @Nullable
395: AttachmentUnmarshaller au) throws JAXBException {
396: Unmarshaller u = context.unmarshallerPool.take();
397: u.setAttachmentUnmarshaller(au);
398: return exit(unmarshal(u, n), u);
399: }
400:
401: public final @NotNull
402: T unmarshal(@NotNull
403: BridgeContext context, @NotNull
404: Node n) throws JAXBException {
405: return unmarshal(((BridgeContextImpl) context).unmarshaller, n);
406: }
407:
408: public abstract @NotNull
409: T unmarshal(@NotNull
410: Unmarshaller context, @NotNull
411: Node n) throws JAXBException;
412:
413: /**
414: * Gets the {@link TypeReference} from which this bridge was created.
415: */
416: public abstract TypeReference getTypeReference();
417: }
|