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