org.xml.sax
인터페이스 DocumentHandler

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

HandlerBase , ParserAdapter

추천 되고 있지 않습니다. 이 인터페이스는, 이름 공간을 지원하는 SAX2 의 ContentHandler 인터페이스로 옮겨놓을 수 있고 있습니다.

public interface DocumentHandler

일반적인 문서 이벤트의 통지를 받습니다.

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

이것은, SAX1, SAX2 의 메인 이벤트 처리 인터페이스였지만, 이름 공간 기능과 스킵 된 엔티티의 보고 기능을 지원하는 ContentHandler 로 옮겨놓을 수 있었습니다. 이 인터페이스는, SAX1 의 유산 어플리케이션의 지원 전용으로서 SAX2 에 포함할 수 있고 있습니다.

이 인터페이스내의 이벤트의 순서는, 문서 자체에 포함되는 정보의 순서를 밀러화한 것이어, 매우 중요합니다. 예를 들어, 어느 요소의 전컨텐츠 (문자 데이터, 처리 명령, 서브 요소등)는, startElement 이벤트와 이것에 대응하는 endElement 이벤트의 사이에 차례로 늘어놓을 수 있습니다.

어플리케이션의 작성자는, 인터페이스 전체를 구현할 필요가 없는 경우는, 디폴트 기능을 구현하는 HandlerBase 로부터 클래스를 파생할 수가 있습니다. 퍼서의 작성자는, HandlerBase 를 인스턴스화해 디폴트 핸들러를 취득할 수 있습니다. 어플리케이션은, Parser 가 제공하는 Locator 인터페이스를 사용해, setDocumentLocator 메소드로부터 임의의 문서 이벤트의 위치를 밝혀낼 수가 있습니다.

도입된 버젼:

SAX 1.0

관련 항목:

Parser.setDocumentHandler(org.xml.sax.DocumentHandler) , Locator , HandlerBase

메소드의 개요

void	characters (char[] ch, int start, int length) 추천 되고 있지 않습니다. 문자 데이터의 통지를 받습니다.
void	endDocument () 추천 되고 있지 않습니다. 문서의 종료 통지를 받습니다.
void	endElement (String name) 추천 되고 있지 않습니다. 요소의 종료 통지를 받습니다.
void	ignorableWhitespace (char[] ch, int start, int length) 추천 되고 있지 않습니다. 요소 컨텐츠에 포함되는 무시할 수 있는 공백 문자의 통지를 받습니다.
void	processingInstruction (String target, String data) 추천 되고 있지 않습니다. 처리 명령의 통지를 받습니다.
void	setDocumentLocator (Locator locator) 추천 되고 있지 않습니다. SAX 문서 이벤트의 발생원을 특정하는 객체를 받습니다.
void	startDocument () 추천 되고 있지 않습니다. 문서의 개시 통지를 받습니다.
void	startElement (String name, AttributeList atts) 추천 되고 있지 않습니다. 요소의 개시 통지를 받습니다.

메소드의 상세

setDocumentLocator

void setDocumentLocator(Locator  locator)

추천 되고 있지 않습니다.

SAX 문서 이벤트의 발생원을 특정하는 객체를 받습니다.

locator가 필요한 경우는, 필수 조건이 아닙니다만, SAX 퍼서를 사용하는 것을 강하게 추천합니다. SAX 퍼서는, DocumentHandler 인터페이스내의 어느 메소드보다 먼저 이 메소드를 호출해, 어플리케이션에 locator를 제공합니다.

어플리케이션은, locator를 이용해, 퍼서가 에러를 보고하지 않는 경우에서도 문서 관련 이벤트의 종료 위치를 특정할 수가 있습니다. 일반적으로, 어플리케이션은 이 정보를 사용해 고유의 에러 (문자 컨텐츠가 어플리케이션의 기능 규칙에 따르지 않은 등)를 보고합니다. 일반적으로, locator로부터 반환되는 정보는 불충분하고, 검색 엔진에서의 사용에 적절하고 있지 않습니다.

locator가 올바른 정보를 돌려주는 것은, 이 인터페이스내에서 이벤트 호출을 하고 있는 동안 뿐입니다. 그 이외 때, 어플리케이션으로 locator의 정보를 이용해야 하는 것이 아닙니다.

파라미터:

locator - SAX 문서 이벤트의 위치를 돌려주는 객체

관련 항목:

Locator

startDocument

void startDocument()
                   throws SAXException 

추천 되고 있지 않습니다.

문서의 개시 통지를 받습니다.

SAX 퍼서는, 이 메소드를 이 인터페이스내 또는 DTDHandler 내의 어느 메소드보다 먼저, 1 회만 호출합니다 (setDocumentLocator 를 제외한다).

예외:

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

endDocument

void endDocument()
                 throws SAXException 

추천 되고 있지 않습니다.

문서의 종료 통지를 받습니다.

SAX 퍼서는, 이 메소드를 구문 분석의 마지막에 1 회만 호출합니다. 회복 불가능한 에러에 의해 구문 분석이 도중에 파기되는지, 입력이 종료할 때까지, 이 메소드는 불려 가지 않습니다.

예외:

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

startElement

void startElement(String  name,
                  AttributeList  atts)
                  throws SAXException 

추천 되고 있지 않습니다.

요소의 개시 통지를 받습니다.

퍼서는 XML 문서내의 각 요소의 전으로 이 메소드를 호출합니다. 각 startElement() 이벤트에는 대응하는 endElement() 이벤트가 있습니다. 이것은, 요소가 빈 상태(empty)인 경우도 바뀌지 않습니다. 대응하는 endElement() 이벤트의 전에, 요소의 컨텐츠 전부가 차례로 보고됩니다.

요소명에 이름 공간 수식자가 붙어 있어도, 일전에치수식자가 삭제될 것은 없습니다. 제공되는 속성 리스트에는, 명시적인 값 (지정된 값 또는 디폴트 값)을 가지는 속성만이 포함됩니다. #IMPLIED 속성은 포함되지 않습니다.

파라미터:

name - 요소형명

atts - 요소에 부가된 속성 (존재하는 경우)

예외:

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

관련 항목:

endElement(java.lang.String) , AttributeList

endElement

void endElement(String  name)
                throws SAXException 

추천 되고 있지 않습니다.

요소의 종료 통지를 받습니다.

SAX 퍼서는, XML 문서내의 각 요소의 마지막에 이 메소드를 호출합니다. 각 endElement() 이벤트에는 대응하는 startElement() 이벤트가 있습니다. 이것은, 요소가 빈 상태(empty)인 경우도 바뀌지 않습니다.

요소명에 이름 공간앞치수식자가 붙어 있어도, 일전에치수식자가 삭제될 것은 없습니다.

파라미터:

name - 요소형명

예외:

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

characters

void characters(char[] ch,
                int start,
                int length)
                throws SAXException 

추천 되고 있지 않습니다.

문자 데이터의 통지를 받습니다.

퍼서는, 이 메소드를 호출해, 각 문자 데이타체크를 보고합니다. SAX 퍼서는, 연속하는 문자 데이터를 단일의 체크로서 또는 몇개의 체크에 분할해 돌려줍니다. 다만, locator로부터 유익한 정보를 얻기 위해서(때문에)는, 단일의 이벤트에 포함되는 문자가 모두 같은 외부 엔티티의 것이 아니면 안됩니다.

어플리케이션은, 지정된 범위외의 배열을 읽어낼 수 없습니다.

일부의 퍼서는, 이 메소드는 아니고 ignorableWhitespace() 메소드를 사용해, 요소 컨텐츠에 포함되는 공백 문자를 보고합니다. 이것은, 타당성을 검사하는 퍼서에게 필수의 기능입니다.

파라미터:

ch - XML 문서의 문자

start - 배열내의 개시 위치

length - 배열로부터 읽어내지는 문자수

예외:

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

관련 항목:

ignorableWhitespace(char[], int, int) , Locator

ignorableWhitespace

void ignorableWhitespace(char[] ch,
                         int start,
                         int length)
                         throws SAXException 

추천 되고 있지 않습니다.

요소 컨텐츠에 포함되는 무시할 수 있는 공백 문자의 통지를 받습니다.

타당성을 검사하는 퍼서는, 이 메소드를 사용해, 무시할 수 있는 공백 문자의 체크를 보고할 필요가 있습니다 (W3C XML 1.0 권고 섹션 2.10 을 참조). 타당성을 검사하지 않는 퍼서도, 컨텐츠 모델의 구문 분석 및 이용이 가능한 경우는, 이 메소드를 사용하는 경우가 있습니다.

SAX 퍼서는, 연속하는 모든 공백 문자를 단일의 체크로서 또는 복수의 체크에 분할해 돌려줍니다. 다만, locator로부터 유익한 정보를 얻기 위해서(때문에)는, 단일의 이벤트에 포함되는 문자가 모두 같은 외부 엔티티의 것이 아니면 안됩니다.

어플리케이션은, 지정된 범위외의 배열을 읽어낼 수 없습니다.

파라미터:

ch - XML 문서의 문자

start - 배열내의 개시 위치

length - 배열로부터 읽어내지는 문자수

예외:

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

관련 항목:

characters(char[], int, int)

processingInstruction

void processingInstruction(String  target,
                           String  data)
                           throws SAXException 

추천 되고 있지 않습니다.

처리 명령의 통지를 받습니다.

퍼서는, 처리 명령을 검출할 때마다 1 회씩 이 메소드를 호출합니다. 처리 명령은, 메인의 문서 요소의 전후에 존재할 가능성이 있습니다.

SAX 퍼서가, 이 메소드를 사용해 XML 선언을 보고할 것은 없습니다 (XML 1.0, 섹션 2.8). 또, 텍스트 선언을 보고하는 일도 없습니다 (XML 1.0, 섹션 4.3. 1).

파라미터:

target - 처리 명령의 타겟

data - 처리 명령 데이터. 데이터가 제공되지 않았던 경우는 null

예외:

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