biz.hammurapi.config
Class DomConfigFactory

java.lang.Object
  biz.hammurapi.config.DomConfigFactory

public class DomConfigFactory
extends java.lang.Object

Creates and configures objects from DOM Element (XML file). DOM Element can be read from InputStream, File or URL. Instantiation and configuration happens as follows:

Instantiation

• If there is no 'type' attribute then type defaults to String and text of the element will be returned. E.g. <name>Pavel</name> will yield string 'Pavel'. 'type' attribute name can be changed through biz.hammurapi.config.DomConfigInfo#setCodeExpression(String) method. Create biz.hammurapi.config.DomConfigInfo, change code expression and then use #DomConfigFactory(DomConfigInfo) to instantiate DomConfigFactory.
• Otherwise class specified in 'type' attribute will be loaded and verified by classAcceptor (if any)
• If there is no nested 'constructor'' element and element text is blank then default constructor will be used
• If there is no nested 'constructor'' element and element text is not blank then constructor which takes a single argument of type java.lang.String will be used
• If there is nested 'constructor' element then 'arg' elements of 'constructor' element are iterated to create a list of arguments. Arguments are constructed in the same way as described here. 'arg' element also supports 'context-ref' attribute. If this attribute is set argument value will be taken from context entry set by DomConfigFactory#setContextEntry(String, Object) method

Configuration

• If element has attribute 'url' and instantiated object (instance) is instance of URLConfigurable then biz.hammurapi.config.URLConfigurable#configure(URL, Map) is invoked to configure instance
• If element has attribute 'file' and instance is instance of FileConfigurable then biz.hammurapi.config.FileConfigurable#configure(File, Map) is invoked to configure instance
• If instance is instance of InputStreamConfigurable then
  • If element has attribute 'url' then that url is opened as InsputStream
  • If element has attribute 'file' then that file is opened as InputStream
  • If element has attribute 'resource' then that resource is opened as InputStream. Instance's class is used to obtain resource which allows to use relative resource names.
  then that InputStream is passed to biz.hammurapi.config.InputStreamConfigurable#configure(InputStream, Map) to configure instance. If none of aforementioned attributes is present then ConfigurationException is thrown.
• If instance is instance of DomConfigurable then
  • If element has attribute 'url' then that url is opened as InsputStream and parsed to DOM tree
  • If element has attribute 'file' then that file is opened as InputStream and parsed to DOM tree
  • If element has attribute 'resource' then that resource is opened as InputStream and parsed to DOM tree. Instance's class is used to obtain resource which allows to use relative resource names.
  then that parsed document is passed to DomConfigurable.configure(Node, Context, ClassLoader). If none of the aforementioned attributes is present then element itself is passed to DomConfigurable.configure(Node, Context, ClassLoader)
• If instance is instance of Parameterizable then
  • If there are subelements 'parameter' with attribute 'name' then value of 'name' is used as parameter name
  • Otherwise names of nested elements used as parameter names
  Parameter values are evaluated in the same way as 'arg' elements for constructors. Parameterizable.setParameter(String, Object) is invoked for each of parameter elements. Parameterizable.setParameter(String, Object) is also invoked for context entries with names which did not match with parameter names. E.g. if there are two context entries 'age' and 'name' and parameter 'name' then setParameter("name", value of parameter 'name') will be invoked and after that setParameter("age", value of context entry 'age') will be invoked.
• If instance is instance of StringConfigurable then element text is passed to StringConfigurable#configure(String, Map) method
• If instance is instance of Map then 'entry' subelements are iterated; 'key' (Configurable through biz.hammurapi.config.DomConfigInfo) and 'value' (Configurable through biz.hammurapi.config.DomConfigInfo) subelements are evaluated in the same way as 'arg' constructors subelements and put to instance by Map.put(java.lang.Object, java.lang.Object)
• If instance is instance of Collection then 'element' subelements are iterated, elements are istantiated in the same way as constructor arguments and then placed into instance by invoking Collection.add(java.lang.Object) method.
• If none of above conditions are met then reflection is used to inject values into instance fields/properties in a similar way as parameters for Parameterizable are set. Special note about injection: If field type or setter parameter type (target type) is compatible with instantiated value then the value is used as is. Otherwise if target type is compatible with source XML Element then the element is used. If value is instance of Wrapper and wrapper's master is compatible with the target type then the master is used. If wrapper is also a component then its setOwner() and start() methods are invoked before obtaining master. If none of aforementioned conditions are true then value is converted to target type. using biz.hammurapi.convert.CompositeConverter.
• If object acceptor is not null then its ObjectAcceptor.accept(Object) is invoked to validate that object has been constructed and configured correctly
• If instance is instance of Validatable then Validatable.validate() is invoked for the instance to validate itself.

Examples

1. <name>Pavel</name> will yield java.lang.String with value 'Pavel'
2. <age type="java.lang.Integer">33</age> will yield java.lang.Integer with value '33'
3. <config type="org.myself.myproject.MyConfig" url="http://myproject.myself.org/MyConfig.xml"/> will load configuration from URL and configure MyConfig object

4. <config type="org.myself.myproject.MyParameterizableConfig">
        <parameter name="pi" type="java.lang.Double">3.14159</parameter>
    </config>

   will create MyParameterizableConfig object and then invoke its setParameter() method if MyParameterizableConfig implements Parameterizable or invoke setPi() method if there is such method. In lenient mode nothing will happen if there is no setPi() method. Otherwise exception will be thrown.

5. <config type="org.myself.myproject.MyParameterizableConfig">
        <pi type="java.lang.Double">3.14159</pi>
    </config>

   same as above.

It is recommended to use XML Beans generated classes instead of this factory.

Version:

$Revision: 1.12 $

Author:

Pavel Vlasov

Field Summary

static java.lang.String	CLASS_LOADER
static java.lang.String	CODE_EXPRESSION
static java.lang.String	CONFIG_RESOURCE_PREFIX
static java.lang.String	MAP_KEY_EXPRESSION
static java.lang.String	MAP_VALUE_EXPRESSION
static java.util.Map	PRIMITIVES
static java.lang.String	RESOURCE_PREFIX
static java.lang.String	XML_EXTENSION

Constructor Summary

DomConfigFactory()
Default constructor

DomConfigFactory(java.lang.ClassLoader classLoader)

DomConfigFactory(java.lang.ClassLoader classLoader, Context context)

DomConfigFactory(Context context)
Default constructor

Method Summary

java.lang.Object	create(java.io.File file, java.lang.String xPath) Parses file and returns object.
java.lang.Object	create(java.io.File file, java.lang.String xPath, ClassAcceptor classAcceptor, ObjectAcceptor objectAcceptor) Parses file and returns object
java.lang.Object	create(java.io.InputStream in, java.lang.String xPath) Same as create(in, xPath, null, null)
java.lang.Object	create(java.io.InputStream in, java.lang.String xPath, ClassAcceptor classAcceptor, ObjectAcceptor objectAcceptor) Creates and configures object from InputStream
java.lang.Object	create(org.w3c.dom.Node node) Creates object.
java.lang.Object	create(org.w3c.dom.Node node, ClassAcceptor classAcceptor, ObjectAcceptor objectAcceptor) Creates and configures object
java.lang.Object	create(java.io.Reader in, java.lang.String xPath) Same as create(in, xPath, null, null)
java.lang.Object	create(java.io.Reader in, java.lang.String xPath, ClassAcceptor classAcceptor, ObjectAcceptor objectAcceptor) Creates and configures object from InputStream
java.lang.Object	create(java.net.URL url, java.lang.String xPath) Same as create(url, xPath, null, null)
java.lang.Object	create(java.net.URL url, java.lang.String xPath, ClassAcceptor classAcceptor, ObjectAcceptor objectAcceptor) Creates and configures object from URL
static void	inject(java.lang.Object instance, Context context) Sets property (field or through setter or appender) using reflection.
static java.util.Iterator	loadProviders(java.lang.Class service, java.lang.ClassLoader classLoader) Loads providers for a given service.
static void	main(java.lang.String[] args)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

XML_EXTENSION

public static final java.lang.String XML_EXTENSION

See Also:

Constant Field Values

CONFIG_RESOURCE_PREFIX

public static final java.lang.String CONFIG_RESOURCE_PREFIX

See Also:

Constant Field Values

RESOURCE_PREFIX

public static final java.lang.String RESOURCE_PREFIX

See Also:

Constant Field Values

CLASS_LOADER

public static final java.lang.String CLASS_LOADER

CODE_EXPRESSION

public static final java.lang.String CODE_EXPRESSION

See Also:

Constant Field Values

MAP_KEY_EXPRESSION

public static final java.lang.String MAP_KEY_EXPRESSION

See Also:

Constant Field Values

MAP_VALUE_EXPRESSION

public static final java.lang.String MAP_VALUE_EXPRESSION

See Also:

Constant Field Values

PRIMITIVES

public static final java.util.Map PRIMITIVES

Constructor Detail

DomConfigFactory

public DomConfigFactory()

Default constructor

DomConfigFactory

public DomConfigFactory(Context context)

Default constructor

DomConfigFactory

public DomConfigFactory(java.lang.ClassLoader classLoader)

DomConfigFactory

public DomConfigFactory(java.lang.ClassLoader classLoader,
                        Context context)

Method Detail

create

public java.lang.Object create(org.w3c.dom.Node node)
                        throws ConfigurationException

Creates object. Same as create(node, null, null)

Parameters:

node -

Returns:

Throws:

ConfigurationException

create

public java.lang.Object create(java.io.File file,
                               java.lang.String xPath)
                        throws ConfigurationException,
                               java.io.IOException

Parses file and returns object. Same as create(file, xPath, null, null)

Parameters:

file - XML configuration file

xPath - XPath expression, can be null

Returns:

configured object

Throws:

ConfigurationException

java.io.IOException

create

public java.lang.Object create(java.io.File file,
                               java.lang.String xPath,
                               ClassAcceptor classAcceptor,
                               ObjectAcceptor objectAcceptor)
                        throws ConfigurationException,
                               java.io.IOException

Parses file and returns object

Parameters:

file - XML configuration file

xPath - XPath expression, can be null

classAcceptor - Class acceptor, validates that class about to be instantiated is 'the right one'

objectAcceptor - Object acceptor, validates instantiated object.

Returns:

Configured object

Throws:

ConfigurationException

java.io.IOException

create

public java.lang.Object create(java.io.InputStream in,
                               java.lang.String xPath)
                        throws ConfigurationException,
                               java.io.IOException

Same as create(in, xPath, null, null)

Parameters:

in - Input stream

xPath - XPath expression, can be null

Returns:

Configured object

Throws:

ConfigurationException

java.io.IOException

create

public java.lang.Object create(java.io.InputStream in,
                               java.lang.String xPath,
                               ClassAcceptor classAcceptor,
                               ObjectAcceptor objectAcceptor)
                        throws ConfigurationException,
                               java.io.IOException

Creates and configures object from InputStream

Parameters:

in - Input stream

xPath - XPath expression, can be null

classAcceptor -

objectAcceptor -

Returns:

Configured object

Throws:

ConfigurationException

java.io.IOException

create

public java.lang.Object create(java.io.Reader in,
                               java.lang.String xPath)
                        throws ConfigurationException,
                               java.io.IOException

Same as create(in, xPath, null, null)

Parameters:

in - Reader

xPath - XPath expression, can be null

Returns:

Configured object

Throws:

ConfigurationException

java.io.IOException

create

public java.lang.Object create(java.io.Reader in,
                               java.lang.String xPath,
                               ClassAcceptor classAcceptor,
                               ObjectAcceptor objectAcceptor)
                        throws ConfigurationException,
                               java.io.IOException

Creates and configures object from InputStream

Parameters:

in - Reader

xPath - XPath expression, can be null

classAcceptor -

objectAcceptor -

Returns:

Configured object

Throws:

ConfigurationException

java.io.IOException

create

public java.lang.Object create(java.net.URL url,
                               java.lang.String xPath)
                        throws ConfigurationException,
                               java.io.IOException

Same as create(url, xPath, null, null)

Parameters:

url - URL to read configuration from

xPath - XPath expression, can be null

Returns:

Configured object

Throws:

ConfigurationException

java.io.IOException

create

public java.lang.Object create(java.net.URL url,
                               java.lang.String xPath,
                               ClassAcceptor classAcceptor,
                               ObjectAcceptor objectAcceptor)
                        throws ConfigurationException,
                               java.io.IOException

Creates and configures object from URL

Parameters:

url - Url

xPath - XPath expression, can be null

classAcceptor -

objectAcceptor -

Returns:

Configured object

Throws:

ConfigurationException

java.io.IOException

create

public java.lang.Object create(org.w3c.dom.Node node,
                               ClassAcceptor classAcceptor,
                               ObjectAcceptor objectAcceptor)
                        throws ConfigurationException

Creates and configures object

Parameters:

node -

classAcceptor -

objectAcceptor -

cxpa - Cached XPath API to accelerate XPath expressions evaluation.

Returns:

Configured object

Throws:

ConfigurationException

inject

public static void inject(java.lang.Object instance,
                          Context context)
                   throws ConfigurationException

Sets property (field or through setter or appender) using reflection. This method can inject single or multiple values from the context to the instance using setXXX(argType arg), setXXX(argType[] arg), setXXX(Collection args), or addXXX(argType arg). For multi-value injections the context shall return collection, array, or iterator instance from its get() method.

Parameters:

instance -

context - Source of data to inject.

Throws:

ConfigurationException

main

public static void main(java.lang.String[] args)

loadProviders

public static java.util.Iterator loadProviders(java.lang.Class service,
                                               java.lang.ClassLoader classLoader)

Loads providers for a given service. Providers are loaded anew at every invocation of this method.

Type Parameters:

T -

Parameters:

service - Service class.

classLoader - Class loader

Returns:

Iterator of providers of given class.

Throws:

ConfigurationException