public abstract class

AbstractConfigurationElement

extends Object
implements ConfigurationElement ConfigurationFile Cloneable
java.lang.Object
   ↳ com.microstrategy.utils.config.AbstractConfigurationElement
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

The AbstractConfigurationElement is the abstract class that represent a ConfigurationElement, that is, a class that can be configured using an external file. It supports reading the definition from an XML file. It also supports loading the definition from multiple configuration sources (i.e., supports customizations).

In its constructor, a subclass registers what are the valid children it may have through 2 methods:

  1. registerElement(String nodeName, Class class): used for those nodes that can appear only once.
  2. registerElementList(String nodeName, Class class): used for those that can appear multiple times as part of a list.

By default, if the attribute was not present in the xml configuration getAttribute() returns null. If the subclass requires that an attribute has a default value other than null, it can be done by extending the initDefaultAttributes() method and setting the attribute value there.

Subclasses also need to implement the getKeyAttribute method to indicate the attribute that can uniquely identify this element within a list. If the Element is not intended to be used in a list, or if it uses more than one attribute as key this method should simply return null, and if necessary implement the getKey():Object method.

The AbstractConfigurationElement also implements the ConfigurationFile interface used to load, reload, save and applyCustomizations, therefore all subclasses can be saved independently in a configuration file.

Summary

Nested Classes
class AbstractConfigurationElement.FilteredList  
Constants
String ATT_CONFIG_SRC
String ATT_DELETED
String ATT_POSITION
String ATT_PROTOTYPE
String ATT_USE_DEFAULT Defines the "use-default" attribute.
Protected Constructors
AbstractConfigurationElement()
Default constructor.
Public Methods
void applyCustomization(CustomizationInfo c)
Applies the corresponding customizations.
void applyCustomizations()
Loops through all the CustomizationInfo in the Customizations class and apply the corresponding customizations.
void cleanUpDeletedElements()
This method when called will delete all the child elements that are marked as deleted.
Object clone()
void delete(Object key)
final AbstractConfigurationElement deltas()
Returns the deltas between the original() and this objects.
AbstractConfigurationElement deltas(AbstractConfigurationElement other)

Returns a partial instance of this object that contains the attributes and elements required to make this object equals to the other paramter.

boolean equals(Object object)
boolean equalsIncludingDeletedElements(Object object)
final ConfigurationValue getAttribute(String name)
Returns the value associated with the given attribute.
HashList getAttributes()
Returns the list of all attributes available to this ConfigurationElement.
String getConfigSrc()
Returns the value of the config-src attribute.
ConfigurationElement getElement(Object key)
Returns the ConfigurationElement instance associated with the given nodeName.
final HashList getElements()
Returns the list of all child-elements available to this ConfigurationElement.
FileLoader getFileLoader()
Returns the file loader instance used by this ConfigurationElement to load files from the file system.
Object getKey()
Default implementation for getKey().
int getLineNumber()
Returns the line number (if known) of the element in the XML file.
Object getNextKey()
Returns an object that can be used as key for a list of child-elements that doesn't have a key by itself.
String getNodeName()
Returns the node-name for this element.
String getNodeValue()
Returns the node value for this element.
AbstractConfigurationElement getParent()
Gets the parent for this configuration element.
int getPosition()
Returns the expected position of this element.
String getSelfInitPath()
Returns the path to the file where this configuration element was originally loaded from.
String getStrAttribute(String name)
Helper method, returns the value of the given attribute as a string.
boolean getUseDefault()
Returns the use-default value.
int hashCode()
void initFromResource(String resourceName)
Initializes this configuration element by loading the contents a resource that exists in the class path.
void initFromXML(Node root)
Initialize the attributes and child elements from the values in the given Node
boolean isActive()
boolean isCustomized()
boolean isDeleted()
Returns true is this element has been mark as deleted.
boolean isDirty()
Returns true is this element or one of its children has been modified programatically after being loaded.
void load(String fileName)
Loads the file with the given name and initializes this ConfigurationElement with its content.
final AbstractConfigurationElement original()
Returns a new instance of this object, populated only with the out of the box values of Microstrategy Web, that is, only default values or those that came from the load method.
ConfigurationElement populate(ConfigurationElement other)
This method takes another configuration element and populates this element with the other's attributes and child-elements.
void reload()
Loops through all the ElementSource of this ConfigurationElement and reloads the content of those whose underlying configuration file has changed.
void replaceList(AbstractConfigurationElement.FilteredList list)
void restore(Object key)
void save()
Saves this ConfigurationElement back into the files where it was loaded from.
void save(CustomizationInfo c)
Saves deltas for this ConfigurationElement into the given CustomizationInfo.
void saveChangesAs(String fileName)
Saves all in-memory changes to the given file.
final void saveConfig(String filePath)
This method is deprecated. To save in a different location, set a custom FileLoader and use the save() method.
void saveFlatXML(String fileName)
Saves the current element structure, in XML format, into the given file.
void setConfigSrc(String path)
Sets the config-src attribute.
void setCustomized(boolean value)
set if this element is a customized element or not.
void setFileLoader(FileLoader fl)
Sets the FileLoader instance to be used to load files.
void setLineNumber(int lineNumber)
Sets the line number of the element in the XML file.
void setPosition(int position)
Sets the expected position of this element.
void setUseDefault(boolean useDefault)
The definition of a ConfigurationElement can come come from different sources, for example, the definition can come from an external file (by specifying a getConfigSrc() value), or it can be modified through a Customization.
void setUseValidation(boolean value)
Defines whether the XML content should validated using a DTD.
String toString()
Generates the String representation of this ConfigurationElement.
synchronized Element toXML(Document doc)
Generates the DOM representation of this ConfigurationElement.
synchronized Element toXML()
Generates the DOM representation of this ConfigurationElement.
boolean useValidation()
Returns whether the XML content should be validated using a DTD.
Protected Methods
void addFileSource(String filePath, String appPath, long lastLoaded)
Adds a reference to a file from a config-source.
boolean equalAtts(AbstractConfigurationElement other)
Returns true if the list of active attributes of the given AbstractConfigurationElement is equal to this list of active attributes of this AbstractConfigurationElement.
boolean equalElements(AbstractConfigurationElement other)
Returns true if the list of all child elements of the given AbstractConfigurationElement is equal to this list of all child-elements of this AbstractConfigurationElement.
boolean equalNodeValues(AbstractConfigurationElement other)
Returns true if the node value of both configuration elements is the same.
void exportAttributesToXML(Element element, ConfigurationSource source)
Appends the list of attributes of this ConfigurationElement into the given node.
void exportElementsToXML(Element element, ConfigurationSource source)
Appends the list of child-elements of this ConfigurationElement into the given node.
void exportNodeValueToXML(Element element, ConfigurationSource source)
Appends the node value associated with the given source key into the given node.
boolean getBoolAttribute(String name)
Helper method, returns the value of the given attribute as boolean (true/false).
Object getChildKey(Node node)
Returns the key that uniquely identifies the child element associated with the given Node.
String getDTDFileName()
Returns the name of a DTD file that will be added as SystemID to the XML resulting from serializing the contents of this ConfigurationElement into a file; null by default.
ConfigurationElement getElement(Object key, boolean includeDeleted)
int getIntAttribute(String name)
Helper method, returns the value of the given attribute as integer.
int getIntAttribute(String name, int defaultValue)
Helper method, returns the value of the given attribute as integer.
abstract String getKeyAttribute()
This method must return the attribute that uniquely identifies this element among its siblings; if no single attribute can be used, return null and override the getKey and setKey methods.
AbstractConfigurationElement.FilteredList getList(String nodeName)
Returns an ImplicitList with all the elements associated with the given nodeName.
String getNodeValue(ConfigurationSource source)
Returns the node value for this element in the given sourceKey.
AbstractConfigurationElement getOrCreateElement(String nodeName, Object key)
Returns the current child instance; if null but the child is registered, it creates a new instance for it.
AbstractConfigurationElement getPrototype()
Returns the current prototype of this instance.
Class getRegisteredClass(String nodeName)
Returns the Class associated with the given nodeName.
ConfigurationSource getSource(String key)
Gets the ElementSource for the given key.
ParserParameters getXMLParserParameters(String fileName)
Returns an instance of ParserParameters used by the XML parser.
SerializerParameters getXMLSerializerParameters()
Returns an instance of SerializerParameters used by the XML serializer in the toXML() By default it returns null.
boolean hasRegisteredClass(String nodeName)
Returns true is there is a child registered for the given nodeName.
int hashCodeAtts()
Returns the hashcode for attributes.
int hashCodeElements()
Returns the hashcode for attributes.
int hashCodeNodeValues()
Returns the hashcode for attributes.
void initAttributesFromXML(Node root, String sourceKey, CustomizationInfo c)
Initializes the list of attributes from given Node
void initDefaultAttributes()
This method can be overridden to set default values for attributes.
void initElementFromXML(Node child, String sourceKey, CustomizationInfo c)
Initializes a single child-element from the given Node
void initElementsFromXML(Node root, String sourceKey, CustomizationInfo c)
Initializes the list of child-elements from given Node
void initFromFile(String filePath, CustomizationInfo c)
Initializes this configuration element by loading the contents of the given filePath using the corresponding CustomizationInfo.
void initFromXML(Node root, String sourceKey, CustomizationInfo c)
Initialize the attributes and child elements from the values in the given Node
void initNodeValueFromXML(Node root, String sourceKey, CustomizationInfo c)
Initializes the list of child-elements from given Node
void initPrototype(String protoName)
Inits the prototype object of this element.
boolean isInSource(String sourceKey)
Returns true if the element already contains an ElementSource for the given key.
boolean isKeyAttribute(String name)
Returns true is the name is that of the key attribute.
void mergeChanges(String srcKey)
Removes deltas and applies them to the given source.
AbstractConfigurationElement newChildInstance(String nodeName, Class childClass)
Creates a new instance of a child element for the given class.
ConfigurationSource newSource(String srcKey, CustomizationInfo c)
Create a new ElementSource and adds to the list of sources of this element.
void printAttributes(StringBuffer outString)
Appends the list of attributes of this ConfigurationElement into the given StringBuffer.
void printElements(StringBuffer outString)
Appends the list of child-elements of this ConfigurationElement into the given StringBuffer.
void printNodeValue(StringBuffer outString)
Appends the node value into the given StringBuffer.
void refreshLists()
void registerClass(String nodeName, Class c)
Registers a child class for the child with the given nodeName.
void registerElement(String nodeName, Class c, boolean canBeNull)
Register a child of this ConfigurationElement.
void registerElement(String nodeName, Class c)
Register a child of this ConfigurationElement.
void registerElementList(String nodeName, Class c)
Register a list of this ConfigurationElement.
void reloadPrototype()
Loops through all the ElementSource of this ConfigurationElement and reloads the content of those whose underlying configuration file has changed.
void removeAttribute(String name)
Completely remove the value for the given attribute.
void removeDefaults(CustomizationInfo c)
This method is called when the use-default attribute is set false, so all previous values of attributes and children must be cleared.
void saveNode(Node node, String fileLocation)
Saves an XML node into a file in the given location.
void saveSource(ConfigurationSource source)
Saves only the contents associated with the given source.
void setAttribute(String name, Object value)
Sets the value for the given attribute.
void setBoolAttribute(String name, boolean value)
Helper method, sets the value of the given attribute from a boolean.
void setChildOriginals()
void setElement(Object key, ConfigurationElement child)
Allows users to add or replace an element.
void setIntAttribute(String name, int value)
Helper method, sets the value of the given attribute from an integer.
void setKey(Element element)
Default implementation for setKey().
void setNodeName(String name)
Sets the name of the node associated with this configuration element.
void setNodeValue(String value)
Returns the node value for this element.
void setPrototype(AbstractConfigurationElement prototype)
Sets the prototype object for this instance.
void setSelfInitPath(String value)
void setStrAttribute(String name, String value)
Helper method, sets the value of the given attribute as a string.
Element toXML(String sourceKey)
Generates the DOM representation of this ConfigurationElement for the list of attributes and elements defined in the given ElementSource.
Element toXML(Document doc, String sourceKey)
Generates the DOM representation of this ConfigurationElement for the list of attributes and elements defined in the given ElementSource.
boolean useNodeValue()
Controls whether this element will use the node value as a property.
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.microstrategy.utils.config.ConfigurationElement
From interface com.microstrategy.utils.config.ConfigurationFile

Constants

protected static final String ATT_CONFIG_SRC

Constant Value: "config-src"

protected static final String ATT_DELETED

Constant Value: "deleted"

protected static final String ATT_POSITION

Constant Value: "position"

protected static final String ATT_PROTOTYPE

Constant Value: "prototype"

public static final String ATT_USE_DEFAULT

Defines the "use-default" attribute.

Constant Value: "use-default"

Protected Constructors

protected AbstractConfigurationElement ()

Default constructor. Calls initDefaultAttributes()

Public Methods

public void applyCustomization (CustomizationInfo c)

Applies the corresponding customizations.

public void applyCustomizations ()

Loops through all the CustomizationInfo in the Customizations class and apply the corresponding customizations.

public void cleanUpDeletedElements ()

This method when called will delete all the child elements that are marked as deleted.

public Object clone ()

Returns
  • a new instance of this object with the same values.

public void delete (Object key)

public final AbstractConfigurationElement deltas ()

Returns the deltas between the original() and this objects. The returned value therefore includes all changes to this object after it was loaded; this includes both programatic changes and plugins changes.

public AbstractConfigurationElement deltas (AbstractConfigurationElement other)

Returns a partial instance of this object that contains the attributes and elements required to make this object equals to the other paramter. It is used to identify the differences between the two instances of this class.

Being a partial instance, the resulting delta includes strictly those attributes and elements required to make it equal to the other object; typically default attributes and elements are not included so its possible that getter methods for properties and/or chidlren will return null.

Notice that if both x and y are AbstractConfigurationElement, and
x != y
, then
 d = x.deltas(y)
 x + d = y
 
Or programatically:
 if (!x.equals(y)) {
   AbstractConfigurationElement d = x.deltas(y);
   x.populates(d).equals(y); //returns true
 }
 

public boolean equals (Object object)

public boolean equalsIncludingDeletedElements (Object object)

public final ConfigurationValue getAttribute (String name)

Returns the value associated with the given attribute. If the attribute was not present in the xml configuration the method returns null.

public HashList getAttributes ()

Returns the list of all attributes available to this ConfigurationElement.

public String getConfigSrc ()

Returns the value of the config-src attribute. This attribute indicates a file path where the definition of this attribute will be loaded from or saved into.

public ConfigurationElement getElement (Object key)

Returns the ConfigurationElement instance associated with the given nodeName. If the ConfigurationElement was not present in the xml configuration, this method might return an empty instance of the corresponding ConfigurationElement or null depending on the canBeNull parameter passed to the registerElement(String, Class) method. If a list is associated with the given nodeName, this method returns a list containing all the ConfigurationElement instances for that nodeName. If no ConfigurationElement is associated with the given nodeName, the method returns null.

public final HashList getElements ()

Returns the list of all child-elements available to this ConfigurationElement.

public FileLoader getFileLoader ()

Returns the file loader instance used by this ConfigurationElement to load files from the file system. If setFileLoader(FileLoader) has not been explicitly called, this method uses the parent's FileLoader, and if it is a root object, it uses the FileLoader singleton, that is FileLoader.getInstance().

public Object getKey ()

Default implementation for getKey(). It assumes a single attribute can be used to uniquely identify this element among its siblings; the attribute to use is specified by the getKeyAttribute() method.

Returns
  • If getKeyAttribute() is empty returns null, otherwise it returns the value of the given attribute.

public int getLineNumber ()

Returns the line number (if known) of the element in the XML file.

Returns
  • The line number (if known). Otherwise, return -1.

public Object getNextKey ()

Returns an object that can be used as key for a list of child-elements that doesn't have a key by itself.

public String getNodeName ()

Returns the node-name for this element.

public String getNodeValue ()

Returns the node value for this element. The node value represents the inner content of the xml tag. If multiple ElementSources are defined for this element, it returns the value of the one with greater priority.

public AbstractConfigurationElement getParent ()

Gets the parent for this configuration element. Returns null if it's a root or if it's still not associated to any element.

public int getPosition ()

Returns the expected position of this element. If the position should be automatically infered from the position found in the XML, it returns -1. This value is stored in the "position" attribute of the node. Notice that the actual position of this element might differ from this value, as the position attribute is not guaranteed to be unique or correct.

public String getSelfInitPath ()

Returns the path to the file where this configuration element was originally loaded from. It only returns a non-null value when this element was loaded using the load(String) method, or if it was loaded from a node that had the "config-src" attribute specified.

public String getStrAttribute (String name)

Helper method, returns the value of the given attribute as a string.

public boolean getUseDefault ()

Returns the use-default value.

Returns
  • the true/false value of the useDefault flag of this Configuration Element

public int hashCode ()

public void initFromResource (String resourceName)

Initializes this configuration element by loading the contents a resource that exists in the class path.

public void initFromXML (Node root)

Initialize the attributes and child elements from the values in the given Node

Parameters
root Node intance representing the configuration element properties

public boolean isActive ()

public boolean isCustomized ()

Returns
  • true - if it is a customized element false - if it is an OOTB element

public boolean isDeleted ()

Returns true is this element has been mark as deleted.

See Also

public boolean isDirty ()

Returns true is this element or one of its children has been modified programatically after being loaded.

public void load (String fileName)

Loads the file with the given name and initializes this ConfigurationElement with its content.

Parameters
fileName The path to the configuration file. This path will be resolved by the FileLoader

public final AbstractConfigurationElement original ()

Returns a new instance of this object, populated only with the out of the box values of Microstrategy Web, that is, only default values or those that came from the load method. Values from customizations or programatic changes are not included.

public ConfigurationElement populate (ConfigurationElement other)

This method takes another configuration element and populates this element with the other's attributes and child-elements. Existing values are merged in this process. After this method is called, attributes and elements from the other will be available in this element.

Returns
  • this same object.

public void reload ()

Loops through all the ElementSource of this ConfigurationElement and reloads the content of those whose underlying configuration file has changed.

public void replaceList (AbstractConfigurationElement.FilteredList list)

public void restore (Object key)

public void save ()

Saves this ConfigurationElement back into the files where it was loaded from. All in-memory changes are automatically applied into the last ElementSource used to load this element.

public void save (CustomizationInfo c)

Saves deltas for this ConfigurationElement into the given CustomizationInfo.

public void saveChangesAs (String fileName)

Saves all in-memory changes to the given file. If this ConfigurationElement was loaded from that file, the resulting file includes the original contents plus the changes.

public final void saveConfig (String filePath)

This method is deprecated.
To save in a different location, set a custom FileLoader and use the save() method.

Saves this element configuration into the given filePath. Notice that this method has been deprecated: To save the configuration file into a different location it's better to create a FileLoader with the new folder path and assign it to the root element:

PageManager pm = new PageManager(); pm.load(".\\WEB-INF\\xml\\pageConfig.xml"); FileLoader fl = new FileLoader(System.getProperty("user.dir") + OUTPUT_FOLDER); //Save it in a different folder: pm.setFileLoader(fl); pm.save();
This makes sure all config-src are saved into their corresponding file.

public void saveFlatXML (String fileName)

Saves the current element structure, in XML format, into the given file.

public void setConfigSrc (String path)

Sets the config-src attribute. If setting it to a non-null value, the definiton of this configuration element will be saved into this location.

public void setCustomized (boolean value)

set if this element is a customized element or not. If user adds a new element it is considered a customized element and user needs to set this element as custom.

public void setFileLoader (FileLoader fl)

Sets the FileLoader instance to be used to load files. This method is typically used to set a different root folder for relative paths. Normally, all relative paths (for example "/WEB-INF/web.xml") are relative to the application's root folder, to change this root folder users can create a new FileLoader instance and set it to this ConfigurationElement, then relative paths are resolved relative to the new FileLoader base path, for example:

FileLoader fl = new FileLoader("C:\\Temp"); PagaManager pm = new PageManager(); pm.load("/WEB-INF/xml/pageConfig.xml", true);
In the previous sample, "/WEB-INF/xml/pageConfig.xml" is resolved to C:\Temp\WEB-INF\xml\pageConfig.xml as the FileLoader's base path is "C:\Temp"

public void setLineNumber (int lineNumber)

Sets the line number of the element in the XML file.

Parameters
lineNumber The line number of this AbstractConfigurationElement in the XML file.

public void setPosition (int position)

Sets the expected position of this element. The value is stored in the "position" attribute of the node. If when calling this method, this instance is a member of an ImplicitList, the element will automatically reposition itself in this list. Setting -1 as position indicates to automatically position this element based on its position in the XML.

public void setUseDefault (boolean useDefault)

The definition of a ConfigurationElement can come come from different sources, for example, the definition can come from an external file (by specifying a getConfigSrc() value), or it can be modified through a Customization. When the useDefault is set to false, values that come from previous sources are ignored and only the definition from the current source is used; this includes all attributes and child elements of this element. This is especially useful in customizations to replace the out of the box values of a node with a new definition.

Parameters
useDefault true/false value

public void setUseValidation (boolean value)

Defines whether the XML content should validated using a DTD.

Parameters
value true requires that the XML is parsed with DTD validation on.

public String toString ()

Generates the String representation of this ConfigurationElement.

public synchronized Element toXML (Document doc)

Generates the DOM representation of this ConfigurationElement. This method returns the list of attributes and elements merged from all ElementSource. Note that the resulting Element will not be associated with the Document parameter. It is important to ensure that all DOM trees have a Document root as some serializers do not behave correctly otherwise. Use toXML() if the resulting DOM is not going to be appended in another DOM structure.

Parameters
doc factory for creating underlying Element
Returns
  • DOM of this instance

public synchronized Element toXML ()

Generates the DOM representation of this ConfigurationElement. This method returns the list of attributes and elements merged from all ElementSource.

Returns
  • a stand alone DOM with its own document root instance

public boolean useValidation ()

Returns whether the XML content should be validated using a DTD. If true when the XML is parsed the file will be validated using the corresponding DTD (as defined in the XML itself).

Protected Methods

protected void addFileSource (String filePath, String appPath, long lastLoaded)

Adds a reference to a file from a config-source. This file will then be automatically reloaded if changed and will be used when the save() method is called.

protected boolean equalAtts (AbstractConfigurationElement other)

Returns true if the list of active attributes of the given AbstractConfigurationElement is equal to this list of active attributes of this AbstractConfigurationElement.

protected boolean equalElements (AbstractConfigurationElement other)

Returns true if the list of all child elements of the given AbstractConfigurationElement is equal to this list of all child-elements of this AbstractConfigurationElement.

protected boolean equalNodeValues (AbstractConfigurationElement other)

Returns true if the node value of both configuration elements is the same.

protected void exportAttributesToXML (Element element, ConfigurationSource source)

Appends the list of attributes of this ConfigurationElement into the given node. The list is filter to include only attributes defined in the given ElementSource. If sourceKey is null, it appends the list of attributes merged from all ElementSources.

protected void exportElementsToXML (Element element, ConfigurationSource source)

Appends the list of child-elements of this ConfigurationElement into the given node. The list is filter to include only elements defined in the given ElementSource. If sourceKey is null, it appends the list of elements merged from all ElementSources.

protected void exportNodeValueToXML (Element element, ConfigurationSource source)

Appends the node value associated with the given source key into the given node. If sourceKey is null, it appends the current node value.

protected boolean getBoolAttribute (String name)

Helper method, returns the value of the given attribute as boolean (true/false). If the attribute has no value it returns false; otherwise it returns valueOf(boolean).

See Also

protected Object getChildKey (Node node)

Returns the key that uniquely identifies the child element associated with the given Node.

protected String getDTDFileName ()

Returns the name of a DTD file that will be added as SystemID to the XML resulting from serializing the contents of this ConfigurationElement into a file; null by default. This method should be extended if the concrete instance of an element has a predefined DTD file associated.

protected ConfigurationElement getElement (Object key, boolean includeDeleted)

protected int getIntAttribute (String name)

Helper method, returns the value of the given attribute as integer. If the attribute has no value, it returns Integer.MIN_VALUE. If the attribute has a non-numeric value, it throws an IllegalArgumentException.

protected int getIntAttribute (String name, int defaultValue)

Helper method, returns the value of the given attribute as integer. If the attribute has no value, it returns the defaultValue parameter. If the attribute has a non-numeric value, it throws an IllegalArgumentException.

protected abstract String getKeyAttribute ()

This method must return the attribute that uniquely identifies this element among its siblings; if no single attribute can be used, return null and override the getKey and setKey methods.

protected AbstractConfigurationElement.FilteredList getList (String nodeName)

Returns an ImplicitList with all the elements associated with the given nodeName. If no child was present in the xml configuration with this name, it will return an empty list. If the nodeName has not been registered for a list, it throws an IllegalArgumentException.

protected String getNodeValue (ConfigurationSource source)

Returns the node value for this element in the given sourceKey. The node value represents the inner content of the xml tag.
If sourceKey is null, it returns the current value.

protected AbstractConfigurationElement getOrCreateElement (String nodeName, Object key)

Returns the current child instance; if null but the child is registered, it creates a new instance for it.

protected AbstractConfigurationElement getPrototype ()

Returns the current prototype of this instance.

protected Class getRegisteredClass (String nodeName)

Returns the Class associated with the given nodeName.

protected ConfigurationSource getSource (String key)

Gets the ElementSource for the given key. If there is no ConfigurationSource for the given key, a new source is automatically added.

protected ParserParameters getXMLParserParameters (String fileName)

Returns an instance of ParserParameters used by the XML parser. By default if using validation creates a new ParserParameters instance with a SimpleErrorHandler and FileLoaderEntityResolver; otherwise it returns null;

protected SerializerParameters getXMLSerializerParameters ()

Returns an instance of SerializerParameters used by the XML serializer in the toXML() By default it returns null. Override if the configuration element requires to pass different parameters than those used by default.

protected boolean hasRegisteredClass (String nodeName)

Returns true is there is a child registered for the given nodeName.

protected int hashCodeAtts ()

Returns the hashcode for attributes.

protected int hashCodeElements ()

Returns the hashcode for attributes.

protected int hashCodeNodeValues ()

Returns the hashcode for attributes.

protected void initAttributesFromXML (Node root, String sourceKey, CustomizationInfo c)

Initializes the list of attributes from given Node

protected void initDefaultAttributes ()

This method can be overridden to set default values for attributes. Simply extend this method and call setAttribute(String, Object)

protected void initElementFromXML (Node child, String sourceKey, CustomizationInfo c)

Initializes a single child-element from the given Node

protected void initElementsFromXML (Node root, String sourceKey, CustomizationInfo c)

Initializes the list of child-elements from given Node

protected void initFromFile (String filePath, CustomizationInfo c)

Initializes this configuration element by loading the contents of the given filePath using the corresponding CustomizationInfo.

protected void initFromXML (Node root, String sourceKey, CustomizationInfo c)

Initialize the attributes and child elements from the values in the given Node

Parameters
root The DOM Node from where the information is read
sourceKey The key that identifies the ElementSource where the values are being read
c CustomizationInfo class where the ElementSource was loaded from.
Throws
ConfigException If an error occurs while reading the definition, typically if there is a problem when reading the file pointed by the config-src attribute.

protected void initNodeValueFromXML (Node root, String sourceKey, CustomizationInfo c)

Initializes the list of child-elements from given Node

protected void initPrototype (String protoName)

Inits the prototype object of this element. This element will inherit all the attribute and child elements from the prototype, but then any values defined through the config-src file or inline take precedence over the prototype. The name attribute represents the name of the prototype as specified in the XML. Typically this is the name of a sibling node in the xml. If name is empty, a different sibling might be used as prototype (like in the case of the PageInfo, which the page marked as isDefault is used as the default prototype). If this object already has a prototype, or if the prototype is not found in the siblings collections this methods throws an Exception.

Parameters
protoName Prototype name, typically the name of a sibling node in the xml.

protected boolean isInSource (String sourceKey)

Returns true if the element already contains an ElementSource for the given key.

protected boolean isKeyAttribute (String name)

Returns true is the name is that of the key attribute.

protected void mergeChanges (String srcKey)

Removes deltas and applies them to the given source.

protected AbstractConfigurationElement newChildInstance (String nodeName, Class childClass)

Creates a new instance of a child element for the given class.

protected ConfigurationSource newSource (String srcKey, CustomizationInfo c)

Create a new ElementSource and adds to the list of sources of this element. If there is already an ElementSource for the given key, this method will return the same instance, but this should be avoided to prevent infinite recursive loops with the config-src attribute.

protected void printAttributes (StringBuffer outString)

Appends the list of attributes of this ConfigurationElement into the given StringBuffer. It includes the list attributes merged from all ElementSources.

protected void printElements (StringBuffer outString)

Appends the list of child-elements of this ConfigurationElement into the given StringBuffer. It appends the list of elements merged from all ElementSources.

protected void printNodeValue (StringBuffer outString)

Appends the node value into the given StringBuffer. It appends the node value of elements merged from all ElementSources.

protected void refreshLists ()

protected void registerClass (String nodeName, Class c)

Registers a child class for the child with the given nodeName. Used to keep track of those children than can have null values.

protected void registerElement (String nodeName, Class c, boolean canBeNull)

Register a child of this ConfigurationElement. When a node with the given name is found in the configuration file, an instance of c is created and initialized with the corresponding configuration. It's assumed that only one child with this name is available in the configuration file; if more than one is found, the corresponding nodes are merged into a single ConfigurationElement.

The canBeNull parameter controls whether the child instance is created by default or not. When false, the getElement(Object) will always return a non-null instance even if the child is not in the XML; if true the child instance is only created if the object is found in the XML, in this case null checks are necessary in your code after calling getElement to make sure the return object is not null.


Only elements registered with this and with the registerElementList(String, Class) methods are valid child nodes in the configuration file. If a child has not been registered, WARNING messages will be logged.

This method should only be called in the constructor, otherwise the clone method will fail. It can only be called if the useNodeValue() method returns false as they are mutually exclusive: by design an element can only use children if its not using the node value.

Currently it is required that all registered child elements extend AbstractConfigurationElement. If the given class c doesn't, this method will throw an IllegalArgumentException.

protected void registerElement (String nodeName, Class c)

Register a child of this ConfigurationElement. When a child is registered with this method it is guaranteed that a non-null instance of this child is returned by the getElement(Object) method regardless of the child being present in the XML or not.

protected void registerElementList (String nodeName, Class c)

Register a list of this ConfigurationElement. When a node with the given name is found in the configuration file, an instance of c is created and initialized with the corresponding configuration. If more than one subnodes are found with this name, one instance for each is created and all of them are added as child of this ConfigurationElement. The list can then be accessed through the getList(String) method.

Only elements registered with this and with the registerElement(String, Class) methods are valid child nodes in the configuration file.

This method should only be called in the constructor, otherwise the clone method will fail. It can only be called if the useNodeValue() method returns false as they are mutually exclusive: by design an element can only use children if its not using the node value.

Currently it is required that all registered child elements extend AbstractConfigurationElement. If the given class c doesn't, this method will throw an IllegalArgumentException.

protected void reloadPrototype ()

Loops through all the ElementSource of this ConfigurationElement and reloads the content of those whose underlying configuration file has changed.

protected void removeAttribute (String name)

Completely remove the value for the given attribute.

protected void removeDefaults (CustomizationInfo c)

This method is called when the use-default attribute is set false, so all previous values of attributes and children must be cleared.

protected void saveNode (Node node, String fileLocation)

Saves an XML node into a file in the given location.

Parameters
node the xml node to save
fileLocation An absolute path for the file location

protected void saveSource (ConfigurationSource source)

Saves only the contents associated with the given source.

protected void setAttribute (String name, Object value)

Sets the value for the given attribute.

protected void setBoolAttribute (String name, boolean value)

Helper method, sets the value of the given attribute from a boolean.

protected void setChildOriginals ()

protected void setElement (Object key, ConfigurationElement child)

Allows users to add or replace an element. If an element with the given key already exists it gets replaced, otherwise it's simply added.

protected void setIntAttribute (String name, int value)

Helper method, sets the value of the given attribute from an integer.

protected void setKey (Element element)

Default implementation for setKey(). It assumes a single attribute can be used to uniquely identify this element among its siblings and adds this attribute to the given element; the attribute to use is specified by the getKeyAttribute() method.

protected void setNodeName (String name)

Sets the name of the node associated with this configuration element.

protected void setNodeValue (String value)

Returns the node value for this element. The node value represents the inner context of the xml tag. If multiple ElementSources are defined for this element, it returns the value of the one with greater priority.

protected void setPrototype (AbstractConfigurationElement prototype)

Sets the prototype object for this instance. The attributes and elements of the prototype are copied into this instance.

protected void setSelfInitPath (String value)

protected void setStrAttribute (String name, String value)

Helper method, sets the value of the given attribute as a string.

protected Element toXML (String sourceKey)

Generates the DOM representation of this ConfigurationElement for the list of attributes and elements defined in the given ElementSource.

Returns
  • a stand alone DOM with its own document root instance

protected Element toXML (Document doc, String sourceKey)

Generates the DOM representation of this ConfigurationElement for the list of attributes and elements defined in the given ElementSource. Note that the resulting Element will not be associated with the Document parameter. It is important to ensure that all DOM trees have a Document root as some serializers do not behave correctly otherwise.

protected boolean useNodeValue ()

Controls whether this element will use the node value as a property. For example, nodes defined as:


  <a att="1">This is the node value</a>
 
can expose a property which will return the node's value (This is the node vale). When this is the case, though, the element can't have any sub elements. They're mutually exclusive.

Returns
  • false by default. Override this method if you want to associate the node value with some property.