패키지 javax.xml.transform

이 패키지는 변환 명령의 처리 및 소스로부터 결과에의 변환을 실행하기 위한 범용 API를 정의합니다.

참조처:
설명

인터페이스 개요

ErrorListener	커스터마이즈 된 에러 처리를 제공하려면, 이 인터페이스를 구현해, setErrorListener 메서드를 사용해, Transformer 로 구현의 인스턴스를 등록합니다.
Result	이 인터페이스를 구현하는 객체에는 변환 결과 트리를 작성하는데 필요한 정보가 포함되어 있습니다.
Source	이 인터페이스를 구현하는 객체에는 소스 입력 (XML 소스 또는 변환 명령)으로서 동작하는데 필요한 정보가 포함되어 있습니다.
SourceLocator	이 인터페이스는 XML 소스 또는 변환 명령내에서 발생한 에러의 장소를 리포트하는 것을 주된 목적으로 하고 있습니다.
Templates	이 인터페이스를 구현하는 객체는 처리된 변환 명령의 실행시 표현입니다.
URIResolver	이 인터페이스를 구현하는 객체는 document(), xsl:import, 또는 xsl:include 로 사용되는 URI를 Source 객체로 변환하는 프로세서로 호출할 수 있습니다 .

클래스 개요

OutputKeys	Transformer 출력 프로퍼티를 설정하기 위해서 혹은 Transformer 또는 Templates 객체로부터 출력 프로퍼티를 꺼내기 위해서 사용할 수 있는 캐릭터 라인 정수를 제공합니다.
Transformer	이 추상 클래스의 인스턴스는 소스 트리를 결과 트리로 변환할 수 있습니다 .
TransformerFactory	TransformerFactory 인스턴스를 사용해, Transformer 및 Templates 객체를 작성할 수 있습니다 .

예외 개요

TransformerConfigurationException	중대한 구성 에러를 나타냅니다.
TransformerException	이 클래스는 변환 처리중에 발생한 예외 상태를 나타냅니다.

에러의 개요

TransformerFactoryConfigurationError

변환 팩토리의 구성으로 문제가 존재하는 경우에 예외를 발생시킵니다.

패키지 javax.xml.transform 설명

이 패키지는 변환 명령의 처리 및 소스로부터 결과에의 변환을 실행하기 위한 범용 API를 정의합니다. 이러한 인터페이스는 SAX 또는 DOM 표준에 존하고 있지 않고, 변환의 소스와 결과의 상세에 관한 가정을 가능한 한 줄이고 있습니다. Source 및 Result 인터페이스를 정의해 이것을 실현합니다.

사용자 의 구상 클래스를 정의하기 위해서 이 API는 루트 레벨에 있는 인터페이스의 특수화를 정의합니다. 이러한 인터페이스는 javax.xml.transform.sax, javax.xml.transform.dom 및 javax.xml.transform.stream에 있습니다.

객체의 작성

API 에의해 구상 TransformerFactory 객체를 static 함수 TransformerFactory.newInstance() 로부터 작성할 수 있게 됩니다.

입력과 출력의 사양

이 API는 Source 및 Result 로 불리는 2개의 인터페이스 객체를 정의합니다. Source 및 Result 객체를 인터페이스에 건네주기 위해서는 구상 클래스를 사용할 필요가 있습니다. StreamSource 와 StreamResult, SAXSource 와 SAXResult 및 DOMSource 와 DOMResult 각 객체에 대해서 3개의 구상표현이 정의됩니다. 이러한 객체는 각각 FEATURE 캐릭터 라인 (URL 형식)을 정의합니다. 이 캐릭터 라인을 TransformerFactory.getFeature(java.lang.String)에 건네주어, 지정된 형태의 Source 또는 Result 객체가 지원 되고 있는지를 확인할 수 있습니다. 예를 들어 DOMSource 및 StreamResult가 지원 되고 있는지를 판정하려면, 다음의 테스트를 실시합니다.

TransformerFactory tfactory = TransformerFactory.newInstance() ;if (tfactory.getFeature(DOMSource.FEATURE) &&
 tfactory.getFeature(StreamResult.FEATURE)) {...}

수식명 표현

「이름 공간」은,XML 객체를 취급할 때의 문제 영역을 제시합니다. 수식명은 XML 마크 업의 접두사가 붙은 이름으로서 표시됩니다. 접두사 자체는 식별 정보를 보관 유지하지 않습니다. 오히려, 접두사는 식별 정보를 보관 유지하는 URI에 컨텍스트 존으로 매핑 됩니다. 따라서, Java 프로그램간에 xyz:foo와 같은 수식명을 건네주는 경우는 xyz를 이름 공간에 매핑 하는 수단을 제공할 필요가 있습니다.

1개의 해결책은 이름 공간 URI와 접두사 및 로컬명을 보관 유지하는 Qname 객체를 작성하는 것입니다. 다만, 예를 들어 딕쇼내리 객체의 키로서 일의의 캐릭터 라인을 사용하는 경우와 같이, 이것이 항상 최적의 해결책이다고는인가 선. 캐릭터 라인 표현이 없으면 XML 문서의 컨텍스트 외의 이름 공간에서 수식된 식별 정보를 지정하는 일도 곤란하게 됩니다.

Transformer 객체에 프로퍼티 또는 파라미터를 설정하는 경우 등, 이름 공간에서 수식된 값을 변환에 건네주기 위해서 이 사양에서는 String 형 qname 객체 파라미터는 2 부 형식의 캐릭터 라인으로서 건네받도록 정의됩니다. 즉, 안괄호 ({})로 둘러싸인 이름 공간 URI 후에 로컬명이 계속됩니다. qname가 null URI를 가지는 경우, String 객체에는 로컬명만이 포함됩니다. 어플리케이션은 이름의 최초의 문자가 「{」문자일지 어떨지를 판정해, null이 아닌 URI를 안전하게 체크할 수 있습니다.

예를 들어 <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/> 로 정의된 요소로부터 URI와 로컬명을 취득했을 경우, 수식명은 {http://xyz.foo.com/yada/baz.html}foo가 되어, 접두사는 없어집니다.

결과 트리의 직렬화

스트림에의 결과 트리의 직렬화는 Transformer.setOutputProperties(java.util.Properties) 및 Transformer.setOutputProperty(java.lang.String, java.lang.String) 메서드를 사용해 제어할 수 있습니다. 이러한 프로퍼티는 스트림 결과에게만 적용되어 결과가 DOM 트리 또는 SAX 이벤트 스트림의 경우는 무슨 영향도 없습니다.

「XSLT specification for xsl」의 출력 속성에 일치하는 캐릭터 라인은 OutputKeys 클래스로부터 참조할 수 있습니다. 다른 캐릭터 라인도 지정할 수 있습니다. 변환이 출력 키를 인식하지 않는 경우, 키명이수식된 이름 공간이 아니면IllegalArgumentException을 발생시킵니다. 이름 공간에서 수식된 출력 키명은 항상 허가되고 있습니다만, 구현에 따라서는 무시되는 경우가 있습니다.

소스로부터 결과에의 단순한 항등변환만이 필요한 경우, TransformerFactory 는 인수를 지정하지 않고 TransformerFactory.newTransformer() 메서드를 제공합니다. 이 메서드는 소스를 결과에 효과적으로 카피하는 Transformer를 작성합니다. 이 메서드를 사용해, SAX 이벤트로부터의 DOM를 작성하는지, DOM 또는 SAX 이벤트로부터 XML 또는 HTML 스트림을 작성할 수 있습니다 .

예외와 에러 리포트

변환 API는 3개의 형태의 특수한 예외를 Throw 합니다. TransformerFactoryConfigurationError 는 FactoryConfigurationError에 대응해, TransformerFactory 에서의 구성에 문제가 존재하면 발생 됩니다. 보통, 이 에러는 javax.xml.transform.TransformerFactory 시스템 프로퍼티를 사용해 지정된 변환 팩토리 클래스가 발견되지 않는 혹은 인스턴스화할 수 없는 경우에 예외를 발생시킵니다.

어떠한 이유로써 Transformer를 작성할 수 없는 경우는 TransformerConfigurationException이 발생되는 일이 있습니다. 변환 명령에 구문 에러가 있는 경우, 예를 들어 TransformerFactory.newTransformer(javax.xml.transform.Source) 가 불려 갔을 경우는 TransformerConfigurationException가 발생되는 일이 있습니다.

TransformerException 는 변환의 과정에서 발생하는 일반적인 예외입니다. Transformer 예외는 다른 예외를 랩 할 수가 있어 그 발생시에 TransformerException.printStackTrace() 메서드중 한쪽이 불려가 면, 최신의 것으로부터 시작되는 스택 덤프의 리스트를 작성합니다. Transformer 예외는 또, 에러가 발생한 소스 트리 또는 변환 명령내의 장소를 나타내는 SourceLocator 객체도 제공합니다. TransformerException.getMessageAndLocation()를 호출해 장소의 정보를 포함한 에러 메세지를 취득할 수가 있어TransformerException.getLocationAsString()를 호출해 장소의 캐릭터 라인만을 취득할 수 있습니다 .

변환의 경고와 에러는 ErrorListener에 보내져 그 시점에서 어플리케이션은 에러 또는 경고를 리포트하도록 결정할 수 있는 것 외에 중대하지 않은 에러의 Exception을 Throw 하도록 결정할 수 있습니다. ErrorListener는 TransformerFactory.setErrorListener(javax.xml.transform.ErrorListener)를 개입시켜 변환 명령의 구문 에러에 관계된 에러를 리포트하도록 설정하는지, Transformer.setErrorListener(javax.xml.transform.ErrorListener)를 개입시켜 변환시에 발생하는 에러를 리포트하도록 설정할 수 있습니다. 양쪽 모두의 객체의 ErrorListener는 어플리케이션에 의해 설정되는지, 프로세서가 제공하는 디폴트의 구현에 의해 설정될까에 관계없이, 항상 유효해, null이 아닐 필요가 있습니다. 프로세서가 제공하는 디폴트의 구현에서는 모든 경고와 에러가 System.err에 리포트되어Exception가 Throw 되지 않습니다. 어플리케이션에서는 경고와 에러의 정상적인 동작을 확보하기 위해, ErrorListener를 등록해 사용하는 것을 강하게 추천합니다.

변환내의 URI 해결

이 API는 스타일 시트 명령내 또는 변환내로부터 참조되는 URI를 호출해 옆어플리케이션으로 해결하는 수단을 제공합니다. 이것은 그 1개의 메서드, URIResolver.resolve(java.lang.String, java.lang.String)를 사용해 URIResolver 인터페이스를 구현하는 클래스를 작성하는 것으로써 실현할 수 있어 이 클래스를 사용해 변환 명령, 혹은 TransformerFactory.setURIResolver(javax.xml.transform.URIResolver), 또는 Transformer.setURIResolver(javax.xml.transform.URIResolver)를 사용한 변환을 위해서 URI 해결을 설정합니다. URIResolver.resolve 메서드는 2개의 String 인수를 취합니다. 1개는 스타일 시트 명령내에 있는 URI 또는 변환 프로세스의 일부로서 구축된 URI 로 이제(이미 ) 1개는 절대 URI가 필요한 경우에 최초의 인수가 절대가 되는 베이스 URI 입니다. 리턴된 Source 객체는 그 구현된 기능으로 지정되고 있도록, Transformer 로 사용 가능하지 않으면 안됩니다.