33장. XML Elements 사용

초록

XML 스키마 요소는 XML 문서에서 요소의 인스턴스를 정의하는 데 사용됩니다.XML Schema elements are used to define an instance of an element in an XML document. 요소는 XML 스키마 문서의 전역 범위에서 정의되거나 복잡한 형식의 멤버로 정의됩니다. 전역 범위에 정의되면 Apache CXF는 이를 더 쉽게 조작할 수 있는 JAXB 요소 클래스에 매핑합니다.

33.1. 개요

XML 문서의 요소 인스턴스는 XML Schema 문서의 전역 범위에 있는 XML Schema 요소 요소에 의해 정의되며, Java 개발자가 요소를 더 쉽게 작업할 수 있도록 합니다. Apache CXF는 전역 범위 요소를 특수 JAXB 요소 클래스 또는 해당 콘텐츠 형식과 일치하도록 생성된 Java 클래스에 전역 범위 요소를 매핑합니다.

요소가 매핑되는 방법은 type 속성에서 참조하는 명명된 유형을 사용하여 요소가 정의되었는지 또는 요소가 인라인 유형 정의를 사용하여 정의되었는지에 따라 달라집니다. 인라인 유형 정의로 정의된 요소는 Java 클래스에 매핑됩니다.

인라인 유형은 스키마의 다른 요소에서 재사용할 수 없기 때문에 명명된 유형을 사용하여 요소를 정의하는 것이 좋습니다.

33.2. XML 스키마 매핑

XML Schema 요소는 요소 요소 를 사용하여 정의됩니다. 요소 요소에 는 하나의 필수 특성이 있습니다. name 은 XML 문서에 표시되는 요소의 이름을 지정합니다.

name 속성 요소 요소 외에도 표 33.1. “요소를 정의하는 데 사용되는 특성” 에 나열된 선택적 속성이 있습니다.

표 33.1. 요소를 정의하는 데 사용되는 특성

속성설명

type

요소의 형식을 지정합니다. 형식은 모든 XML 스키마 기본 유형 또는 계약에 정의된 이름이 지정된 복잡한 유형일 수 있습니다. 이 속성을 지정하지 않으면 인라인 유형 정의를 포함해야 합니다.

nillable

요소가 문서에서 완전히 벗어날 수 있는지 여부를 지정합니다.Specifies if an element can be left out of a document entirely. nillable 을 true 로 설정하면 스키마를 사용하여 생성된 문서에서 요소를 생략할 수 있습니다.

abstract

인스턴스 문서에서 요소를 사용할 수 있는지 여부를 지정합니다.Specifies if an element can be used in an instance document. true 는 요소가 인스턴스 문서에 나타나지 않음을 나타냅니다. 대신 substitutionGroup 속성에 이 요소의 QName이 포함된 다른 요소가 이 요소의 위치에 표시되어야 합니다. 이 특성의 효과 코드 생성에 대한 자세한 내용은 “추상 요소의 Java 매핑” 을 참조하십시오.

substitutionGroup

이 요소로 대체할 수 있는 요소의 이름을 지정합니다. 유형 대체 사용에 대한 자세한 내용은 37장. element Substitution 을 참조하십시오.

default

요소의 기본값을 지정합니다. 이 특성의 효과 코드 생성에 대한 자세한 내용은 “Java 요소의 기본값을 사용하여 매핑” 을 참조하십시오.

fixed

요소에 대한 고정 값을 지정합니다.Specifies a fixed value for the element.

예 33.1. “간단한 XML 스키마 요소 정의” 간단한 요소 정의를 보여줍니다.

예 33.1. 간단한 XML 스키마 요소 정의

<element name="joeFred" type="xsd:string" />

요소는 또한 인라인 유형 정의를 사용하여 자체 유형을 정의할 수 있습니다. 인라인 형식은 complexType 요소 또는 simpleType 요소를 사용하여 지정됩니다. 데이터 유형이 복잡하고 간단한지 여부를 지정하면 각 유형의 데이터에 사용할 수 있는 도구를 사용하여 필요한 모든 유형의 데이터를 정의할 수 있습니다.

예 33.2. “인라인 유형을 사용한 XML 스키마 요소 정의” 줄 형식 정의를 사용하여 요소 정의를 표시합니다.Shows an element definition with an in-line type definition.

예 33.2. 인라인 유형을 사용한 XML 스키마 요소 정의

<element name="skate">
  <complexType>
    <sequence>
      <element name="numWheels" type="xsd:int" />
      <element name="brand" type="xsd:string" />
    </sequence>
  </complexType>
</element>

33.3. 명명된 유형을 사용하여 요소의 매핑

기본적으로 전역적으로 정의된 요소는 요소 요소의 type 속성 값으로 템플릿 클래스가 결정되는 JAXBElement<T > 개체에 매핑됩니다. 기본 유형의 경우 템플릿 클래스는 “래퍼 클래스” 에 설명된 래퍼 클래스 매핑을 사용하여 파생됩니다. 복잡한 유형의 경우 복잡한 유형을 지원하기 위해 생성된 Java 클래스가 템플릿 클래스로 사용됩니다.

매핑을 지원하고 요소의 QName에 대한 불필요한 걱정의 개발자를 완화하기 위해 예 33.3. “Globally Scoped Element에 대한 Object Factory Method” 과 같이 전역적으로 정의된 각 요소에 대해 개체 팩토리 메서드가 생성됩니다.

예 33.3. Globally Scoped Element에 대한 Object Factory Method

public class ObjectFactory {

    private final static QName _name_QNAME = new QName("targetNamespace", "localName");

    ...

    @XmlElementDecl(namespace = "targetNamespace", name = "localName")
    public JAXBElement<type> createname(type value);

}

예를 들어 예 33.1. “간단한 XML 스키마 요소 정의” 에 정의된 요소는 예 33.4. “간단한 요소용 개체 팩토리” 로 표시된 오브젝트 팩토리 메서드가 생성됩니다.

예 33.4. 간단한 요소용 개체 팩토리

public class ObjectFactory {

    private final static QName _JoeFred_QNAME = new QName("...", "joeFred");

    ...

    @XmlElementDecl(namespace = "...", name = "joeFred")
    public JAXBElement<String> createJoeFred(String value);

}

예 33.5. “글로벌 범위 요소 사용” Java에서 전역 범위가 지정된 요소를 사용하는 예를 보여줍니다.

예 33.5. 글로벌 범위 요소 사용

JAXBElement<String> element = createJoeFred("Green");
String color = element.getValue();

33.4. WSDL에서 명명된 유형에서 요소 사용

전역 범위 요소가 메시지 부분을 정의하는 데 사용되는 경우 생성된 Java 매개 변수는 JAXBElement<T >의 인스턴스가 아닙니다. 대신 일반 Java 유형 또는 클래스에 매핑됩니다.

예 33.6. “Element를 메시지 파트로 Using an item as a message part” 에 표시된 WSDL 조각이 있는 경우 결과 메서드에는 문자열 유형의 매개 변수가 있습니다.

예 33.6. Element를 메시지 파트로 Using an item as a message part

<?xml version="1.0" encoding=";UTF-8"?>
<wsdl:definitions name="HelloWorld"
                  targetNamespace="http://apache.org/hello_world_soap_http"
                  xmlns="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://apache.org/hello_world_soap_http"
                  xmlns:x1="http://apache.org/hello_world_soap_http/types"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <wsdl:types>
    <schema targetNamespace="http://apache.org/hello_world_soap_http/types"
            xmlns="http://www.w3.org/2001/XMLSchema"
            elementFormDefault="qualified"><element name="sayHi">
      <element name="sayHi" type="string"/>
      <element name="sayHiResponse" type="string"/>
    </schema>
  </wsdl:types>

  <wsdl:message name="sayHiRequest">
    <wsdl:part element="x1:sayHi" name="in"/>
  </wsdl:message>
  <wsdl:message name="sayHiResponse">
    <wsdl:part element="x1:sayHiResponse" name="out"/>
  </wsdl:message>

  <wsdl:portType name="Greeter">
    <wsdl:operation name="sayHi">
      <wsdl:input message="tns:sayHiRequest" name="sayHiRequest"/>
      <wsdl:output message="tns:sayHiResponse" name="sayHiResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  ...
</wsdl:definitions>

예 33.7. “글로벌 요소를 파트로 사용하는 Java Method” sayHi 작업에 대해 생성된 메서드 서명을 보여줍니다.

예 33.7. 글로벌 요소를 파트로 사용하는 Java Method

stringsayHistringin

33.5. 인라인 유형을 사용하여 요소의 매핑

인라인 유형을 사용하여 요소가 정의되면 다른 유형을 Java에 매핑하는 데 사용되는 동일한 규칙에 따라 Java에 매핑됩니다. 간단한 유형의 규칙은 34장. 간단한 유형 사용 에 설명되어 있습니다. 복잡한 유형의 규칙은 35장. 복합 유형 사용 에 설명되어 있습니다.

인라인 유형 정의가 있는 요소에 대해 Java 클래스가 생성되면 생성된 클래스는 @XmlRootElement 주석으로 장식됩니다. @XmlRootElement 주석에는 name 및 namespace 의 두 가지 유용한 속성이 있습니다. 이러한 속성은 표 33.2. “@XmlRootElement 주석에 대한 속성” 에 설명되어 있습니다.

표 33.2. @XmlRootElement 주석에 대한 속성

속성설명

name

XML Schema 요소 의 name 특성 값을 지정합니다.

namespace

요소가 정의된 네임스페이스를 지정합니다. 대상 네임스페이스에 이 요소가 정의되면 속성이 지정되지 않습니다.If this element is defined in the target namespace, the property is not specified.

요소가 다음 조건 중 하나 이상을 충족하는 경우 @XmlRootElement 주석이 사용되지 않습니다.

  • 요소의 nillable 속성이 true로 설정됩니다.

  • 요소는 대체 그룹의 헤드 요소입니다.

    대체 그룹에 대한 자세한 내용은 37장. element Substitution 을 참조하십시오.

33.6. 추상 요소의 Java 매핑

요소의 abstract 속성을 true로 설정하면 형식의 인스턴스를 인스턴스화하는 데 필요한 개체 팩토리 메서드가 생성되지 않습니다.When the element's abstract attribute is set to true the object factory method for instantiating instances of the type is not generated. 인라인 유형을 사용하여 요소가 정의된 경우 인라인 유형을 지원하는 Java 클래스가 생성됩니다.

33.7. Java 요소의 기본값을 사용하여 매핑

요소의 기본 특성이 사용되는 경우 defaultValue 속성이 생성된 @XmlElementDecl 주석에 추가됩니다. 예를 들어 예 33.8. “XML Schema Element with a Default Value” 에 정의된 요소는 예 33.9. “기본 값이 있는 Element에 대한 Object Factory Method” 로 표시된 오브젝트 팩토리 메서드가 생성됩니다.

예 33.8. XML Schema Element with a Default Value

<element name="size" type="xsd:int" default="7"/>

예 33.9. 기본 값이 있는 Element에 대한 Object Factory Method

   @XmlElementDecl(namespace = "...", name = "size", defaultValue = "7")
   public JAXBElement<Integer> createUnionJoe(Integer value) {
       return new JAXBElement<Integer>(_Size_QNAME, Integer.class, null, value);
   }