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