API

com.ibm.xml.xapi
Class XFactory

java.lang.Object
  extended by com.ibm.xml.xapi.XFactory

public abstract class XFactory
extends Object

The XFactory class is the main factory class for creating executables for XPath, XQuery, and XSLT. It is also the means for creating instances of other classes and factories such as the XStaticContext, XDynamicContext, XItemFactory, and XSequenceTypeFactory classes. Use the newInstance method to get a concrete XFactory object.

An instance of XFactory maintains a set of registered schemas and can be validating or non-validating. A validating factory produces schema-aware executables and ensures that source documents get validated against the set of registered schemas before they are processed. If a source document includes a schema location and that schema is not already registered then it will be registered automatically when the source document is processed. If different sets of stylesheets, queries or expressions need different sets of schemas, these can be kept separate by using more than one XFactory instance.

An instance of XFactory is thread safe as long as the settings remain stable.


Field Summary
static int FULL_VALIDATION
          Constant indicating that executables should be schema aware and input documents will be validated.
static int NO_VALIDATION
          Constant indicating that executables should not be schema aware and input documents will not be validated.
 
Constructor Summary
XFactory()
           
 
Method Summary
abstract  XCompilationFactory getCompilationFactory()
          Get the compilation factory.
abstract  XItemFactory getItemFactory()
          Get the item factory.
abstract  XMessageHandler getMessageHandler()
          Get the message handler.
abstract  XSchemaResolver getSchemaResolver()
          Get the currently registered schema resolver.
abstract  XSequenceTypeFactory getSequenceTypeFactory()
          Get the sequence type factory.
abstract  Document getValidatedDOM(Document document)
          Get a validated DOM.
abstract  Document getValidatedDOM(StreamSource source)
          Get a validated DOM.
abstract  int getValidating()
          Get the validation setting.
static String getVersion()
          Get the version of the XFactory.
abstract  XDynamicContext newDynamicContext()
          Create a new XDynamicContext.
static XFactory newInstance()
          Create the default XFactory instance.
abstract  XOutputParameters newOutputParameters()
          Create a new XOutputParameters.
abstract  XStaticContext newStaticContext()
          Create a new XStaticContext.
abstract  XPathExecutable prepareXPath(StreamSource expression)
          Create an XPathExecutable for an XPath expression which can then be used to apply that expression to input documents.
abstract  XPathExecutable prepareXPath(StreamSource expression, XStaticContext context)
          Create an XPathExecutable for an XPath expression which can then be used to apply that expression to input documents.
abstract  XPathExecutable prepareXPath(String expression)
          Create an XPathExecutable for an XPath expression which can then be used to apply that expression to input documents.
abstract  XPathExecutable prepareXPath(String expression, XStaticContext context)
          Create an XPathExecutable for an XPath expression which can then be used to apply that expression to input documents.
abstract  XQueryExecutable prepareXQuery(StreamSource query)
          Create an XQueryExecutable for an XQuery expression which can then be used to apply that expression to input documents.
abstract  XQueryExecutable prepareXQuery(StreamSource query, XStaticContext context)
          Create an XQueryExecutable for an XQuery expression which can then be used to apply that expression to input documents.
abstract  XQueryExecutable prepareXQuery(String query)
          Create an XQueryExecutable for an XQuery expression which can then be used to apply that expression to input documents.
abstract  XQueryExecutable prepareXQuery(String query, XStaticContext context)
          Create an XQueryExecutable for an XQuery expression which can then be used to apply that expression to input documents.
abstract  XSLTExecutable prepareXSLT(Source stylesheet)
          Create an XSLTransformExecutable for an XSL stylesheet which can then be used to apply that stylesheet to input documents.
abstract  XSLTExecutable prepareXSLT(Source stylesheet, XStaticContext context)
          Create an XSLTransformExecutable for an XSL stylesheet which can then be used to apply that stylesheet to input documents.
abstract  void registerSchema(Source source)
          Register a schema.
abstract  void registerSchemas(List<? extends Source> schemas)
          Register a list of schemas.
abstract  void setMessageHandler(XMessageHandler handler)
          Set the message handler to be used when registering schemas, creating new items and sequences, and preparing and executing expressions, queries and stylesheets.
abstract  void setSchemaResolver(XSchemaResolver resolver)
          Set the schema resolver to be used for imports in schemas registered using the registerSchema method or for schemas imported in XSLT using the xsl:import-schema declaration.
abstract  void setValidating(int value)
          When full validation is enabled the factory will create validating executables and the input document will be validated on execution.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NO_VALIDATION

public static final int NO_VALIDATION
Constant indicating that executables should not be schema aware and input documents will not be validated.

See Also:
setValidating(int), Constant Field Values

FULL_VALIDATION

public static final int FULL_VALIDATION
Constant indicating that executables should be schema aware and input documents will be validated.

See Also:
setValidating(int), Constant Field Values
Constructor Detail

XFactory

public XFactory()
Method Detail

newInstance

public static XFactory newInstance()
                            throws ClassNotFoundException,
                                   IllegalAccessException,
                                   InstantiationException
Create the default XFactory instance.

Returns:
The new XFactory instance.
Throws:
ClassNotFoundException - if the class cannot be found.
IllegalAccessException - if the class is not accessible.
InstantiationException - if the class cannot be instantiated.

getVersion

public static String getVersion()
Get the version of the XFactory. Use this method to determine what features are available.

Returns:
The version as a string.

prepareXPath

public abstract XPathExecutable prepareXPath(String expression)
Create an XPathExecutable for an XPath expression which can then be used to apply that expression to input documents. The default static context settings are used.

Parameters:
expression - The XPath expression as a String.
Returns:
An XPathExecutable object for the XPath expression.
Throws:
NullPointerException - if the expression is null.
XProcessException - if the prepare fails because of errors in the expression.

prepareXPath

public abstract XPathExecutable prepareXPath(String expression,
                                             XStaticContext context)
Create an XPathExecutable for an XPath expression which can then be used to apply that expression to input documents.

Parameters:
expression - The XPath expression as a String.
context - The static context.
Returns:
An XPathExecutable object for the XPath expression.
Throws:
NullPointerException - if the expression is null.
XProcessException - if the prepare fails because of errors in the expression.

prepareXPath

public abstract XPathExecutable prepareXPath(StreamSource expression)
Create an XPathExecutable for an XPath expression which can then be used to apply that expression to input documents. The default static context settings are used.

Parameters:
expression - The XPath expression as a StreamSource.
Returns:
An XPathExecutable object for the XPath expression.
Throws:
NullPointerException - if the expression is null.
XProcessException - if the prepare fails because of errors in the expression.

prepareXPath

public abstract XPathExecutable prepareXPath(StreamSource expression,
                                             XStaticContext context)
Create an XPathExecutable for an XPath expression which can then be used to apply that expression to input documents.

Parameters:
expression - The XPath expression as a StreamSource.
context - The static context.
Returns:
An XPathExecutable object for the XPath expression.
Throws:
NullPointerException - if the expression is null.
XProcessException - if the prepare fails because of errors in the expression.

prepareXQuery

public abstract XQueryExecutable prepareXQuery(String query)
Create an XQueryExecutable for an XQuery expression which can then be used to apply that expression to input documents. The default static context settings are used.

Parameters:
query - The XQuery expression as an String.
Returns:
An XQueryExecutable object for the XQuery expression.
Throws:
NullPointerException - if the query is null.
XProcessException - if the prepare fails because of errors in the query.

prepareXQuery

public abstract XQueryExecutable prepareXQuery(String query,
                                               XStaticContext context)
Create an XQueryExecutable for an XQuery expression which can then be used to apply that expression to input documents.

Parameters:
query - The XQuery expression as a String.
context - The static context.
Returns:
An XQueryExecutable object for the XQuery expression.
Throws:
NullPointerException - if the query is null.
XProcessException - if the prepare fails because of errors in the query.

prepareXQuery

public abstract XQueryExecutable prepareXQuery(StreamSource query)
Create an XQueryExecutable for an XQuery expression which can then be used to apply that expression to input documents. The default static context settings are used.

Parameters:
query - The XQuery expression as a StreamSource.
Returns:
An XQueryExecutable object for the XQuery expression.
Throws:
NullPointerException - if the query is null.
XProcessException - if the prepare fails because of errors in the query.

prepareXQuery

public abstract XQueryExecutable prepareXQuery(StreamSource query,
                                               XStaticContext context)
Create an XQueryExecutable for an XQuery expression which can then be used to apply that expression to input documents.

Parameters:
query - The XQuery expression as a StreamSource.
context - The static context.
Returns:
An XQueryExecutable object for the XQuery expression.
Throws:
NullPointerException - if the query is null.
XProcessException - if the prepare fails because of errors in the query.

prepareXSLT

public abstract XSLTExecutable prepareXSLT(Source stylesheet)
Create an XSLTransformExecutable for an XSL stylesheet which can then be used to apply that stylesheet to input documents. The default static context settings are used.

Parameters:
stylesheet - The XSL stylesheet as a Source object.
Returns:
An XSLTransformExecutable object for the XSL stylesheet.
Throws:
NullPointerException - if the stylesheet is null.
XProcessException - if the prepare fails because of errors in the stylesheet.

prepareXSLT

public abstract XSLTExecutable prepareXSLT(Source stylesheet,
                                           XStaticContext context)
Create an XSLTransformExecutable for an XSL stylesheet which can then be used to apply that stylesheet to input documents.

Parameters:
stylesheet - The XSL stylesheet as a Source object.
context - The static context.
Returns:
An XSLTransformExecutable object for the XSL stylesheet.
Throws:
NullPointerException - if the stylesheet is null.
XProcessException - if the prepare fails because of errors in the stylesheet.

newStaticContext

public abstract XStaticContext newStaticContext()
Create a new XStaticContext.

Returns:
A new XStaticContext object.

newDynamicContext

public abstract XDynamicContext newDynamicContext()
Create a new XDynamicContext.

Returns:
A new XDynamicContext object.

setValidating

public abstract void setValidating(int value)
When full validation is enabled the factory will create validating executables and the input document will be validated on execution. Depends on the schemas that have been registered. The default is NO_VALIDATION.

Parameters:
value - Set to FULL_VALIDATION for full schema validation, NO_VALIDATION for no schema validation.
See Also:
registerSchema(Source), FULL_VALIDATION, NO_VALIDATION

getValidating

public abstract int getValidating()
Get the validation setting.


registerSchema

public abstract void registerSchema(Source source)
Register a schema. Has no effect if validating is not enabled. Valid Source types are:

Parameters:
source - The schema to register.
Throws:
NullPointerException - if the source is null.
See Also:
setValidating(int)

registerSchemas

public abstract void registerSchemas(List<? extends Source> schemas)
Register a list of schemas. Has no effect if validating is not enabled. Valid Source types are:

Parameters:
schemas - A list of schemas to register.
Throws:
NullPointerException - if the list is null.
See Also:
setValidating(int)

setSchemaResolver

public abstract void setSchemaResolver(XSchemaResolver resolver)

Set the schema resolver to be used for imports in schemas registered using the registerSchema method or for schemas imported in XSLT using the xsl:import-schema declaration.

The default behaviour for resolving imports within a schema is to use the base URI of the schema to resolve the imported schema's location. The default behaviour for XSLT schema imports is to use the base URI of the xsl:import-schema declaration to resolve the location specified in the declaration.

Parameters:
resolver - The schema resolver implementation or null to revert to the default schema resolution behaviour.

getSchemaResolver

public abstract XSchemaResolver getSchemaResolver()
Get the currently registered schema resolver.

Returns:
The schema resolver implementation or null if none was set.

getItemFactory

public abstract XItemFactory getItemFactory()
Get the item factory.

There is a direct association between an item factory and an XFactory instance since the item factory depends on the registered schemas and whether validating is enabled when processing Source objects. New schemas registered using the registerSchema method will be visible by the item factory.


getSequenceTypeFactory

public abstract XSequenceTypeFactory getSequenceTypeFactory()
Get the sequence type factory.

There is a direct association between a sequence type factory and an XFactory instance since the sequence type factory depends on the registered schemas. New schemas registered using the registerSchema method will be visible by the sequence type factory.


getCompilationFactory

public abstract XCompilationFactory getCompilationFactory()
Get the compilation factory.

There is a direct association between a compilation factory and an XFactory instance since the compilation factory depends on the registered schemas and whether validating is enabled when generating compiled executables. New schemas registered using the registerSchema method will be visible by the compilation factory.


newOutputParameters

public abstract XOutputParameters newOutputParameters()
Create a new XOutputParameters.

Returns:
A new XOutputParameters object.

getValidatedDOM

public abstract Document getValidatedDOM(StreamSource source)
Get a validated DOM. Required schemas must be registered using the registerSchema method prior to calling this method.

Parameters:
source - The source.
Returns:
A validated Document.
See Also:
registerSchema(Source)

getValidatedDOM

public abstract Document getValidatedDOM(Document document)
Get a validated DOM. Required schemas must be registered using the registerSchema method prior to calling this method.

Parameters:
document - The document.
Returns:
A validated Document.
See Also:
registerSchema(Source)

setMessageHandler

public abstract void setMessageHandler(XMessageHandler handler)
Set the message handler to be used when registering schemas, creating new items and sequences, and preparing and executing expressions, queries and stylesheets. The message handler used when preparing an expression, query or stylesheet can be overridden by setting the message handler on the XStaticContext. The message handler used when executing an expression, query or stylesheet can be overridden by setting the message handler on the XDynamicContext.

Parameters:
handler - The message handler. Pass in null to restore the default message handling behaviour.
See Also:
XStaticContext.setMessageHandler(XMessageHandler), XDynamicContext.setMessageHandler(XMessageHandler)

getMessageHandler

public abstract XMessageHandler getMessageHandler()
Get the message handler.

Returns:
The message handler or null if not set.

IBM Copyright 2004-2008