FileDocCategorySizeDatePackage
BasicParserConfiguration.javaAPI DocApache Xerces 3.0.121889Fri Sep 14 20:33:56 BST 2007org.apache.xerces.parsers

BasicParserConfiguration

public abstract class BasicParserConfiguration extends org.apache.xerces.util.ParserConfigurationSettings implements org.apache.xerces.xni.parser.XMLParserConfiguration
A very basic parser configuration. This configuration class can be used as a base class for custom parser configurations. The basic parser configuration creates the symbol table (if not specified at construction time) and manages all of the recognized features and properties.

The basic parser configuration does not mandate any particular pipeline configuration or the use of specific components except for the symbol table. If even this is too much for a basic parser configuration, the programmer can create a new configuration class that implements the XMLParserConfiguration interface.

Subclasses of the basic parser configuration can add their own recognized features and properties by calling the addRecognizedFeature and addRecognizedProperty methods, respectively.

The basic parser configuration assumes that the configuration will be made up of various parser components that implement the XMLComponent interface. If subclasses of this configuration create their own components for use in the parser configuration, then each component should be added to the list of components by calling the addComponent method. The basic parser configuration will make sure to call the reset method of each registered component before parsing an instance document.

This class recognizes the following features and properties:

  • Features
    • http://xml.org/sax/features/validation
    • http://xml.org/sax/features/namespaces
    • http://xml.org/sax/features/external-general-entities
    • http://xml.org/sax/features/external-parameter-entities
  • Properties
    • http://xml.org/sax/properties/xml-string
    • http://apache.org/xml/properties/internal/symbol-table
    • http://apache.org/xml/properties/internal/error-handler
    • http://apache.org/xml/properties/internal/entity-resolver
author
Arnaud Le Hors, IBM
author
Andy Clark, IBM
version
$Id: BasicParserConfiguration.java 447239 2006-09-18 05:08:26Z mrglavas $

Fields Summary
protected static final String
VALIDATION
Feature identifier: validation.
protected static final String
NAMESPACES
Feature identifier: namespaces.
protected static final String
EXTERNAL_GENERAL_ENTITIES
Feature identifier: external general entities.
protected static final String
EXTERNAL_PARAMETER_ENTITIES
Feature identifier: external parameter entities.
protected static final String
XML_STRING
Property identifier: xml string.
protected static final String
SYMBOL_TABLE
Property identifier: symbol table.
protected static final String
ERROR_HANDLER
Property identifier: error handler.
protected static final String
ENTITY_RESOLVER
Property identifier: entity resolver.
protected org.apache.xerces.util.SymbolTable
fSymbolTable
Symbol table.
protected Locale
fLocale
Locale.
protected ArrayList
fComponents
Components.
protected org.apache.xerces.xni.XMLDocumentHandler
fDocumentHandler
The document handler.
protected org.apache.xerces.xni.XMLDTDHandler
fDTDHandler
The DTD handler.
protected org.apache.xerces.xni.XMLDTDContentModelHandler
fDTDContentModelHandler
The DTD content model handler.
protected org.apache.xerces.xni.parser.XMLDocumentSource
fLastComponent
Last component in the document pipeline
Constructors Summary
protected BasicParserConfiguration()
Default Constructor.


    //
    // Constructors
    //

       
      
        this(null, null);
    
protected BasicParserConfiguration(org.apache.xerces.util.SymbolTable symbolTable)
Constructs a parser configuration using the specified symbol table.

param
symbolTable The symbol table to use.

        this(symbolTable, null);
    
protected BasicParserConfiguration(org.apache.xerces.util.SymbolTable symbolTable, org.apache.xerces.xni.parser.XMLComponentManager parentSettings)
Constructs a parser configuration using the specified symbol table and parent settings.

param
symbolTable The symbol table to use.
param
parentSettings The parent settings.

        super(parentSettings);

        // create a vector to hold all the components in use
        fComponents = new ArrayList();

        // create storage for recognized features and properties
        fRecognizedFeatures = new ArrayList();
        fRecognizedProperties = new ArrayList();

        // create table for features and properties
        fFeatures = new HashMap();
        fProperties = new HashMap();

        // add default recognized features
        final String[] recognizedFeatures = {
        	PARSER_SETTINGS,
            VALIDATION,                 
            NAMESPACES, 
            EXTERNAL_GENERAL_ENTITIES,  
            EXTERNAL_PARAMETER_ENTITIES,
        };
        addRecognizedFeatures(recognizedFeatures);
        fFeatures.put(PARSER_SETTINGS, Boolean.TRUE);
        // set state for default features
		fFeatures.put(VALIDATION, Boolean.FALSE);
		fFeatures.put(NAMESPACES, Boolean.TRUE);
		fFeatures.put(EXTERNAL_GENERAL_ENTITIES, Boolean.TRUE);
		fFeatures.put(EXTERNAL_PARAMETER_ENTITIES, Boolean.TRUE);

        // add default recognized properties
        final String[] recognizedProperties = {
            XML_STRING,     
            SYMBOL_TABLE,
            ERROR_HANDLER,  
            ENTITY_RESOLVER,
        };
        addRecognizedProperties(recognizedProperties);

        if (symbolTable == null) {
            symbolTable = new SymbolTable();
        }
        fSymbolTable = symbolTable;
        fProperties.put(SYMBOL_TABLE, fSymbolTable);

    
Methods Summary
protected voidaddComponent(org.apache.xerces.xni.parser.XMLComponent component)
Adds a component to the parser configuration. This method will also add all of the component's recognized features and properties to the list of default recognized features and properties.

param
component The component to add.


        // don't add a component more than once
        if (fComponents.contains(component)) {
            return;
        }
        fComponents.add(component);

        // register component's recognized features
        String[] recognizedFeatures = component.getRecognizedFeatures();
        addRecognizedFeatures(recognizedFeatures);
        
        // register component's recognized properties
        String[] recognizedProperties = component.getRecognizedProperties();
        addRecognizedProperties(recognizedProperties);

        // set default values
        if (recognizedFeatures != null) {
            for (int i = 0; i < recognizedFeatures.length; i++) {
                String featureId = recognizedFeatures[i];
                Boolean state = component.getFeatureDefault(featureId);
                if (state != null) {
                    super.setFeature(featureId, state.booleanValue());
                }
            }
        }
        if (recognizedProperties != null) {
            for (int i = 0; i < recognizedProperties.length; i++) {
                String propertyId = recognizedProperties[i];
                Object value = component.getPropertyDefault(propertyId);
                if (value != null) {
                    super.setProperty(propertyId, value);
                }
            }
        }

    
protected voidcheckFeature(java.lang.String featureId)
Check a feature. If feature is know and supported, this method simply returns. Otherwise, the appropriate exception is thrown.

param
featureId The unique identifier (URI) of the feature.
throws
XMLConfigurationException Thrown for configuration error. In general, components should only throw this exception if it is really a critical error.


        //
        // Xerces Features
        //
        if (featureId.startsWith(Constants.XERCES_FEATURE_PREFIX)) {
            final int suffixLength = featureId.length() - Constants.XERCES_FEATURE_PREFIX.length();

            //
            // special performance feature: no one by component manager is allowed to set it
            //
            if (suffixLength == Constants.PARSER_SETTINGS.length() && 
                featureId.endsWith(Constants.PARSER_SETTINGS)) {
                short type = XMLConfigurationException.NOT_SUPPORTED;
                throw new XMLConfigurationException(type, featureId);
            }
        }

        super.checkFeature(featureId);

     
protected voidcheckProperty(java.lang.String propertyId)
Check a property. If the property is known and supported, this method simply returns. Otherwise, the appropriate exception is thrown.

param
propertyId The unique identifier (URI) of the property being set.
exception
org.apache.xerces.xni.parser.XMLConfigurationException If the requested feature is not known or supported.


        // special cases
        if (propertyId.startsWith(Constants.SAX_PROPERTY_PREFIX)) {
            final int suffixLength = propertyId.length() - Constants.SAX_PROPERTY_PREFIX.length();	
        	
            //
            // http://xml.org/sax/properties/xml-string
            // Value type: String
            // Access: read-only
            //   Get the literal string of characters associated with the
            //   current event.  If the parser recognises and supports this
            //   property but is not currently parsing text, it should return
            //   null (this is a good way to check for availability before the
            //   parse begins).
            //
            if (suffixLength == Constants.XML_STRING_PROPERTY.length() && 
                propertyId.endsWith(Constants.XML_STRING_PROPERTY)) {
                // REVISIT - we should probably ask xml-dev for a precise
                // definition of what this is actually supposed to return, and
                // in exactly which circumstances.
                short type = XMLConfigurationException.NOT_SUPPORTED;
                throw new XMLConfigurationException(type, propertyId);
            }
        }

        // check property
        super.checkProperty(propertyId);

    
public org.apache.xerces.xni.XMLDTDContentModelHandlergetDTDContentModelHandler()
Returns the registered DTD content model handler.

        return fDTDContentModelHandler;
    
public org.apache.xerces.xni.XMLDTDHandlergetDTDHandler()
Returns the registered DTD handler.

        return fDTDHandler;
    
public org.apache.xerces.xni.XMLDocumentHandlergetDocumentHandler()
Returns the registered document handler.

        return fDocumentHandler;
    
public org.apache.xerces.xni.parser.XMLEntityResolvergetEntityResolver()
Return the current entity resolver.

return
The current entity resolver, or null if none has been registered.
see
#setEntityResolver

        // REVISIT: Should this be a property?
        return (XMLEntityResolver)fProperties.get(ENTITY_RESOLVER);
    
public org.apache.xerces.xni.parser.XMLErrorHandlergetErrorHandler()
Return the current error handler.

return
The current error handler, or null if none has been registered.
see
#setErrorHandler

        // REVISIT: Should this be a property?
        return (XMLErrorHandler)fProperties.get(ERROR_HANDLER);
    
public java.util.LocalegetLocale()
Returns the locale.

        return fLocale;
    
public abstract voidparse(org.apache.xerces.xni.parser.XMLInputSource inputSource)
Parse an XML document.

The parser can use this method to instruct this configuration to begin parsing an XML document from any valid input source (a character stream, a byte stream, or a URI).

Parsers may not invoke this method while a parse is in progress. Once a parse is complete, the parser may then parse another XML document.

This method is synchronous: it will not return until parsing has ended. If a client application wants to terminate parsing early, it should throw an exception.

param
inputSource The input source for the top-level of the XML document.
exception
XNIException Any XNI exception, possibly wrapping another exception.
exception
IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the parser.

protected voidreset()
reset all components before parsing and namespace context


        // reset every component
        int count = fComponents.size();
        for (int i = 0; i < count; i++) {
            XMLComponent c = (XMLComponent) fComponents.get(i);
            c.reset(this);
        }

    
public voidsetDTDContentModelHandler(org.apache.xerces.xni.XMLDTDContentModelHandler handler)
Sets the DTD content model handler.

param
handler The DTD content model handler.

        fDTDContentModelHandler = handler;
    
public voidsetDTDHandler(org.apache.xerces.xni.XMLDTDHandler dtdHandler)
Sets the DTD handler.

param
dtdHandler The DTD handler.

        fDTDHandler = dtdHandler;
    
public voidsetDocumentHandler(org.apache.xerces.xni.XMLDocumentHandler documentHandler)
Sets the document handler on the last component in the pipeline to receive information about the document.

param
documentHandler The document handler.

        fDocumentHandler = documentHandler;
        if (fLastComponent != null) {
            fLastComponent.setDocumentHandler(fDocumentHandler);
            if (fDocumentHandler !=null){
                fDocumentHandler.setDocumentSource(fLastComponent);
            }
        }
    
public voidsetEntityResolver(org.apache.xerces.xni.parser.XMLEntityResolver resolver)
Sets the resolver used to resolve external entities. The EntityResolver interface supports resolution of public and system identifiers.

param
resolver The new entity resolver. Passing a null value will uninstall the currently installed resolver.

        // REVISIT: Should this be a property?
        fProperties.put(ENTITY_RESOLVER, resolver);
    
public voidsetErrorHandler(org.apache.xerces.xni.parser.XMLErrorHandler errorHandler)
Allow an application to register an error event handler.

If the application does not register an error handler, all error events reported by the SAX parser will be silently ignored; however, normal processing may not continue. It is highly recommended that all SAX applications implement an error handler to avoid unexpected bugs.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

param
errorHandler The error handler.
exception
java.lang.NullPointerException If the handler argument is null.
see
#getErrorHandler

        // REVISIT: Should this be a property?
        fProperties.put(ERROR_HANDLER, errorHandler);
    
public voidsetFeature(java.lang.String featureId, boolean state)
Set the state of a feature. Set the state of any feature in a SAX2 parser. The parser might not recognize the feature, and if it does recognize it, it might not be able to fulfill the request.

param
featureId The unique identifier (URI) of the feature.
param
state The requested state of the feature (true or false).
exception
org.apache.xerces.xni.parser.XMLConfigurationException If the requested feature is not known.


        // forward to every component
        int count = fComponents.size();
        for (int i = 0; i < count; i++) {
            XMLComponent c = (XMLComponent) fComponents.get(i);
            c.setFeature(featureId, state);
        }
        // save state if noone "objects"
        super.setFeature(featureId, state);

    
public voidsetLocale(java.util.Locale locale)
Set the locale to use for messages.

param
locale The locale object to use for localization of messages.
exception
XNIException Thrown if the parser does not support the specified locale.

        fLocale = locale;
    
public voidsetProperty(java.lang.String propertyId, java.lang.Object value)
setProperty

param
propertyId
param
value


        // forward to every component
        int count = fComponents.size();
        for (int i = 0; i < count; i++) {
            XMLComponent c = (XMLComponent) fComponents.get(i);
            c.setProperty(propertyId, value);
        }

        // store value if noone "objects"
        super.setProperty(propertyId, value);