概觀  軟體套件   類別  使用  階層樹  已過時  索引  說明 
JavaTM 2 Platform
Standard Ed. 6
 上一個類別   下一個類別 框架    無框架    
摘要： 巢狀 | 欄位 | 建構子 | 方法 詳細資訊： 欄位 | 建構子 | 方法

javax.xml.validation
類別 SchemaFactory

java.lang.Object
  繼承者 javax.xml.validation.SchemaFactory

public abstract class SchemaFactory
extends Object

創建 Schema 物件的處理器。驗證 API 的入口點。

SchemaFactory 是一個網要編譯器。它讀取網要的外部表示形式並準備驗證它們。

SchemaFactory 類別不是執行緒安全的。換句話說，應用程序負責確保任意給定時刻至多只有一個執行緒使用 SchemaFactory 物件。鼓勵實作將方法標記為 synchronized，以保護客戶機不至於崩潰。

SchemaFactory 不是重入（re-entrant）方法。當正在調用某個 newSchema 方法時，應用程序不能試圖以遞歸方式調用 newSchema 方法，甚至不能從相同執行緒調用該方法。

網要語言

此規範使用名稱空間 URI 來指定網要語言。下表顯示了此規範定義的值。

要遵守此規範，實作只需支持 W3C XML 網要 1.0 即可。但是，如果實作選擇支持其他網要語言，那麼它必須遵守此規範中所描述的相關行為。

此處未列出的網要語言應參考它們自己的 URI 來表示它們本身。SchemaFactory 類別能夠在運行時定位其他網要語言的其他實作。

注意，因為 XML DTD 與解析過程有緊密聯繫，並對解析過程產生很大影響，因此不能將 DTD 驗證定義為與解析無關的過程。出於此原因，此規範不定義 XML DTD 的語義。這並不限制實作者以他們瞭解的合適方式來實作它，但這裡提醒使用者，此介面上實作的任何 DTD 驗證必然偏離 XML 1.0 中所定義的 XML DTD 語義。

值 語言
XMLConstants.W3C_XML_SCHEMA_NS_URI ("http://www.w3.org/2001/XMLSchema") W3C XML Schema 1.0
XMLConstants.RELAXNG_NS_URI ("http://relaxng.org/ns/structure/1.0") RELAX NG 1.0

從以下版本開始：
1.5

建構子摘要
protected SchemaFactory()
          派生類別的建構子。
 
方法摘要
abstract  ErrorHandler getErrorHandler()
          獲取設置為此 SchemaFactory 的當前 ErrorHandler。
 boolean getFeature(String name)
          尋找功能標誌的值。
 Object getProperty(String name)
          尋找屬性值。
abstract  LSResourceResolver getResourceResolver()
          獲取設置為此 SchemaFactory 的當前 LSResourceResolver。
abstract  boolean isSchemaLanguageSupported(String schemaLanguage)
          此 SchemaFactory 支持指定的網要嗎？
static SchemaFactory newInstance(String schemaLanguage)
          尋找支持指定網要語言的 SchemaFactory 的實作並返回它。
static SchemaFactory newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)
          根據類別名稱獲得一個新 SchemaFactory 實例。
abstract  Schema newSchema()
          創建特殊的 Schema 物件。
 Schema newSchema(File schema)
          解析作為網要的指定 File 並以 Schema 的形式返回它。
 Schema newSchema(Source schema)
          解析作為網要的指定源並以網要形式返回它。
abstract  Schema newSchema(Source[] schemas)
          解析作為網要的指定源（或多個源），並以網要形式返回它。
 Schema newSchema(URL schema)
          解析作為網要的指定 URL 並以 Schema 形式返回它。
abstract  void setErrorHandler(ErrorHandler errorHandler)
          設置 ErrorHandler 以接收在 newSchema 方法調用期間遇到的錯誤。
 void setFeature(String name, boolean value)
          設置此 SchemaFactory 的特性，Schema 由此處理器創建，更進一步說，Validator 和 ValidatorHandler 由這些 Schema 創建。
 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
 

建構子詳細資訊

SchemaFactory

protected SchemaFactory()

派生類別的建構子。

建構子不執行任何動作。

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

方法詳細資訊

newInstance

public static final SchemaFactory newInstance(String schemaLanguage)

尋找支持指定網要語言的 SchemaFactory 的實作並返回它。

為了尋找給定網要語言的 SchemaFactory 物件，此方法按照以下順序尋找以下位置，其中“類別載入器”指上下文類別載入器：

  1. 如果系統屬性 "javax.xml.validation.SchemaFactory:schemaLanguage" 存在（其中 schemaLanguage 是此方法的參數），那麼可以將它的值作為類別名稱來讀取。該方法試圖通過使用類別載入器來創建此類別的新實例，如果創建成功，則返回它。
  2. 讀取 $java.home/lib/jaxp.properties，並尋找與作為系統屬性的鍵關聯的值。如果存在這樣的值，則按上面的方式處理該值。

  3. 類別載入器要求服務提供者的提供者配置檔案與資源目錄 META-INF/services 中的 javax.xml.validation.SchemaFactory 比對。參見檔案格式和解析規則的 JAR File Specification。每個可能的服務提供者均要實作以下方法：

            isSchemaLanguageSupported(String schemaLanguage)
    返回支持指定網要語言的類別載入器順序中的第一個服務提供者。
  4. 以特定於實作的方式來定位平臺預設的 SchemaFactory。必須存在 W3C XML 網要的平臺預設 SchemaFactory。

如果這些都失敗，則將拋出 IllegalArgumentException。

疑難解答提示：

有關如何精確解析屬性檔案的資訊，請參閱 Properties.load(java.io.InputStream)。尤其要指出的是，冒號 ':'在屬性檔案中需要轉義，因此要確保網要語言 URI 在其中進行正確轉義。例如：

 http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory

參數：
schemaLanguage - 指定返回的 SchemaFactory 理解的網要語言。有關可能的值，請參閱 可用網要語言列表。
返回：
新的 SchemaFactory 實例
拋出：
IllegalArgumentException - 如果沒有可用的網要語言實作。
NullPointerException - 如果 schemaLanguage 參數為 null。
另請參見：
newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)

newInstance

public static SchemaFactory newInstance(String schemaLanguage,
                                        String factoryClassName,
                                        ClassLoader classLoader)

根據類別名稱獲得一個新 SchemaFactory 實例。如果指定的處理器類別支持指定的網要語言，則返回 SchemaFactory。當類別路徑中有多個提供者時此功能很有用。它給了應用程序更多的控制權，因為它能指定應該載入哪個提供者。

疑難解答提示

設置 jaxp.debug 系統屬性將導致此方法將許多除錯訊息列印到 System.err，以說明它執行的操作以及在何處尋找這些操作。

如有問題，請嘗試：

 java -Djaxp.debug=1 YourProgram ....

參數：
schemaLanguage - 指定返回的 SchemaFactory 理解的網要語言。有關可能的值，請參閱 the list of available schema languages。
factoryClassName - 完全限定處理器類別名稱，提供 javax.xml.validation.SchemaFactory 的實作。
classLoader - 用來載入處理器類別的 ClassLoader。如果為 null，則使用當前 Thread 的上下文 classLoader 來載入處理器類別。
返回：
新的 SchemaFactory 實例
拋出：
IllegalArgumentException - 如果 factoryClassName 為 null、處理器類別不能被載入或實例化、處理器類別不支持 schemLanguage 參數中指定的網要語言。
NullPointerException - 如果 schemaLanguage 參數為 null。
從以下版本開始：
1.6
另請參見：
newInstance(String schemaLanguage)

isSchemaLanguageSupported

public abstract boolean isSchemaLanguageSupported(String schemaLanguage)

此 SchemaFactory 支持指定的網要嗎？

參數：
schemaLanguage - 指定返回的 SchemaFactory 理解的網要語言。schemaLanguage 必須指定有效的網要語言。
返回：
如果 SchemaFactory 支持 schemaLanguage，則返回 true，否則返回 false。
拋出：
NullPointerException - 如果 schemaLanguage 為 null。
IllegalArgumentException - 如果 schemaLanguage.length() == 0 或 schemaLanguage 未指定有效的網要語言。

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
尋找功能標誌的值。

功能名稱是任何完全限定的 URI。SchemaFactory 有可能識別功能名稱，但暫時不能返回其值。

實作者可隨意選擇（鼓勵）創建自己的功能，方法是使用在它們自己的 URI 上建構的名稱。

參數：
name - 功能名稱，它是非 null 的完全限定 URI。
返回：
功能的當前值（true 或 false）。
拋出：
SAXNotRecognizedException - 如果不能分派或檢索功能值。
SAXNotSupportedException - 當 SchemaFactory 可以識別功能名稱但不能確定它此時的值時。
NullPointerException - 如果 name 為 null。
另請參見：
setFeature(String, boolean)

setFeature

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

設置此 SchemaFactory 的特性，Schema 由此處理器創建，更進一步說，Validator 和 ValidatorHandler 由這些 Schema 創建。

實作者和開發人員應該特別注意 newSchema() 返回的特殊 Schema 物件是如何處理的。在某些情況下，例如，當 SchemaFactory 和類別實際上載入來自不同實作的網要時，SchemaFactory 特性將無法自動繼承。開發人員應該確保在兩個地方都顯式地設置了特性（如安全處理）。

功能名稱是任何完全限定的 URI。SchemaFactory 有可能公開功能值，但不能更改當前值。

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

參數：
name - 功能名稱，它是非 null 的完全限定 URI。
value - 所請求的功能值（true 或 false）。
拋出：
SAXNotRecognizedException - 如果不能分派或檢索功能值。
SAXNotSupportedException - 當 SchemaFactory 可以識別功能名稱，但不能設置請求的值時。
NullPointerException - 如果 name 為 null。
另請參見：
getFeature(String)

setProperty

public void setProperty(String name,
                        Object object)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
設置屬性值。

屬性名稱是任何完全限定的 URI。SchemaFactory 有可能識別屬性名稱，但不能更改當前值。

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

參數：
name - 屬性名稱，它是非 null 的完全限定 URI。
object - 所請求的屬性值。
拋出：
SAXNotRecognizedException - 如果不能分派或檢索屬性值。
SAXNotSupportedException - 當 SchemaFactory 可以識別屬性名稱，但不能設置請求的值時。
NullPointerException - 如果 name 為 null。

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
尋找屬性值。

屬性名稱是任何完全限定的 URI。SchemaFactory 有可能識別屬性名稱，但暫時不能返回其值。

SchemaFactory 無需識別任何特定的屬性名稱。

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

參數：
name - 屬性名稱，它是非 null 的完全限定 URI。
返回：
屬性的當前值。
拋出：
SAXNotRecognizedException - 如果不能分派或檢索屬性值。
SAXNotSupportedException - 當 XMLReader 可以識別屬性名稱，但不能確定它此時的值時。
NullPointerException - 如果 name 為 null。
另請參見：
setProperty(String, Object)

setErrorHandler

public abstract void setErrorHandler(ErrorHandler errorHandler)
設置 ErrorHandler 以接收在 newSchema 方法調用期間遇到的錯誤。

錯誤處理程序可用於自定義網要解析期間的錯誤處理過程。當設置 ErrorHandler 時，網要解析期間發現的錯誤將首先發送到 ErrorHandler。

通過拋出處理程序中的 SAXException，錯誤處理程序可以立即中止網要的解析。例如，它可以將錯誤列印到螢幕上，並嘗試通過從 ErrorHandler 正常返回來繼續該過程。

如果從 ErrorHandler 拋出任何 Throwable（或其派生類別的實例），則 newSchema 方法的調用者將接收相同的 Throwable 物件。

在 SchemaFactory 沒有先向 ErrorHandler 報告之前，不能拋出 SAXException。

甚至正在解析 Schema 期間，應用程序也可以調用此方法。

當 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
     }
 }

當創建新 SchemaFactory 物件時，此欄位在初始化時被設置為 null。不要 將此欄位繼承給從此 SchemaFactory 創建的 Schema、Validator 或 ValidatorHandler。

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

getErrorHandler

public abstract ErrorHandler getErrorHandler()
獲取設置為此 SchemaFactory 的當前 ErrorHandler。

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

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver resourceResolver)
設置 LSResourceResolver 以自定義解析網要時的資源解析。

在網要解析中，SchemaFactory 在需要尋找外部資源時使用 LSResourceResolver，雖然“尋找外部資源”的準確含義取決於每個網要語言。例如，對於 W3C XML Schema，這包括檔案 <include>d 或 <import>ed，以及從網要檔案參考的 DTD 等。

甚至正在解析 Schema 期間，應用程序也可以調用此方法。

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

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

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

當創建新 SchemaFactory 物件時，此欄位在初始化時被設置為 null。不要 將此欄位繼承給從此 SchemaFactory 創建的 Schema、Validator 或 ValidatorHandler。

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

getResourceResolver

public abstract LSResourceResolver getResourceResolver()
獲取設置為此 SchemaFactory 的當前 LSResourceResolver。

返回：
此方法返回通過 setResourceResolver(LSResourceResolver) 方法設置的最後一個物件，如果自從創建此 SchemaFactory 以來一直未調用該方法，則返回 null。
另請參見：
setErrorHandler(ErrorHandler)

newSchema

public Schema newSchema(Source schema)
                 throws SAXException

解析作為網要的指定源並以網要形式返回它。

這是一個針對 newSchema(Source[] schemas) 的便捷方法。

參數：
schema - 表示網要的源。
返回：
從解析 schema 得到的新 Schema。
拋出：
SAXException - 如果解析期間發生 SAX 錯誤。
NullPointerException - 如果 schema 為 null。

newSchema

public Schema newSchema(File schema)
                 throws SAXException

解析作為網要的指定 File 並以 Schema 的形式返回它。

這是一個針對 newSchema(Source schema) 的便捷方法。

參數：
schema - 表示網要的 File。
返回：
從解析 schema 得到的新 Schema。
拋出：
SAXException - 如果解析期間發生 SAX 錯誤。
NullPointerException - 如果 schema 為 null。

newSchema

public Schema newSchema(URL schema)
                 throws SAXException

解析作為網要的指定 URL 並以 Schema 形式返回它。

這是一個針對 newSchema(Source schema) 的便捷方法。

參數：
schema - 表示網要的 URL。
返回：
從解析 schema 得到的新 Schema。
拋出：
SAXException - 如果解析期間發生 SAX 錯誤。
NullPointerException - 如果 schema 為 null。

newSchema

public abstract Schema newSchema(Source[] schemas)
                          throws SAXException
解析作為網要的指定源（或多個源），並以網要形式返回它。

被調用者將讀取所有 Source 並將它們組合到一個網要中。組合的精確語義取決於此 SchemaFactory 物件為其創建的網要語言。

當設置 ErrorHandler 時，被調用者將向處理程序報告源中發現的所有錯誤。如果處理程序執行異常，則它將中止網要組合，且將從此方法拋出相同的異常。同樣，向處理程序報告錯誤後，允許被調用者通過拋出該錯誤來中止下一步處理。如果未設置錯誤處理程序，則被調用者將拋出在源中發現的第一個錯誤。

W3C XML 網要 1.0

得到的網要包含來自指定源的元件。如果使用合適的 schemaLocation 值和名稱空間值將所有這些源導入具有不同 targetNamespace 且沒有其自己元件的單個網要文檔中，如果以與源相同的順序給定導入元素，則將得到相同結果。XML 網要建議的第 4.2.3 節描述了處理器關於這方面的選項。當處理器應與其 JAXP 網要源和 XML 網要導入的處理一致時，JAXP 相容的解析器之間的行為可能不同，特別是解析器可能選擇忽略所有給定名稱空間的 <import>（第一個除外），而不管 schemaLocation 中所提供的資訊。

如果解析後的網要集包含 XML 網要規範第 5.1 節指定的錯誤（或多個錯誤），則必須將錯誤報告給 ErrorHandler。

RELAX NG

對於 RELAX NG，如果 schemas.length!=1，則此方法必須拋出 UnsupportedOperationException。

參數：
schemas - 要解析的輸入。SchemaFactory 必須識別 SAXSource、StreamSource、StAXSource 和 DOMSource。輸入網要必須是 XML 文檔或 XML 元素，並且不得為 null。為了向後相容，傳遞文檔或元素以外的任何內容的所得結果都由實作決定。實作必須能識別並處理輸入，否則將拋出 IllegalArgumentException。
返回：
總返回非 null 的有效 Schema 物件。注意，當已報告錯誤後，不保證返回的 Schema 物件有意義。
拋出：
SAXException - 如果在處理指定輸入期間發現錯誤。當設置 ErrorHandler 時，首先將錯誤報告到該處。參見 setErrorHandler(ErrorHandler)。
NullPointerException - 如果 schemas 參數本身為 null，或陣列中的任何項為 null。
IllegalArgumentException - 如果此方法不識別陣列中的任何項。
UnsupportedOperationException - 如果網要語言不支持此操作。

newSchema

public abstract Schema newSchema()
                          throws SAXException
創建特殊的 Schema 物件。

返回的 Schema 物件的精確語義取決於此 SchemaFactory 為其創建的網要語言。

同樣，允許實作使用特定於實作的屬性/功能來更改此方法的語義。

實作者和開發人員應該特別注意此 SchemaFactory 上設置的特性是如何由此特殊 Schema 物件處理的。在某些情況下，例如，當 SchemaFactory 和類別實際上載入來自不同實作的網要時，SchemaFactory 特性將無法自動繼承。開發人員應該確保在兩個地方都顯式地設置了特性（如安全處理）。

W3C XML 網要 1.0

對於 XML 網要，此方法創建 Schema 物件，該物件通過使用文檔中指定的位置提示來執行驗證。

返回的 Schema 物件假定如果文檔指向網要位置提示中的相同 URL，則它們將總是解析為相同的網要文檔。此假定允許實作重用解析後的網要文檔結果，以便相對於相同網要的多個驗證可以更快地運行。

注意，網要位置提示的使用引入了惡意的拒絕服務攻擊。

RELAX NG

RELAX NG 不支持此操作。

返回：
總返回非 null 的有效 Schema 物件。
拋出：
UnsupportedOperationException - 如果被調用者不支持此操作。
SAXException - 如果此操作受支持但由於某種原因而失敗。
概觀  軟體套件   類別  使用  階層樹  已過時  索引  說明 
JavaTM 2 Platform
Standard Ed. 6
 上一個類別   下一個類別 框架    無框架    
摘要： 巢狀 | 欄位 | 建構子 | 方法 詳細資訊： 欄位 | 建構子 | 方法
提交錯誤或意見

版權所有 2008 Sun Microsystems, Inc. 保留所有權利。請遵守GNU General Public License, version 2 only。