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

javax.xml.bind.annotation.XmlElementDecl Maven / Gradle / Ivy

There is a newer version: 4.0.3
Show newest version
/*
 * Copyright (c) 2004, 2018 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 javax.xml.bind.annotation;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.RetentionPolicy.RUNTIME;
import static java.lang.annotation.ElementType.METHOD;

/**
 * Maps a factory method to a XML element.
 *
 * 

Usage

* * The annotation creates a mapping between an XML schema element * declaration and a element factory method that returns a * JAXBElement instance representing the element * declaration. Typically, the element factory method is generated * (and annotated) from a schema into the ObjectFactory class in a * Java package that represents the binding of the element * declaration's target namespace. Thus, while the annotation syntax * allows @XmlElementDecl to be used on any method, semantically * its use is restricted to annotation of element factory method. * * The usage is subject to the following constraints: * *
    *
  • The class containing the element factory method annotated * with @XmlElementDecl must be marked with {@link * XmlRegistry}.
  • *
  • The element factory method must take one parameter * assignable to {@link Object}.
  • *
* *

Example 1: Annotation on a factory method *

 *     // Example: code fragment
 *     @XmlRegistry
 *     class ObjectFactory {
 *         @XmlElementDecl(name="foo")
 *         JAXBElement<String> createFoo(String s) { ... }
 *     }
 * 
*
 {@code
 * 
 *     
 *     string
 *
 *     // Example: code fragment corresponding to XML input
 *     JAXBElement o =
 *     (JAXBElement)unmarshaller.unmarshal(aboveDocument);
 *     // print JAXBElement instance to show values
 *     System.out.println(o.getName());   // prints  "{}foo"
 *     System.out.println(o.getValue());  // prints  "string"
 *     System.out.println(o.getValue().getClass()); // prints "java.lang.String"
 *
 *     
 *     
 * }
* *

Example 2: Element declaration with non local scope *

* The following example illustrates the use of scope annotation * parameter in binding of element declaration in schema derived * code. *

* The following example may be replaced in a future revision of * this javadoc. * *

{@code
 *     
 *     
 *       
 *         
 *           
 *           
 *         
 *       
 *       
 *     
 * }
*
 *     // Example: expected default binding
 *     class Pea {
 *         @XmlElementRefs({
 *             @XmlElementRef(name="foo",type=JAXBElement.class)
 *             @XmlElementRef(name="bar",type=JAXBElement.class)
 *         })
 *         List<JAXBElement<String>> fooOrBar;
 *     }
 * 
 *     @XmlRegistry
 *     class ObjectFactory {
 *         @XmlElementDecl(scope=Pea.class,name="foo")
 *         JAXBElement<String> createPeaFoo(String s);
 * 
 *         @XmlElementDecl(scope=Pea.class,name="bar")
 *         JAXBElement<String> createPeaBar(String s);
 * 
 *         @XmlElementDecl(name="foo")
 *         JAXBElement<Integer> createFoo(Integer i);
 *     }
 * 
 * 
* Without scope createFoo and createPeaFoo would become ambiguous * since both of them map to a XML schema element with the same local * name "foo". * * @see XmlRegistry * @since 1.6, JAXB 2.0 */ @Retention(RUNTIME) @Target({METHOD}) public @interface XmlElementDecl { /** * scope of the mapping. * *

* If this is not {@link XmlElementDecl.GLOBAL}, then this element * declaration mapping is only active within the specified class. */ Class scope() default GLOBAL.class; /** * namespace name of the XML element. *

* If the value is "##default", then the value is the namespace * name for the package of the class containing this factory method. * * @see #name() */ String namespace() default "##default"; /** * local name of the XML element. * *

* Note to reviewers: There is no default name; since * the annotation is on a factory method, it is not clear that the * method name can be derived from the factory method name. * @see #namespace() */ String name(); /** * namespace name of a substitution group's head XML element. *

* This specifies the namespace name of the XML element whose local * name is specified by {@code substitutionHeadName()}. *

* If {@code susbtitutionHeadName()} is "", then this * value can only be "##default". But the value is ignored since * since this element is not part of susbtitution group when the * value of {@code susbstitutionHeadName()} is "". *

* If {@code susbtitutionHeadName()} is not "" and the value is * "##default", then the namespace name is the namespace name to * which the package of the containing class, marked with {@link * XmlRegistry }, is mapped. *

* If {@code susbtitutionHeadName()} is not "" and the value is * not "##default", then the value is the namespace name. * * @see #substitutionHeadName() */ String substitutionHeadNamespace() default "##default"; /** * XML local name of a substitution group's head element. *

* If the value is "", then this element is not part of any * substitution group. * * @see #substitutionHeadNamespace() */ String substitutionHeadName() default ""; /** * Default value of this element. * *

* The

'\u0000'
value specified as a default of this annotation element * is used as a poor-man's substitute for null to allow implementations * to recognize the 'no default value' state. */ String defaultValue() default "\u0000"; /** * Used in {@link XmlElementDecl#scope()} to * signal that the declaration is in the global scope. */ public final class GLOBAL {} }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy