Fri, 24 Oct 2014 15:02:28 +0200
8054367: More references for endpoints
Summary: fix also reviewed by Iaroslav.Savytskyi@oracle.com, Alexander.Fomin@oracle.com
Reviewed-by: mullan, skoivu
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 */
26 package com.sun.xml.internal.bind.api;
28 import java.io.IOException;
29 import java.lang.reflect.Type;
30 import java.util.Collection;
31 import java.util.Collections;
32 import java.util.List;
33 import java.util.Map;
35 import javax.xml.bind.JAXBContext;
36 import javax.xml.bind.JAXBException;
37 import javax.xml.bind.Marshaller;
38 import javax.xml.bind.SchemaOutputResolver;
39 import javax.xml.bind.annotation.XmlAttachmentRef;
40 import javax.xml.namespace.QName;
41 import javax.xml.transform.Result;
43 import com.sun.istack.internal.NotNull;
44 import com.sun.istack.internal.Nullable;
45 import com.sun.xml.internal.bind.api.impl.NameConverter;
46 import com.sun.xml.internal.bind.v2.ContextFactory;
47 import com.sun.xml.internal.bind.v2.model.annotation.RuntimeAnnotationReader;
48 import com.sun.xml.internal.bind.v2.model.runtime.RuntimeTypeInfoSet;
49 import java.util.HashMap;
51 /**
52 * {@link JAXBContext} enhanced with JAXB RI specific functionalities.
53 *
54 * <p>
55 * <b>Subject to change without notice</b>.
56 *
57 * @since 2.0 EA1
58 * @author
59 * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
60 */
61 public abstract class JAXBRIContext extends JAXBContext {
63 protected JAXBRIContext() {}
65 /**
66 * Creates a new {@link JAXBRIContext}.
67 *
68 * <p>
69 * {@link JAXBContext#newInstance(Class[]) JAXBContext.newInstance()} methods may
70 * return other JAXB providers that are not compatible with the JAX-RPC RI.
71 * This method guarantees that the JAX-WS RI will finds the JAXB RI.
72 *
73 * @param classes
74 * Classes to be bound. See {@link JAXBContext#newInstance(Class[])} for the meaning.
75 * @param typeRefs
76 * See {@link #TYPE_REFERENCES} for the meaning of this parameter.
77 * Can be null.
78 * @param subclassReplacements
79 * See {@link #SUBCLASS_REPLACEMENTS} for the meaning of this parameter.
80 * Can be null.
81 * @param defaultNamespaceRemap
82 * See {@link #DEFAULT_NAMESPACE_REMAP} for the meaning of this parameter.
83 * Can be null (and should be null for ordinary use of JAXB.)
84 * @param c14nSupport
85 * See {@link #CANONICALIZATION_SUPPORT} for the meaning of this parameter.
86 * @param ar
87 * See {@link #ANNOTATION_READER} for the meaning of this parameter.
88 * Can be null.
89 * @since JAXB 2.1 EA2
90 */
91 public static JAXBRIContext newInstance(@NotNull Class[] classes,
92 @Nullable Collection<TypeReference> typeRefs,
93 @Nullable Map<Class,Class> subclassReplacements,
94 @Nullable String defaultNamespaceRemap, boolean c14nSupport,
95 @Nullable RuntimeAnnotationReader ar) throws JAXBException {
96 return newInstance(classes, typeRefs, subclassReplacements,
97 defaultNamespaceRemap, c14nSupport, ar, false, false, false, false);
98 }
100 /**
101 * Creates a new {@link JAXBRIContext}.
102 *
103 * <p>
104 * {@link JAXBContext#newInstance(Class[]) JAXBContext.newInstance()} methods may
105 * return other JAXB providers that are not compatible with the JAX-RPC RI.
106 * This method guarantees that the JAX-WS RI will finds the JAXB RI.
107 *
108 * @param classes
109 * Classes to be bound. See {@link JAXBContext#newInstance(Class[])} for the meaning.
110 * @param typeRefs
111 * See {@link #TYPE_REFERENCES} for the meaning of this parameter.
112 * Can be null.
113 * @param subclassReplacements
114 * See {@link #SUBCLASS_REPLACEMENTS} for the meaning of this parameter.
115 * Can be null.
116 * @param defaultNamespaceRemap
117 * See {@link #DEFAULT_NAMESPACE_REMAP} for the meaning of this parameter.
118 * Can be null (and should be null for ordinary use of JAXB.)
119 * @param c14nSupport
120 * See {@link #CANONICALIZATION_SUPPORT} for the meaning of this parameter.
121 * @param ar
122 * See {@link #ANNOTATION_READER} for the meaning of this parameter.
123 * Can be null.
124 * @param xmlAccessorFactorySupport
125 * See {@link #XMLACCESSORFACTORY_SUPPORT} for the meaning of this parameter.
126 * @param allNillable
127 * See {@link #TREAT_EVERYTHING_NILLABLE} for the meaning of this parameter.
128 * @param retainPropertyInfo
129 * See {@link #RETAIN_REFERENCE_TO_INFO} for the meaning of this parameter.
130 * @param supressAccessorWarnings
131 * See {@link #SUPRESS_ACCESSOR_WARNINGS} for the meaning of this parameter.
132 */
133 public static JAXBRIContext newInstance(@NotNull Class[] classes,
134 @Nullable Collection<TypeReference> typeRefs,
135 @Nullable Map<Class,Class> subclassReplacements,
136 @Nullable String defaultNamespaceRemap, boolean c14nSupport,
137 @Nullable RuntimeAnnotationReader ar,
138 boolean xmlAccessorFactorySupport,
139 boolean allNillable,
140 boolean retainPropertyInfo,
141 boolean supressAccessorWarnings) throws JAXBException {
142 Map<String, Object> properties = new HashMap<String, Object>();
143 if (typeRefs != null) properties.put(JAXBRIContext.TYPE_REFERENCES, typeRefs);
144 if (subclassReplacements != null) properties.put(JAXBRIContext.SUBCLASS_REPLACEMENTS, subclassReplacements);
145 if (defaultNamespaceRemap != null) properties.put(JAXBRIContext.DEFAULT_NAMESPACE_REMAP, defaultNamespaceRemap);
146 if (ar != null) properties.put(JAXBRIContext.ANNOTATION_READER, ar);
147 properties.put(JAXBRIContext.CANONICALIZATION_SUPPORT, Boolean.valueOf(c14nSupport));
148 properties.put(JAXBRIContext.XMLACCESSORFACTORY_SUPPORT, Boolean.valueOf(xmlAccessorFactorySupport));
149 properties.put(JAXBRIContext.TREAT_EVERYTHING_NILLABLE, Boolean.valueOf(allNillable));
150 properties.put(JAXBRIContext.RETAIN_REFERENCE_TO_INFO, Boolean.valueOf(retainPropertyInfo));
151 properties.put(JAXBRIContext.SUPRESS_ACCESSOR_WARNINGS, Boolean.valueOf(supressAccessorWarnings));
152 return (JAXBRIContext) ContextFactory.createContext(classes, properties);
153 }
155 /**
156 * @deprecated
157 * Compatibility with older versions.
158 */
159 public static JAXBRIContext newInstance(@NotNull Class[] classes,
160 @Nullable Collection<TypeReference> typeRefs,
161 @Nullable String defaultNamespaceRemap, boolean c14nSupport ) throws JAXBException {
162 return newInstance(classes,typeRefs, Collections.<Class,Class>emptyMap(),
163 defaultNamespaceRemap,c14nSupport,null);
164 }
166 /**
167 * Returns true if this context includes a class
168 * that has {@link XmlAttachmentRef}.
169 *
170 * @since 2.1
171 */
172 public abstract boolean hasSwaRef();
174 /**
175 * If the given object is bound to an element in XML by JAXB,
176 * returns the element name.
177 *
178 * @return null
179 * if the object is not bound to an element.
180 * @throws JAXBException
181 * if the object is not known to this context.
182 *
183 * @since 2.0 EA1
184 */
185 public abstract @Nullable QName getElementName(@NotNull Object o) throws JAXBException;
187 /**
188 * Allows to retrieve the element name based on Class.
189 * @param o
190 * @return
191 * @throws javax.xml.bind.JAXBException
192 * @since 2.1.10
193 */
194 public abstract @Nullable QName getElementName(@NotNull Class o) throws JAXBException;
196 /**
197 * Creates a mini-marshaller/unmarshaller that can process a {@link TypeReference}.
198 *
199 * @return
200 * null if the specified reference is not given to {@link JAXBRIContext#newInstance}.
201 *
202 * @since 2.0 EA1
203 */
204 public abstract Bridge createBridge(@NotNull TypeReference ref);
206 /**
207 * Creates a new {@link BridgeContext} instance.
208 *
209 * @return
210 * always a valid non-null instance.
211 *
212 * @since 2.0 EA1
213 */
214 public abstract @NotNull BridgeContext createBridgeContext();
216 /**
217 * Gets a {@link RawAccessor} for the specified element property of the specified wrapper bean class.
218 *
219 * <p>
220 * This method is designed to assist the JAX-RPC RI fill in a wrapper bean (in the doc/lit/wrap mode.)
221 * In the said mode, a wrapper bean is supposed to only have properties that match elements,
222 * and for each element that appear in the content model there's one property.
223 *
224 * <p>
225 * Therefore, this method takes a wrapper bean and a tag name that identifies a property
226 * on the given wrapper bean, then returns a {@link RawAccessor} that allows the caller
227 * to set/get a value from the property of the bean.
228 *
229 * <p>
230 * This method is not designed for a performance. The caller is expected to cache the result.
231 *
232 * @param <B>
233 * type of the wrapper bean
234 * @param <V>
235 * type of the property of the bean
236 * @return
237 * always return non-null valid accessor object.
238 * @throws JAXBException
239 * if the specified wrapper bean is not bound by JAXB, or if it doesn't have an element property
240 * of the given name.
241 *
242 * @since 2.0 EA1
243 */
244 public abstract <B,V> RawAccessor<B,V> getElementPropertyAccessor( Class<B> wrapperBean, String nsUri, String localName )
245 throws JAXBException;
247 /**
248 * Gets the namespace URIs statically known to this {@link JAXBContext}.
249 *
250 * <p>
251 * When JAXB is used to marshal into sub-trees, it declares
252 * these namespace URIs at each top-level element that it marshals.
253 *
254 * To avoid repeated namespace declarations at sub-elements, the application
255 * may declare those namespaces at a higher level.
256 *
257 * @return
258 * always non-null.
259 *
260 * @since 2.0 EA2
261 */
262 public abstract @NotNull List<String> getKnownNamespaceURIs();
265 /**
266 * Generates the schema documents from the model.
267 *
268 * <p>
269 * The caller can use the additionalElementDecls parameter to
270 * add element declarations to the generate schema.
271 * For example, if the JAX-RPC passes in the following entry:
272 *
273 * {foo}bar -> DeclaredType for java.lang.String
274 *
275 * then JAXB generates the following element declaration (in the schema
276 * document for the namespace "foo")"
277 *
278 * <xs:element name="bar" type="xs:string" />
279 *
280 * This can be used for generating schema components necessary for WSDL.
281 *
282 * @param outputResolver
283 * this object controls the output to which schemas
284 * will be sent.
285 *
286 * @throws IOException
287 * if {@link SchemaOutputResolver} throws an {@link IOException}.
288 */
289 @Override
290 public abstract void generateSchema(@NotNull SchemaOutputResolver outputResolver) throws IOException;
292 /**
293 * Returns the name of the XML Type bound to the
294 * specified Java type.
295 *
296 * @param tr
297 * must not be null. This must be one of the {@link TypeReference}s specified
298 * in the {@link JAXBRIContext#newInstance} method.
299 *
300 * @throws IllegalArgumentException
301 * if the parameter is null or not a part of the {@link TypeReference}s specified
302 * in the {@link JAXBRIContext#newInstance} method.
303 *
304 * @return null
305 * if the referenced type is an anonymous and therefore doesn't have a name.
306 */
307 public abstract QName getTypeName(@NotNull TypeReference tr);
309 /**
310 * Gets the build information of the JAXB runtime.
311 *
312 * @return
313 * may be null, if the runtime is loaded by a class loader that doesn't support
314 * the access to the manifest informatino.
315 */
316 public abstract @NotNull String getBuildId();
318 /**
319 * Generates the episode file that represents the binding known to this {@link JAXBContext},
320 * so that XJC can later do separate compilation.
321 *
322 * <p>
323 * Episode file is really just a JAXB customization file, except that currently
324 * we use the RI-specific SCD to refer to schema components.
325 *
326 * @param output
327 * This receives the generated episode file.
328 *
329 * @since 2.1
330 */
331 public abstract void generateEpisode(Result output);
333 /**
334 * Allows you to access the runtime model information of the JAXB XML/Java binding.
335 *
336 * <p>
337 * This is useful for doing a deeper integration with the JAXB RI.
338 * For more information about the model, see https://jaxb2-reflection.dev.java.net/
339 *
340 * @since 2.1.10
341 */
342 public abstract RuntimeTypeInfoSet getRuntimeTypeInfoSet();
344 /**
345 * Computes a Java identifier from a local name.
346 *
347 * <p>
348 * This method faithfully implements the name mangling rule as specified in the JAXB spec.
349 *
350 * <p>
351 * In JAXB, a collision with a Java reserved word (such as "return") never happens.
352 * Accordingly, this method may return an identifier that collides with reserved words.
353 *
354 * <p>
355 * Use <tt>JJavaName.isJavaIdentifier(String)</tt> to check for such collision.
356 *
357 * @return
358 * Typically, this method returns "nameLikeThis".
359 */
360 public static @NotNull String mangleNameToVariableName(@NotNull String localName) {
361 return NameConverter.standard.toVariableName(localName);
362 }
364 /**
365 * Computes a Java class name from a local name.
366 *
367 * <p>
368 * This method faithfully implements the name mangling rule as specified in the JAXB spec.
369 *
370 * @return
371 * Typically, this method returns "NameLikeThis".
372 */
373 public static @NotNull String mangleNameToClassName(@NotNull String localName) {
374 return NameConverter.standard.toClassName(localName);
375 }
377 /**
378 * Computes a Java class name from a local name.
379 *
380 * <p>
381 * This method faithfully implements the name mangling rule as specified in the JAXB spec.
382 * This method works like {@link #mangleNameToClassName(String)} except that it looks
383 * for "getClass" and returns something else.
384 *
385 * @return
386 * Typically, this method returns "NameLikeThis".
387 */
388 public static @NotNull String mangleNameToPropertyName(@NotNull String localName) {
389 return NameConverter.standard.toPropertyName(localName);
390 }
392 /**
393 * Gets the parameterization of the given base type.
394 *
395 * <p>
396 * For example, given the following
397 * <pre><xmp>
398 * interface Foo<T> extends List<List<T>> {}
399 * interface Bar extends Foo<String> {}
400 * </xmp></pre>
401 * This method works like this:
402 * <pre><xmp>
403 * getBaseClass( Bar, List ) = List<List<String>
404 * getBaseClass( Bar, Foo ) = Foo<String>
405 * getBaseClass( Foo<? extends Number>, Collection ) = Collection<List<? extends Number>>
406 * getBaseClass( ArrayList<? extends BigInteger>, List ) = List<? extends BigInteger>
407 * </xmp></pre>
408 *
409 * @param type
410 * The type that derives from {@code baseType}
411 * @param baseType
412 * The class whose parameterization we are interested in.
413 * @return
414 * The use of {@code baseType} in {@code type}.
415 * or null if the type is not assignable to the base type.
416 * @since 2.0 FCS
417 */
418 public static @Nullable Type getBaseType(@NotNull Type type, @NotNull Class baseType) {
419 return Utils.REFLECTION_NAVIGATOR.getBaseClass(type, baseType);
420 }
422 /**
423 * The property that you can specify to {@link JAXBContext#newInstance}
424 * to reassign the default namespace URI to something else at the runtime.
425 *
426 * <p>
427 * The value of the property is {@link String}, and it is used as the namespace URI
428 * that succeeds the default namespace URI.
429 *
430 * @since 2.0 EA1
431 */
432 public static final String DEFAULT_NAMESPACE_REMAP = "com.sun.xml.internal.bind.defaultNamespaceRemap";
434 /**
435 * The property that you can specify to {@link JAXBContext#newInstance}
436 * to put additional JAXB type references into the {@link JAXBContext}.
437 *
438 * <p>
439 * The value of the property is {@link Collection}<{@link TypeReference}>.
440 * Those {@link TypeReference}s can then be used to create {@link Bridge}s.
441 *
442 * <p>
443 * This mechanism allows additional element declarations that were not a part of
444 * the schema into the created {@link JAXBContext}.
445 *
446 * @since 2.0 EA1
447 */
448 public static final String TYPE_REFERENCES = "com.sun.xml.internal.bind.typeReferences";
450 /**
451 * The property that you can specify to {@link JAXBContext#newInstance}
452 * and {@link Marshaller#setProperty(String, Object)}
453 * to enable the c14n marshalling support in the {@link JAXBContext}.
454 *
455 * Boolean
456 * @see C14nSupport_ArchitectureDocument
457 * @since 2.0 EA2
458 */
459 public static final String CANONICALIZATION_SUPPORT = "com.sun.xml.internal.bind.c14n";
461 /**
462 * The property that you can specify to {@link JAXBContext#newInstance}
463 * to allow unmarshaller to honor <tt>xsi:nil</tt> anywhere, even if they are
464 * not specifically allowed by the schema.
465 *
466 * Boolean
467 * @since 2.1.3
468 */
469 public static final String TREAT_EVERYTHING_NILLABLE = "com.sun.xml.internal.bind.treatEverythingNillable";
471 /**
472 * The property that you can specify to {@link JAXBContext#newInstance}
473 * to use alternative {@link RuntimeAnnotationReader} implementation.
474 *
475 * @since 2.1 EA2
476 */
477 public static final String ANNOTATION_READER = RuntimeAnnotationReader.class.getName();
479 /**
480 * Marshaller/Unmarshaller property to enable XOP processing.
481 *
482 * @since 2.0 EA2
483 */
484 public static final String ENABLE_XOP = "com.sun.xml.internal.bind.XOP";
486 /**
487 * The property that you can specify to {@link JAXBContext#newInstance}
488 * to specify specific classes that replace the reference to generic classes.
489 *
490 * <p>
491 * See the release notes for more details about this feature.
492 *
493 * @since 2.1 EA2
494 */
495 public static final String SUBCLASS_REPLACEMENTS = "com.sun.xml.internal.bind.subclassReplacements";
497 /**
498 * The property that you can specify to {@link JAXBContext#newInstance}
499 * enable support of XmlAccessorFactory annotation in the {@link JAXBContext}.
500 *
501 * @since 2.1 EA2
502 */
503 public static final String XMLACCESSORFACTORY_SUPPORT = "com.sun.xml.internal.bind.XmlAccessorFactory";
505 /**
506 * Retains references to PropertyInfos.
507 *
508 * Boolean
509 * @since 2.1.10
510 */
511 public static final String RETAIN_REFERENCE_TO_INFO = "retainReferenceToInfo";
513 /**
514 * Supress security warnings when trying to access fields through reflection.
515 *
516 * Boolean
517 * @since 2.1.14, 2.2.2
518 */
519 public static final String SUPRESS_ACCESSOR_WARNINGS = "supressAccessorWarnings";
521 /**
522 * Improves handling of xsi:type used on leaf properties.
523 *
524 * Boolean
525 * @since 2.2.3
526 */
527 public static final String IMPROVED_XSI_TYPE_HANDLING = "com.sun.xml.internal.bind.improvedXsiTypeHandling";
529 /**
530 * If true XML security features when parsing XML documents will be disabled.
531 * The default value is false.
532 *
533 * Boolean
534 * @since 2.2.6
535 */
536 public static final String DISABLE_XML_SECURITY = "com.sun.xml.internal.bind.disableXmlSecurity";
537 }