Тип аннотации XmlElementRef

@Retention(value=RUNTIME)
 @Target(value={FIELD,METHOD})
public @interface XmlElementRef

Сопоставляет свойство JavaBean с XML-элементом, полученным из типа свойства.

Использование

Аннотация @XmlElementRef может использоваться со свойством JavaBean или внутри XmlElementRefs

Данная аннотация динамически связывает имя XML-элемента со свойством JavaBean. Когда свойство JavaBean аннотировано с помощью XmlElement, имя XML-элемента статически выводится из имени свойства JavaBean. Однако при использовании этой аннотации имя XML-элемента выводится из экземпляра типа свойства JavaBean во время выполнения.

Поддержка групп подстановки XML-схемы

XML-схема позволяет автору XML-документа использовать имена XML-элементов, которые не были статически указаны в модели содержимого схемы, используя группы подстановки. Сгенерированный по схеме код поддерживает группы подстановки, используя свойство элемента (раздел 5.5.5, «Свойство элемента» спецификации JAXB 2.0). Подпись метода свойства элемента имеет вид:

public void setTerm(JAXBElement extends Operator>);
     public JAXBElement extends Operator> getTerm();

Метод фабрики элементов, аннотированный с помощью XmlElementDecl, используется для создания экземпляра JAXBElement, содержащего имя XML-элемента. Наличие аннотации @XmlElementRef на свойстве элемента указывает на то, что имя элемента из экземпляра JAXBElement должно использоваться вместо вывода имени XML-элемента из имени свойства JavaBean.

Использование ограничено следующими условиями:

• Если тип элемента коллекции (для свойства коллекции) или тип свойства (для свойства с единственным значением) равен JAXBElement, то @XmlElementRef}.name() и @XmlElementRef.namespace() должны указывать на метод фабрики элементов с аннотацией @XmlElementDecl в классе, аннотированном @XmlRegistry (обычно класс ObjectFactory, сгенерированный компилятором схемы):
  • @XmlElementDecl.name() должно быть равно @XmlElementRef.name()
  • @XmlElementDecl.namespace() должно быть равно @XmlElementRef.namespace().
• Если тип элемента коллекции (для свойства коллекции) или тип свойства (для свойства с единственным значением) не равен JAXBElement, то тип, на который ссылается свойство или поле, должен быть аннотирован с помощью XmlRootElement.
• Эту аннотацию можно использовать с такими аннотациями: XmlElementWrapper, XmlJavaTypeAdapter.

См. "Спецификацию пакета" в документации javax.xml.bind.package для дополнительной общей информации.

Пример 1: Пример задачи Ant

Следующая иерархия классов Java моделирует сценарий сборки Ant. Задача Ant соответствует классу в иерархии классов. Имя XML-элемента задачи Ant указывается аннотацией @XmlRootElement на соответствующем классе.

@XmlRootElement(name="target")
     class Target {
         // The presence of @XmlElementRef indicates that the XML
         // element name will be derived from the @XmlRootElement
         // annotation on the type (for e.g. "jar" for JarTask).
         @XmlElementRef
         List<Task> tasks;
     }

     abstract class Task {
     }

     @XmlRootElement(name="jar")
     class JarTask extends Task {
         ...
     }

     @XmlRootElement(name="javac")
     class JavacTask extends Task {
         ...
     }

     <!-- XML Schema fragment -->
     <xs:element name="target" type="Target">
     <xs:complexType name="Target">
       <xs:sequence>
         <xs:choice maxOccurs="unbounded">
           <xs:element ref="jar">
           <xs:element ref="javac">
         </xs:choice>
       </xs:sequence>
     </xs:complexType>

Таким образом, следующий фрагмент кода:

Target target = new Target();
     target.tasks.add(new JarTask());
     target.tasks.add(new JavacTask());
     marshal(target);

приведет к следующему XML-выводу:

<target>
       <jar>
         ....
       </jar>
       <javac>
         ....
       </javac>
     </target>

Не является ошибкой наличие класса, расширяющего Task и не имеющего XmlRootElement. Но они не могут отображаться в XML-экземпляре (поскольку у них нет имён XML-элементов).

Пример 2: Поддержка групп подстановки XML-схемы

Следующий пример демонстрирует аннотации для групп подстановки XML-схемы. Аннотации и ObjectFactory получены из схемы.

@XmlElement
     class Math {
         //  The value of type()is
         //  JAXBElement.class , which indicates the XML
         //  element name ObjectFactory - in general a class marked
         //  with @XmlRegistry. (See ObjectFactory below)
         //
         //  The name() is "operator", a pointer to a
         // factory method annotated with a
         //  XmlElementDecl with the name "operator". Since
         //  "operator" is the head of a substitution group that
         //  contains elements "add" and "sub" elements, "operator"
         //  element can be substituted in an instance document by
         //  elements "add" or "sub". At runtime, JAXBElement
         //  instance contains the element name that has been
         //  substituted in the XML document.
         //
         @XmlElementRef(type=JAXBElement.class,name="operator")
         JAXBElement<? extends Operator> term;
     }

     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(name="operator")
         JAXBElement<Operator> createOperator(Operator o) {...}
         @XmlElementDecl(name="add",substitutionHeadName="operator")
         JAXBElement<Operator> createAdd(Operator o) {...}
         @XmlElementDecl(name="sub",substitutionHeadName="operator")
         JAXBElement<Operator> createSub(Operator o) {...}
     }

     class Operator {
         ...
     }

Таким образом, следующий фрагмент кода

Math m = new Math();
     m.term = new ObjectFactory().createAdd(new Operator());
     marshal(m);

приведет к следующему XML-выводу:

<math>
       <add>...</add>
     </math>

Элементы

type

public abstract Class type

По умолчанию:

javax.xml.bind.annotation.XmlElementRef.DEFAULT.class

namespace

public abstract String namespace

По умолчанию:

""

name

public abstract String name

См. также:

namespace()

По умолчанию:

"##default"

required

public abstract boolean required

С момента:

2.2

По умолчанию:

true