Thu, 31 Aug 2017 15:18:52 +0800
merge
1 /*
2 * Copyright (c) 1997, 2013, 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 */
26 package com.sun.xml.internal.ws.spi.db;
28 import java.io.IOException;
29 import java.util.Collection;
30 import java.util.List;
32 import javax.xml.bind.JAXBContext;
33 import javax.xml.bind.JAXBException;
34 import javax.xml.bind.Marshaller;
35 import javax.xml.bind.SchemaOutputResolver;
36 import javax.xml.bind.Unmarshaller;
37 import javax.xml.bind.annotation.XmlAttachmentRef;
38 import javax.xml.namespace.QName;
40 import com.sun.istack.internal.NotNull;
41 import com.sun.istack.internal.Nullable;
43 /**
44 * {@link JAXBContext} enhanced with JAXB RI specific functionalities.
45 *
46 * <p>
47 * <b>Subject to change without notice</b>.
48 *
49 * @since 2.0 EA1
50 * @author
51 * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
52 *
53 * @author shih-chang.chen@oracle.com
54 */
55 public interface BindingContext {
57 //following are found in JAXBContext used by jaxws
58 abstract public Marshaller createMarshaller() throws JAXBException;
59 abstract public Unmarshaller createUnmarshaller() throws JAXBException;
60 abstract public JAXBContext getJAXBContext();
61 abstract public Object newWrapperInstace(Class<?> wrapperType)
62 throws InstantiationException, IllegalAccessException;
68 /**
69 * Returns true if this context includes a class
70 * that has {@link XmlAttachmentRef}.
71 *
72 * @since 2.1
73 */
74 public abstract boolean hasSwaRef();
76 /**
77 * If the given object is bound to an element in XML by JAXB,
78 * returns the element name.
79 *
80 * @return null
81 * if the object is not bound to an element.
82 * @throws JAXBException
83 * if the object is not known to this context.
84 *
85 * @since 2.0 EA1
86 */
87 public abstract @Nullable QName getElementName(@NotNull Object o) throws JAXBException;
89 /**
90 * Allows to retrieve the element name based on Class.
91 * @param o
92 * @return
93 * @throws javax.xml.bind.JAXBException
94 * @since 2.1.10
95 */
96 public abstract @Nullable QName getElementName(@NotNull Class o) throws JAXBException;
98 /**
99 * Creates a mini-marshaller/unmarshaller that can process a {@link TypeInfo}.
100 *
101 * @return
102 * null if the specified reference is not given to {@link BindingContext#newWrapperInstace(Class)}.
103 *
104 * @since 2.0 EA1
105 */
106 public abstract XMLBridge createBridge(@NotNull TypeInfo ref);
107 public abstract XMLBridge createFragmentBridge();
109 /**
110 * Creates a new {@link BridgeContext} instance.
111 *
112 * @return
113 * always a valid non-null instance.
114 *
115 * @since 2.0 EA1
116 */
117 // public abstract @NotNull BridgeContext createBridgeContext();
119 /**
120 * Gets a {@link PropertyAccessor} for the specified element property of the specified wrapper bean class.
121 *
122 * <p>
123 * This method is designed to assist the JAX-RPC RI fill in a wrapper bean (in the doc/lit/wrap mode.)
124 * In the said mode, a wrapper bean is supposed to only have properties that match elements,
125 * and for each element that appear in the content model there's one property.
126 *
127 * <p>
128 * Therefore, this method takes a wrapper bean and a tag name that identifies a property
129 * on the given wrapper bean, then returns a {@link PropertyAccessor} that allows the caller
130 * to set/get a value from the property of the bean.
131 *
132 * <p>
133 * This method is not designed for a performance. The caller is expected to cache the result.
134 *
135 * @param <B>
136 * type of the wrapper bean
137 * @param <V>
138 * type of the property of the bean
139 * @return
140 * always return non-null valid accessor object.
141 * @throws JAXBException
142 * if the specified wrapper bean is not bound by JAXB, or if it doesn't have an element property
143 * of the given name.
144 *
145 * @since 2.0 EA1
146 */
147 public abstract <B,V> PropertyAccessor<B,V> getElementPropertyAccessor( Class<B> wrapperBean, String nsUri, String localName )
148 throws JAXBException;
150 /**
151 * Gets the namespace URIs statically known to this {@link JAXBContext}.
152 *
153 * <p>
154 * When JAXB is used to marshal into sub-trees, it declares
155 * these namespace URIs at each top-level element that it marshals.
156 *
157 * To avoid repeated namespace declarations at sub-elements, the application
158 * may declare those namespaces at a higher level.
159 *
160 * @return
161 * always non-null.
162 *
163 * @since 2.0 EA2
164 */
165 public abstract @NotNull List<String> getKnownNamespaceURIs();
168 /**
169 * Generates the schema documents from the model.
170 *
171 * <p>
172 * The caller can use the additionalElementDecls parameter to
173 * add element declarations to the generate schema.
174 * For example, if the JAX-RPC passes in the following entry:
175 *
176 * {foo}bar -> DeclaredType for java.lang.String
177 *
178 * then JAXB generates the following element declaration (in the schema
179 * document for the namespace "foo")"
180 *
181 * <xs:element name="bar" type="xs:string" />
182 *
183 * This can be used for generating schema components necessary for WSDL.
184 *
185 * @param outputResolver
186 * this object controls the output to which schemas
187 * will be sent.
188 *
189 * @throws IOException
190 * if {@link SchemaOutputResolver} throws an {@link IOException}.
191 */
192 public abstract void generateSchema(@NotNull SchemaOutputResolver outputResolver) throws IOException;
194 /**
195 * Returns the name of the XML Type bound to the
196 * specified Java type.
197 *
198 * @param tr
199 * must not be null. This must be one of the {@link TypeInfo}s specified
200 * in the {@link BindingContext#newInstance} method.
201 *
202 * @throws IllegalArgumentException
203 * if the parameter is null or not a part of the {@link TypeInfo}s specified
204 * in the {@link BindingContext#newWrapperInstace(Class)} method.
205 *
206 * @return null
207 * if the referenced type is an anonymous and therefore doesn't have a name.
208 */
209 public abstract QName getTypeName(@NotNull TypeInfo tr);
211 /**
212 * Gets the build information of the JAXB runtime.
213 *
214 * @return
215 * may be null, if the runtime is loaded by a class loader that doesn't support
216 * the access to the manifest informatino.
217 */
218 public abstract @NotNull String getBuildId();
220 /**
221 * The property that you can specify to {@link JAXBContext#newInstance}
222 * to reassign the default namespace URI to something else at the runtime.
223 *
224 * <p>
225 * The value of the property is {@link String}, and it is used as the namespace URI
226 * that succeeds the default namespace URI.
227 *
228 * @since 2.0 EA1
229 */
230 public static final String DEFAULT_NAMESPACE_REMAP = "com.sun.xml.internal.bind.defaultNamespaceRemap";
232 /**
233 * The property that you can specify to {@link JAXBContext#newInstance}
234 * to put additional JAXB type references into the {@link JAXBContext}.
235 *
236 * <p>
237 * The value of the property is {@link Collection}<{@link TypeInfo}>.
238 * Those {@link TypeInfo}s can then be used to create {@link XMLBridge}s.
239 *
240 * <p>
241 * This mechanism allows additional element declarations that were not a part of
242 * the schema into the created {@link JAXBContext}.
243 *
244 * @since 2.0 EA1
245 */
246 public static final String TYPE_REFERENCES = "com.sun.xml.internal.bind.typeReferences";
248 /**
249 * The property that you can specify to {@link JAXBContext#newInstance}
250 * and {@link Marshaller#setProperty(String, Object)}
251 * to enable the c14n marshalling support in the {@link JAXBContext}.
252 *
253 * @see C14nSupport_ArchitectureDocument
254 * @since 2.0 EA2
255 */
256 public static final String CANONICALIZATION_SUPPORT = "com.sun.xml.internal.bind.c14n";
258 /**
259 * The property that you can specify to {@link JAXBContext#newInstance}
260 * to allow unmarshaller to honor <tt>xsi:nil</tt> anywhere, even if they are
261 * not specifically allowed by the schema.
262 *
263 * @since 2.1.3
264 */
265 public static final String TREAT_EVERYTHING_NILLABLE = "com.sun.xml.internal.bind.treatEverythingNillable";
267 /**
268 * The property that you can specify to {@link JAXBContext#newInstance}
269 * to use alternative {@link RuntimeAnnotationReader} implementation.
270 *
271 * @since 2.1 EA2
272 */
273 // public static final String ANNOTATION_READER = RuntimeAnnotationReader.class.getName();
275 /**
276 * Marshaller/Unmarshaller property to enable XOP processing.
277 *
278 * @since 2.0 EA2
279 */
280 public static final String ENABLE_XOP = "com.sun.xml.internal.bind.XOP";
282 /**
283 * The property that you can specify to {@link JAXBContext#newInstance}
284 * to specify specific classes that replace the reference to generic classes.
285 *
286 * <p>
287 * See the release notes for more details about this feature.
288 *
289 * @since 2.1 EA2
290 */
291 public static final String SUBCLASS_REPLACEMENTS = "com.sun.xml.internal.bind.subclassReplacements";
293 /**
294 * The property that you can specify to {@link JAXBContext#newInstance}
295 * enable support of XmlAccessorFactory annotation in the {@link JAXBContext}.
296 *
297 * @since 2.1 EA2
298 */
299 public static final String XMLACCESSORFACTORY_SUPPORT = "com.sun.xml.internal.bind.XmlAccessorFactory";
301 /**
302 * Retains references to PropertyInfos.
303 *
304 * @since 2.1.10
305 */
306 public static final String RETAIN_REFERENCE_TO_INFO = "retainReferenceToInfo";
308 }