|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一個類別 下一個類別 | 框架 無框架 | |||||||||
| 摘要： 巢狀 | 欄位 | 建構子 | 方法 | 詳細資訊： 欄位 | 建構子 | 方法 | |||||||||
public interface LSSerializer
LSSerializer 提供了將 DOM 文檔序列化（編寫）為 XML 的 API。XML 資料被寫入字元串或輸入串流。在序列化期間所做的任何更改或修復僅影響序列化的資料。Document 物件及其子物件永遠不會被序列化操作所改變。
在序列化 XML 資料期間，將像在 [DOM Level 3 Core] 的附錄 B 中所定義的那樣，執行名稱空間修復。[DOM Level 2 Core] 允許空字元串作為實際名稱空間 URI。如果一個 Node 的 namespaceURI 是空字元串，則序列化將把它們視為 null，從而忽略前綴（如果有）。
LSSerializer 接受任何用於序列化的節點型別。對於 Document 或 Entity 型別的節點，將在可能的情況下創建格式良好的 XML（如果文檔或實體來自解析操作並且自創建以來沒有改變，則可保證格式良好性）。這些節點型別的序列化輸出分別作為 XML 文檔或外部 XML 實體，並且是 XML 解析器可接受的輸入。對於所有其他型別的節點，序列化格式是依賴於實作的。
在被序列化的 Document、DocumentFragment 或 Entity 內，將按如下方式處理 Nodes
Document 節點，包括 XML 宣告（除非參數 "xml-declaration" 設置為 false）和 DTD 子集（如果 DOM 中存在一個）。編寫 Document 節點序列化整個文檔。
Entity 節點直接由 LSSerializer.write 編寫時將輸出實體擴展，但不執行名稱空間修復。得到的輸出將作為有效的外部實體。
true，則把 EntityReference 節點序列化為輸出中形式 " &entityName;" 的實體參考。將忽略實體參考的子節點（擴展）。如果參數 "entities" 設置為 false，則僅序列化實體參考的子項。將始終序列化不帶有子項的 EntityReference 節點（沒有相應的 Entity 節點，或者相應的 Entity 節點沒有子節點）。
CDATAsections 套件括不能用指定的輸出編碼表示的內容字元，將根據 "split-cdata-sections" 參數對其進行處理。如果將該參數設置為 true，則將拆分 CDATAsections，將不可表示的字元序列化為普通內容中的數字字元參考。不指定拆分的精確位置和數量。如果參數設置為 false，則參數 "well-formed" 設置為 true 時，CDATAsection 中不可表示的字元將報告為 "wf-invalid-character" 錯誤。該錯誤不可恢復 - 沒有提供替換字元和繼續進行序列化的機制。
DocumentFragment 節點可通過按照文檔片段的子片段在文檔片段中出現的順序序列化這些子片段得以序列化。
註：序列化 Node 並不總能產生格式良好的 XML 文檔，即解析得到的序列化時 LSParser 可能會拋出嚴重錯誤。
在文檔的字元資料中（在標記之外），任何無法直接表示的字元都將替換為字元參考。'<' 和 '&' 將由預定義實體 < 和 & 替換。除非必需（例如在 ']]>' 這一情況下使用 >），否則不能使用其他預定義實體（>、' 和 "）。無法用輸入字元編碼直接表示的任何字元都將序列化為數值字元參考（由於字元編碼標準一般使用字元的十六進製表示形式，所以在序列化字元參考時鼓勵使用十六進製表示形式）。
若要允許屬性值同時包括單引號和雙引號，可以將省略號或單引號字元 (') 表示為 "'"，雙引號字元 (") 表示為 """。無法直接用輸出字元編碼表示的新行字元和其他字元將被序列化為數值字元參考。
在標記內（但在屬性外），無法用輸出字元編碼表示的任何字元都將被報告為 DOMError 嚴重錯誤。其中的一個範例就是使用 encoding="us-ascii" 序列化元素 <LaCa?ada/>。這將導致產生 DOMError "wf-invalid-character-in-node-name"（在 "well-formed" 中建議的）。
當通過將 LSSerializer 上的參數 "normalize-characters" 設置為 true 請求字元標準化時，對所有被序列化的資料（包括標識和字元資料），將根據對 "fully normalized" 字元（包括在 [XML 1.1] 的附錄 E 中）的定義實施字元標準化。字元標準化過程只影響正在編寫的資料；在序列化完成之後不會改變 DOM 的文檔視圖。
需要實作支持編碼 "UTF-8"、"UTF-16"、"UTF-16BE" 和 "UTF-16LE"，以保證資料在需要得到所有 XML 解析器支持的所有編碼中能夠序列化。當編碼是 UTF-8 時，無論位元組順序標記是否得到了序列化，無論輸出是大尾端還是 小尾端，都具有實作依賴性。當編碼是 UTF-16 時，無論輸出是大尾端還是小尾端，都具有實作依賴性，但必須為非字元輸出（如 LSOutput.byteStream 或 LSOutput.systemId）產生位元組順序標記。如果未產生位元組順序標記，則報告一個 "byte-order-mark-needed" 警告。當編碼是 UTF-16LE 或 UTF-16BE 時，輸出是大尾端 (UTF-16BE) 或小尾端 (UTF-16LE)，將不產生位元組順序標記。在所有這些情況下，編碼宣告（如果已產生）將與序列化期間使用的編碼一致（例如，如果請求 UTF-16，則 encoding="UTF-16" 將出現）。
名稱空間將在序列化期間進行修復，序列化過程將檢驗名稱空間宣告、名稱空間前綴以及與元素和屬性相關的名稱空間 URI 是否一致。如果發現有不一致，則將改變文檔的序列化形式以刪除它們。序列化文檔時修復名稱空間所使用的方法是在 [DOM Level 3 Core] 的附錄 B.1 "Namespace normalization" 中定義的演算法。
在序列化文檔期間，參數 "discard-default-content" 控制是否序列化非指定資料。
在序列化期間，將通過錯誤處理程序（LSSerializer.domConfig 的 "error-handler" 參數）將錯誤和警告報告給應用程序。此規範從不嘗試定義序列化 DOM 節點期間可能發生的所有錯誤和警告，但卻對一些常見的錯誤和警告情形做了定義。此規範定義的錯誤和警告型別 (DOMError.type) 套件括：
"no-output-specified" [fatal]LSOutput 中指定輸出的情況下向 LSOutput 寫入時，將引發此錯誤。 "unbound-prefix-in-entity-reference" [fatal] 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 調用 LSSerializer.write，並且 LSOutput.systemId 被設置為 uri 參數。 |
| 方法詳細資訊 |
|---|
DOMConfiguration getDomConfig()
LSSerializer 使用的 DOMConfiguration 物件。LSSerializer 的 DOMConfiguration 物件還將添加或修改以下參數：
"canonical-form"truetrue 將把參數 "format-pretty-print"、"discard-default-content" 和 "xml-declaration " 設置為 false。將其中的一個參數設置為 true 將把此參數設置為 false。當 "canonical-form" 為 true 時序列化 XML 1.1 文檔將產生嚴重錯誤。 false。"discard-default-content"trueAttr.specified 屬性來決定必須丟棄哪些屬性。注意，有些實作可能使用任何可供實作使用的資訊（即 XML 網要、DTD、Attr.specified 屬性等）來決定在此參數設置為 true 時應丟棄哪些屬性和內容。 false。"format-pretty-print"truefalse。"ignore-unknown-character-denormalizations" true"unknown-character-denormalization" 警告（而不是像未設置此參數那樣引發錯誤），並將忽略由這些字元引起的任何可能的反向標準化。 false。"normalize-characters"DOMConfiguration 定義的參數等效。與在 Core 中不同，此參數的預設值是 true。儘管根據 [XML 1.1] 中的附錄 E 的規定，不需要 DOM 實作支持完全標準化文檔中的字元，但如果支持，則預設情況下必須啟動此參數。 "xml-declaration"trueDocument、Element 或 Entity 節點被序列化，則必須包括 XML 宣告或文本宣告。版本（如果文檔是 Level 3 文檔並且版本為非 null，則使用 Document.xmlVersion，否則使用值 "1.0"）和輸出編碼（關於如何尋找輸出編碼的詳細資訊請參見 LSSerializer.write ）在已序列化的 XML 宣告中指定。false。"xml-declaration-needed" 警告。
String getNewLine()
null 將把其值重置為預設值。
void setNewLine(String newLine)
null 將把其值重置為預設值。
LSSerializerFilter getFilter()
DOMConfiguration 參數請求的操作後調用。例如，如果把 "cdata-sections" 設置為 false，則不會將 CDATA 節傳遞給過濾器。
void setFilter(LSSerializerFilter filter)
DOMConfiguration 參數請求的操作後調用。例如，如果把 "cdata-sections" 設置為 false，則不會將 CDATA 節傳遞給過濾器。
boolean write(Node nodeArg,
LSOutput destination)
throws LSException
LSSerializer 介面的一般介紹中所描述的那樣序列化指定的節點。將輸出寫入所提供的 LSOutput。LSOutput 寫入時，編碼可以通過尋找可通過 LSOutput 獲得的編碼資訊和按如下順序編寫的條目（或者其所有者文檔）來發現：
LSOutput.encoding,
Document.inputEncoding,
Document.xmlEncoding.
LSOutput 中未指定輸出，則將引發 "no-output-specified" 嚴重錯誤。
nodeArg - 將序列化的節點。destination - 已序列化 DOM 的目標。
node 被成功序列化，則返回 true。如果常規處理停止，但實作仍在序列化文檔，則返回 false；序列化的結果是具有實作依賴性。
LSException - SERIALIZE_ERR:如果 LSSerializer 不能序列化節點，則引發此異常。如果 DOM 應用程序想獲得有關錯誤的詳細資訊，則它必須附加上使用參數 "error-handler" 的 DOMErrorHandler。
boolean writeToURI(Node nodeArg,
String uri)
throws LSException
LSOutput 調用 LSSerializer.write，並且 LSOutput.systemId 被設置為 uri 參數。
nodeArg - 要序列化的節點。uri - 要寫入到的 URI。
node 被成功序列化，則返回 true。如果常規處理停止，但實作仍在序列化文檔，則返回 false；序列化的結果是具有實作依賴性。
LSException - SERIALIZE_ERR:如果 LSSerializer 無法序列化節點，則引發此異常。如果 DOM 應用程序想獲得有關錯誤的詳細資訊，則它必須附加上使用參數 "error-handler" 的 DOMErrorHandler。
String writeToString(Node nodeArg)
throws DOMException,
LSException
LSSerializer 介面的一般介紹中所描述的那樣序列化指定的節點。將輸出寫入到返回給調用者的 DOMString。所使用的編碼是 DOMString 型別的編碼，即 UTF-16。注意，在 DOMString 物件中未產生位元組順序標記。
nodeArg - 將序列化的節點。
DOMException - DOMSTRING_SIZE_ERR: 如果得到的字元串太長，不能放在 DOMString 中，則將引發此異常。
LSException - SERIALIZE_ERR: 如果 LSSerializer 不能序列化節點，則引發此異常。如果 DOM 應用程序想獲得有關錯誤的詳細資訊，則它必須附加上使用參數 "error-handler" 的 DOMErrorHandler。
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一個類別 下一個類別 | 框架 無框架 | |||||||||
| 摘要： 巢狀 | 欄位 | 建構子 | 方法 | 詳細資訊： 欄位 | 建構子 | 方法 | |||||||||
版權所有 2008 Sun Microsystems, Inc. 保留所有權利。請遵守GNU General Public License, version 2 only。