org.apache.commons.betwixt.io
Class BeanReader

java.lang.Object
  extended by org.xml.sax.helpers.DefaultHandler
      extended by org.apache.commons.digester.Digester
          extended by org.apache.commons.betwixt.io.BeanReader
All Implemented Interfaces:
org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public class BeanReader
extends org.apache.commons.digester.Digester

BeanReader reads a tree of beans from an XML document.

Call registerBeanClass(Class) or registerBeanClass(String, Class) to add rules to map a bean class.

Author:
James Strachan

Field Summary
 
Fields inherited from class org.apache.commons.digester.Digester
bodyText, bodyTexts, classLoader, configured, entityResolver, entityValidator, errorHandler, factory, JAXP_SCHEMA_LANGUAGE, locator, match, matches, namespaceAware, namespaces, params, parser, publicId, reader, root, rules, saxLog, schemaLanguage, schemaLocation, stack, substitutor, useContextClassLoader, validating, W3C_XML_SCHEMA
 
Constructor Summary
BeanReader()
          Construct a new BeanReader with default properties.
BeanReader(javax.xml.parsers.SAXParser parser)
          Construct a new BeanReader, allowing a SAXParser to be passed in.
BeanReader(org.xml.sax.XMLReader reader)
          Construct a new BeanReader, allowing an XMLReader to be passed in.
 
Method Summary
protected  void addBeanCreateRule(java.lang.String path, ElementDescriptor elementDescriptor, java.lang.Class beanClass)
          Adds a new bean create rule for the specified path
 void deregisterBeanClass(java.lang.Class beanClass)
          Remove the given class from the register.
 void flushRegisteredBeanClasses()
          Flush all registered bean classes.
 BindingConfiguration getBindingConfiguration()
          Gets the dynamic configuration setting to be used for bean reading.
 org.apache.commons.logging.Log getLog()
           Get the current level for logging.
 boolean getMatchIDs()
          Deprecated. 0.5 use BindingConfiguration.getMapIDs()
 ReadConfiguration getReadConfiguration()
          Gets read specific configuration details.
 XMLIntrospector getXMLIntrospector()
           Get the introspector used.
 void registerBeanClass(java.lang.Class beanClass)
          Register a bean class and add mapping rules for this bean class.
 void registerBeanClass(org.xml.sax.InputSource mapping, java.lang.Class beanClass)
          Registers a class with a custom mapping.
 void registerBeanClass(java.lang.String path, java.lang.Class beanClass)
          Registers a bean class and add mapping rules for this bean class at the given path expression.
 void registerMultiMapping(org.xml.sax.InputSource mapping)
          Registers a class with a multi-mapping.
 void setBindingConfiguration(BindingConfiguration bindingConfiguration)
          Sets the dynamic configuration setting to be used for bean reading.
 void setLog(org.apache.commons.logging.Log log)
           Set the current logging level.
 void setMatchIDs(boolean matchIDs)
          Deprecated. 0.5 use BindingConfiguration.setMapIDs(boolean)
 void setReadConfiguration(ReadConfiguration readConfiguration)
          Sets the read specific configuration details.
 void setXMLIntrospector(XMLIntrospector introspector)
           Set the introspector to be used.
 
Methods inherited from class org.apache.commons.digester.Digester
addBeanPropertySetter, addBeanPropertySetter, addCallMethod, addCallMethod, addCallMethod, addCallMethod, addCallParam, addCallParam, addCallParam, addCallParam, addCallParamPath, addFactoryCreate, addFactoryCreate, addFactoryCreate, addFactoryCreate, addFactoryCreate, addFactoryCreate, addFactoryCreate, addFactoryCreate, addFactoryCreate, addFactoryCreate, addObjectCreate, addObjectCreate, addObjectCreate, addObjectCreate, addObjectParam, addRule, addRuleSet, addSetNestedProperties, addSetNestedProperties, addSetNestedProperties, addSetNext, addSetNext, addSetProperties, addSetProperties, addSetProperties, addSetProperty, addSetRoot, addSetRoot, addSetTop, addSetTop, characters, clear, configure, createSAXException, createSAXException, createSAXException, endDocument, endElement, endPrefixMapping, error, fatalError, findNamespaceURI, getClassLoader, getCount, getCurrentElementName, getCustomContentHandler, getDebug, getDocumentLocator, getEntityResolver, getErrorHandler, getFactory, getFeature, getLogger, getMatch, getNamespaceAware, getParser, getProperty, getPublicId, getReader, getRoot, getRuleNamespaceURI, getRules, getSAXLogger, getSchema, getSchemaLanguage, getSubstitutor, getUseContextClassLoader, getValidating, getXMLReader, ignorableWhitespace, initialize, isEmpty, log, log, notationDecl, parse, parse, parse, parse, parse, peek, peek, peek, peek, peekParams, peekParams, pop, pop, popParams, processingInstruction, push, push, pushParams, register, resetRoot, resolveEntity, setClassLoader, setCustomContentHandler, setDebug, setDocumentLocator, setEntityResolver, setErrorHandler, setFeature, setLogger, setNamespaceAware, setProperty, setPublicId, setRuleNamespaceURI, setRules, setSAXLogger, setSchema, setSchemaLanguage, setSubstitutor, setUseContextClassLoader, setValidating, skippedEntity, startDocument, startElement, startPrefixMapping, unparsedEntityDecl, warning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BeanReader

public BeanReader()
Construct a new BeanReader with default properties.


BeanReader

public BeanReader(javax.xml.parsers.SAXParser parser)
Construct a new BeanReader, allowing a SAXParser to be passed in. This allows BeanReader to be used in environments which are unfriendly to JAXP1.1 (such as WebLogic 6.0). Thanks for the request to change go to James House (james@interobjective.com). This may help in places where you are able to load JAXP 1.1 classes yourself.

Parameters:
parser - use this SAXParser

BeanReader

public BeanReader(org.xml.sax.XMLReader reader)
Construct a new BeanReader, allowing an XMLReader to be passed in. This allows BeanReader to be used in environments which are unfriendly to JAXP1.1 (such as WebLogic 6.0). Note that if you use this option you have to configure namespace and validation support yourself, as these properties only affect the SAXParser and emtpy constructor.

Parameters:
reader - use this XMLReader as source for SAX events
Method Detail

registerBeanClass

public void registerBeanClass(java.lang.Class beanClass)
                       throws java.beans.IntrospectionException

Register a bean class and add mapping rules for this bean class.

A bean class is introspected when it is registered. It will not be introspected again even if the introspection settings are changed. If re-introspection is required, then deregisterBeanClass(java.lang.Class) must be called and the bean re-registered.

A bean class can only be registered once. If the same class is registered a second time, this registration will be ignored. In order to change a registration, call deregisterBeanClass(java.lang.Class) before calling this method.

All the rules required to digest this bean are added when this method is called. Other rules that you want to execute before these should be added before this method is called. Those that should be executed afterwards, should be added afterwards.

Parameters:
beanClass - the Class to be registered
Throws:
java.beans.IntrospectionException - if the bean introspection fails

registerBeanClass

public void registerBeanClass(java.lang.String path,
                              java.lang.Class beanClass)
                       throws java.beans.IntrospectionException

Registers a bean class and add mapping rules for this bean class at the given path expression.

A bean class is introspected when it is registered. It will not be introspected again even if the introspection settings are changed. If re-introspection is required, then deregisterBeanClass(java.lang.Class) must be called and the bean re-registered.

A bean class can only be registered once. If the same class is registered a second time, this registration will be ignored. In order to change a registration, call deregisterBeanClass(java.lang.Class) before calling this method.

All the rules required to digest this bean are added when this method is called. Other rules that you want to execute before these should be added before this method is called. Those that should be executed afterwards, should be added afterwards.

Parameters:
path - the xml path expression where the class is to registered. This should be in digester path notation
beanClass - the Class to be registered
Throws:
java.beans.IntrospectionException - if the bean introspection fails

registerMultiMapping

public void registerMultiMapping(org.xml.sax.InputSource mapping)
                          throws java.beans.IntrospectionException,
                                 java.io.IOException,
                                 org.xml.sax.SAXException

Registers a class with a multi-mapping. This mapping is specified by the multi-mapping document contained in the given InputSource.

Note: the custom mappings will be registered with the introspector. This must remain so for the reading to work correctly It is recommended that use of the pre-registeration process provided by XMLIntrospector.register(org.xml.sax.InputSource) be considered as an alternative to this method.

Parameters:
mapping - InputSource giving the multi-mapping document specifying the mapping
Throws:
java.beans.IntrospectionException
org.xml.sax.SAXException
java.io.IOException
Since:
0.7
See Also:
since the general notes given there apply equally to this, for more details on the multi-mapping format

registerBeanClass

public void registerBeanClass(org.xml.sax.InputSource mapping,
                              java.lang.Class beanClass)
                       throws java.beans.IntrospectionException,
                              java.io.IOException,
                              org.xml.sax.SAXException

Registers a class with a custom mapping. This mapping is specified by the standard dot betwixt document contained in the given InputSource.

Note: the custom mapping will be registered with the introspector. This must remain so for the reading to work correctly It is recommended that use of the pre-registeration process provided by XMLIntrospector.register(org.xml.sax.InputSource) be considered as an alternative to this method.

Parameters:
mapping - InputSource giving the dot betwixt document specifying the mapping
beanClass - Class that should be register
Throws:
java.beans.IntrospectionException
org.xml.sax.SAXException
java.io.IOException
Since:
0.7
See Also:
since the general notes given there apply equally to this

flushRegisteredBeanClasses

public void flushRegisteredBeanClasses()

Flush all registered bean classes. This allows all bean classes to be re-registered by a subsequent calls to registerBeanClass.

Note that deregistering a bean does not remove the Digester rules associated with that bean.

Since:
0.5

deregisterBeanClass

public void deregisterBeanClass(java.lang.Class beanClass)

Remove the given class from the register. Calling this method will allow the bean class to be re-registered by a subsequent call to registerBeanClass. This allows (for example) a bean to be reintrospected after a change to the introspection settings.

Note that deregistering a bean does not remove the Digester rules associated with that bean.

Parameters:
beanClass - the Class to remove from the set of registered bean classes
Since:
0.5

getXMLIntrospector

public XMLIntrospector getXMLIntrospector()

Get the introspector used.

The XMLBeanInfo used to map each bean is created by the XMLIntrospector. One way in which the mapping can be customized is by altering the XMLIntrospector.

Returns:
the XMLIntrospector used for the introspection

setXMLIntrospector

public void setXMLIntrospector(XMLIntrospector introspector)

Set the introspector to be used.

The XMLBeanInfo used to map each bean is created by the XMLIntrospector. One way in which the mapping can be customized is by altering the XMLIntrospector.

Parameters:
introspector - use this introspector

getLog

public org.apache.commons.logging.Log getLog()

Get the current level for logging.

Returns:
the Log implementation this class logs to

setLog

public void setLog(org.apache.commons.logging.Log log)

Set the current logging level.

Parameters:
log - the Logimplementation to use for logging

getMatchIDs

public boolean getMatchIDs()
Deprecated. 0.5 use BindingConfiguration.getMapIDs()

Should the reader use ID attributes to match beans.

Returns:
true if ID and IDREF attributes should be used to match instances

setMatchIDs

public void setMatchIDs(boolean matchIDs)
Deprecated. 0.5 use BindingConfiguration.setMapIDs(boolean)

Set whether the read should use ID attributes to match beans.

Parameters:
matchIDs - pass true if ID's should be matched

getBindingConfiguration

public BindingConfiguration getBindingConfiguration()
Gets the dynamic configuration setting to be used for bean reading.

Returns:
the BindingConfiguration settings, not null
Since:
0.5

setBindingConfiguration

public void setBindingConfiguration(BindingConfiguration bindingConfiguration)
Sets the dynamic configuration setting to be used for bean reading.

Parameters:
bindingConfiguration - the BindingConfiguration settings, not null
Since:
0.5

getReadConfiguration

public ReadConfiguration getReadConfiguration()
Gets read specific configuration details.

Returns:
the ReadConfiguration, not null
Since:
0.5

setReadConfiguration

public void setReadConfiguration(ReadConfiguration readConfiguration)
Sets the read specific configuration details.

Parameters:
readConfiguration - not null
Since:
0.5

addBeanCreateRule

protected void addBeanCreateRule(java.lang.String path,
                                 ElementDescriptor elementDescriptor,
                                 java.lang.Class beanClass)
Adds a new bean create rule for the specified path

Parameters:
path - the digester path at which this rule should be added
elementDescriptor - the ElementDescriptor describes the expected element
beanClass - the Class of the bean created by this rule


Copyright 2002-2008 The Apache Software Foundation. All Rights Reserved.