org.sape.carbon.core.config.format
Class AbstractConfigurationProxy

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

All Implemented Interfaces:

Configuration, InvocationHandler, Serializable

Direct Known Subclasses:

JDOMConfigurationProxy

public abstract class AbstractConfigurationProxy

extends GenericProxy

implements Configuration, Serializable

This abstract class includes basic support for configuration objects in XML. This class implements the Dynamic Proxy InvocationHandler interface. By utilizing Dynamic Proxies this class can implement any subclass of Configuration and automatically support reading and writing the data of that object to XML.

This abstract class implements the basic functionality for managing a JDOM Document. It also provides abstract method declarations that allow a subclass to choose exactly the format for that XML and how it is treated by a Configuration object.

Copyright 2002 Sapient

Since:

carbon 1.0

Version:

$Revision: 1.58 $($Author: dvoet $ / $Date: 2003/11/26 20:30:18 $)

Author:

Greg Hinkle, January 2002

See Also:

Serialized Form

Field Summary

protected org.jdom.Document	document JDOM Document object that holds the xml version of this configuration object's data.
protected Class	documentType The Class of object that this configuration object is implementing.
protected org.jdom.Element	element The root element of this configuration object.
private org.apache.commons.logging.Log	log Provides a handle to Apache-commons logger
protected String	name The fully qualified configuration name for this configuration object
protected static String	REF_PREFIX Prefix for config values that reference other configs.
protected static int	REF_PREFIX_LENGTH Holds the length of reference prefix.
private static String	ROOT_TAG The root XML tag for configuration documnts
private boolean	writable True if this object may be altered, false if it should throw exceptions when attempts are made to alter it.

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

Constructor Summary

protected	AbstractConfigurationProxy(Class documentType) Constructs an AbstractConfigurationProxy for the supplied document.
protected	AbstractConfigurationProxy(org.jdom.Document document, org.jdom.Element root, Class documentType) Constructs an AbstractConfigurationProxy for the supplied document.

Method Summary

abstract org.jdom.Element	addAttribute(String entityName, Class type, Object obj) This method should add a child entity to this configuration entity
abstract 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.
abstract Object	clone() This method makes a deep-copy of the underlying data structure for this configuration
abstract Object	getArray(String attributeName, Class componentType) Retrieves an array of objects of the specified type that have the specified name.
protected Object	getArrayValue(String attributeName, Class type, int index) Gets the value from an configuration array.
Class	getChildType(String attributeName) Retrieves the type of a JavaBean attribute by introspecting for its retrieval method and checking its return type.
protected Class	getCollectionComponentType(String attrName) Gets the type of class contained within a map.
Class	getConfigurationInterface() This method returns the Class of this component's configuration.
protected Class	getConfigurationInterface(org.jdom.Element element, Class defaultInterface) Gets the ConfigurationInterface specifed in an element.
String	getConfigurationName() Retrieves this configuration object's name
org.jdom.Document	getDataStructure() Returns a JDOM Document object representing the underlying data of this configuration object.
Class	getDocumentType() Retrieves the primary type of this configuration
abstract Map	getMap(String attributeName, Class contentType) Retrieves a java.util.Map of objects of the specified type that have the specified name.
org.jdom.Element	getRootElement() Retrieves the root element of the data being currently mapped by this configuration object.
static String	getSimpleClassName(Class theClass) Returns the simple class name without the prepended package structure
protected Object	handleInvoke(Object proxy, Method m, Object[] args) This method provides the basic implementation of invocations from the standpoint of DynamicProxies.
boolean	isChildConfiguration(org.jdom.Element childElement) Checks whether or not childElement is a child configuration or not
boolean	isConfigurationWritable() Is this configuration document writable or is it read-only.
protected boolean	isMapAttribute(String attrName) Checks if the given attribute contains a map.
boolean	isReference(org.jdom.Element element) Checks whether or not element is a reference to another configuration.
abstract 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 Object	lookupDefaultAttributeValue(Class type, String attributeName, Class returnType) Retrieves the default value for a requested configuration attribute from an interface static variable with the same name as the requested attribute.
protected Boolean	proxyEquals(Object proxy, Object other) This method implements the standard proxyEquals method for subclassed invocation handler dynamic proxies.
protected Integer	proxyHashCode(Object proxy) Implements the standard hashCode method with a simple call to System.identityHashCode().
abstract 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	setConfigurationName(String name) Sets the name of this configuration object
void	setConfigurationReadOnly() Sets whether this configuration may be altered.
abstract 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.util.reflection.GenericProxy

invoke, proxyToString

Methods inherited from class java.lang.Object

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

Field Detail

log

private org.apache.commons.logging.Log log

Provides a handle to Apache-commons logger

REF_PREFIX

protected static final String REF_PREFIX

Prefix for config values that reference other configs.

See Also:

Constant Field Values

REF_PREFIX_LENGTH

protected static final int REF_PREFIX_LENGTH

Holds the length of reference prefix.

document

protected org.jdom.Document document

JDOM Document object that holds the xml version of this configuration object's data.

element

protected org.jdom.Element element

The root element of this configuration object. May represent the root node of the document or it may be a sub-element for included object types.

documentType

protected Class documentType

The Class of object that this configuration object is implementing.

name

protected String name

The fully qualified configuration name for this configuration object

ROOT_TAG

private static final String ROOT_TAG

The root XML tag for configuration documnts

See Also:

Constant Field Values

writable

private boolean writable

True if this object may be altered, false if it should throw exceptions when attempts are made to alter it.

Constructor Detail

AbstractConfigurationProxy

protected AbstractConfigurationProxy(org.jdom.Document document,
                                     org.jdom.Element root,
                                     Class documentType)

Constructs an AbstractConfigurationProxy for the supplied document.

Parameters:

document - The JDOM document object representing the XML for this configuration object

root - The root element of this configuration object, not necessarily the root of the document

documentType - the Class of object represented by the DynamicProxy form of this object

AbstractConfigurationProxy

protected AbstractConfigurationProxy(Class documentType)

Constructs an AbstractConfigurationProxy for the supplied document.

Parameters:

documentType - the Class of object represented by the DynamicProxy form of this object

Method Detail

getConfigurationName

public String getConfigurationName()

Retrieves this configuration object's name

Specified by:

getConfigurationName in interface Configuration

Returns:

the fully qualified path name for this configuration object in the configuration service; null if this configuration object has not yet been stored in the configuration service

setConfigurationName

public void setConfigurationName(String name)

Sets the name of this configuration object

Specified by:

setConfigurationName in interface Configuration

Parameters:

name - the fully qualified name of this configuration in the configuration service

getDocumentType

public Class getDocumentType()

Retrieves the primary type of this configuration

Returns:

the type of this configuration object. This is the primary class type of the DynamicProxy that was built to support the storage and retrieval of configurations for that interface

handleInvoke

protected Object handleInvoke(Object proxy,
                              Method m,
                              Object[] args)
                       throws Throwable

This method provides the basic implementation of invocations from the standpoint of DynamicProxies. The base proxy class, GenericProxy provides a default implemenetation of an InvocationHandler and basic handling for the standad Object methods. Other methods are passed to this method for invocation.

This AbstractConfigurationProxy will handle basic bean based calls into an object graph and utilize method name and JavaBean based naming standards to determine the proper data item to query.

Sublcasses of AbstractConfigurationProxy will be able to provide specific implementations of these methods based on what the underlying datastore type is.

Specified by:

handleInvoke in class GenericProxy

Parameters:

proxy - the proxy object on which the method was called

m - the method which was called to be executed

args - the array of arguments to the specified method call

Returns:

the object value returned from the real delegated method call

Throws:

Throwable - when an invoke fails with any exception - this is cast by standard dynamic proxy functionality into an appropriate exception for the type of method that was actually called.

getArrayValue

protected Object getArrayValue(String attributeName,
                               Class type,
                               int index)

Gets the value from an configuration array.

Parameters:

attributeName - the name of the attribute that holds the array

type - the type of class within the array

index - the index of the value to retreive

Returns:

the object at the given index in the array

Throws:

InvalidParameterException - indicates there was an error accessing the give index in the array such as an IndexOutOfBoundsException

isMapAttribute

protected boolean isMapAttribute(String attrName)

Checks if the given attribute contains a map.

Parameters:

attrName - the attribute to test for being a map

Returns:

true if the given attribute is for a map

getCollectionComponentType

protected Class getCollectionComponentType(String attrName)

Gets the type of class contained within a map.

Parameters:

attrName - the name of the attribute to determine the class type of

Returns:

the type of class contained within the array or null if it is unable to determine the type.

getChildType

public Class getChildType(String attributeName)

Retrieves the type of a JavaBean attribute by introspecting for its retrieval method and checking its return type.

Parameters:

attributeName - the name of the attribute to get the type of

Returns:

the class type of the attribute

lookupDefaultAttributeValue

protected Object lookupDefaultAttributeValue(Class type,
                                             String attributeName,
                                             Class returnType)

Retrieves the default value for a requested configuration attribute from an interface static variable with the same name as the requested attribute.

Parameters:

type - the Class of the configuration interface that may contain a default value

attributeName - the name of the attribute being looked for

returnType - the return type of the method

Returns:

the default value of the specified attribute

alterAttribute

public abstract 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.

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

lookupAttribute

public abstract Object lookupAttribute(String attributeName,
                                       Class returnType)

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.

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

getArray

public abstract 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.

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 abstract Map getMap(String attributeName,
                           Class contentType)

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.

Parameters:

attributeName - 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

setArrayValue

public abstract 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. Implementing classes must set the specified index of the array named by attributeName to the specified value.

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

setMapValue

public abstract 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.

Parameters:

attributeName - the name of the array to alter

attributeType - the type of the objects in the map

key - the key within the map to set

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

addAttribute

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

This method should add a child entity to this configuration entity

Parameters:

entityName - 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

getSimpleClassName

public static String getSimpleClassName(Class theClass)

Returns the simple class name without the prepended package structure

Parameters:

theClass - the class whose name is returned

Returns:

the unqualifiedclass name of the supplied class

getConfigurationInterface

public Class getConfigurationInterface()

Description copied from interface: Configuration

This method returns the Class of this component's configuration.

Specified by:

getConfigurationInterface in interface Configuration

Returns:

Class the class object for either an interface or a class that will hold the configuration representation for a Component.

See Also:

Configuration.getConfigurationInterface()

getDataStructure

public org.jdom.Document getDataStructure()

Description copied from interface: Configuration

Returns a JDOM Document object representing the underlying data of this configuration object. Making direct changes to the data in this object may conflict with internal Carbon Core functionality.

Specified by:

getDataStructure in interface Configuration

Returns:

an Document object representing the full data set of this configuration document

See Also:

Configuration.getDataStructure()

getRootElement

public org.jdom.Element getRootElement()

Retrieves the root element of the data being currently mapped by this configuration object. Child structures will have a different root then the root of the "Document" object.

Specified by:

getRootElement in interface Configuration

Returns:

the root element being proxied by this object

clone

public abstract Object clone()

Description copied from interface: Configuration

This method makes a deep-copy of the underlying data structure for this configuration

Specified by:

clone in interface Configuration

Overrides:

clone in class Object

Returns:

the newly created copy of configuration

See Also:

Object.clone()

isChildConfiguration

public boolean isChildConfiguration(org.jdom.Element childElement)

Checks whether or not childElement is a child configuration or not

Parameters:

childElement - element to be tested.

Returns:

boolean true if childElement is a configuration

isReference

public boolean isReference(org.jdom.Element element)

Checks whether or not element is a reference to another configuration.

Parameters:

element - element to check if it is a reference

Returns:

true is the text of element starts with REF_PREFIX

getConfigurationInterface

protected Class getConfigurationInterface(org.jdom.Element element,
                                          Class defaultInterface)

Gets the ConfigurationInterface specifed in an element. If the ConfigurationInterface is not defined by the element of the class specified is not found, defaultInterface is returned.

Parameters:

element - the element to retreive the configuration element from

defaultInterface - the default interface if there is no configuration interface defined by the element

Returns:

ConfigurationInterface from the element or default

proxyEquals

protected Boolean proxyEquals(Object proxy,
                              Object other)

Description copied from class: GenericProxy

This method implements the standard proxyEquals method for subclassed invocation handler dynamic proxies.

Overrides:

proxyEquals in class GenericProxy

Parameters:

proxy - the proxy object for which equals is being handled

other - the other object being compared too

Returns:

true if they are symantically equal, false otherwise

See Also:

GenericProxy.proxyEquals(Object, Object)

proxyHashCode

protected Integer proxyHashCode(Object proxy)

Description copied from class: GenericProxy

Implements the standard hashCode method with a simple call to System.identityHashCode().

Overrides:

proxyHashCode in class GenericProxy

Parameters:

proxy - the object for which a hashcode should be returned

Returns:

the hash code of the provided object

See Also:

GenericProxy.proxyHashCode(Object)

isConfigurationWritable

public boolean isConfigurationWritable()

Is this configuration document writable or is it read-only. Shared cache instances of configuration objects should either be synchronized or marked not writable. When a configuration object is not writable, it should throw an exception if an attempt is made to modify it.

Specified by:

isConfigurationWritable in interface Configuration

Returns:

true if this cofiguration object may be altered.

Since:

carbon 1.1

setConfigurationReadOnly

public void setConfigurationReadOnly()

Sets whether this configuration may be altered.

Specified by:

setConfigurationReadOnly in interface Configuration

Since:

carbon 1.1