View Javadoc
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       */
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  
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      */
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 
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      */
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      */
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      */
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      */
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      */
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      */
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      */
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      */
243     public boolean supportOutputStream();
244 }