org.w3c.dom.ls
인터페이스 LSParser

public interface LSParser

다양한 입력 소스로부터 DOM 트리를 구축 또는 확장할 수 있는 객체에의 인터페이스입니다.

LSParser는 XML를 해석해, 대응하는 DOM 문서 구조를 구축하기 위한 API를 제공합니다. LSParser인스턴스는 DOMImplementationLS.createLSParser() 메서드를 호출해 취득할 수 있습니다.

「DOM Level 3 Core」로 지정되고 있도록, 문서를 LSParser를 개입시켜 이용할 수 있는 경우

• NODE_TEXT 형의 인접하는 2개의 노드는 존재하지 않는다. 또, 비어있는 텍스트 노드도 존재하지 않는다
• Attr 노드의 value 속성과 nodeValue 속성은, 「XML 1.0 normalized value」를 최초로 돌려준다. 다만, 「validate-if-schema」파라미터와「datatype-normalization」파라미터가 true로 설정되어 있는 경우, 사용하고 있는 속성 정규화에 응해, 속성값는 XML 1.0 속성 정규화로 취득된 속성값와는 다를 가능성이 있다. 「datatype-normalization」파라미터가 false로 설정되어 있는 경우는 XML 1.0 속성 정규화의 발생이 보증되어 속성 리스트가 이름 공간 선언을 포함하지 않는 경우, Element 노드의 attributes 속성은「XML Information Set」로 정의되고 있는 [attributes] 프로퍼티를 나타낸다

비동기 LSParser객체는 events::EventTarget인터페이스도 구현합니다. 따라서, 비동기 LSParser 객체에 이벤트 리스너를 등록할 수 있습니다.

비동기 LSParser 객체가 지원 하고 있는 이벤트는 다음과 같습니다.

로드

LSParser는 문서의 로드를 완료 합니다. LSLoadEvent인터페이스의 정의도 참조하십시오.

진척

LSParser는 데이터를 해석할 때에 진척을 통지합니다. 이 사양에서는 진척 이벤트를 정확하게 언제 디스패치 할 필요가 있는지 정의하지 않습니다. 즉, 도적으로 구현 존대로 되어 있어. 여기에서는 어플리케이션이 진척 이벤트를 디스패치 하는 방법의 일례를 나타냅니다. 파서가 데이터의 수신을 개시하면, 진척 이벤트가 디스 패치 되어 해석이 개시된 것을 나타냅니다. 이 이후, 수신 및 해석함 4096 바이트의 데이터 마다 진척 이벤트가 디스패치 됩니다.이것은 일례에 지나지 않습니다만, 구현에서는 해석중에 언제라도 진척 이벤트를 디스패치 하도록, 또는 전혀 디스패치 하지 않게 선택 할 수 있습니다. LSProgressEvent인터페이스도 참조하십시오.

주: 이 사양으로 정의 떠날 수 있어 모든 이벤트는 이름 공간 URI 「http://www.w3.org/2002/DOMLS」를 사용합니다.

입력 소스를 해석중, 에러는 에러 핸들러 (LSParser.domConfig 「error-handler」파라미터)를 사용해 보고됩니다. 이 사양에서는 XML 나 다른 마크 업을 해석중에 발생할 가능성이 있는 모든 에러는 정의되지 않습니다 만, 일반적인 에러 케이스의 일부를 정의하고 있습니다. 이 사양으로 정의되고 있는 에러의 종류 (DOMError.type) 고 경고는 다음과 같습니다.

"check-character-normalization-failure" [error]

「check-character-normalization」 파라미터가 true 로 설정되어 있어, 캐릭터 라인으로 정규화 체크가 실패 했을 경우에 리턴됩니다 .

"doctype-not-allowed" [fatal]

disallow-doctype 구성 파라미터가 true (으)로 설정되어 있어, 「doctype」가 검출되었을 경우에 리턴됩니다 .

"no-input-specified" [fatal]

문서를 로드해, LSInput 객체로 입력이 지정되지 않는다 경우에 리턴됩니다 .

"pi-base-uri-not-preserved" [warning]

처리 명령의 베이스 URI를 보관 유지할 수 없는 장소에서 처리 명령이 검출되었을 경우에 리턴됩니다 . 이 경고가 리턴된 일례에는 다음과 같이「entities」 구성 파라미터가 false로 설정되어 있어, XML 파일이 해석되었을 경우를 들 수 있습니다.

<! DOCTYPE root [ <! ENTITY e SYSTEM 'subdir/myentity.ent' ]>
<root> &e; </root>

또, subdir/myentity.ent이 다음을 포함한 경우

<one> <two/> </one> <? pi 3.14159? >

<more/>

"unbound-prefix-in-entity" [warning]

「namespaces」구성 파라미터가 true로 설정되어 있어, 바인드되어 있지 않은 이름 공간의 접두사가 실체의 치환 텍스트로 검출되었을 경우는 구현 존의 경고가 리턴됩니다 . 이 경고를 돌려주는 것은 강제당하지 않습니다. 이것은 일부의 기존의 파서가 실체의 치환 텍스트에 있는 바인드되어 있지 않은 이름 공간의 접두사를 인식하지 않을 가능성이 있기 때문에입니다.

"unknown-character-denormalization" [fatal]

「ignore-unknown-character-denormalizations」구성 파라미터가 false로 설정되어 있어, 정규화 프로퍼티를 판정할 수 없는 문자가 처리로 검출되었을 경우에 리턴됩니다 .

"unsupported-encoding" [fatal]

지원 되어 있지 않은 인코딩이 검출되었을 경우에 리턴됩니다 .

"unsupported-media-type" [fatal]

「supported-media-types-only」구성 파라미터가 true로 설정되어 있어, 지원 되어 있지 않은 미디어 타입이 검출되었을 경우에 리턴됩니다 .

정의 끝난 에러나 경고를 돌려주는데 더해, 구현에서는 IO 에러 ( 「파일이 발견되지 않습니다, 접근 권한은 거부되었습니다 ...」), XML 정형식 에러등을 부르는 다른 에러나 경고에 대해 구현 고유의 에러를 리턴합니다.

「Document Object Model (DOM) Level 3 Load and Save Specification」도 참조하십시오.

필드 개요

static short	ACTION_APPEND_AS_CHILDREN 해석 조작의 결과를 컨텍스트 노드의자식 로서 추가합니다.
static short	ACTION_INSERT_AFTER 해석 조작의 결과를 컨텍스트 노드의 직후의 형제 위제트로서 삽입합니다.
static short	ACTION_INSERT_BEFORE 해석 조작의 결과를 컨텍스트 노드의 직전의 형제 위제트로서 삽입합니다.
static short	ACTION_REPLACE 컨텍스트 노드를 해석 조작의 결과에 옮겨놓습니다.
static short	ACTION_REPLACE_CHILDREN 컨텍스트 노드의 모든 자식을 해석 조작의 결과에 옮겨놓습니다.

메서드 개요

void	abort () 현재 LSParser로 로드 되고 있는 문서의 로딩을 중단합니다.
boolean	getAsync () LSParser가 비동기의 경우는 true, 동기의 경우는 false 입니다.
boolean	getBusy () LSParser가 현재 문서를 로드하고 있어, Busy 상태의 경우는 true, 그렇지 않은 경우는 false 입니다.
DOMConfiguration	getDomConfig () 입력 소스를 해석할 경우에 사용되는 DOMConfiguration 객체입니다.
LSParserFilter	getFilter () 필터가 있는 경우, DOM 트리 구조를 필터가 구성해 있는것 같이, 구현은 필터를 호출합니다.
Document	parse (LSInput input) LSInput로 식별된 자원으로부터 XML 문서를 해석합니다.
Document	parseURI (String uri) URI 참조「IETF RFC 2396」으로 특정된 장소로부터 XML 문서를 해석합니다.
Node	parseWithContext (LSInput input, Node contextArg, short action) LSInput에 의해 특정된 자원으로부터 XML fragment를 해석해, 기존의 문서의 context인수와 action인수로 지정된 위치에 컨텐츠를 삽입합니다.
void	setFilter (LSParserFilter filter) 필터가 있는 경우, DOM 트리 구조를 필터가 구성해 있는것 같이, 구현은 필터를 호출합니다.

필드의 상세

ACTION_APPEND_AS_CHILDREN

static final short ACTION_APPEND_AS_CHILDREN

해석 조작의 결과를 컨텍스트 노드의자식 로서 추가합니다. 이 액션이 기능하려면, 컨텍스트 노드가Element 또는 DocumentFragment이 되어 있을 필요가 있습니다.

관련 항목:

정수 필드값

ACTION_REPLACE_CHILDREN

static final short ACTION_REPLACE_CHILDREN

컨텍스트 노드의 모든 자식을 해석 조작의 결과에 옮겨놓습니다. 이 액션이 기능하려면, 컨텍스트 노드가Element, Document, 혹은 DocumentFragment이 되어 있을 필요가 있습니다.

관련 항목:

정수 필드값

ACTION_INSERT_BEFORE

static final short ACTION_INSERT_BEFORE

해석 조작의 결과를 컨텍스트 노드의 직전의 형제 위제트로서 삽입합니다. 이 액션이 기능하려면, 컨텍스트 노드의 부모가Element 또는 DocumentFragment로가 되어 있을 필요가 있습니다.

관련 항목:

정수 필드값

ACTION_INSERT_AFTER

static final short ACTION_INSERT_AFTER

해석 조작의 결과를 컨텍스트 노드의 직후의 형제 위제트로서 삽입합니다. 이 액션이 기능하려면, 컨텍스트 노드의 부모가Element 또는 DocumentFragment이 되어 있을 필요가 있습니다.

관련 항목:

정수 필드값

ACTION_REPLACE

static final short ACTION_REPLACE

컨텍스트 노드를 해석 조작의 결과에 옮겨놓습니다. 이 액션이 기능하려면, 컨텍스트 노드가 부모를 가지지 않으면 안되어, 그 부모가 Element 또는 DocumentFragment이 되어 있을 필요가 있습니다.

관련 항목:

정수 필드값

메서드의 상세

getDomConfig

DOMConfiguration  getDomConfig()

입력 소스를 해석할 경우에 사용되는 DOMConfiguration 객체입니다. 이 DOMConfiguration는 해석 조작에 고유합니다. 또, DOMConfiguration 객체의 파라미터값는 해석 조작에 보다 작성 또는 사용되는 Document DOMConfiguration 객체에 자동적으로 건네받을 것은 없습니다. DOM 어플리케이션이, DOMConfiguration 객체로부터, Document 객체가 참조하는 DOMConfiguration 객체에 필요한 파라미터값를 건네주는 권한을 가집니다.
「DOM Level 3 Core」로 정의된「DOMConfiguration」 인터페이스로 인식되고 있는 파라미터에 가세해, LSParser DOMConfiguration객체는 다음의 파라미터를 추가 또는 변경합니다.

"charset-overrides-xml-encoding"

true

「옵션」(디폴트) HTTP「IETF RFC 2616」 등의 고위 레벨 프로토콜이 처리중의 입력 스트림의 문자 인코딩을 지시하는 경우, XML 선언이나 텍스트 선언 ( 「XML 1.0」의 섹션 4.3. 3 「실체의 문자 인코딩」도 참조) 그리고 지정된 인코딩은 고위 레벨 프로토콜에 한 문자 인코딩에 의해 오버라이드(override) 됩니다. 또, LSInput 그리고 명시적으로 인코딩을 설정하면, 프로토콜의 인코딩은 오버라이드(override) 됩니다.

false

「필수」 파서는 고위 레벨 프로토콜의 캐릭터 세트 인코딩 정보를 무시합니다.

"disallow-doctype"

true

「옵션」문서를 해석중에 doctype 노드가 발견되었을 경우, 치명적인 에러의 「doctype-not-allowed」를 Throw 합니다. 이것은 doctype 노드가 허가되지 않는 SOAP 포락선과 같은 것을 취급하면 나무에 도움이 됩니다.

false

「필수」 (디폴트) 문서로 doctype 노드를 허용합니다.

"ignore-unknown-character-denormalizations"

true

「필수」(디폴트) 「XML 1.1」을 지원 하고 있어, 완전한 정규화를 확인중에 정규화 프로퍼티 를 판정할 수 없는 문자를 프로세서가 검출했을 경우, 프로세서는 그 문자로 생기고 가능성이 있는 불완전한 정규화를 무시합니다. 이 파라미터는 「XML 1.0」 에 대해서는 무시됩니다.

false

「옵션」정규화 프로퍼티를 판정할 수 없는 문자를 프로세서가 검출했을 경우, 치명적인 에러의 「unknown-character-denormalization」 를 통지합니다.

"infoset"

이 파라미터의 상세한 것에 대하여는 DOMConfiguration 정의를 참조하십시오. 「DOM Level 3 Core」 과는 달리, 이 파라미터는 LSParser에 대해서 디폴트로 true로 설정됩니다.

"namespaces"

true

「필수」(디폴트) XML 이름 공간 (와)과 XML 이름 공간 1.1 정의에 따라 이름 공간 처리를 실시합니다.

false

「옵션」이름 공간 처리를 실행하지 않습니다.

"resource-resolver"

「필수」 LSResourceResolver 객체에 대한 참조, 또는 null. 외부 자원 (외부 XML 실체 또는 XML schema 로케이션)이 검출되고 때에 이 파라미터가 null이 아닌 경우, 구현은 이 파라미터로 참조된 LSResourceResolver에 의해 자원을 해결하도록 요구합니다.

"supported-media-types-only"

true

「옵션」해석되었다 자원의 미디어 타입이 지원 되고 있는 미디어 타입인 것을 체크합니다. 지원 되어 있지 않은 미디어 타입이 검출되었을 경우, 형태「unsupported-media-type」의 치명적 에러가 리턴됩니다 . 「IETF RFC 3023」 그리고 정의되고 있는 미디어 타입은 항상 받아들여집니다.

false

「필수」(디폴트) 임의의 미디어 타입을 받아들입니다.

"validate"

이 파라미터의 상세한 것에 대하여는 DOMConfiguration 정의를 참조하십시오. 「DOM Level 3 Core」 과는 달리, 이 파라미터가 false로 설정되었을 경우, 내부 부분집합의 처리는 항상 실행됩니다.

"validate-if-schema"

이 파라미터의 상세한 것에 대하여는 DOMConfiguration 정의를 참조하십시오. 「DOM Level 3 Core」란 달라, 이 파라미터가 false (으)로 설정되었을 경우, 내부 부분집합의 처리는 항상 실행됩니다.

"well-formed"

이 파라미터의 상세한 것에 대하여는 DOMConfiguration 정의를 참조하십시오. 「DOM Level 3 Core」란 달라, 이 파라미터는 false로 설정할 수 없습니다.

getFilter

LSParserFilter  getFilter()

필터가 있는 경우, DOM 트리 구조를 필터가 구성해 있는것 같이, 구현은 필터를 호출합니다. 필터에서는 구축하고 있는 문서로부터 요소를 삭제하거나 초기에 해석을 종료하거나 하는 것을 선택할 수 있습니다.
필터는 DOMConfiguration 파라미터로 요구된 조작이 적용된 뒤에 호출합니다. 예를 들어, 「validate」가 true로 설정되어 있으면, 검증은 필터가 불려가기 전에 실행됩니다.

setFilter

void setFilter(LSParserFilter  filter)

필터가 있는 경우, DOM 트리 구조를 필터가 구성해 있는것 같이, 구현은 필터를 호출합니다. 필터에서는 구축하고 있는 문서로부터 요소를 삭제하거나 초기에 해석을 종료하거나 하는 것을 선택할 수 있습니다.
필터는 DOMConfiguration 파라미터로 요구된 조작이 적용된 뒤에 호출합니다. 예를 들어, 「validate」가 true로 설정되어 있으면, 검증은 필터가 불려가기 전에 실행됩니다.

getAsync

boolean getAsync()

LSParser가 비동기의 경우는 true, 동기의 경우는 false 입니다.

getBusy

boolean getBusy()

LSParser가 현재 문서를 로드하고 있어, Busy 상태의 경우는 true, 그렇지 않은 경우는 false 입니다.

parse

Document  parse(LSInput  input)
               throws DOMException,

                      LSException 

LSInput로 식별된 자원으로부터 XML 문서를 해석합니다.

파라미터:

input - 문서의 소스가 읽어내지는 LSInput

반환값:

LSParser가 동기 LSParser인 경우는 새롭게 작성되어 값이 설정된 Document이 리턴된다. LSParser가 비동기의 경우는 이 메서드가 값을 돌려줄 때 문서 객체가 아직 구축되어 있지 않을 가능성이 있으므로null이 리턴된다

예외:

DOMException - INVALID_STATE_ERR: LSParser LSParser.busy 속성이 true인 경우

LSException - PARSE_ERR: LSParser가 XML 문서를 로드할 수 없었던 경우. DOM 에러에 관한 상세를 얻는인 경우, 어플리케이션은「error-handler」파라미터를 사용해 DOMErrorHandler를 접속할 필요가 있다

parseURI

Document  parseURI(String  uri)
                  throws DOMException,

                         LSException 

URI 참조「IETF RFC 2396」으로 특정된 장소로부터 XML 문서를 해석합니다. URI에 fragment 식별자가 포함되는 경우 (「IETF RFC 2396」의 섹션 4.1을 참조), 이 사양에서는 동작은 정의되지 않습니다. 동작은 이 사양의 장래 버전 으로 정의될 가능성이 있습니다.

파라미터:

uri - 읽어내지는 XML 문서의 장소

반환값:

LSParser가 동기 LSParser인 경우는 새롭게 작성되어 값이 설정된 Document이 리턴된다. 에러가 발생했을 경우는 null이 리턴된다. LSParser가 비동기의 경우는 이 메서드가 값을 돌려줄 때 문서 객체가 아직 구축되어 있지 않을 가능성이 있으므로null이 리턴된다

예외:

DOMException - INVALID_STATE_ERR: LSParser.busy 속성이 true인 경우

LSException - PARSE_ERR: LSParser가 XML 문서를 로드할 수 없었던 경우. DOM 에러에 관한 상세를 얻는인 경우, 어플리케이션은「error-handler」파라미터를 사용해 DOMErrorHandler를 접속할 필요가 있다

parseWithContext

Node  parseWithContext(LSInput  input,
                      Node  contextArg,
                      short action)
                      throws DOMException,

                             LSException 

LSInput에 의해 특정된 자원으로부터 XML fragment를 해석해, 기존의 문서의 context인수와 action인수로 지정된 위치에 컨텐츠를 삽입합니다. 입력 스트림을 해석중, 컨텍스트 노드 (또는 그 부모. 결과가 삽입되는 장소에 응해 다르다)는 바인드되어 있지 않은 이름 공간 접두사를 해결하기 위해서 사용됩니다. 컨텍스트 노드의 ownerDocument 노드 (노드형이 DOCUMENT_NODE인 경우는 노드 자체)는 디폴트 속성과 실체 참조를 해결하기 위해서 사용됩니다.
새로운 데이터가 문서에 삽입될 때, 컨텍스트 노드의 새로운 직접적인자식 또는 형제 위제트 마다 적어도 1개의 변경 이벤트가 트리거 됩니다.
컨텍스트 노드가 Document 노드이며, 액션이 ACTION_REPLACE_CHILDREN인 경우, 컨텍스트 노드로서 건네받는 문서는 xmlEncoding, documentURI, xmlVersion, inputEncoding, xmlStandalone 및 다른 모든 같은 속성이, LSParser.parse()를 사용해 입력 소스가 해석되었을 경우로 설정되는 값으로 설정되도록 변경됩니다.
이 메서드는 LSParser가 비동기의 경우에서도 (LSParser.async는 true), 항상 동출력니다.
해석중에 에러가 발생하면, DOMConfiguration 「error-handler」파라미터에 관련된 ErrorHandler인스턴스를 통해서 호출해 측에 통지됩니다.
parseWithContext를 호출하고 있을 때는 「validate」, 「validate-if-schema」, 「element-content-whitespace」의 구성 파라미터의 값은 무시되어 항상 기본값이 사용됩니다. 다른 파라미터는 보통 대로 사용되어 파서는 문서 전체를 해석했는지와 같이, LSParserFilter를 호출합니다.

파라미터:

input - 소스 문서가 읽어내지는 LSInput. 소스 문서는 XML fragment, 즉 완전한 XML 문서 (컨텍스트 노드가 DOCUMENT_NODE 형, 액션이 ACTION_REPLACE_CHILDREN인 경우를 제외하다), DOCTYPE (내부 부분집합), 실체 선언, 표기법선언, 혹은 XML 선언 또는 텍스트 선언) 이외에 될 필요가 있는

contextArg - 해석되는 데이터의 컨텍스트 으로서 사용되는 노드. 이 노드는 Document 노드, DocumentFragment 노드, 혹은 Element 노드의자식 로서 허가되는 형태의 노드가 될 필요가 있다. 예를 들어, Attribute 노드는 불가

action - 이 파라미터는 삽입되고 있는 새로운 노드 세트와 컨텍스트 노드의 기존의자식와의 사이에 실행할 필요가 있는 액션을 나타낸다. 생각되는 액션세트는 전술의 ACTION_TYPES 으로 정의된다

반환값:

해석 조작의 결과인 노드. 결과가 톱 레벨 노드보다 고위에 있는 경우는 최초의 노드가 리턴된다

예외:

DOMException - HIERARCHY_REQUEST_ERR: 컨텐츠를 컨텍스트 노드의자식에 게 옮겨놓거나 컨텍스트 노드의자식 의 앞이나 뒤로 삽입할 수 없는 경우 (「DOM Level 3 Core」의 Node.insertBefore 나 Node.replaceChild도 참조)
NOT_SUPPORTED_ERR: LSParser가 이 메서드를 지원 하지 않는 경우, 또는 컨텍스트 노드가 형태 Document 노드로 DOM 구현이자식 DocumentType 나자식 Element 치환을 지원 하지 않는 경우
NO_MODIFICATION_ALLOWED_ERR: 컨텍스트 노드가 읽기 전용 노드로 컨텍스트이 그자식 의 리스트에 추가되고 있는 경우, 또는 컨텍스트 노드의 부모노드가 읽기 전용 노드로 컨텍스트이 그자식 의 리스트에 삽입되고 있는 경우
INVALID_STATE_ERR: LSParser.busy 속성이 true인 경우

LSException - PARSE_ERR: LSParser가 XML fragment를 로드할 수 없었던 경우. DOM 에러에 관한 상세를 얻는인 경우, 어플리케이션은「error-handler」파라미터를 사용해 DOMErrorHandler를 접속할 필요가 있다

abort

void abort()

현재 LSParser로 로드 되고 있는 문서의 로딩을 중단합니다. LSParser가 현재 Busy 상태가 아닌 경우, 이 메서드에의 호출은 아무것도 영향을 주지 않습니다.