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.ws.spi.db; 27 28 import java.io.InputStream; 29 import java.io.OutputStream; 30 31 import javax.xml.bind.JAXBException; 32 import javax.xml.bind.attachment.AttachmentMarshaller; 33 import javax.xml.bind.attachment.AttachmentUnmarshaller; 34 import javax.xml.namespace.NamespaceContext; 35 import javax.xml.stream.XMLStreamReader; 36 import javax.xml.stream.XMLStreamWriter; 37 import javax.xml.transform.Result; 38 import javax.xml.transform.Source; 39 40 import com.sun.istack.internal.NotNull; 41 import com.sun.istack.internal.Nullable; 42 import org.w3c.dom.Node; 43 import org.xml.sax.ContentHandler; 44 45 /** 46 * The XMLBridge is a Glassfish JAXWS side of Glassfish JAXB Bridge. 47 * 48 * Mini-marshaller/unmarshaller that is specialized for a particular 49 * element name and a type. 50 * 51 * <p> 52 * Instances of this class is stateless and multi-thread safe. 53 * They are reentrant. 54 * 55 * <p> 56 * All the marshal operation generates fragments. 57 * 58 * <p> 59 * <b>Subject to change without notice</b>. 60 * 61 * @since JAXB 2.0 EA1 62 * @author Kohsuke Kawaguchi 63 * @author shih-chang.chen@oracle.com 64 */ 65 public interface XMLBridge<T> { 66 /** 67 * Gets the {@link BindingContext} to which this object belongs. 68 * 69 * @since 2.1 70 */ context()71 public @NotNull BindingContext context(); 72 73 /** 74 * 75 * @throws JAXBException 76 * if there was an error while marshalling. 77 * 78 * @since 2.0 EA1 79 */ 80 // public void marshal(T object,XMLStreamWriter output) throws JAXBException; 81 marshal(T object,XMLStreamWriter output, AttachmentMarshaller am)82 public void marshal(T object,XMLStreamWriter output, AttachmentMarshaller am) throws JAXBException; 83 84 /** 85 * Marshals the specified type object with the implicit element name 86 * associated with this instance of {@link Bond}. 87 * 88 * @param nsContext 89 * if this marshalling is done to marshal a subelement, this {@link NamespaceContext} 90 * represents in-scope namespace bindings available for that element. Can be null, 91 * in which case JAXB assumes no in-scope namespaces. 92 * @throws JAXBException 93 * if there was an error while marshalling. 94 * 95 * @since 2.0 EA1 96 */ 97 // public void marshal(T object,OutputStream output, NamespaceContext nsContext) throws JAXBException; 98 99 /** 100 * @since 2.0.2 101 */ marshal(T object,OutputStream output, NamespaceContext nsContext, AttachmentMarshaller am)102 public void marshal(T object,OutputStream output, NamespaceContext nsContext, AttachmentMarshaller am) throws JAXBException ; 103 // 104 //// public void marshal(@NotNull BridgeContext context,T object,OutputStream output, NamespaceContext nsContext) throws JAXBException; 105 // 106 // public void marshal(@NotNull Marshaller m,T object,OutputStream output, NamespaceContext nsContext) throws JAXBException; 107 108 marshal(T object,Node output)109 public void marshal(T object,Node output) throws JAXBException ; 110 // 111 //// public void marshal(@NotNull BridgeContext context,T object,Node output) throws JAXBException ; 112 // 113 // public void marshal(@NotNull Marshaller m,T object,Node output) throws JAXBException; 114 115 116 /** 117 * @since 2.0 EA4 118 */ 119 // public void marshal(T object, ContentHandler contentHandler) throws JAXBException; 120 /** 121 * @since 2.0.2 122 */ marshal(T object, ContentHandler contentHandler, AttachmentMarshaller am)123 public void marshal(T object, ContentHandler contentHandler, AttachmentMarshaller am) throws JAXBException ; 124 125 //// public void marshal(@NotNull BridgeContext context,T object, ContentHandler contentHandler) throws JAXBException; 126 // 127 // public void marshal(@NotNull Marshaller m,T object, ContentHandler contentHandler) throws JAXBException; 128 129 /** 130 * @since 2.0 EA4 131 */ marshal(T object, Result result)132 public void marshal(T object, Result result) throws JAXBException; 133 134 //// public void marshal(@NotNull BridgeContext context,T object, Result result) throws JAXBException; 135 // public void marshal(@NotNull Marshaller m,T object, Result result) throws JAXBException; 136 137 138 139 /** 140 * Unmarshals the specified type object. 141 * 142 * @param in 143 * the parser must be pointing at a start tag 144 * that encloses the XML type that this {@link Bond} is 145 * instanciated for. 146 * 147 * @return 148 * never null. 149 * 150 * @throws JAXBException 151 * if there was an error while unmarshalling. 152 * 153 * @since 2.0 EA1 154 */ 155 // public @NotNull T unmarshal(@NotNull XMLStreamReader in) throws JAXBException ; 156 /** 157 * @since 2.0.3 158 */ unmarshal(@otNull XMLStreamReader in, @Nullable AttachmentUnmarshaller au)159 public @NotNull T unmarshal(@NotNull XMLStreamReader in, @Nullable AttachmentUnmarshaller au) throws JAXBException; 160 // public @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull XMLStreamReader in) throws JAXBException ; 161 // public @NotNull T unmarshal(@NotNull Unmarshaller u, @NotNull XMLStreamReader in) throws JAXBException; 162 163 /** 164 * Unmarshals the specified type object. 165 * 166 * @param in 167 * the parser must be pointing at a start tag 168 * that encloses the XML type that this {@link Bond} is 169 * instanciated for. 170 * 171 * @return 172 * never null. 173 * 174 * @throws JAXBException 175 * if there was an error while unmarshalling. 176 * 177 * @since 2.0 EA1 178 */ 179 // public @NotNull T unmarshal(@NotNull Source in) throws JAXBException ; 180 /** 181 * @since 2.0.3 182 */ unmarshal(@otNull Source in, @Nullable AttachmentUnmarshaller au)183 public @NotNull T unmarshal(@NotNull Source in, @Nullable AttachmentUnmarshaller au) throws JAXBException; 184 // public @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull Source in) throws JAXBException; 185 // public @NotNull T unmarshal(@NotNull Unmarshaller u, @NotNull Source in) throws JAXBException; 186 187 /** 188 * Unmarshals the specified type object. 189 * 190 * @param in 191 * the parser must be pointing at a start tag 192 * that encloses the XML type that this {@link XMLBridge} is 193 * instanciated for. 194 * 195 * @return 196 * never null. 197 * 198 * @throws JAXBException 199 * if there was an error while unmarshalling. 200 * 201 * @since 2.0 EA1 202 */ unmarshal(@otNull InputStream in)203 public @NotNull T unmarshal(@NotNull InputStream in) throws JAXBException ; 204 205 // public @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull InputStream in) throws JAXBException ; 206 207 // public @NotNull T unmarshal(@NotNull Unmarshaller u, @NotNull InputStream in) throws JAXBException; 208 209 /** 210 * Unmarshals the specified type object. 211 * 212 * @param n 213 * Node to be unmarshalled. 214 * 215 * @return 216 * never null. 217 * 218 * @throws JAXBException 219 * if there was an error while unmarshalling. 220 * 221 * @since 2.0 FCS 222 */ 223 // public @NotNull T unmarshal(@NotNull Node n) throws JAXBException ; 224 /** 225 * @since 2.0.3 226 */ unmarshal(@otNull Node n, @Nullable AttachmentUnmarshaller au)227 public @NotNull T unmarshal(@NotNull Node n, @Nullable AttachmentUnmarshaller au) throws JAXBException; 228 // public @NotNull T unmarshal(@NotNull BridgeContext context, @NotNull Node n) throws JAXBException; 229 // public @NotNull T unmarshal(@NotNull Unmarshaller context, @NotNull Node n) throws JAXBException; 230 231 /** 232 * Gets the {@link TypeInfo} from which this bridge was created. 233 */ getTypeInfo()234 public TypeInfo getTypeInfo(); 235 236 /** 237 * This can be used to determine whether XMLStreamWriter or OutputStream is 238 * prefered by the implementation. 239 * 240 * @return true if marshall to OutputStream is supported in the 241 * implementation. 242 */ supportOutputStream()243 public boolean supportOutputStream(); 244 } 245