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

public interface LSSerializer

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

「DOM Level 3 Core」, 부록 B 로 정의되고 있도록, XML 데이터의 직렬화중에 이름 공간 수정을 합니다. 「DOM Level 2 Core」에서는 비어있는 캐릭터 라인을 진정한 이름 공간 URI 로서 사용할 수 있습니다. Node namespaceURI가 비어있는 캐릭터 라인인 경우, 직렬화에서는 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;」출력 형식의 실체 참조로서 직렬화 된다. 실체 참조의자식 노드 (전개)는 무시된다. 「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 진표현을 사용하는 것을 추천합니다.

단일 인용부호와 이중 인용부호의 양쪽 모두를 포함한 속성값을 사용할 수 있도록 하려면, 어퍼스트로피 또는 단일 인용부호 문자 (')는 「&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 ()
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()

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 에러에 관한 상세를 얻는인 경우, 어플리케이션은「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 에러에 관한 상세를 얻는인 경우, 어플리케이션은「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 에러에 관한 상세를 얻는인 경우, 어플리케이션은「error-handler」파라미터를 사용해 DOMErrorHandler를 접속할 필요가 있다