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


Copyright 1999-2003 Sapient Corporation. All Rights Reserved.