All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.glassfish.jaxb.runtime.api.JAXBRIContext Maven / Gradle / Ivy

There is a newer version: 4.0.5
Show newest version
/*
 * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0, which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package org.glassfish.jaxb.runtime.api;

import com.sun.istack.NotNull;
import com.sun.istack.Nullable;
import org.glassfish.jaxb.core.api.impl.NameConverter;
import org.glassfish.jaxb.runtime.v2.ContextFactory;
import org.glassfish.jaxb.runtime.v2.model.annotation.RuntimeAnnotationReader;
import org.glassfish.jaxb.runtime.v2.model.runtime.RuntimeTypeInfoSet;
import jakarta.xml.bind.JAXBContext;
import jakarta.xml.bind.JAXBException;
import jakarta.xml.bind.Marshaller;
import jakarta.xml.bind.SchemaOutputResolver;
import jakarta.xml.bind.annotation.XmlAttachmentRef;

import javax.xml.namespace.QName;
import javax.xml.transform.Result;
import java.io.IOException;
import java.lang.reflect.Type;
import java.util.*;

/**
 * {@link JAXBContext} enhanced with JAXB RI specific functionalities.
 *
 * 

* Subject to change without notice. * * @since 2.0 EA1 * @author * Kohsuke Kawaguchi ([email protected]) */ public abstract class JAXBRIContext extends JAXBContext { protected JAXBRIContext() {} /** * Creates a new . * *

* {@link JAXBContext#newInstance(Class[]) JAXBContext.newInstance()} methods may * return other JAXB providers that are not compatible with the JAX-RPC RI. * This method guarantees that the JAX-WS RI will finds the JAXB RI. * * @param classes * Classes to be bound. See {@link JAXBContext#newInstance(Class[])} for the meaning. * @param typeRefs * See {@link #TYPE_REFERENCES} for the meaning of this parameter. * Can be null. * @param subclassReplacements * See {@link #SUBCLASS_REPLACEMENTS} for the meaning of this parameter. * Can be null. * @param defaultNamespaceRemap * See {@link #DEFAULT_NAMESPACE_REMAP} for the meaning of this parameter. * Can be null (and should be null for ordinary use of JAXB.) * @param c14nSupport * See {@link #CANONICALIZATION_SUPPORT} for the meaning of this parameter. * @param ar * See {@link #ANNOTATION_READER} for the meaning of this parameter. * Can be null. * @since JAXB 2.1 EA2 */ public static JAXBRIContext newInstance(@NotNull Class[] classes, @Nullable Collection typeRefs, @Nullable Map subclassReplacements, @Nullable String defaultNamespaceRemap, boolean c14nSupport, @Nullable RuntimeAnnotationReader ar) throws JAXBException { return newInstance(classes, typeRefs, subclassReplacements, defaultNamespaceRemap, c14nSupport, ar, false, false, false, false); } /** * Creates a new . * *

* {@link JAXBContext#newInstance(Class[]) JAXBContext.newInstance()} methods may * return other JAXB providers that are not compatible with the JAX-RPC RI. * This method guarantees that the JAX-WS RI will finds the JAXB RI. * * @param classes * Classes to be bound. See {@link JAXBContext#newInstance(Class[])} for the meaning. * @param typeRefs * See {@link #TYPE_REFERENCES} for the meaning of this parameter. * Can be null. * @param subclassReplacements * See {@link #SUBCLASS_REPLACEMENTS} for the meaning of this parameter. * Can be null. * @param defaultNamespaceRemap * See {@link #DEFAULT_NAMESPACE_REMAP} for the meaning of this parameter. * Can be null (and should be null for ordinary use of JAXB.) * @param c14nSupport * See {@link #CANONICALIZATION_SUPPORT} for the meaning of this parameter. * @param ar * See {@link #ANNOTATION_READER} for the meaning of this parameter. * Can be null. * @param xmlAccessorFactorySupport * See {@link #XMLACCESSORFACTORY_SUPPORT} for the meaning of this parameter. * @param allNillable * See {@link #TREAT_EVERYTHING_NILLABLE} for the meaning of this parameter. * @param retainPropertyInfo * See {@link #RETAIN_REFERENCE_TO_INFO} for the meaning of this parameter. * @param supressAccessorWarnings * See {@link #SUPRESS_ACCESSOR_WARNINGS} for the meaning of this parameter. */ public static JAXBRIContext newInstance(@NotNull Class[] classes, @Nullable Collection typeRefs, @Nullable Map subclassReplacements, @Nullable String defaultNamespaceRemap, boolean c14nSupport, @Nullable RuntimeAnnotationReader ar, boolean xmlAccessorFactorySupport, boolean allNillable, boolean retainPropertyInfo, boolean supressAccessorWarnings) throws JAXBException { Map properties = new HashMap<>(); if (typeRefs != null) properties.put(JAXBRIContext.TYPE_REFERENCES, typeRefs); if (subclassReplacements != null) properties.put(JAXBRIContext.SUBCLASS_REPLACEMENTS, subclassReplacements); if (defaultNamespaceRemap != null) properties.put(JAXBRIContext.DEFAULT_NAMESPACE_REMAP, defaultNamespaceRemap); if (ar != null) properties.put(JAXBRIContext.ANNOTATION_READER, ar); properties.put(JAXBRIContext.CANONICALIZATION_SUPPORT, c14nSupport); properties.put(JAXBRIContext.XMLACCESSORFACTORY_SUPPORT, xmlAccessorFactorySupport); properties.put(JAXBRIContext.TREAT_EVERYTHING_NILLABLE, allNillable); properties.put(JAXBRIContext.RETAIN_REFERENCE_TO_INFO, retainPropertyInfo); properties.put(JAXBRIContext.SUPRESS_ACCESSOR_WARNINGS, supressAccessorWarnings); return (JAXBRIContext) ContextFactory.createContext(classes, properties); } /** * Returns true if this context includes a class * that has {@link XmlAttachmentRef}. * * @since 2.1 */ public abstract boolean hasSwaRef(); /** * If the given object is bound to an element in XML by JAXB, * returns the element name. * * @return null * if the object is not bound to an element. * @throws JAXBException * if the object is not known to this context. * * @since 2.0 EA1 */ public abstract @Nullable QName getElementName(@NotNull Object o) throws JAXBException; /** * Allows to retrieve the element name based on Class. * @since 2.1.10 */ public abstract @Nullable QName getElementName(@NotNull Class o) throws JAXBException; /** * Creates a mini-marshaller/unmarshaller that can process a {@link TypeReference}. * * @return * null if the specified reference is not given to {@link JAXBRIContext#newInstance}. * * @since 2.0 EA1 */ public abstract Bridge createBridge(@NotNull TypeReference ref); /** * Gets a {@link RawAccessor} for the specified element property of the specified wrapper bean class. * *

* This method is designed to assist the JAX-RPC RI fill in a wrapper bean (in the doc/lit/wrap mode.) * In the said mode, a wrapper bean is supposed to only have properties that match elements, * and for each element that appear in the content model there's one property. * *

* Therefore, this method takes a wrapper bean and a tag name that identifies a property * on the given wrapper bean, then returns a {@link RawAccessor} that allows the caller * to set/get a value from the property of the bean. * *

* This method is not designed for a performance. The caller is expected to cache the result. * * @param * type of the wrapper bean * @param * type of the property of the bean * @return * always return non-null valid accessor object. * @throws JAXBException * if the specified wrapper bean is not bound by JAXB, or if it doesn't have an element property * of the given name. * * @since 2.0 EA1 */ public abstract RawAccessor getElementPropertyAccessor( Class wrapperBean, String nsUri, String localName ) throws JAXBException; /** * Gets the namespace URIs statically known to this {@link JAXBContext}. * *

* When JAXB is used to marshal into sub-trees, it declares * these namespace URIs at each top-level element that it marshals. * * To avoid repeated namespace declarations at sub-elements, the application * may declare those namespaces at a higher level. * * @return * always non-null. * * @since 2.0 EA2 */ public abstract @NotNull List getKnownNamespaceURIs(); /** * Generates the schema documents from the model. * *

* The caller can use the additionalElementDecls parameter to * add element declarations to the generate schema. * For example, if the JAX-RPC passes in the following entry: * * {@code {foo}bar -> DeclaredType for java.lang.String} * * then JAXB generates the following element declaration (in the schema * document for the namespace "foo")" * * {@code } * * This can be used for generating schema components necessary for WSDL. * * @param outputResolver * this object controls the output to which schemas * will be sent. * * @throws IOException * if {@link SchemaOutputResolver} throws an {@link IOException}. */ @Override public abstract void generateSchema(@NotNull SchemaOutputResolver outputResolver) throws IOException; /** * Returns the name of the XML Type bound to the * specified Java type. * * @param tr * must not be null. This must be one of the {@link TypeReference}s specified * in the {@link JAXBRIContext#newInstance} method. * * @throws IllegalArgumentException * if the parameter is null or not a part of the {@link TypeReference}s specified * in the {@link JAXBRIContext#newInstance} method. * * @return null * if the referenced type is an anonymous and therefore doesn't have a name. */ public abstract QName getTypeName(@NotNull TypeReference tr); /** * Gets the build information of the JAXB runtime. * * @return * may be null, if the runtime is loaded by a class loader that doesn't support * the access to the manifest informatino. */ public abstract @NotNull String getBuildId(); /** * Generates the episode file that represents the binding known to this {@link JAXBContext}, * so that XJC can later do separate compilation. * *

* Episode file is really just a JAXB customization file, except that currently * we use the RI-specific SCD to refer to schema components. * * @param output * This receives the generated episode file. * * @since 2.1 */ public abstract void generateEpisode(Result output); /** * Allows you to access the runtime model information of the JAXB XML/Java binding. * *

* This is useful for doing a deeper integration with the JAXB RI. * For more information about the model, see https://jaxb2-reflection.dev.java.net/ * * @since 2.1.10 */ public abstract RuntimeTypeInfoSet getRuntimeTypeInfoSet(); /** * Computes a Java identifier from a local name. * *

* This method faithfully implements the name mangling rule as specified in the JAXB spec. * *

* In JAXB, a collision with a Java reserved word (such as "return") never happens. * Accordingly, this method may return an identifier that collides with reserved words. * *

* Use {@code JJavaName.isJavaIdentifier(String)} to check for such collision. * * @return * Typically, this method returns "nameLikeThis". */ public static @NotNull String mangleNameToVariableName(@NotNull String localName) { return NameConverter.standard.toVariableName(localName); } /** * Computes a Java class name from a local name. * *

* This method faithfully implements the name mangling rule as specified in the JAXB spec. * * @return * Typically, this method returns "NameLikeThis". */ public static @NotNull String mangleNameToClassName(@NotNull String localName) { return NameConverter.standard.toClassName(localName); } /** * Computes a Java class name from a local name. * *

* This method faithfully implements the name mangling rule as specified in the JAXB spec. * This method works like {@link #mangleNameToClassName(String)} except that it looks * for "getClass" and returns something else. * * @return * Typically, this method returns "NameLikeThis". */ public static @NotNull String mangleNameToPropertyName(@NotNull String localName) { return NameConverter.standard.toPropertyName(localName); } /** * Gets the parameterization of the given base type. * *

* For example, given the following *

{@code
     * interface Foo extends List> {}
     * interface Bar extends Foo {}
     * }
* This method works like this: *
{@code
     * getBaseClass( Bar, List ) = List
     * getBaseClass( Bar, Foo  ) = Foo
     * getBaseClass( Foo, Collection ) = Collection>
     * getBaseClass( ArrayList, List ) = List
     * }
* * @param type * The type that derives from {@code baseType} * @param baseType * The class whose parameterization we are interested in. * @return * The use of {@code baseType} in {@code type}. * or null if the type is not assignable to the base type. * @since 2.0 FCS */ public static @Nullable Type getBaseType(@NotNull Type type, @NotNull Class baseType) { return Utils.REFLECTION_NAVIGATOR.getBaseClass(type, baseType); } /** * The property that you can specify to {@link JAXBContext#newInstance} * to reassign the default namespace URI to something else at the runtime. * *

* The value of the property is {@link String}, and it is used as the namespace URI * that succeeds the default namespace URI. * * @since 2.0 EA1 */ public static final String DEFAULT_NAMESPACE_REMAP = "org.glassfish.jaxb.defaultNamespaceRemap"; /** * The property that you can specify to {@link JAXBContext#newInstance} * to put additional JAXB type references into the {@link JAXBContext}. * *

* The value of the property is {@link Collection}{@code <}{@link TypeReference}{@code >}. * Those {@link TypeReference}s can then be used to create {@link Bridge}s. * *

* This mechanism allows additional element declarations that were not a part of * the schema into the created {@link JAXBContext}. * * @since 2.0 EA1 */ public static final String TYPE_REFERENCES = "org.glassfish.jaxb.typeReferences"; /** * The property that you can specify to {@link JAXBContext#newInstance} * and {@link Marshaller#setProperty(String, Object)} * to enable the c14n marshalling support in the {@link JAXBContext}. * * Boolean * @since 2.0 EA2 */ public static final String CANONICALIZATION_SUPPORT = "org.glassfish.jaxb.c14n"; /** * The property that you can specify to {@link JAXBContext#newInstance} * to allow unmarshaller to honor {@code xsi:nil} anywhere, even if they are * not specifically allowed by the schema. * * Boolean * @since 2.1.3 */ public static final String TREAT_EVERYTHING_NILLABLE = "org.glassfish.jaxb.treatEverythingNillable"; /** * The property that you can specify to {@link JAXBContext#newInstance} * to use alternative {@link RuntimeAnnotationReader} implementation. * * @since 2.1 EA2 */ public static final String ANNOTATION_READER = RuntimeAnnotationReader.class.getName(); /** * Marshaller/Unmarshaller property to enable XOP processing. * * @since 2.0 EA2 */ public static final String ENABLE_XOP = "org.glassfish.jaxb.XOP"; /** * The property that you can specify to {@link JAXBContext#newInstance} * to specify specific classes that replace the reference to generic classes. * *

* See the release notes for more details about this feature. * * @since 2.1 EA2 */ public static final String SUBCLASS_REPLACEMENTS = "org.glassfish.jaxb.subclassReplacements"; /** * The property that you can specify to {@link JAXBContext#newInstance} * enable support of XmlAccessorFactory annotation in the {@link JAXBContext}. * * @since 2.1 EA2 */ public static final String XMLACCESSORFACTORY_SUPPORT = "org.glassfish.jaxb.XmlAccessorFactory"; /** * Retains references to PropertyInfos. * * Boolean * @since 2.1.10 */ public static final String RETAIN_REFERENCE_TO_INFO = "retainReferenceToInfo"; /** * Supress security warnings when trying to access fields through reflection. * * Boolean * @since 2.1.14, 2.2.2 */ public static final String SUPRESS_ACCESSOR_WARNINGS = "supressAccessorWarnings"; /** * Improves handling of xsi:type used on leaf properties. * * Boolean * @since 2.2.3 */ public static final String IMPROVED_XSI_TYPE_HANDLING = "org.glassfish.jaxb.improvedXsiTypeHandling"; /** * If true XML security features when parsing XML documents will be disabled. * The default value is false. * * Boolean * @since 2.2.6 */ public static final String DISABLE_XML_SECURITY = "org.glassfish.jaxb.disableXmlSecurity"; /** * If true and element namespace is not specified, namespace of parent element will be used. * The default value is false. * * Boolean * @since 2.3.0 */ public static final String BACKUP_WITH_PARENT_NAMESPACE = "org.glassfish.jaxb.backupWithParentNamespace"; /** * The maximum number of errors to report. Use negative value to report all errors. * The default value is 10. * * Boolean * @since 2.3.3 */ public static final String MAX_ERRORS = "org.glassfish.jaxb.maxErrorsCount"; }