javax.xml.validation
類別 ValidatorHandler

java.lang.Object
  javax.xml.validation.ValidatorHandler

所有已實作的介面：

ContentHandler

public abstract class ValidatorHandler
extends Object
implements ContentHandler

處理 SAX 串流的串流驗證器。

ValidatorHandler 物件不是執行緒安全的，也不能重入。換句話說，應用程序負責確保在任何給定時刻使用 ValidatorHandler 物件的執行緒不多於一個。

ValidatorHandler 檢查 SAX 事件是否遵守關聯的 Schema 中所描述的約束集，此外它可以修改 SAX 事件（例如添加預設值等）。

ValidatorHandler 擴展自 ContentHandler，但它按以下方式修改了底層 ContentHandler：

1. 對於 uri、localName 和 qname，即使 SAX 允許當中一些值為 null，startElement/endElement 事件也必須接收非 null String。類似地，對於這 3 個參數，使用者指定的 ContentHandler 也將接收非 null String。
2. 應用程序必須確保正確調用 ValidatorHandler 的 ContentHandler.startPrefixMapping(String,String) 和 ContentHandler.endPrefixMapping(String)。類似地，使用者指定的 ContentHandler 將接收 startPrefixMapping/endPrefixMapping 事件。如果 ValidatorHandler 引入了額外的名稱空間綁定，則使用者指定的 ContentHandler 將接收額外的 startPrefixMapping/endPrefixMapping 事件。
3. ContentHandler.startElement(String,String,String,Attributes) 的 Attributes 可以包括也可以不包括 xmlns* 屬性。

每次調用 startDocument 方法時將自動重置 ValidatorHandler。

識別的屬性和特性

此規範定義了以下特性，所有 ValidatorHandler 實作必須識別這些特性。

http://xml.org/sax/features/namespace-prefixes

此特性控制 ValidatorHandler 如何引入原始 SAX 事件串流中不存在的名稱空間綁定。當此特性設置為 true 時，它必須確保使用者的 ContentHandler 將看到 ContentHandler.startElement(String,String,String,Attributes) 回調的 Attributes 物件中相應的 xmlns* 屬性。否則，不得將 xmlns* 屬性添加到傳遞給使用者指定的 ContentHandler 的 Attributes。

（注意，無論特性如何切換，名稱空間綁定總是通過使用者所指定的 ContentHandler 的 ContentHandler.startPrefixMapping(String,String) 和 ContentHandler.endPrefixMapping(String) 方法通知應用程序。）

注意，此特性不 影響 ValidatorHandler 接收 SAX 事件的方式。它僅更改其擴充 SAX 事件的方式。

此特性預設設置為 false。

從以下版本開始：

1.5

建構子摘要

protected

ValidatorHandler() 派生類別的建構子。

方法摘要

abstract ContentHandler	getContentHandler() 獲取接收擴充的驗證結果的 ContentHandler。
abstract ErrorHandler	getErrorHandler() 獲取設置為此 ValidatorHandler 的當前 ErrorHandler。
boolean	getFeature(String name) 尋找特性標誌的值。
Object	getProperty(String name) 尋找屬性值。
abstract LSResourceResolver	getResourceResolver() 獲取設置到此 ValidatorHandler 的當前 LSResourceResolver。
abstract TypeInfoProvider	getTypeInfoProvider() 獲取此 ValidatorHandler 的 TypeInfoProvider 實作。
abstract void	setContentHandler(ContentHandler receiver) 設置 ContentHandler，它接收擴充的驗證結果。
abstract void	setErrorHandler(ErrorHandler errorHandler) 設置 ErrorHandler 以接收驗證期間遇到的錯誤。
void	setFeature(String name, boolean value) 設置此 ValidatorHandler 的特性。
void	setProperty(String name, Object object) 設置屬性值。
abstract void	setResourceResolver(LSResourceResolver resourceResolver) 設置 LSResourceResolver 以自定義驗證期間的資源解析。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

從介面 org.xml.sax.ContentHandler 繼承的方法

characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping

建構子詳細資訊

ValidatorHandler

protected ValidatorHandler()

派生類別的建構子。

該建構子不執行任何操作。

派生類別必須創建具有 null ErrorHandler 和 null LSResourceResolver 的 ValidatorHandler 物件。

方法詳細資訊

setContentHandler

public abstract void setContentHandler(ContentHandler receiver)

設置 ContentHandler，它接收擴充的驗證結果。

當指定了 ContentHandler 時，ValidatorHandler 將充當過濾器，實際上是將輸入事件複製到指定的 ContentHandler。

在複製過程中，ValidatorHandler 可以修改事件，例如添加預設屬性。

ValidatorHandler 可以對事件進行一定程度的緩衝，但要使解析器使用 ValidatorHandler，必須滿足以下要求。

1. 當對 ValidatorHandler 調用 ContentHandler.startElement(String, String, String, Attributes)、ContentHandler.endElement(String, String, String)、ContentHandler.startDocument() 或 ContentHandler.endDocument() 時，在回調返回之前，必須針對相同事件對使用者指定的 ContentHandler 調用相同的方法。
2. ValidatorHandler 不能引入輸入中不存在的新元素。
3. ValidatorHandler 不能移除輸入中存在的屬性。

當對指定的 ContentHandler 調用回調方法拋出異常時，必須從 ValidatorHandler 拋出相同的異常物件。ErrorHandler 不應該獲得此類別異常的通知。

甚至在驗證期間也可以調用此方法。

參數：

receiver - ContentHandler 或 null 值。

getContentHandler

public abstract ContentHandler getContentHandler()

獲取接收擴充的驗證結果的 ContentHandler。

返回：

此方法返回通過 getContentHandler() 方法設置的最後一個物件；如果自從創建此 ValidatorHandler 以來一直未調用該方法，則返回 null。

另請參見：

setContentHandler(ContentHandler)

setErrorHandler

public abstract void setErrorHandler(ErrorHandler errorHandler)

設置 ErrorHandler 以接收驗證期間遇到的錯誤。

錯誤處理程序可用於自定義驗證期間的錯誤處理過程。設置了 ErrorHandler 時，驗證期間發現的錯誤將首先被發送到 ErrorHandler。

錯誤處理程序通過拋出來自處理程序的 SAXException 可以立即中止進一步驗證。或者，它可以將錯誤列印到螢幕上，並嘗試通過從 ErrorHandler 正常返回來繼續該驗證。

如果從 ErrorHandler 拋出任何 Throwable，則將向調用堆疊(stack)空間的根拋出相同的 Throwable 物件。

在 ValidatorHandler 首先向 ErrorHandler 報告之前，不允許拋出 SAXException。

當 ErrorHandler 為 null 時，實作的行為就好像設置了以下 ErrorHandler 一樣：

 class DraconianErrorHandler implements ErrorHandler {
     public void fatalError( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void error( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void warning( SAXParseException e ) throws SAXException {
         // noop
     }
 }
 

當創建新 ValidatorHandler 物件時，此欄位最初被設置為 null。

參數：

errorHandler - 要設置的新錯誤處理程序。此參數可以為 null。

getErrorHandler

public abstract ErrorHandler getErrorHandler()

獲取設置為此 ValidatorHandler 的當前 ErrorHandler。

返回：

此方法返回通過 setErrorHandler(ErrorHandler) 方法設置的最後一個物件；如果自從創建此 ValidatorHandler 以來一直未調用該方法，則返回 null。

另請參見：

setErrorHandler(ErrorHandler)

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver resourceResolver)

設置 LSResourceResolver 以自定義驗證期間的資源解析。

驗證期間，ValidatorHandler 在需要尋找外部資源時使用 LSResourceResolver，雖然組成“尋找外部資源”的準確語句取決於每個網要語言。

當 LSResourceResolver 為 null 時，實作的行為就好像設置了以下 LSResourceResolver 一樣：

 class DumbLSResourceResolver implements LSResourceResolver {
     public LSInput resolveResource(
         String publicId, String systemId, String baseURI) {
         
         return null; // always return null
     }
 }
 

如果 LSResourceResolver 拋出 RuntimeException（或其派生類別的實例），則 ValidatorHandler 將中止解析，且 validate 方法的調用者將接收相同的 RuntimeException。

當創建新 ValidatorHandler 物件時，此欄位最初被設置為 null。

參數：

resourceResolver - 要設置的新資源解析器。此參數可以為 null。

getResourceResolver

public abstract LSResourceResolver getResourceResolver()

獲取設置到此 ValidatorHandler 的當前 LSResourceResolver。

返回：

此方法返回通過 setResourceResolver(LSResourceResolver) 方法設置的最後一個物件；如果自從創建此 ValidatorHandler 以來一直未調用該方法，則返回 null。

另請參見：

setErrorHandler(ErrorHandler)

getTypeInfoProvider

public abstract TypeInfoProvider getTypeInfoProvider()

獲取此 ValidatorHandler 的 TypeInfoProvider 實作。

在解析期間可以查詢所獲取的 TypeInfoProvider，以存取驗證器確定的型別資訊。

某些網要語言未定義型別概念，對於這些語言，此方法可能不受支持。但是，為了遵守此規範，W3C XML 網要 1.0 實作必須支持此操作。

返回：

如果驗證器/網要語言不支持 TypeInfo 概念，則返回 null。否則返回非 null 的有效 TypeInfoProvider。

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

尋找特性標誌的值。

特性名稱是任何完全限定的 URI。ValidatorHandler 可以識別特性名稱，但暫時不能返回其值。某些特性值只有在特定上下文中才能使用，例如在驗證前、驗證中或驗證之後。

使用在自己的 URI 上建構的名稱，實作者可隨意選擇（鼓勵）創建自己的特性。

參數：

name - 特性名稱，它是非 null 的完全限定 URI。

返回：

特性的當前值（true 或 false）。

拋出：

SAXNotRecognizedException - 如果不能分派或檢索特性值。

SAXNotSupportedException - 當 ValidatorHandler 可以識別特性名稱但不能確定其此時的值時。

NullPointerException - 當 name 為 null 時。

另請參見：

setFeature(String, boolean)

setFeature

public void setFeature(String name,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException

設置此 ValidatorHandler 的特性。

特性可用於控制 ValidatorHandler 解析網要的方式。特性名稱是任何完全限定的 URI。ValidatorHandler 可以公開特性值，但不能更改當前值。某些特性值只有在特定上下文中才是不可變的或可變的，例如在驗證前、驗證中或驗證之後。

所有實作必須支持 XMLConstants.FEATURE_SECURE_PROCESSING 特性。當特性為以下情況時：

• true：該實作將限制 XML 處理遵守實作限制。範例包括實體擴展限制和將使用大量資源的 XML 網要建構。如果由於安全原因 XML 處理受到限制，則將通過調用註冊的 ErrorHandler.fatalError(SAXParseException exception) 來報告此情況。參見 setErrorHandler(ErrorHandler errorHandler)。
• false：實作將根據 XML 規範來處理 XML，而不管可能的實作限制。

參數：

name - 特性名稱，它是非 null 的完全限定 URI。

value - 所請求的特性值（true 或 false）。

拋出：

SAXNotRecognizedException - 如果不能分派或檢索特性值。

SAXNotSupportedException - 當 ValidatorHandler 可以識別特性名稱，但不能設置請求的值時。

NullPointerException - 當 name 為 null時。

另請參見：

getFeature(String)

setProperty

public void setProperty(String name,
                        Object object)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException

設置屬性值。

屬性名稱是任何完全限定的 URI。ValidatorHandler 可以識別屬性名稱，但不能更改當前值。某些屬性值只有在特定上下文中才是不可變的或可變的，例如在驗證前、驗證中或驗證之後。

ValidatorHandler 無需識別設置任何特定的屬性名稱。

參數：

name - 屬性名稱，它是非 null 的完全限定 URI。

object - 所請求的屬性值。

拋出：

SAXNotRecognizedException - 如果不能分派或檢索屬性值。

SAXNotSupportedException - 當 ValidatorHandler 可以識別屬性名稱，但不能設置請求的值時。

NullPointerException - 當 name 為 null 時。

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

尋找屬性值。

屬性名稱是任何完全限定的 URI。ValidatorHandler 可以識別屬性名稱，但暫時不能返回其值。某些屬性值只有在特定上下文中才能使用，例如在驗證前、驗證中或驗證之後。

ValidatorHandler 無需識別任何指定的屬性名稱。

使用在自己 URI 上建構的名稱，實作者可隨意選擇（鼓勵）創建自己的屬性。

參數：

name - 屬性名稱，它是非 null 的完全限定 URI。

返回：

屬性的當前值。

拋出：

SAXNotRecognizedException - 如果不能分派或檢索屬性值。

SAXNotSupportedException - 當 XMLReader 可以識別屬性名稱，但不能確定其此時的值時。

NullPointerException - 當 name 為 null 時。

另請參見：

setProperty(String, Object)