org.xml.sax
인터페이스 ContentHandler

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

TemplatesHandler, TransformerHandler

알려진 구현 클래스 목록:

DefaultHandler, DefaultHandler2, ValidatorHandler, XMLFilterImpl, XMLReaderAdapter

public interface ContentHandler

문서의 논리 컨텐츠의 통지를 받습니다.

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

대부분의 SAX 어플리케이션이, 이 인터페이스를 구현하고 있습니다. 표준의 구문 분석 이벤트의 통지를 받을 필요가 있는 경우, 어플리케이션은 이 인터페이스를 구현해, org.xml.sax.XMLReader#setContentHandler setContentHandler 메서드를 사용해 인스턴스를 SAX 파서에 등록합니다. 파서는 이 인스턴스를 사용해, 요소나 문자 데이터의 개시, 종료라고 하는 표준의 문서 관련 이벤트를 보고합니다.

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

이 인터페이스는 현재는비추천으로 가리키는 SAX 1.0 DocumentHandler 인터페이스와 닮아 있습니다만, 새롭게 이름 공간의 지원와 타당성을 검증하지 않는 XML 프로세서로 스킵 된 실체의 보고의 지원가 추가되고 있습니다.

구현자는 java.net 패키지에 ContentHandler 클래스가 포함되어 있는 점을 고려해, 다음과 같은 처리는 반드시 피해 주세요.

import java.net. *;
 import org.xml.sax. *;
 

보통, 「import ...*」를 사용한 프로그램은 엉성한 (sloppy) 프로그램이라고 보여집니다. 사용자는 버그보다 이 점에 주위를 기울일 필요가 있습니다.

도입된 버전 :

SAX 2.0

관련 항목:

XMLReader, DTDHandler, ErrorHandler

메서드 개요

void	characters (char[] ch, int start, int length) 문자 데이터의 통지를 받습니다.
void	endDocument () 문서의 종료 통지를 받습니다.
void	endElement (String uri, String localName, String qName) 요소의 종료 통지를 받습니다.
void	endPrefixMapping (String prefix) 접두사와 URI 매핑의 스코프를 종료합니다.
void	ignorableWhitespace (char[] ch, int start, int length) 요소 컨텐츠에 포함되는 무시할 수 있는 공백 문자의 통지를 받습니다.
void	processingInstruction (String target, String data) 처리 명령의 통지를 받습니다.
void	setDocumentLocator (Locator locator) SAX 문서 이벤트의 발생원을 특정하는 객체를 받습니다.
void	skippedEntity (String name) 스킵 된 실체의 통지를 받습니다.
void	startDocument () 문서의 개시 통지를 받습니다.
void	startElement (String uri, String localName, String qName, Attributes atts) 요소의 개시 통지를 받습니다.
void	startPrefixMapping (String prefix, String uri) 접두사와 URI 이름 공간 매핑의 스코프를 개시합니다.

메서드의 상세

setDocumentLocator

void setDocumentLocator(Locator  locator)

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

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

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

locator는 startDocument 가 리턴된 뒤, endDocument 가 불려가기 전의 호출 SAX 이벤트 콜백중에 한해 적정한 정보를 리턴합니다. 어플리케이션은 호출 SAX 이벤트 콜백 이외에 locator를 사용할 수 없습니다.

파라미터:

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

관련 항목:

Locator

startDocument

void startDocument()
                   throws SAXException 

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

SAX 파서는 다른 이벤트가 콜백 되기 전에 1회 만 이 메서드를 호출합니다 (setDocumentLocator 이외).

예외:

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

관련 항목:

endDocument()

endDocument

void endDocument()
                 throws SAXException 

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

이 메서드의 메뉴얼과 endDocument() 메뉴얼과의 사이에는 분명하게 모순이 있습니다. 클라이언트는 향후의 메이저 릴리스로 이 애매함이 해결되지 않는 한, 파서가 fatalError()를 보고하거나 예외를 Throw 했을 때에 endDocument()가 불려 갈지 어떨지를 가정하지 않게 할 필요가 있습니다.　

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

예외:

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

관련 항목:

startDocument()

startPrefixMapping

void startPrefixMapping(String  prefix,
                        String  uri)
                        throws SAXException 

접두사와 URI 이름 공간 매핑의 스코프를 개시합니다.

보통 의 이름 공간 처리는 이벤트로부터 제공되는 정보를 필요로 하지 않습니다. SAX XML 리더는 http://xml.org/sax/features/namespaces 기능의 값이 true (디폴트)로 설정되어 있으면, 요소 및 속성명의 접두사를 자동적으로 옮겨놓습니다.

그러나, 어플리케이션에 의해 문자 데이터나 속성값 안에서 사용되는 경우, 접두사를 안전하게 전개할 수 없습니다. 이러한 어플리케이션에는 필요에 따라서, start/endPrefixMapping 이벤트에의해 접두사를 어플리케이션 컨텍스트 내에서 확장하기 위해서 필요한 정보가 제공됩니다.

start/endPrefixMapping 이벤트가 각각 올바르게 상자로 될지 어떨지는 보증되지 않습니다. 모든 startPrefixMapping 이벤트는 대응하는 startElement 이벤트의 전에 즉시 발생해, 모든 endPrefixMapping 이벤트는 대응하는 endElement 이벤트의 나중에 발생합니다만, 이러한 차례는 보증되지 않습니다.

「xml」접두사는 사전에 선언되는 불변의 수식자이므로 그 start/endPrefixMapping 이벤트는 존재하지 않습니다.

파라미터:

prefix - 선언되는 이름 공간 접두사. 디폴트에 한 요소의 이름 공간에 사용하는 공문자열 (접두사 없음).

uri - 접두사의 맵 사키나 마에조라간 URI

예외:

SAXException - 처리중에 클라이언트가 예외를 Throw 하는 일이 있는

관련 항목:

endPrefixMapping(java.lang.String), startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endPrefixMapping

void endPrefixMapping(String  prefix)
                      throws SAXException 

접두사와 URI 매핑의 스코프를 종료합니다.

자세한 것은 startPrefixMapping를 참조하십시오. 이러한 이벤트는 항상, 대응하는 endElement 이벤트의 후에 곧 발생합니다만, endPrefixMapping 이벤트의 차례는 보증되지 않습니다.

파라미터:

prefix - 매핑 된 접두사. 디폴트 매핑의 스코프가 종료하는 경우는 공문자열이 된다

예외:

SAXException - 처리중에 클라이언트가 예외를 Throw 하는 일이 있는

관련 항목:

startPrefixMapping(java.lang.String, java.lang.String), endElement(java.lang.String, java.lang.String, java.lang.String)

startElement

void startElement(String  uri,
                  String  localName,
                  String  qName,
                  Attributes  atts)
                  throws SAXException 

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

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

이 이벤트에서는 각 요소에 최대 3개의 이름 컴퍼넌트를 허용합니다.

1. 이름 공간 URI
2. 로컬명
3. 접두사 첨부의 수식명

http://xml.org/sax/features/namespaces 프로퍼티 및 http://xml.org/sax/features/namespace-prefixes 프로퍼티의 값에의해 이러한 어떤 것인가 또는 전부가 제공됩니다.

• 이름 공간 URI와 로컬명은 namespaces 프로퍼티가 true (디폴트)인 경우는 필수. namespaces 프로퍼티가 false 인 경우는 옵션 (한편이 지정되고 있으면 양쪽 모두가 필요)
• 수식명은 namespace-prefixes 프로퍼티가 true 인 경우는 필수. namespace-prefixes 프로퍼티가 false (디폴트)인 경우는 옵션

제공되는 속성 리스트에는 명시적인 값 (지정된 값 또는 기본값)을 가지는 속성만이 포함됩니다. #IMPLIED 속성은 포함되지 않습니다. 이 리스트에는 http://xml.org/sax/features/namespace-prefixes 프로퍼티가 true (디폴트의 설정은 false. true 지원은 옵션)인 경우에 한정해, 이름 공간 정의 (xmlns* 속성)에 사용되는 속성이 포함됩니다.

속성값는 characters() 와 같이 2개 이상의 char값을 필요로 하는 캐릭터 라인을 가지는 경우가 있습니다.

파라미터:

uri - 이름 공간 URI. 요소가 이름 공간 URI를 가지지 않는 경우, 또는 이름 공간 처리를 하지 않는 경우는 공문자열

localName - 접두사를 포함하지 않는 로컬명. 이름 공간 처리를 하지 않는 경우는 공문자열

qName - 접두사를 가지는 수식명. 수식명을 사용할 수 없는 경우는 공문자열

atts - 요소에 추가된 속성. 속성이 없는 경우는 비어있는 Attributes 객체가 된다. startElement가 리턴된 뒤의 이 객체의 값은 정의되지 않는다

예외:

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

관련 항목:

endElement(java.lang.String, java.lang.String, java.lang.String), Attributes, AttributesImpl

endElement

void endElement(String  uri,
                String  localName,
                String  qName)
                throws SAXException 

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

SAX 파서는 XML 문서내의 각 요소의 마지막에 이 메서드를 호출합니다. 각 endElement 이벤트에는 대응하는 startElement 이벤트가 있습니다. 이것은 요소가 비어있는 경우도 바뀌지 않습니다.

이름에 대해서는 startElement를 참조하십시오.

파라미터:

uri - 이름 공간 URI. 요소가 이름 공간 URI를 가지지 않는 경우, 또는 이름 공간 처리를 하지 않는 경우는 공문자열

localName - 접두사를 포함하지 않는 로컬명. 이름 공간 처리를 하지 않는 경우는 공문자열

qName - 접두사를 가지는 수식된 XML 명. 수식명을 사용할 수 없는 경우는 공문자열

예외:

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

characters

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

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

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

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

각각의 캐릭터 라인은 2개 이상의 Java char값으로 구성됩니다. 캐릭터 라인을 16 비트 이내에서 표시할 수 없기 때문에 2개의 중요한 케이스가 발생합니다. 1개는 캐릭터 라인이 2개의 Unicode값을 사용해 「Surrogate Pair」로 나타내지는 것입니다. 이러한 캐릭터 라인은 「Astral Planes」라고 불려 U+FFFF 보다 큰 코드 포인트를 가집니다. 이제(이미 ) 1개는 1개 이상의 엑센트 문자에 결합하고 있는 베이스 캐릭터 라인등의 합성 캐릭터 라인이 되는 것입니다.

char-at-a-time 관용법을 사용하는 알고리즘은 캐릭터 라인을 분할하는 경우도 있으므로 캐릭터 라인 단위로 처리하고 있으면 상정 해서는 안됩니다. 이것은 XML가 속성값, 처리 명령 데이터, 코멘트등의 임의의 캐릭터 라인이나, 이 메서드로부터 보고된 데이터내에 있는 임의의 캐릭터 라인을 허가하는 장소에 관련합니다. 또, 일반적으로는 Java 코드가 국제화 된 텍스트를 조작하는 장소에 관련합니다만, 발행은 XML에 일의의 것이 아닙니다.

일부의 파서는 이 메서드가 아니고 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).

처리 명령 데이터는 characters() 와 같이 2개 이상의 char값을 필요로 하는 캐릭터 라인을 가지는 경우가 있습니다.

파라미터:

target - 처리 명령의 타겟

data - 처리 명령을 받는 데이터. 데이터가 제공되지 않는 경우는 null. 데이터에는 타겟과 자신을 구별하기 위한 공백 문자는 포함되지 않는다

예외:

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

skippedEntity

void skippedEntity(String  name)
                   throws SAXException 

스킵 된 실체의 통지를 받습니다. 이것은 요소 개시 태그나 마크 업 선언등의 마크 업 구조내의 실체 참조에 대해서는 불려가 지 않습니다. XML 권고에서는 스킵 된 외부 실체의 보고가 필요합니다. 또, SAX도 마크 업 구조내를 제외한 내부 실체의 확장의 유무를 보고합니다.

파서는 실체가 스킵 될 때마다 1회 씩 이 메서드를 호출합니다. 타당성을 검증하지 않는 프로세서는 (실체가 외부 DTD 부분집합내에 정의되고 있는 등의 이유로써) 선언이 검출되지 않으면 실체를 스킵 합니다. 모든 프로세서는 http://xml.org/sax/features/external-general-entities 프로퍼티와 http://xml.org/sax/features/external-parameter-entities 프로퍼티의 값에의해 외부 실체를 스킵 할 가능성이 있습니다.

파라미터:

name - 스킵 된 실체의 이름. 파라미터 실체의 경우, 이 이름은 「%」로 시작된다. 외부 DTD 부분집합의 경우, 캐릭터 라인 「[dtd]」로 시작된다

예외:

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