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 
  26 package com.sun.xml.internal.bind.api;
  27 
  28 import java.io.InputStream;
  29 import java.io.OutputStream;
  30 
  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;
  41 
  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;
  46 
  47 import org.w3c.dom.Node;
  48 import 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  */
  67 public 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 }