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

public interface LSSerializer

LSSerializer 는, DOM 문서를 XML 에 직렬화하는 (기입한다) API 를 제공합니다. XML 데이터는, 캐릭터 라인 또는 출력 스트림에 기입해집니다. 직렬화를 실행하는 동안에 어떠한 변경이나 수정을 해도, 영향이 있는 것은 직렬화 된 데이터만입니다. Document 와 그 아이가 직렬화의 조작에 의해 변경될 것은 없습니다.

「DOM Level 3 Core」, 부록 B 로 정의되고 있도록(듯이), XML 데이터의 직렬화중에 이름 공간 수정을 합니다. 「DOM Level 2 Core」에서는, 빈 상태(empty)의 캐릭터 라인을 진정한 이름 공간 URI 로서 사용할 수 있습니다. Node 의 namespaceURI 가 빈 상태(empty)의 캐릭터 라인인 경우, 직렬화에서는 namespaceURI 를 null 로서 취급해, 접두사를 무시합니다 (존재하는 경우).

LSSerializer 는, 어떤 노드형도 받아들여 직렬화합니다. Document 또는 Entity 형의 노드의 경우, 가능하면 정형식의 XML가 작성됩니다 (해석 조작으로부터 문서 또는 엔티티가 작성되어 작성되고 나서 변경되어 있지 않은 경우에, 정형식을 보증). 이러한 노드형의 직렬화 출력은, 각각 XML 문서 또는 외부 XML 엔티티로서 출력되어 XML 퍼서의 수락 가능한 입력이 됩니다. 다른 모든 노드형의 직렬화 된 형식은, 구현에 의해 정해집니다.

직렬화 되는 Document,DocumentFragment, 또는 Entity 내에서는,Nodes 는 다음과 같이 처리됩니다.

• XML 선언 ( 「xml-declaration」가 false 로 설정되어 있지 않은 경우)과 DTD 부분집합을 포함해 (DOM 에 존재하는 경우),Document 노드가 기입해진다. Document 노드를 기입한다고 문서 전체가 직렬화 된다
• LSSerializer.write 에 의해 직접 기입해졌을 경우,Entity 노드는 엔티티 확장을 출력하지만, 이름 공간 수정은 행해지지 않는다. 결과의 출력은 외부 엔티티로서 유효하게 된다
• 「entities」파라미터가 true 로 설정되는 경우,EntityReference 노드는 「&entityName;」출력 형식의 엔티티 참조로서 직렬화 된다. 엔티티 참조의 자식(child) 노드 (전개)는 무시된다. 「entities」파라미터가 false 로 설정되는 경우는, 엔티티 참조의 아이만이 직렬화 된다. 아이를 가지지 않는 EntityReference 노드 (대응하는 Entity 노드가 없는지, 대응하는 Entity 노드가 아이를 가지지 않는다)는 항상 직렬화 된다
• 지정된 출력 인코딩에서는 나타낼 수 없는 컨텐츠 문자를 포함한 CDATAsections 는,「split-cdata-sections」파라미터에 따라 처리된다. 파라미터가 true 로 설정되어 있으면(자),CDATAsections 가 분할되어 표시할 수 없는 문자는 일반적으로의 컨텐츠의 수치 참조로서 직렬화 된다. 정확한 위치와 분할수는 지정되지 않는다. 파라미터가 false 로 설정되어 있으면(자),CDATAsection 내의 표시할 수 없는 문자는「well-formed」파라미터가 true 로 설정되어 있을 때의「wf-invalid-character」에러로서 보고된다. 대체 문자가 제공되지 않고, 직렬화가 속행되므로 에러는 회복할 수 없다
• DocumentFragment 노드는, 문서 fragment에 나타나는 순서로 문서 fragment의 아이를 직렬화하는 것으로 직렬화 된다
• 다른 모든 노드형 (Element, Text 등)은, 대응하는 XML 소스 형식에 직렬화 된다

주:Node 의 직렬화는, 반드시 정형식의 XML 문서를 생성하지 않습니다. 즉,LSParser 는 결과의 직렬화를 해석하고 있을 때 치명적인 에러를 throw 할 가능성이 있습니다.

문서 (마크 업의 범위외)의 문자 데이터내에서는, 직접 나타낼 수가 없는 모든 문자는, 문자 참조로 옮겨집니다. 출현하는 「<」(와)과「&」는 사전 정의 엔티티의 「&lt;」(와)과「&amp;」로 옮겨집니다. 다른 사전 정의 엔티티 ( 「&gt;」, 「&apos;」, 및 「&quot;」)는, 필요한 경우를 제외해 사용할 수 없을 가능성이 있습니다 (예, 「]]>」에 「&gt;」를 사용하는 등). 출력 문자 인코딩으로 직접 나타낼 수가 없는 모든 문자는, 수치 참조로서 직렬화 됩니다. 문자 인코딩 표준에서는, 일반적으로 문자의 16 진표현을 사용하므로, 문자 참조를 직렬화할 때, 16 진표현을 사용하는 것을 추천합니다.

단일 인용부호와 이중 인용부호의 양쪽 모두를 포함한 속성치를 사용할 수 있도록(듯이) 하려면 , apostrophe 또는 단일 인용부호 문자 (')는 「&apos;」로, 이중 인용부호 문자 (")는 「&quot;」로 각각 표현할 수 있습니다. 출력 문자 인코딩의 속성치로 직접 나타낼 수 없는 개행 문자나 다른 문자는, 수치 참조로서 직렬화 됩니다.

출력 문자 인코딩으로 나타낼 수 없는 문자가 마크 업내에, 그러나 속성의 밖에 출현하면(자), 치명적인 에러 DOMError 로서 보고됩니다. 예로서encoding="us-ascii" 로 <LaCa? ada/> 요소를 직렬화하는 경우를 들 수 있습니다. 이 결과,DOMError「wf-invalid-character-in-node-name」가 생성됩니다 (「well-formed」로 제시되고 있다).

LSSerializer 로「normalize-characters」파라미터를 true 로 설정해 직렬화가 요구되었을 경우, 문자의 정규화는, 직렬화 되는 모든 데이터 (마크 업 데이터와 문자 데이터)로「XML 1.1」의 부록 E 에 포함되는완전하게 정규화된 문자의 정의에 따라 실행됩니다. 문자의 정규화 처리는, 기입중의 데이터인 만큼 영향을 줍니다. 직렬화의 완료 후, 처리에 의해 문서의 DOM 의 뷰가 변화할 것은 없습니다.

구현에서는, 「UTF-8」, 「UTF-16」, 「UTF-16 BE」, 및 「UTF-16 LE」인코딩을 지원해, 모든 XML 퍼서에 의해 지원될 필요가 있는 모든 인코딩으로, 데이터가 직렬화 되는 것을 보증할 필요가 있습니다. 인코딩이 UTF-8 의 경우, 바이트 순서 기호가 직렬화 될지 어떨지, 또는 출력이 빅 endian나 little endian의 어느 쪽인가는, 구현에 의존합니다. 인코딩이 UTF-16 의 경우, 출력이 빅 endian나 little endian의 어느 쪽인가는 구현에 의존합니다만, 바이트 순서 기호는 비문자 출력 (LSOutput.byteStream 나 LSOutput.systemId 등)에 대해서 생성됩니다. 바이트 순서 기호가 생성되지 않는 경우, 경고 「byte-order-mark-needed」가 보고됩니다. 인코딩이 UTF-16BE 또는 UTF-16LE 의 경우, 출력은 빅 endian (UTF-16BE) 또는 little endian (UTF-16LE)로, 바이트 순서 기호는 생성되지 않습니다. 어느 케이스도, 인코딩 선언 (생성되는 경우)은, 직렬화의 사이에 사용되는 인코딩에 대응합니다 (예를 들어,encoding="UTF-16" 는, UTF-16 가 요구되었을 경우에 표시된다).

이름 공간은 직렬화중에 수정되어 직렬화 처리에서는 이름 공간 선언, 이름 공간 접두사, 및 요소와 속성에 관련지을 수 있었던 이름 공간 URI 가 일관하고 있는 것이 확인됩니다. 모순이 검출되었을 경우, 문서의 직렬화 된 형식은 변경되어 모순을 삭제합니다. 문서를 직렬화중, 이름 공간의 수정을 실시하기 위해서(때문에) 사용되는 메소드는,「DOM Level 3 Core」의 부록 B. 1 「이름 공간의 정규화」로 정의되고 있는 알고리즘입니다.

문서를 직렬화중에, 지정 이외의 데이터가 직렬화 될지 어떨지는 「discard-default-content」파라미터에 의해 제어됩니다.

직렬화중에, 에러와 경고는 에러 핸들러 (LSSerializer.domConfig 의「error-handler」파라미터)를 사용해 어플리케이션에 보고됩니다. 이 스펙에서는, DOM 노드를 직렬화중에 발생할 가능성이 있는 모든 에러와 경고는 정의되고 있지 않습니다만, 일반적인 에러와 경고의 케이스의 일부를 정의하고 있습니다. 이 스펙으로 정의되고 있는 에러와 경고의 종류 (DOMError.type)는 다음과 같습니다.

"no-output-specified" [fatal]

LSOutput 에 기입해 안에,LSOutput 로 출력이 지정되지 않았던 경우에 돌려주어집니다.

"unbound-prefix-in-entity-reference" [fatal]

「namespaces」구성 파라미터가 true 로 설정되어 있어, 엔티티의 치환 텍스트가 바인드되어 있지 않은 이름 공간 접두사를 포함해, 엔티티가 이름 공간 접두사의 바인딩이 없는 위치에서 참조되는 경우에 돌려주어집니다.

"unsupported-encoding" [fatal]

지원되어 있지 않은 인코딩이 검출되었을 경우에 돌려주어집니다.

정의 끝난 에러나 경고를 돌려주는데 더해, 구현에서는, IO 에러 ( 「파일이 발견되지 않습니다, 액세스권은 거부되었습니다 ...」) 등을 부르는 것 외의 에러나 경고에 대해 구현 고유의 에러를 돌려줍니다.

「Document Object Model (DOM) Level 3 Load and Save Specification」도 참조해 주세요.

메소드의 개요

DOMConfiguration	getDomConfig () DOM 노드의 직렬화중에 LSSerializer 가 사용하는 DOMConfiguration 객체.
LSSerializerFilter	getFilter () 어플리케이션으로 필터가 준비되어 있으면(자), 직렬화 처리는 각 노드를 직렬화하기 전에 필터를 호출합니다.
String	getNewLine () 써내지고 있는 XML 로 사용되는 줄 끝 순서 문자입니다.
void	setFilter (LSSerializerFilter filter) 어플리케이션으로 필터가 준비되어 있으면(자), 직렬화 처리는 각 노드를 직렬화하기 전에 필터를 호출합니다.
void	setNewLine (String newLine) 써내지고 있는 XML 로 사용되는 줄 끝 순서 문자입니다.
boolean	write (Node nodeArg, LSOutput destination) LSSerializer 인터페이스의 일반적인 설명으로, 전술과 같이 지정된 노드를 직렬화합니다.
String	writeToString (Node nodeArg) LSSerializer 인터페이스의 일반적인 설명으로, 전술과 같이 지정된 노드를 직렬화합니다.
boolean	writeToURI (Node nodeArg, String uri) 인코딩을 지정하지 않고,LSOutput.systemId 를 uri 인수로 설정해,LSOutput 로 LSSerializer.write 가 불려 갔는지와 같이 기능하는 편리한 메소드입니다.

메소드의 상세

getDomConfig

DOMConfiguration  getDomConfig()

DOM 노드의 직렬화중에 LSSerializer 가 사용하는 DOMConfiguration 객체.
「DOM Level 3 Core」로 정의된 DOMConfiguration 인터페이스에 의해 인식되는 파라미터에 가세해,LSSerializer 의 DOMConfiguration 객체는 다음의 파라미터를 추가 또는 변경합니다.

"canonical-form"

true

[옵션] 「정규 XML」로 지정되고 있는 규칙에 따라 문서에 기입합니다. 이 파라미터를 true 로 설정하면(자),「DOM Level 3 Core」의「canonical-form」에 기술되고 있는 동작에 가세해, 「format-pretty-print」, 「discard-default-content」, 및 「xml-declaration」의 각 파라미터가 false 로 설정됩니다. 이러한 파라미터의 어느쪽이든을 true 로 설정하면(자), 이 파라미터는 false 로 설정됩니다. 「canonical-form」가 true 일 때 XML 1.1 문서를 직렬화하면(자), 치명적인 에러가 발생합니다.

false

[필수] (디폴트) 출력을 표준화 하지 않습니다.

"discard-default-content"

true

[필수] (디폴트) Attr.specified 속성을 사용해, 어느 속성을 파기할까를 결정합니다. 이 파라미터가 true 로 설정되어 있는 경우, 구현에 따라서는, 파기하는 속성과 컨텐츠를 결정할 때에, 구현으로 사용 가능한 모든 정보 (XML schema, DTD,Attr.specified 속성등)를 사용할 가능성이 있습니다.

false

[필수] 모든 속성과 컨텐츠를 보관 유지합니다.

"format-pretty-print"

true

[옵션] 공백을 추가해 출력을 서식 설정해, 프리티 프린트 처리되어 인덴트 된 읽기 쉬운 형식으로 합니다. 이 스펙에서는, 변환의 엄밀한 형식은 지정되고 있지 않습니다. 프리티 프린트 처리에 의해, 문서의 컨텐츠가 변경되어 문서의 유효성에 영향이 생길 가능성이 있습니다. 구현의 유효성을 검증하는 것으로써 유효성이 유지됩니다.

false

[필수] (디폴트) 결과를 프리티 프린트 처리하지 않습니다.

"ignore-unknown-character-denormalizations"

true

[필수] (디폴트) 「XML 1.1」을 지원하고 있어, 완전한 정규화를 확인중에, 정규화 프로퍼티을 판정할 수 없는 문자를 검출했을 경우, 「unknown-character-denormalization」경고 (이 파라미터가 설정되어 있지 않은 경우는 경고는 아니고 에러)를 내, 이러한 문자에 의해 생길 가능성이 있는 불완전한 정규화를 무시합니다.

false

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

"normalize-characters"

이 파라미터는,「DOM Level 3 Core」의 DOMConfiguration 로 정의되고 있는 파라미터와 동등합니다. 코어와는 달라, 이 파라미터의 디폴트 값는 true 입니다. DOM 구현에서는「XML 1.1」의 「부록 E」에 따라 문서에 포함되는 문자의완전한 정규화를 지원할 필요는 없습니다만, 지원하는 경우는, 디폴트로 이 파라미터를 유효하게 할 필요가 있습니다.

"xml-declaration"

true

[필수] (디폴트) Document 노드,Element 노드, 또는 Entity 노드가 직렬화 되고 있는 경우는, XML 선언 또는 텍스트 선언을 포함할 필요가 있습니다. 버젼 (문서가 Level 3 문서이며, 버젼이 null 가 아닌 경우는 Document.xmlVersion, 그 이외의 경우는 값 「1.0」) 및 출력 인코딩 (출력 인코딩의 분별법에 대해서는 LSSerializer.write 를 참조)은, 직렬화 된 XML 선언으로 지정됩니다.

false

[필수] XML 선언과 텍스트 선언을 직렬화하지 않습니다. 이것에 의해 문제 (직렬화 된 데이터가「XML 1.0」이외의 XML 버젼의 것이거나 직렬화 데이터의 재해석을 가능하게 하기 위해서 인코딩이 필요한 경우등)가 발생하면(자), 「xml-declaration-needed」경고를 통지합니다.

getNewLine

String  getNewLine()

써내지고 있는 XML 로 사용되는 줄 끝 순서 문자입니다. 임의의 문자가 지원됩니다만, XML 에서는 특정의 캐릭터 세트의 순서만을 줄 끝으로서 취급합니다 (직렬화 된 컨텐츠가 XML 1.0 의 경우는「XML 1.0」의 「End-of-Line Handling」섹션 2.11 을 참조. 직렬화 된 컨텐츠가 XML 1.1 의 경우는「XML 1.1」의 「End-of-Line Handling」섹션 2.11 을 참조). 추천되어 있지 않은 문자 순서를 사용하면(자), 문서가 직렬화 불가가 되거나 정형식이 되지 않게 되거나 합니다.
취득시, 이 속성의 디폴트 값는, 구현 고유의 디폴트 줄 끝 순서입니다. DOM 구현에서는, 디폴트의 줄 끝 순서를 선택해, 사용하고 있는 환경의 텍스트 파일의 일반적으로의 규칙에 맞출 필요가 있습니다. 직렬화 된 컨텐츠에 따라서는, 구현으로, XML 1.0 또는 XML 1.1 에 의해 허가되고 있는 줄 끝 순서의 1 개에 일치하는 디폴트의 순서를 선택할 필요가 있습니다. 이 속성을 null 로 설정하면(자), 그 값은 디폴트 값에 리셋 됩니다.

setNewLine

void setNewLine(String  newLine)

써내지고 있는 XML 로 사용되는 줄 끝 순서 문자입니다. 임의의 문자가 지원됩니다만, XML 에서는 특정의 캐릭터 세트의 순서만을 줄 끝으로서 취급합니다 (직렬화 된 컨텐츠가 XML 1.0 의 경우는「XML 1.0」의 「End-of-Line Handling」섹션 2.11 을 참조. 직렬화 된 컨텐츠가 XML 1.1 의 경우는「XML 1.1」의 「End-of-Line Handling」섹션 2.11 을 참조). 추천되어 있지 않은 문자 순서를 사용하면(자), 문서가 직렬화 불가가 되거나 정형식이 되지 않게 되거나 합니다.
취득시, 이 속성의 디폴트 값는, 구현 고유의 디폴트 줄 끝 순서입니다. DOM 구현에서는, 디폴트의 줄 끝 순서를 선택해, 사용하고 있는 환경의 텍스트 파일의 일반적으로의 규칙에 맞출 필요가 있습니다. 직렬화 된 컨텐츠에 따라서는, 구현으로, XML 1.0 또는 XML 1.1 에 의해 허가되고 있는 줄 끝 순서의 1 개에 일치하는 디폴트의 순서를 선택할 필요가 있습니다. 이 속성을 null 로 설정하면(자), 그 값은 디폴트 값에 리셋 됩니다.

getFilter

LSSerializerFilter  getFilter()

어플리케이션으로 필터가 준비되어 있으면(자), 직렬화 처리는 각 노드를 직렬화하기 전에 필터를 호출합니다. 필터의 구현에서는, 스트림로부터 노드를 삭제하거나 조기에 직렬화를 종료하는 등의 선택을 할 수 있습니다.
적용되고 있는 DOMConfiguration 파라미터에 의해, 요구된 조작의 후에 필터가 불려 갑니다. 예를 들어, CDATA 섹션은,「cdata-sections」가 false 로 설정되면(자) 필터에게 건네지지 않습니다.

setFilter

void setFilter(LSSerializerFilter  filter)

어플리케이션으로 필터가 준비되어 있으면(자), 직렬화 처리는 각 노드를 직렬화하기 전에 필터를 호출합니다. 필터의 구현에서는, 스트림로부터 노드를 삭제하거나 조기에 직렬화를 종료하는 등의 선택을 할 수 있습니다.
적용되고 있는 DOMConfiguration 파라미터에 의해, 요구된 조작의 후에 필터가 불려 갑니다. 예를 들어, CDATA 섹션은,「cdata-sections」가 false 로 설정되면(자) 필터에게 건네지지 않습니다.

write

boolean write(Node  nodeArg,
              LSOutput  destination)
              throws LSException 

LSSerializer 인터페이스의 일반적인 설명으로, 전술과 같이 지정된 노드를 직렬화합니다. 출력은, 지정한 LSOutput 에 기입해집니다. LSOutput 에의 기입해 때, 인코딩은,LSOutput 나 다음의 순서에 기입해지는 아이템 (또는 아이템의 소유자 문서)을 통해서 액세스 가능한 인코딩 정보를 확인해 찾아낼 수 있습니다.

1. LSOutput.encoding
2. Document.inputEncoding
3. Document.xmlEncoding

전술의 프로퍼티을 통해서 인코딩에 액세스 할 수 없는 경우는, 「UTF-8」의 디폴트 인코딩이 사용됩니다. 지정한 인코딩이 지원되어 있지 않은 경우는, 치명적인 에러의 「unsupported-encoding」가 돌려주어집니다.
출력이 LSOutput 로 지정되어 있지 않은 경우는, 치명적인 에러의 「no-output-specified」가 돌려주어집니다.
구현에서는, 적절한 미디어 타입을 직렬화 된 데이터에 관련지을 필요가 있습니다.
HTTP URI 에 기입할 때는, HTTP PUT 가 실행됩니다. 다른 형태의 URI 에 기입할 때, 그 URI 에 데이터를 기입하는 메카니즘은 구현에 따라서 다릅니다.

파라미터:

nodeArg - 직렬화하는 노드

destination - 직렬화 된 DOM 의 행선지

반환값:

node 가 정상적으로 직렬화 되었을 경우는 true. 일반적으로의 처리는 정지되었지만, 구현이 문서를 직렬계속 화했을 경우는 false. 그 후의 직렬화의 결과는 구현에 따라서 다르다

예외:

LSException - SERIALIZE_ERR:LSSerializer 가 노드를 직렬화 할 수 없었던 경우. DOM 에러에 관한 상세를 취득하는 경우, DOM 어플리케이션은「error-handler」파라미터를 사용해 DOMErrorHandler 를 접속할 필요가 있다

writeToURI

boolean writeToURI(Node  nodeArg,
                   String  uri)
                   throws LSException 

인코딩을 지정하지 않고,LSOutput.systemId 를 uri 인수로 설정해,LSOutput 로 LSSerializer.write 가 불려 갔는지와 같이 기능하는 편리한 메소드입니다.

파라미터:

nodeArg - 직렬화하는 노드

uri - 기입처의 URI

반환값:

node 가 정상적으로 직렬화 되었을 경우는 true. 일반적으로의 처리는 정지되었지만, 구현이 문서를 직렬계속 화했을 경우는 false. 그 후의 직렬화의 결과는 구현에 따라서 다르다

예외:

LSException - SERIALIZE_ERR:LSSerializer 가 노드를 직렬화 할 수 없었던 경우. DOM 에러에 관한 상세를 취득하는 경우, DOM 어플리케이션은「error-handler」파라미터를 사용해 DOMErrorHandler 를 접속할 필요가 있다

writeToString

String  writeToString(Node  nodeArg)
                     throws DOMException ,
                            LSException 

LSSerializer 인터페이스의 일반적인 설명으로, 전술과 같이 지정된 노드를 직렬화합니다. 출력은 호출해 옆에 반환되는 DOMString 에 기입해집니다. 사용되는 인코딩은 UTF-16 등의 DOMString 형의 인코딩입니다. 바이트 순서 기호는 DOMString 객체에서는 생성되지 않습니다.

파라미터:

nodeArg - 직렬화하는 노드

반환값:

직렬화 된 데이터를 돌려준다

예외:

DOMException - DOMSTRING_SIZE_ERR:결과의 캐릭터 라인이 너무 길어 DOMString 내에 들어가지 않는 경우

LSException - SERIALIZE_ERR:LSSerializer 가 노드를 직렬화 할 수 없었던 경우. DOM 에러에 관한 상세를 취득하는 경우, DOM 어플리케이션은「error-handler」파라미터를 사용해 DOMErrorHandler 를 접속할 필요가 있다