org.sape.carbon.core.config.format.jdom
Class JDOMConfigurationProxy

java.lang.Object
  |
  +--org.sape.carbon.core.util.reflection.GenericProxy
        |
        +--org.sape.carbon.core.config.format.AbstractConfigurationProxy
              |
              +--org.sape.carbon.core.config.format.jdom.JDOMConfigurationProxy

All Implemented Interfaces:

Configuration, InvocationHandler, Serializable

public class JDOMConfigurationProxy

extends AbstractConfigurationProxy

This is an extension of an AbstractConfigurationProxy that is backed by a JDOM Document data structure.

Copyright 2002 Sapient

Since:

carbon 1.0

Version:

$Revision: 1.53 $($Author: dvoet $ / $Date: 2003/12/10 21:11:00 $)

Author:

Greg Hinkle, February 2002, Douglas Voet

See Also:

Serialized Form

Field Summary

protected Map	attributeCache Map for caching previously accessed attributes
static String	MAP_KEY_ATTRIBUTE Key attribute for a map element.
protected ConfigurationTypeService	typeService Holds the type service for configuration.

Fields inherited from class org.sape.carbon.core.config.format.AbstractConfigurationProxy

document, documentType, element, name, REF_PREFIX, REF_PREFIX_LENGTH

Fields inherited from class org.sape.carbon.core.util.reflection.GenericProxy

Constructor Summary

JDOMConfigurationProxy(Class configurationClass)
Constructs a JDOMConfigurationProxy for the specified class type.

JDOMConfigurationProxy(org.jdom.Document document, Class configurationClass)
Constructs a JDOMConfigurationProxy for the specified class type.

JDOMConfigurationProxy(org.jdom.Element element, Class configurationClass)
Constructs a JDOMConfigurationProxy for the specified class type.

Method Summary

protected org.jdom.Element	addAttribute(org.jdom.Element element, String attributeName, Class type, Object obj) Adds an attribute.
org.jdom.Element	addAttribute(String attributeName, Class type, Object obj) This method should add a child entity to this configuration entity
void	alterAttribute(String attributeName, Class attributeType, Object newValue) Implementations of this method should provide the ability to alter an attribute within the configuration object setting its value to the provide newValue.
Object	clone() This method clones this Configuration object through a deep-copy of it's underlying datastructure.
protected org.jdom.Element	configurationToElement(Configuration config) Converts a configuration to its jdom representation.
protected org.jdom.Element	constructElement(String entityName, Class type, Object obj) Constructs a jdom element from the given object by calling the ConfigurationTypeService
protected Object	formatContainedElement(org.jdom.Element element, String name, String key, Class type) Converts the element to its object representation.
protected Object	formatElement(org.jdom.Element element, String name, Class type) Converts the element to its object representation.
Object	getArray(String attributeName, Class componentType) Retrieves an array of objects of the specified type that have the specified name.
protected Configuration	getChildConfiguration(Class requiredInterface, org.jdom.Element element, String name) Builds a new implementation of the specified configuration class by using a JDOMConfigurationProxy as the InvocationHandler for a Dynamic Proxy.
protected org.jdom.Element	getCollectionElement(String attributeName, Class type) Gets the element containing either an array or Map object.
Map	getMap(String tagName, Class contentType) Retrieves a java.util.Map of objects of the specified type that have the specified name.
Object	lookupAttribute(String attributeName, Class returnType) Implementations of this method should retrieve a value from the configuration object with the specified name and Type.
protected void	preLoadAttributeCache() This method is not in use as of carbon 1.1.
String	proxyToString(Object proxy) This method overrides the base proxy's toString implementation so that useful data is printed out when toString is called.
void	setArrayValue(String attributeName, Class attributeType, int index, Object value) Sets the value of a specific index in an array of data in this configuration object.
void	setConfigurationReadOnly() Sets whether this configuration may be altered.
void	setMapValue(String attributeName, Class attributeType, Object key, Object value) Sets the value of a specific index in an array of data in this configuration object.

Methods inherited from class org.sape.carbon.core.config.format.AbstractConfigurationProxy

getArrayValue, getChildType, getCollectionComponentType, getConfigurationInterface, getConfigurationInterface, getConfigurationName, getDataStructure, getDocumentType, getRootElement, getSimpleClassName, handleInvoke, isChildConfiguration, isConfigurationWritable, isMapAttribute, isReference, lookupDefaultAttributeValue, proxyEquals, proxyHashCode, setConfigurationName

Methods inherited from class org.sape.carbon.core.util.reflection.GenericProxy

invoke

Methods inherited from class java.lang.Object

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

Field Detail

typeService

protected final ConfigurationTypeService typeService

Holds the type service for configuration.

attributeCache

protected Map attributeCache

Map for caching previously accessed attributes

Since:

carbon 1.1

MAP_KEY_ATTRIBUTE

public static final String MAP_KEY_ATTRIBUTE

Key attribute for a map element.

See Also:

Constant Field Values

Constructor Detail

JDOMConfigurationProxy

public JDOMConfigurationProxy(Class configurationClass)

Constructs a JDOMConfigurationProxy for the specified class type. This class only supports subclasses of the Configuration object.

Parameters:

configurationClass - The type of Configuration object that should be returned

JDOMConfigurationProxy

public JDOMConfigurationProxy(org.jdom.Document document,
                              Class configurationClass)

Constructs a JDOMConfigurationProxy for the specified class type. This class only supports subclasses of the Configuration object. The supplied document is used as the backing store for this configuration object's data.

Parameters:

document - The JDOM Document object representing a configurations data

configurationClass - The type of configuration to be implemented

JDOMConfigurationProxy

public JDOMConfigurationProxy(org.jdom.Element element,
                              Class configurationClass)

Constructs a JDOMConfigurationProxy for the specified class type. This class only supports subclasses of the Configuration object. The supplied Element is used as the backing datastore for this configuration object and it's document object will be modified when this object is modified.

Parameters:

element - The JDOM element object representing to root node of this configuration object

configurationClass - The type of configuration object that will be implemented

Method Detail

proxyToString

public String proxyToString(Object proxy)

This method overrides the base proxy's toString implementation so that useful data is printed out when toString is called.

Overrides:

proxyToString in class GenericProxy

Parameters:

proxy - the proxy to print

Returns:

a string representation of this configuration object

clone

public Object clone()

This method clones this Configuration object through a deep-copy of it's underlying datastructure. The resulting configuration object is a new object and can be altered without affecting the original.

Specified by:

clone in interface Configuration

Specified by:

clone in class AbstractConfigurationProxy

Returns:

Object the cloned configuration object

See Also:

Object.clone()

lookupAttribute

public Object lookupAttribute(String attributeName,
                              Class returnType)

Description copied from class: AbstractConfigurationProxy

Implementations of this method should retrieve a value from the configuration object with the specified name and Type. The Type information is gleaned from the providing configuration interface and allows the system to determine the proper mechanism for instantiating this value. This may involve the usage of the micro-level formatting for configuration values.

Specified by:

lookupAttribute in class AbstractConfigurationProxy

Parameters:

attributeName - the name of the attribute to retrieve

returnType - the class type of the object that should be returned

Returns:

the object representing the specified confuguration value

See Also:

AbstractConfigurationProxy.lookupAttribute(java.lang.String, java.lang.Class)

getArray

public Object getArray(String attributeName,
                       Class componentType)

Retrieves an array of objects of the specified type that have the specified name. This might get a list of dependent objects or a list of string values.

Specified by:

getArray in class AbstractConfigurationProxy

Parameters:

attributeName - the name of the array to retrieve

componentType - the type of the objects that should be retrieved within the array

Returns:

an array of objects that match the name and type specified

getMap

public Map getMap(String tagName,
                  Class contentType)

Description copied from class: AbstractConfigurationProxy

Retrieves a java.util.Map of objects of the specified type that have the specified name. This might get a list of dependent objects or a list of string values.

Specified by:

getMap in class AbstractConfigurationProxy

Parameters:

tagName - the name of the array to retrieve

contentType - the type of the objects that should be retrieved within the Map

Returns:

a Map of objects that match the name and type specified

See Also:

AbstractConfigurationProxy.getMap(java.lang.String, java.lang.Class)

alterAttribute

public void alterAttribute(String attributeName,
                           Class attributeType,
                           Object newValue)

Description copied from class: AbstractConfigurationProxy

Implementations of this method should provide the ability to alter an attribute within the configuration object setting its value to the provide newValue.

Specified by:

alterAttribute in class AbstractConfigurationProxy

Parameters:

attributeName - the name of the attribute to be altered

attributeType - the type of the attribute

newValue - the new value to change that attribute to

See Also:

AbstractConfigurationProxy.alterAttribute(java.lang.String, java.lang.Class, java.lang.Object)

addAttribute

public org.jdom.Element addAttribute(String attributeName,
                                     Class type,
                                     Object obj)

Description copied from class: AbstractConfigurationProxy

This method should add a child entity to this configuration entity

Specified by:

addAttribute in class AbstractConfigurationProxy

Parameters:

attributeName - the name of the array on which to add a particular value

type - type of class of the child entity

obj - The object to be added as a configuration entity

Returns:

the element representing the added attribute

See Also:

AbstractConfigurationProxy.addAttribute(java.lang.String, java.lang.Class, java.lang.Object)

addAttribute

protected org.jdom.Element addAttribute(org.jdom.Element element,
                                        String attributeName,
                                        Class type,
                                        Object obj)

Adds an attribute.

Parameters:

element - the element to add an attribute to

attributeName - the name of the attribute to add

type - the classtype of the attribute

obj - the attribute to add

Returns:

the newly created images

setArrayValue

public void setArrayValue(String attributeName,
                          Class attributeType,
                          int index,
                          Object value)

Description copied from class: AbstractConfigurationProxy

Sets the value of a specific index in an array of data in this configuration object. Implementing classes must set the specified index of the array named by attributeName to the specified value.

Specified by:

setArrayValue in class AbstractConfigurationProxy

Parameters:

attributeName - the name of the array to alter

attributeType - the type of the objects in the array

index - the indicie of the array to alter

value - the Object to set as the value of this indicie

See Also:

AbstractConfigurationProxy.setArrayValue(java.lang.String, java.lang.Class, int, java.lang.Object)

setMapValue

public void setMapValue(String attributeName,
                        Class attributeType,
                        Object key,
                        Object value)

Sets the value of a specific index in an array of data in this configuration object. Implementing classes must set the specified index of the array named by attributeName to the specified value.

Specified by:

setMapValue in class AbstractConfigurationProxy

Parameters:

attributeName - the name of the array to alter

attributeType - the component type of the value within the map.

key - the key within the map to set

value - the Object to set as the value of this indicie

getCollectionElement

protected org.jdom.Element getCollectionElement(String attributeName,
                                                Class type)

Gets the element containing either an array or Map object.

Parameters:

attributeName - name of the attribute to get the element for

type - the type of class contained in the array or Map

Returns:

element containing the array or Map

formatElement

protected Object formatElement(org.jdom.Element element,
                               String name,
                               Class type)
                        throws ConfigurationFormatException

Converts the element to its object representation.

This implementation will create a new configuration proxy if the type is a subtype of Configuration or the type is complex. If it is not a configuration subtype, the type handlers will be used to convert the data to an object. If type is not a Configuration or complex type and element is null or its type handler returns null, this implementation will attempt to lookup a default via a call to lookupDefaultAttributeValue from the super class. If element is null or its type handler returns null and there is no default and type is a primitive, an exception is thrown.

Parameters:

element - the element to be converted

name - the name of the element, used to name the resulting object when it is a subtype of Configuration

type - expected type of the resulting object

Returns:

Object the object representation of element

Throws:

ConfigurationFormatException - indicates an error formatting the element

formatContainedElement

protected Object formatContainedElement(org.jdom.Element element,
                                        String name,
                                        String key,
                                        Class type)
                                 throws ConfigurationFormatException

Converts the element to its object representation.

The method is the same as formatElement except that it does not look up a default for the element if it is null.

Parameters:

element - the element to be converted

name - the name of the element, used to name the resulting object when it is a subtype of Configuration

key - the accessor key of the element, used to name the resulting object when it is a subtype of Configuration

type - expected type of the resulting object

Returns:

Object the object representation of element

Throws:

ConfigurationFormatException - indicates an error formatting the contained element

getChildConfiguration

protected Configuration getChildConfiguration(Class requiredInterface,
                                              org.jdom.Element element,
                                              String name)

Builds a new implementation of the specified configuration class by using a JDOMConfigurationProxy as the InvocationHandler for a Dynamic Proxy.

If the configuration is a reference (the element text starts with "ref://"), the referenced configuraiton is fetched from the config service and returned, otherwise, a new configuration object is created.

Parameters:

requiredInterface - The class that will be implemented by the configuration

element - The root element of the configuration object

name - the name of the child configuration being retreived

Returns:

the new configuration object implementation representing the data supplied in the element

constructElement

protected org.jdom.Element constructElement(String entityName,
                                            Class type,
                                            Object obj)

Constructs a jdom element from the given object by calling the ConfigurationTypeService

Parameters:

entityName - name of the element to construct

type - type of data represented by obj

obj - data represented by returned element

Returns:

Element jdom element representation of obj

configurationToElement

protected org.jdom.Element configurationToElement(Configuration config)

Converts a configuration to its jdom representation. If config is a nested configuration (either its name is null or its name starts with this configuration's name), a clone of its root element is returned. If config exists outside of this configuration, a reference to config is created.

Parameters:

config - configuration to be converted

Returns:

Element jdom represnetation

setConfigurationReadOnly

public void setConfigurationReadOnly()

Description copied from class: AbstractConfigurationProxy

Sets whether this configuration may be altered.

Specified by:

setConfigurationReadOnly in interface Configuration

Overrides:

setConfigurationReadOnly in class AbstractConfigurationProxy

preLoadAttributeCache

protected void preLoadAttributeCache()

This method is not in use as of carbon 1.1. It causes an infinite loop in the case of circular references within configs. Until a better solution is found for preloading configuration, the attributeCache is synchronized when the config is read-only.

Loads all the attributes into the attribute cache. This is used when the configuration object is switched to read-only mode to prevent concurrent reads from corrupting the cache. After this, there should never be a lookup that needs to add to the cache; the cache effectively becomes read-only.

This implementation uses the Introspector to get all the properties of the configuration interface, then looks up each property using either lookupAttribute or getArray, depending on whether or not the property is indexed.

Since:

carbon 1.1