javax.xml.bind.annotation
주석형 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 Schema 치환 그룹 지원

XML Schema 에서는, XML 문서 작성자는 치환 그룹을 사용해, schema의 컨텐츠 모델로 정적으로 지정되어 있지 않은 XML 요소명을 사용할 수가 있습니다. schema 파생 코드는, 「요소 프로퍼티」을 사용해 치환 그룹의 지원를 제공합니다 (5.5. 5 절, JAXB 2.0 스펙의 「요소 프로퍼티」). 요소 프로파티메소드시그니챠는, 다음의 형식을 취합니다.

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

XmlElementDecl 로 주석 된 요소 팩토리 메소드는, XML 요소명을 포함한 JAXBElement 인스턴스를 작성하기 위해서 사용됩니다. 요소 프로퍼티에 @XmlElementRef 주석이 존재하는 것은, JavaBean 프로퍼티명으로부터 XML 요소명이 파생하므로 없고,JAXBElement 인스턴스로부터의 요소명이 사용되는 것을 의미합니다.

사용에는 다음의 제약이 있습니다.

• 컬렉션 항목형 (컬렉션 프로퍼티의 경우) 또는 프로퍼티형 (단일치 프로퍼티의 경우)이 JAXBElement 의 경우, @XmlElementRef.name()과 @XmlElementRef.namespace()는, @XmlRegistry 로 주석 된 클래스내의 @XmlElementDecl 주석을 수반하는 요소 팩토리 메소드를 나타낼 필요가 있습니다 (일반적으로, 이 클래스는 schema 컴파일러에 의해 생성되는 ObjectFactory 클래스).
  • @XmlElementDecl.name()는, @XmlElementRef.name()와 같지 않으면 안됩니다.
  • @XmlElementDecl.namespace()는, @XmlElementRef.namespace()와 같지 않으면 안됩니다.
• 컬렉션 항목의 형태 (컬렉션 프로퍼티의 경우) 또는 프로퍼티형 (단일치 프로퍼티의 경우)이 JAXBElement 이외의 경우, 프로퍼티 또는 필드에 의해 참조되는 형태가 XmlRootElement 로 주석 될 필요가 있습니다.
• 이 주석은, 다음의 주석과 함께 사용할 수 있습니다. XmlElementWrapper ,XmlJavaTypeAdapter .

추가의 일반적인 정보에 대해서는, javax.xml.bind.package javadoc 의 「패키지의 스펙」을 참조해 주세요.

예 1:Ant 태스크의 예

다음의 Java 클래스 계층은, Ant 빌드 스크립트를 모델링 한 것입니다. Ant 태스크는, 클래스 계층내의 1 개의 클래스에 대응하고 있습니다. Ant 태스크의 XML 요소명은, 대응하는 클래스에 대한 @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>

 

다음에 코드 fragment를 나타냅니다.

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

상기의 코드 fragment는 다음의 XML 출력을 생성합니다.

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

XmlRootElement 를 가지지 않는 Task 를 확장하는 클래스를 가지는 것은 에러가 아닙니다. 그러나, 이것들은 XML 인스턴스에 표시할 수 없습니다 (이것들에는 XML 요소명이 없기 때문입니다).

예 2:XML Schema 치환 그룹 지원

다음의 예는, XML Schema 치환 그룹용의 주석을 나타냅니다. 주석과 ObjectFactory 는, schema로부터 파생합니다.

     @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 {
         ...
     }
 

다음에 코드 fragment를 나타냅니다.

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

상기의 코드 fragment는 다음의 XML 출력을 생성합니다.

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

도입된 버젼:

JAXB2. 0

관련 항목:

XmlElementRefs

임의 요소의 개요

String	name
String	namespace 이 파라미터와 name() 가 사용되어, JavaBean 프로퍼티의 XML 요소가 결정됩니다.
Class	type 참조되는 Java 형입니다.

type

public abstract Class  type

참조되는 Java 형입니다.

값이 DEFAULT.class 의 경우, 형태는 JavaBean 프로퍼티의 형태로부터 추정됩니다.

디폴트:

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

namespace

public abstract String  namespace

이 파라미터와 name() 가 사용되어, JavaBean 프로퍼티의 XML 요소가 결정됩니다.

type() 가 JAXBElement.class 의 경우,namespace() 와 name() 는,XmlElementDecl 를 수반하는 팩토리 메소드를 나타냅니다. XML 요소명은, 팩토리 메소드 XmlElementDecl 주석의 요소명인지, 또는, 그 치환 그룹의 요소가 XML 문서로 치환되었을 경우, 치환 요소에 대한 XmlElementDecl 의 요소명입니다.

type() 가 JAXBElement.class 이외의 경우, XML 요소명은, 형태에 대한 XmlRootElement 주석을 사용해 형태에 정적으로 관련지을 수 있었던 XML 요소명입니다. 형태가 XmlElementDecl 로 주석되어 있지 않은 경우, 에러입니다.

type() 가 JAXBElement.class 이외의 경우, 이 값은 「」이 됩니다.

디폴트:

""

name

public abstract String  name

관련 항목:

namespace()

디폴트:

"##default"