|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一個類別 下一個類別 | 框架 無框架 | |||||||||
| 摘要： 巢狀 | 欄位 | 建構子 | 方法 | 詳細資訊： 欄位 | 建構子 | 方法 | |||||||||
public interface LSParser
可以建構的物件介面，或者參數、來自各種輸入源的 DOM 階層樹。
LSParser 提供了用於解析 XML 和建構相應的 DOM 文檔結構的 API。LSParser 實例可以通過調用 DOMImplementationLS.createLSParser() 方法獲取。
如 [DOM Level 3 Core] 中指定的那樣，當通過 LSParser 第一次使文檔可供使用時：
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] "doctype-not-allowed" [fatal]true 並且遇到了 doctype，則將引發此錯誤。 "no-input-specified" [fatal]LSInput 物件中指定輸入時引發此錯誤。 "pi-base-uri-not-preserved" [warning]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]true 並且在實體的替換文本中碰到了未綁定的名稱空間前綴時,可以引發此警告。並非強制引發此警告，因為有些現有的解析器不能在實體的替換文本中識別未綁定的名稱空間前綴。 "unknown-character-denormalization" [fatal]false 並且遇到了處理器無法為其確定標準化屬性的字元，則引發此錯誤。 "unsupported-encoding" [fatal]"unsupported-media-type" [fatal]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 當前正忙於載入文檔，則為 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 片段，並將其內容插入到用 context 和 action 參數指定的位置的現有文檔。 |
void |
setFilter(LSParserFilter filter)
當提供過濾器時，實作將在建構 DOM 階層樹結構時調出該過濾器。 |
| 欄位詳細資訊 |
|---|
static final short ACTION_APPEND_AS_CHILDREN
Element 或 DocumentFragment。
static final short ACTION_REPLACE_CHILDREN
Element、Document 或 DocumentFragment。
static final short ACTION_INSERT_BEFORE
Element 或 DocumentFragment。
static final short ACTION_INSERT_AFTER
Element 或 DocumentFragment。
static final short ACTION_REPLACE
Element 或 DocumentFragment。
| 方法詳細資訊 |
|---|
DOMConfiguration getDomConfig()
DOMConfiguration 物件。此 DOMConfiguration 特定於解析操作。在由解析操作創建或使用的 Document 上，沒有參數值從此 DOMConfiguration 物件被自動傳遞到 DOMConfiguration 物件。DOM 應用程序負責將任何所需的參數值從此 DOMConfiguration 物件傳遞到由 Document 物件參考的 DOMConfiguration 物件。LSParser 的 DOMConfiguration 物件還可以添加或修改以下參數：
"charset-overrides-xml-encoding"trueLSInput 中設置編碼將覆寫協議中的任何編碼。false"disallow-doctype"truefalse"ignore-unknown-character-denormalizations"truefalse"infoset"DOMConfiguration 的定義。與在 [DOM Level 3 Core] 中不同，對於 LSParser，此參數將預設為 true。 "namespaces"truefalse"resource-resolver"LSResourceResolver 物件的參考，或為 null。如果遇到外部資源（如外部 XML 實體或 XML 網要位置）時此參數的值不為 null，則實作將請求在此參數中參考的 LSResourceResolver 解析該資源。 "supported-media-types-only"truefalse"validate"DOMConfiguration 的定義。與在 [DOM Level 3 Core] 中不同，總是要完成對內部子集的處理，即使此參數設置為 false。 "validate-if-schema"DOMConfiguration 的定義。與在 [DOM Level 3 Core] 中不同，總是要完成對內部子集的處理，即使此參數設置為 false。"well-formed"DOMConfiguration 的定義。與在 [DOM Level 3 Core] 中不同，不能將此參數設置為 false。
LSParserFilter getFilter()
DOMConfiguration 參數請求的操作後調用。例如，如果 "validate" 設置為 true，則在調用過濾器前進行驗證。
void setFilter(LSParserFilter filter)
DOMConfiguration 參數請求的操作後調用。例如，如果 "validate" 設置為 true，則在調用過濾器前進行驗證。
boolean getAsync()
LSParser 是非同步的，為 true，如果它是同步的，則為 false。
boolean getBusy()
LSParser 當前正忙於載入文檔，則為 true，否則為 false。
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。
Document parseURI(String uri)
throws DOMException,
LSException
uri - 將讀取的 XML 文檔的位置。
LSParser 是同步 LSParser，則將返回新創建並已填充的 Document，如果發生錯誤，則返回 null。如果 LSParser 是非同步的，則返回 null，因為當此方法返回時，還不可以建構該文檔物件。
DOMException - INVALID_STATE_ERR:如果 LSParser.busy 屬性為 true，則將引發此異常。
LSException - PARSE_ERR:如果 LSParser 無法載入 XML 文檔，則將引發此異常。如果 DOM 應用程序想獲得關於錯誤的詳細資訊，則它必須附加一個使用參數 "error-handler" 的 DOMErrorHandler。
Node parseWithContext(LSInput input,
Node contextArg,
short action)
throws DOMException,
LSException
LSInput 標識的資源中解析 XML 片段，並將其內容插入到用 context 和 action 參數指定的位置的現有文檔。當解析輸入串流時，上下文節點（或其父節點，取決於在哪裡將結果插入）用於解析未綁定的名稱空間前綴。上下文節點的 ownerDocument 節點（如果是型別 DOCUMENT_NODE 的節點，則為節點本身）用來解析預設屬性和實體參考。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 片段，即除完整的 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），則引發此異常。 LSParser 不支持此方法，或者上下文節點是型別 Document，並且 DOM 實作不支持替換 DocumentType 子節點或 Element 子節點，則引發此異常。 LSParser.busy 屬性為 true，則將引發此異常。
LSException - PARSE_ERR:如果 LSParser 無法載入 XML 片段，則將引發此異常。如果 DOM 應用程序想獲得關於錯誤的詳細資訊，則它必須附加一個使用參數 "error-handler" 的 DOMErrorHandler。void abort()
LSParser 載入的文檔的載入。如果當前 LSParser 不忙，則調用此方法無效。
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一個類別 下一個類別 | 框架 無框架 | |||||||||
| 摘要： 巢狀 | 欄位 | 建構子 | 方法 | 詳細資訊： 欄位 | 建構子 | 方法 | |||||||||
版權所有 2008 Sun Microsystems, Inc. 保留所有權利。請遵守GNU General Public License, version 2 only。