org.xml.sax
인터페이스 XMLReader

기존의 서브 인터페이스의 일람:

XMLFilter

기존의 구현 클래스의 일람:

ParserAdapter , XMLFilterImpl

public interface XMLReader

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

이 모듈은 원시 코드, 문서 모두 공개 도메인에 놓여져 있습니다. 따라서, 내용에 관한프로텍션은 일절 제공되지 않습니다.

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

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

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

이 인터페이스는 현재는 비추천으로 지정되고 있는 SAX 1.0 의 Parser 인터페이스에 대신하는 인터페이스입니다. XMLReader 인터페이스는 낡은 Parser 인터페이스의 기능에 가세해, 2 kr의 중요한 확장 기능을 갖추고 있습니다.

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

public boolean getFeature(String  name)
                   throws SAXNotRecognizedException ,
                          SAXNotSupportedException 

기능의 값을 검색합니다.

기능명은 완전 수식 URI 로 나타내집니다. XMLReader 는 기능명을 인식합니다만, 그 값을 돌려줄 수 없습니다. 이것은 특히 SAX1 의 Parser 용 어댑터에 들어맞읍니다. 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 - XMLReader 가 기능명을 인식하지 않는 경우

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

관련 항목:

setFeature(java.lang.String, boolean)

setFeature

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

기능 상태를 설정합니다.

기능명은 완전 수식 URI 로 나타내집니다. XMLReader 는 기능명을 인식합니다만, 그 값을 설정할 수 없습니다. 이것은 특히 SAX1 의 Parser 용 어댑터에 들어맞읍니다. 예를 들어, SAX1 의 Parser 용 어댑터는 파서에 타당성을 검증을 실행시킬지 어떨지를 결정할 수가 없습니다.

모든 XMLReader 는 http://xml.org/sax/features/namespaces 와 http://xml.org/sax/features/namespace-prefixes 를 false 로 설정할 수 없으면 안됩니다.

일부의 기능의 값은 특정의 상황 (구문 분석전, 구문 분석중, 구문 분석 후등)으로만 불변 또는 가변이 됩니다.

파라미터:

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

예외:

SAXNotRecognizedException - XMLReader 가 기능명을 인식하지 않는 경우

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

관련 항목:

getFeature(java.lang.String)

getProperty

public Object  getProperty(String  name)
                   throws SAXNotRecognizedException ,
                          SAXNotSupportedException 

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

프로퍼티명은 완전 수식 URI 로 나타내집니다. XMLReader 는 프로퍼티를 인식하는 것만으로, 그 상태를 돌려줄 수 없습니다. 이것은 특히 SAX1 의 Parser 용 어댑터에 들어맞읍니다.

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

일부의 프로퍼티치는 특정의 상황 (구문 분석전, 구문 분석중, 구문 분석 후등)으로만 사용 가능합니다.

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

파라미터:

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

반환값:

현재의 프로퍼티치

예외:

SAXNotRecognizedException - XMLReader 가 프로퍼티명을 인식하지 않는 경우

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

관련 항목:

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

setProperty

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

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

프로퍼티명은 완전 수식 URI 로 나타내집니다. XMLReader 는 프로퍼티를 인식하는 것만으로, 그 값을 설정할 수 없습니다. 이것은 특히 SAX1 의 Parser 용 어댑터에 들어맞읍니다.

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

일부의 프로퍼티치는 특정의 상황 (구문 분석전, 구문 분석중, 구문 분석 후등)으로만 불변 또는 가변이 됩니다.

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

파라미터:

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

예외:

SAXNotRecognizedException - XMLReader 가 프로퍼티명을 인식하지 않는 경우

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

setEntityResolver

public void setEntityResolver(EntityResolver  resolver)

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

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

어플리케이션은 구문 분석중도 새로운 엔티티리조르바를 등록할 수 있습니다. 새로운 resolver가 등록되면(자), SAX 파서는 즉시 이 resolver의 사용을 개시하지 않으면 안됩니다.

파라미터:

resolver - 엔티티리조르바

예외:

NullPointerException - resolver 인수가 null 의 경우

관련 항목:

getEntityResolver()

getEntityResolver

public EntityResolver  getEntityResolver()

현재의 엔티티리조르바를 돌려줍니다.

반환값:

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

관련 항목:

setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

public void setDTDHandler(DTDHandler  handler)

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

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

어플리케이션은 구문 분석중도 새로운 핸들러를 등록할 수 있습니다. 새로운 핸들러가 등록되면(자), SAX 파서는 즉시 이 핸들러의 사용을 개시하지 않으면 안됩니다.

파라미터:

handler - DTD 핸들러

예외:

NullPointerException - 핸들러 인수가 null 의 경우

관련 항목:

getDTDHandler()

getDTDHandler

public DTDHandler  getDTDHandler()

현재의 DTD 핸들러를 돌려줍니다.

반환값:

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

관련 항목:

setDTDHandler(org.xml.sax.DTDHandler)

setContentHandler

public void setContentHandler(ContentHandler  handler)

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

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

어플리케이션은 구문 분석중도 새로운 핸들러를 등록할 수 있습니다. 새로운 핸들러가 등록되면(자), SAX 파서는 즉시 이 핸들러의 사용을 개시하지 않으면 안됩니다.

파라미터:

handler - 컨텐츠 핸들러

예외:

NullPointerException - 핸들러 인수가 null 의 경우

관련 항목:

getContentHandler()

getContentHandler

public ContentHandler  getContentHandler()

현재의 컨텐츠 핸들러를 돌려줍니다.

반환값:

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

관련 항목:

setContentHandler(org.xml.sax.ContentHandler)

setErrorHandler

public void setErrorHandler(ErrorHandler  handler)

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

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

어플리케이션은 구문 분석중도 새로운 핸들러를 등록할 수 있습니다. 새로운 핸들러가 등록되면(자), SAX 파서는 즉시 이 핸들러의 사용을 개시하지 않으면 안됩니다.

파라미터:

handler - 에러 핸들러

예외:

NullPointerException - 핸들러 인수가 null 의 경우

관련 항목:

getErrorHandler()

getErrorHandler

public ErrorHandler  getErrorHandler()

현재의 에러 핸들러를 돌려줍니다.

반환값:

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

관련 항목:

setErrorHandler(org.xml.sax.ErrorHandler)

parse

public void parse(InputSource  input)
           throws IOException ,
                  SAXException 

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

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

구문 분석중은 어플리케이션으로부터 이 메소드를 호출할 수 없습니다. 상자가 되어 있는 XML 문서 1 kr 1 kr에 대해서 새로운 XML 리더를 작성할 필요가 있습니다. 구문 분석이 완료하면(자), 같은 XMLReader 오브젝트를 재이용할 수 있습니다. 다른 입력 소스에서의 재이용도 가능합니다.

구문 분석중, XMLReader 는 등록을 마친 이벤트 핸들러를 개입시켜 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

public 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)