org.geotools.xml
Class Configuration

Object
  extended by Configuration
Direct Known Subclasses:
ApplicationSchemaConfiguration, GMLConfiguration, GMLConfiguration, GMLConfiguration, KMLConfiguration, OGCConfiguration, OGCConfiguration, OGCConfiguration, OWSConfiguration, OWSConfiguration, SLDConfiguration, SMIL20Configuration, SMIL20LANGConfiguration, WFSConfiguration, WPSConfiguration, XLINKConfiguration, XMLConfiguration, XSConfiguration

public abstract class Configuration
extends Object

Responsible for configuring a parser runtime environment.

Implementations have the following responsibilites:

Dependencies

Configurations have dependencies on one another, that result from teh fact that one schema imports another. Configuration dependencies are transitive. Each configuration should declare all dependencies in the constructor using the addDependency(Configuration) method.

         class MyConfiguration extends Configuration {
     public MyConfiguration() {
       super();

       addDependency( new FooConfiguration() );
       addDependency( new BarConfiguration() );
     }
     ...
  }
         

Binding Configuration

In able for a particular binding to be found during a parse, the configuration must first populate a container with said binding. This can be done by returning the appropriate instance of org.geotools.xml.BindingConfiguration in #getBindingConfiguration():

          
  BindingConfiguration getBindingConfiguration() {
      return new MyBindingConfiguration();
  }
          
  
Instances of type org.geotools.xml.BindingConfiguration are used to populate a container with all the bindings from a particular schema.

Context Configuration

Many bindings have dependencies on other types of objects. The pattern used to satisfy these dependencies is known as Constructor Injection. Which means that any dependencies a binding has is passed to it in its constructor. For instance, the following binding has a dependency on java.util.List.

         
 class MyBinding implements SimpleBinding {

                List list;

                 public MyBinding(List list) {
                         this.list = list;
                 }
 }
         
 
Before a binding can be created, the container in which it is housed in must be able to satisfy all of its dependencies. It is the responsibility of the configuration to statisfy this criteria. This is known as configuring the binding context. The following is a suitable configuration for the above binding.
         
 class MyConfiguration extends Configuration {
        ....
                void configureContext(MutablePicoContainer container) {
                        container.registerComponentImplementation(ArrayList.class);
                }
 }
         
 

Schema Resolution

XML instance documents often contain schema uri references that are invalid with respect to the parser, or non-existant. A configuration can supply specialized look up classes to prevent the parser from following an invalid uri and prevent any errors that may occur as a result.

An instance of XSDSchemaLocationResolver can be used to override a schemaLocation referencing another schema. This can be useful when the entity parsing an instance document stores schemas in a location unkown to the entity providing hte instance document.

An instance of XSDSchemaLocator can be used to provide an pre-parsed schema and prevent the parser from parsing a schemaLocation manually. This can be useful when an instance document does not supply a schemaLocation for the targetNamespace of the document.

         
 class MyConfiguration implements Configuration {

                XSDSchemaLocationResolver getSchemaLocationResolver() {
                  return new MySchemaLocationResolver();
                }

                XSDSchemaLocator getSchemaLocator() {
                  return new MySchemaLocator();
                }
 }
         
 

The XSDSchemaLocator and XSDSchemaLocationResolver implementations are used in a couple of scenarios. The first is when the schemaLocation attribute of the root element of the instance document is being parsed. The schemaLocation attribute has the form:

 
         schemaLocation="namespace location namespace location ..."
 
 
In which (namespace,location) tuples are listed. For each each namespace encountered when parsing the schemaLocation attribute, an appropriate resolver / locator is looked up. If an override is not aviable, the framework attempts to resolve the location part of the tuple into a schema. The second scenario occurs when the parsing of a schema encounters an import or an include element. These elements have the form:
  
      <import namespace="" schemaLocation=""/>
        
  
and:
  
      <include schemaLocation="">
  
        
respectivley. Similar to above, the schemaLocation (and namespace in the case of an import) are used to find an override. If not found they are resolved directly.

Author:
Justin Deoliveira,Refractions Research Inc.,jdeolive@refractions.net
See Also:
org.geotools.xml.BindingConfiguration
Module:
modules/extension/xsd-core (gt-xsd-core.jar)

Constructor Summary
Configuration(XSD xsd)
          Creates a new configuration.
 
Method Summary
protected  void addDependency(Configuration dependency)
          Adds a dependent configuration.
 List allDependencies()
          Returns all dependencies in the configuration dependency tree.
protected  void configureBindings(Map bindings)
          Template method allowing subclass to override any bindings.
protected  void configureBindings(MutablePicoContainer container)
          Deprecated. use configureBindings(Map).
protected  void configureContext(MutablePicoContainer container)
          Configures the root context to be used when parsing elements.
 boolean equals(Object obj)
          Equals override, equality is based soley on getNamespaceURI().
 MutablePicoContainer getContext()
          Returns an internal context which is copied into the runtime context while parsing.
 List getDependencies()
           
 String getNamespaceURI()
           
 Set getProperties()
          Returns a list of parser properties to set.
 String getSchemaFileURL()
          Deprecated. use XSD.getSchemaLocation().
 XSDSchemaLocationResolver getSchemaLocationResolver()
          Deprecated.  
 XSDSchemaLocator getSchemaLocator()
          Deprecated.  
 XSD getXSD()
          The XSD instance representing the schema for which the schema works against.
 int hashCode()
           
 boolean hasProperty(QName property)
          Searches the configuration and all dependent configuration for the speciifed property.
protected  void registerBindings(Map bindings)
          Registers the bindings for the configuration.
protected  void registerBindings(MutablePicoContainer container)
          Deprecated. use registerBindings(Map).
 XSDSchema schema()
          Deprecated. use getXSD() and XSD.getSchema().
 Map setupBindings()
          Creates the map of QName to Binding which is used during parsing to attach bindinds to an element,attribute, or type.
 MutablePicoContainer setupBindings(MutablePicoContainer container)
          Deprecated. use setupBindings().
 MutablePicoContainer setupContext(MutablePicoContainer container)
          Configures the root context to be used when parsing elements.
 
Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Configuration

public Configuration(XSD xsd)
Creates a new configuration.

Any dependent schemas should be added in sublcass constructor. The xml schema dependency does not have to be added.

Method Detail

getXSD

public XSD getXSD()
The XSD instance representing the schema for which the schema works against.


getDependencies

public final List getDependencies()
Returns:
a list of direct dependencies of the configuration.

getProperties

public final Set getProperties()
Returns a list of parser properties to set.

To set a parser property:

 Configuration configuration = ...
 configuration.getProperties().add( Parser.Properties.... );
 

Beware this class is not thread safe so take the needed precautions when using the list returned by this method.

Returns:
A list of hte set parser properties.

hasProperty

public final boolean hasProperty(QName property)
Searches the configuration and all dependent configuration for the speciifed property.


allDependencies

public final List allDependencies()
Returns all dependencies in the configuration dependency tree.

The return list contains no duplicates.

Returns:
All dependencies in teh configuration dependency tree.

addDependency

protected void addDependency(Configuration dependency)
Adds a dependent configuration.

This method should only be called from the constructor.

Parameters:
dependency -

getNamespaceURI

public final String getNamespaceURI()
Returns:
The namespace of the configuration schema.

getSchemaFileURL

public final String getSchemaFileURL()
Deprecated. use XSD.getSchemaLocation().

Returns the url to the file definiing hte schema.

For schema which are defined by multiple files, this method should return the base schema which includes all other files that define the schema.


getSchemaLocationResolver

public final XSDSchemaLocationResolver getSchemaLocationResolver()
Deprecated. 

Returns a schema location resolver instance used to override schema location uri's encountered in an instance document.

This method should be overridden to return such an instance. The default implemntation returns null

Returns:
The schema location resolver, or null

getSchemaLocator

public final XSDSchemaLocator getSchemaLocator()
Deprecated. 

Returns a schema locator, used to create imported and included schemas when parsing an instance document.

This method may be overriden to return such an instance. The default delegates to #createSchemaLocator() to and caches the restult. This method may return null to indicate that no such locator should be used.

Returns:
The schema locator, or null

schema

public XSDSchema schema()
Deprecated. use getXSD() and XSD.getSchema().

Convenience method for creating an instance of the schema for this configuration.

Returns:
The schema for this configuration.

getContext

public final MutablePicoContainer getContext()
Returns an internal context which is copied into the runtime context while parsing.

This context is provided to allow for placing values in the parsing context without having to sublcass.

Returns:
The context.

setupBindings

public final MutablePicoContainer setupBindings(MutablePicoContainer container)
Deprecated. use setupBindings().

Configures a container which houses all the bindings used during a parse.

Parameters:
container - The container housing the binding objects.

setupBindings

public final Map setupBindings()
Creates the map of QName to Binding which is used during parsing to attach bindinds to an element,attribute, or type.

Returns:
A map of Qname,[Class|Object]

registerBindings

protected void registerBindings(MutablePicoContainer container)
Deprecated. use registerBindings(Map).

Registers the bindings for the configuration.

This method is intended to provide the default bindings for a configuration and is intended to be subclassed by client code. Client code should use configureBindings(MutablePicoContainer) .

Subclasses should mark this method as final after implementing.

Parameters:
container - Container containing all bindings, keyed by QName.

registerBindings

protected void registerBindings(Map bindings)
Registers the bindings for the configuration.

This method is intended to provide the "default" bindings for a configuration and is not intended to be subclassed by client code. Client code should use configureBindings(MutablePicoContainer) to override/remove/add new bindings on teh fly.

The key of the bindings map is of type QName. The value can be class, or an instance. In the case of a class, the binding will be instantiated by the parser at runtime. In the instance case the binding will be used as is.


configureBindings

protected void configureBindings(MutablePicoContainer container)
Deprecated. use configureBindings(Map).

Template method allowing subclass to override any bindings.

Parameters:
container - Container containing all bindings, keyed by QName.

configureBindings

protected void configureBindings(Map bindings)
Template method allowing subclass to override any bindings.

Parameters:
bindings - Map containing all bindings, keyed by QName.

setupContext

public final MutablePicoContainer setupContext(MutablePicoContainer container)
Configures the root context to be used when parsing elements.

Parameters:
container - The container representing the context.

configureContext

protected void configureContext(MutablePicoContainer container)
Configures the root context to be used when parsing elements.

The context satisifies any depenencencies needed by a binding. This is often a factory used to create something.

This method should be overriden. The default implementation does nothing.

Parameters:
container - The container representing the context.

equals

public final boolean equals(Object obj)
Equals override, equality is based soley on getNamespaceURI().

Overrides:
equals in class Object

hashCode

public final int hashCode()
Overrides:
hashCode in class Object


Copyright © 1996-2009 Geotools. All Rights Reserved.