org.xml.sax
인터페이스 XMLReader

알려진 서브 인터페이스 목록 :

XMLFilter

알려진 구현 클래스 목록:

ParserAdapter, XMLFilterImpl

public interface XMLReader

콜백을 사용해 XML 문서를 읽어내기 위한 인터페이스입니다.

이 모듈은 원시 코드, 문서 모두 공개 도메인에 놓여져 있습니다. 따라서, 내용에 관한보증은 일절 제공되지 않습니다. 자세한 내용은 http://www.saxproject.org 를 참조하십시오.

주: 이 인터페이스는 그 이름에도 불구하고, 표준 Java Reader 인터페이스를 확장하지 않습니다. 이것은 XML 독해와 문자 데이터의 독해가 근본적으로 차이가 나기 때문입니다.

XMLReader는 XML 파서의 SAX2 드라이버가 구현해야 하는 필수 인터페이스입니다. 어플리케이션은 파서의 기능이나 프로퍼티의 설정 및 조회, 문서 처리를 위한 이벤트 핸들러의 등록, 문서의 구문 분석의 개시에 이 인터페이스를 사용합니다.

모든 SAX 인터페이스는 동기 하고 있는 것이라고 보여집니다. parse 메서드는 구문 분석이 완료할 때까지 종료하지 않습니다. 리더는 이벤트 핸들러의 콜백이 리턴된 것을 기다리고 나서, 다음의 이벤트를 보고합니다.

이 인터페이스는 현재는 비추천으로 가리키는 SAX 1.0 Parser 인터페이스에 대신하는 인터페이스입니다. XMLReader 인터페이스는 낡은 Parser 인터페이스나 일부의 마이너스적인 인터페이스의 기능에 가세해, 2개의 중요한 확장 기능을 갖추고 있습니다.

1. 기능이나 프로퍼티를 조회 및 설정하기 위한 표준적인 방법
2. 고도의 XML 표준으로 필요하게 되는 것이 많은 이름 공간의 지원

SAX1 Parser와 SAX2 XMLReader를 상호 변환하기 위한 어댑터도 준비되어 있습니다.

도입된 버전 :

SAX 2.0

관련 항목:

XMLFilter, ParserAdapter, XMLReaderAdapter

메서드 개요

ContentHandler	getContentHandler () 현재의 컨텐츠 핸들러를 리턴합니다.
DTDHandler	getDTDHandler () 현재의 DTD 핸들러를 리턴합니다.
EntityResolver	getEntityResolver () 현재의 엔티티리조르바를 리턴합니다.
ErrorHandler	getErrorHandler () 현재의 에러 핸들러를 리턴합니다.
boolean	getFeature (String name) 기능 플래그의 값을 검색합니다.
Object	getProperty (String name) 프로퍼티치를 검색합니다.
void	parse (InputSource input) XML 문서를 구문 분석 합니다.
void	parse (String systemId) 시스템 식별자 (URI)로부터 XML 문서를 구문 분석 합니다.
void	setContentHandler (ContentHandler handler) 어플리케이션에 컨텐츠 이벤트 핸들러의 등록을 허용합니다.
void	setDTDHandler (DTDHandler handler) 어플리케이션에 DTD 이벤트 핸들러의 등록을 허용합니다.
void	setEntityResolver (EntityResolver resolver) 어플리케이션에 엔티티리조르바의 등록을 허용합니다.
void	setErrorHandler (ErrorHandler handler) 어플리케이션에 에러 이벤트 핸들러의 등록을 허용합니다.
void	setFeature (String name, boolean value) 기능 플래그의 값을 설정합니다.
void	setProperty (String name, Object value) 프로퍼티치를 설정합니다.

메서드의 상세

getFeature

boolean getFeature(String  name)
                   throws SAXNotRecognizedException,

                          SAXNotSupportedException 

기능 플래그의 값을 검색합니다.

기능명은 완전 수식 URI 입니다. XMLReader는 기능명을 인식할 수 있습니다만, 동시에 그 값을 돌려줄 수 없습니다. 기능의 값에 따라서는 구문 분석의 실행전, 실행중, 실행 후등의 특정의 컨텍스트에 서만 사용 가능한 경우가 있습니다. 또, 프로그램에서는 액세스 할 수 없는 기능치도 있습니다. SAX1 Parser 어댑터의 경우, 기본이 되는 파서가 검증을 실행하고 있을지 어떨지나, 외부 엔티티를 확장하고 있을지 어떨지 등을 표시하는 방법은 구현에 존하지 않습니다.

모든 XMLReader는 http://xml.org/sax/features/namespaces와 http://xml.org/sax/features/namespace-prefixes 기능명을 인식할 필요가 있습니다.

일반적인 사용 방법은 다음과 같습니다.

 XMLReader r = new MySAXDriver();

                         // try to activate validation
 try {
   r.setFeature("http://xml.org/sax/features/validation", true);
 } catch (SAXException e) {
   System.err.println("Cannot activate validation. "); 
 }

                         // register event handlers
 r.setContentHandler(new MyContentHandler());
 r.setErrorHandler(new MyErrorHandler());

                         // parse the first document
 try {
   r.parse("http://www.foo.com/mydoc.xml");
 } catch (IOException e) {
   System.err.println("I/O exception reading XML document");
 } catch (SAXException e) {
   System.err.println("XML exception reading document. ");
 }
 

독자적인 URI에 근거해 작성된 이름을 사용해, 구현자가 독자적인 기능을 작성할 수도 있습니다 (추천).

파라미터:

name - 기능명. 완전 수식 URI 로 나타내진다

반환값:

기능의 현재의 값 (true 또는 false)

예외:

SAXNotRecognizedException - 기능의 값을 할당해 또는 취득할 수 없는 경우

SAXNotSupportedException - XMLReader가 기능명을 인식하는 것만으로 현시점에서는 그 값을 판단할 수 없는 경우

관련 항목:

setFeature(java.lang.String, boolean)

setFeature

void setFeature(String  name,
                boolean value)
                throws SAXNotRecognizedException,

                       SAXNotSupportedException 

기능 플래그의 값을 설정합니다.

기능명은 완전 수식 URI 입니다. XMLReader는 기능의 값을 표시할 수 있습니다만, 현재의 값을 변경할 수 없습니다. 기능의 값에 따라서는 구문 분석의 실행전, 실행중, 실행 후등의 특정의 컨텍스트에 서만 불변 또는 가변인 경우가 있습니다.

모든 XMLReader 로 http://xml.org/sax/features/namespaces와 http://xml.org/sax/features/namespace-prefixes가 false 로 설정되어 있을 필요가 있습니다.

파라미터:

name - 기능명. 완전 수식 URI 로 나타내지는

value - 기능의 요구된 값 (true 또는 false)

예외:

SAXNotRecognizedException - 기능의 값을 할당해 또는 취득할 수 없는 경우

SAXNotSupportedException - XMLReader가 기능명을 인식하는 것만으로 요구된 값을 설정할 수 없는 경우

관련 항목:

getFeature(java.lang.String)

getProperty

Object  getProperty(String  name)
                   throws SAXNotRecognizedException,

                          SAXNotSupportedException 

프로퍼티치를 검색합니다.

프로퍼티명은 완전 수식 URI 입니다. XMLReader는 프로퍼티명을 인식할 수 있습니다만, 일시적으로 그 값을 돌려줄 수 없습니다. 프로퍼티의 값에 따라서는 구문 분석의 실행전, 실행중, 실행 후등의 특정의 컨텍스트 으로 밖에 사용할 수 없는 경우가 있습니다.

SAX2에는 초기 코어 세트가 문서화 되고 있습니다만, XMLReader는 특정의 프로퍼티명을 인식할 수 없어도 괜찮습니다.

독자적인 URI에 근거해 작성된 이름을 사용해, 구현자가 독자적인 프로퍼티를 작성할 수도 있습니다 (추천).

파라미터:

name - 프로퍼티명. 완전 수식 URI 로 나타내진다

반환값:

현재의 프로퍼티치

예외:

SAXNotRecognizedException - 프로퍼티의 값을 할당해 또는 취득할 수 없는 경우

SAXNotSupportedException - XMLReader가 프로퍼티명을 인식하는 것만으로 현시점에서는 그 값을 판단할 수 없는 경우

관련 항목:

setProperty(java.lang.String, java.lang.Object)

setProperty

void setProperty(String  name,
                 Object  value)
                 throws SAXNotRecognizedException,

                        SAXNotSupportedException 

프로퍼티치를 설정합니다.

프로퍼티명은 완전 수식 URI 입니다. XMLReader는 프로퍼티명을 인식할 수 있습니다만, 현재의 값을 변경할 수 없습니다. 프로퍼티의 값에 따라서는 구문 분석의 실행전, 실행중, 실행 후등의 특정의 컨텍스트에 서만 불변 또는 가변인 경우가 있습니다.

코어 세트는 SAX2에 의해 정의되고 있습니다만, XMLReader는 특정의 프로퍼티명을 인식할 수 없어도 괜찮습니다.

이 메서드는 확장 핸들러의 설정에 사용하는 표준 도구이기도 합니다.

파라미터:

name - 프로퍼티명. 완전 수식 URI 로 나타내지는

value - 요구된 프로퍼티치

예외:

SAXNotRecognizedException - 프로퍼티의 값을 할당해 또는 취득할 수 없는 경우

SAXNotSupportedException - XMLReader가 프로퍼티명을 인식하는 것만으로 요구된 값을 설정할 수 없는 경우

setEntityResolver

void setEntityResolver(EntityResolver  resolver)

어플리케이션에 엔티티리조르바의 등록을 허용합니다.

어플리케이션이 엔티티리조르바를 등록하지 않으면 XMLReader가 디폴트의 해결을 독자적으로 실시합니다.

어플리케이션은 구문 분석중도 새로운 엔티티리조르바를 등록할 수 있습니다. 새로운 리절버가 등록되는 대로 SAX 파서는 즉시 이 리절버의 사용을 개시할 필요가 있습니다.

파라미터:

resolver - 엔티티리조르바

관련 항목:

getEntityResolver()

getEntityResolver

EntityResolver  getEntityResolver()

현재의 엔티티리조르바를 리턴합니다.

반환값:

현재의 엔티티리조르바. 등록되지 않은 경우는 null

관련 항목:

setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

void setDTDHandler(DTDHandler  handler)

어플리케이션에 DTD 이벤트 핸들러의 등록을 허용합니다.

어플리케이션이 DTD 핸들러를 등록하지 않으면 SAX 파서로부터 보고되는 모든 DTD 이벤트는 통지 없게 무시됩니다.

어플리케이션은 구문 분석중도 새로운 핸들러를 등록할 수 있습니다. 새로운 핸들러가 등록되는 대로 SAX 파서는 즉시 이 핸들러의 사용을 개시할 필요가 있습니다.

파라미터:

handler - DTD 핸들러

관련 항목:

getDTDHandler()

getDTDHandler

DTDHandler  getDTDHandler()

현재의 DTD 핸들러를 리턴합니다.

반환값:

현재의 DTD 핸들러. 등록되지 않은 경우는 null

관련 항목:

setDTDHandler(org.xml.sax.DTDHandler)

setContentHandler

void setContentHandler(ContentHandler  handler)

어플리케이션에 컨텐츠 이벤트 핸들러의 등록을 허용합니다.

어플리케이션이 컨텐츠 핸들러를 등록하지 않으면 SAX 파서로부터 보고되는 모든 컨텐츠 이벤트는 통지 없게 무시됩니다.

어플리케이션은 구문 분석중도 새로운 핸들러를 등록할 수 있습니다. 새로운 핸들러가 등록되는 대로 SAX 파서는 즉시 이 핸들러의 사용을 개시할 필요가 있습니다.

파라미터:

handler - 컨텐츠 핸들러

관련 항목:

getContentHandler()

getContentHandler

ContentHandler  getContentHandler()

현재의 컨텐츠 핸들러를 리턴합니다.

반환값:

현재의 컨텐츠 핸들러. 등록되지 않은 경우는 null

관련 항목:

setContentHandler(org.xml.sax.ContentHandler)

setErrorHandler

void setErrorHandler(ErrorHandler  handler)

어플리케이션에 에러 이벤트 핸들러의 등록을 허용합니다.

어플리케이션이 에러 핸들러를 등록하지 않으면 SAX 파서로부터 보고되는 모든 에러 이벤트는 통지 없게 무시됩니다. 다만, 보통 처리는 속행할 수 있습니다. 예상외의 버그를 회피하기 위해, 모든 SAX 어플리케이션에 에러 핸들러를 구현하는 것을 강하게 추천합니다.

어플리케이션은 구문 분석중도 새로운 핸들러를 등록할 수 있습니다. 새로운 핸들러가 등록되는 대로 SAX 파서는 즉시 이 핸들러의 사용을 개시할 필요가 있습니다.

파라미터:

handler - 에러 핸들러

관련 항목:

getErrorHandler()

getErrorHandler

ErrorHandler  getErrorHandler()

현재의 에러 핸들러를 리턴합니다.

반환값:

현재의 에러 핸들러. 등록되지 않은 경우는 null

관련 항목:

setErrorHandler(org.xml.sax.ErrorHandler)

parse

void parse(InputSource  input)
           throws IOException,

                  SAXException 

XML 문서를 구문 분석 합니다.

어플리케이션은 이 메서드를 사용해, 유효한 임의의 입력 소스 (문자 스트림, 바이트 스트림, 또는 URI)로부터 XML 문서의 구문 분석을 개시하도록 XML 리더에게 지시를 보냅니다.

구문 분석중은 어플리케이션으로부터 이 메서드를 호출할 수 없습니다. 어플리케이션은 상자가 되어 있는 각각의 XML 문서에 대해서 대신에 새로운 XMLReader를 작성할 필요가 있습니다. 구문 분석이 종료하면 어플리케이션은 같은 XMLReader 객체를 재이용합니다만, 다른 입력 소스에서의 재이용도 가능합니다. 기능 플래그나 프로퍼티로 설정된 핸들러 바인딩이나 값등의 XMLReader 객체의 구성은 구성의 그 면의 정의가 다른 동작을 명시적으로 지정하지 않는 한, 구문 분석이 종료해도 변경되지 않습니다. 이것에는 구문 분석 되고 있는 문서의 특성을 공개하는 기능 플래그나 프로퍼티가 있습니다.

구문 분석중, XMLReader는 등록을 마친 이벤트 핸들러를 개입시켜 XML 문서에 관한 정보를 제공합니다.

이 메서드는 동기 메서드이며, 구문 분석이 종료할 때까지는 종료하지 않습니다. 클라이언트 어플리케이션으로부터 구문 분석을 조기에 종료하는 요구가 있었을 경우는 예외를 Throw 합니다.

파라미터:

input - XML 문서의 톱 레벨의 입력 소스입니다.

예외:

SAXException - SAX 예외. 다른 예외를 랩 하고 있을 가능성이 있다

IOException - 파서로부터의 IO 예외. 보통, 어플리케이션이 제공하는 바이트 스트림 또는 문자 스트림로부터의 예외

관련 항목:

InputSource, parse(java.lang.String), setEntityResolver(org.xml.sax.EntityResolver), setDTDHandler(org.xml.sax.DTDHandler), setContentHandler(org.xml.sax.ContentHandler), setErrorHandler(org.xml.sax.ErrorHandler)

parse

void parse(String  systemId)
           throws IOException,

                  SAXException 

시스템 식별자 (URI)로부터 XML 문서를 구문 분석 합니다.

이 메서드를 사용하면, 시스템 식별자로부터 간단하게 문서를 읽어낼 수가 있습니다. 다음의 지정에서도 같은 것이 생깁니다.

parse(new InputSource(systemId));
 

시스템 식별자가 URL인 경우, 어플리케이션은 이것을 파서에 건네주기 전에 완전하게 해결할 필요가 있습니다.

파라미터:

systemId - 시스템 식별자 (URI)

예외:

SAXException - SAX 예외. 다른 예외를 랩 하고 있을 가능성이 있다

IOException - 파서로부터의 IO 예외. 보통, 어플리케이션이 제공하는 바이트 스트림 또는 문자 스트림로부터의 예외

관련 항목:

parse(org.xml.sax.InputSource)