com.novell.nds.dirxml.engine.gcv
Class GCDefinitions

java.lang.Object
  com.novell.nds.dirxml.engine.gcv.GCDefinitions

All Implemented Interfaces:

ConfigElement

Direct Known Subclasses:

EngineControls, JobParams, ResourceParams, ShimParams

public class GCDefinitions

extends Object

implements ConfigElement

GCDefinitions is an aggregation of GCValue objects.

Methods are provided to parse an XML representation of Global Configuration Values and to serialize the contained collection of GCVs to an XML representation.

For user interface purposes the list of GCValue objects is ordered.

Field Summary

protected List

defsList

Constructor Summary

GCDefinitions()
Construct an empty GCDefinitions object.

Method Summary

void	appendValue(GCValue value) Add a GCV to the end of the current list of GCVs.
boolean	apply(Node target) Replace GCV references in an XML document with the values from GCVs in this GCDefinitions instance.
boolean	apply(String[] target) Replace GCV references in a String with values from GCVs in this GCDefinitions instance.
boolean	checkAllowedType(int type) Check whether or not a particular GCV type is allowed in this collection of GCVs.
protected static GCDefinitions	construct(byte[] bytes, GCDefinitions definitions, String baseURI) Populate a GCDefinitions object and associated GCValue objects from an array of bytes containing the serialized XML representation.
static GCDefinitions	construct(byte[] bytes, String baseURI) Construct a GCDefinitions object and associated GCValue objects from an array of bytes containing the serialized XML representation.
static GCDefinitions	construct(Document document) Construct a GCDefinitions object and association GCValue objects from a DOM XML document containing the XML representation.
static GCDefinitions	construct(Node parent) Construct a GCDefinitions object and association GCValue objects from a DOM XML document containing the XML representation.
protected static GCDefinitions	construct(Node parent, GCDefinitions definitions) Populate a GCDefinitions object and association GCValue objects from a DOM XML document containing the XML representation.
protected static GCDefinitions	construct0(Element element, GCDefinitions definitions) Populate a GCDefinitions object and association GCValue objects from a DOM XML element containing the XML representation.
GCValue	getValue(String name) Get a GCValue object by name.
boolean	hasBeenModified() Return true if this instance has been modified.
void	insertValue(GCValue newValue, GCValue insertionPoint) Insert a GCV into the current list of GCVs.
void	insertValue(GCValue newValue, String insertionPoint) Insert a GCV into the current list of GCVs.
Iterator	iterator() Return an Iterator instance that can be used to iterate through the list of GCVs.
void	localize(LocalizedMessageSource messageSource) Localize any display names and descriptions that have localization refs ("display-name-ref" and "description-ref") attributes.
void	merge(GCDefinitions other) Merge this GCDefinitions instance with another.
boolean	removeValue(GCValue value) Remove a GCV from the list of GCVs.
boolean	removeValue(String name) Remove a GCV from the list of GCVs.
void	resetModified() Reset the modified flag for this instance such that hasBeenModified() will return false.
Iterator	shallowIterator() Return an Iterator instance that can be used to iterate through the list of GCVs.
byte[]	toBytes() Return the serialized XML representation of this GCDefinitions object and associated GCValue object.
Document	toXml() Return the DOM XML representation of this GCDefintions object and associated GCValue objects.
Element	toXML(Node parent) Construct a DOM XML representation of this GCDefinitions instance under the passed DOM Node.

Methods inherited from class java.lang.Object

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

Field Detail

defsList

protected List defsList

Constructor Detail

GCDefinitions

public GCDefinitions()

Construct an empty GCDefinitions object.

Method Detail

construct

public static GCDefinitions construct(byte[] bytes,
                                      String baseURI)
                               throws GCVException

Construct a GCDefinitions object and associated GCValue objects from an array of bytes containing the serialized XML representation.

Typically, the array of bytes would come from the value of the DirXML-ConfigValues attribute.

Parameters:

bytes - byte array containing serialized XML.

baseURI - used for error reporting (may be null)

Throws:

GCVException - thrown if XML is incorrect in any way.

construct

protected static GCDefinitions construct(byte[] bytes,
                                         GCDefinitions definitions,
                                         String baseURI)
                                  throws GCVException

Populate a GCDefinitions object and associated GCValue objects from an array of bytes containing the serialized XML representation.

Typically, the array of bytes would come from the value of the DirXML-ConfigValues attribute.

Parameters:

bytes - byte array containing serialized XML.

definitions - the instance to populate.

baseURI - used for error reporting (may be null)

Throws:

GCVException - thrown if XML is incorrect in any way.

construct

public static GCDefinitions construct(Document document)
                               throws GCVException

Construct a GCDefinitions object and association GCValue objects from a DOM XML document containing the XML representation.

Typically, the DOM document would be the result of parsing the value of the DirXML-ConfigValues attribute.

Parameters:

document - DOM document

Throws:

GCVException - thrown if XML is incorrect in any way.

construct

public static GCDefinitions construct(Node parent)
                               throws GCVException

Construct a GCDefinitions object and association GCValue objects from a DOM XML document containing the XML representation.

Typically, the DOM document would be the result of parsing the value of the DirXML-ConfigValues attribute.

Parameters:

parent - DOM Node under which the <configuration-values> element appears

Throws:

GCVException - thrown if XML is incorrect in any way.

construct

protected static GCDefinitions construct(Node parent,
                                         GCDefinitions definitions)
                                  throws GCVException

Populate a GCDefinitions object and association GCValue objects from a DOM XML document containing the XML representation.

Typically, the DOM document would be the result of parsing the value of the DirXML-ConfigValues attribute.

Parameters:

parent - DOM Node with child <configuration-values> element

definitions - the instance to populate.

Throws:

GCVException - thrown if XML is incorrect in any way.

construct0

protected static GCDefinitions construct0(Element element,
                                          GCDefinitions definitions)
                                   throws GCVException

Populate a GCDefinitions object and association GCValue objects from a DOM XML element containing the XML representation.

Typically, the DOM element would be the result of parsing the value of the DirXML-ConfigValues attribute.

Parameters:

element - DOM element

definitions - the instance to populate.

Throws:

GCVException - thrown if XML is incorrect in any way.

hasBeenModified

public boolean hasBeenModified()

Return true if this instance has been modified.

The instance is considered to have been modified if a change was made that affects the persistent representation since:

1. The instance was constructed from an XML representation.
2. resetModified() was last called

Specified by:

hasBeenModified in interface ConfigElement

Returns:

true or false

See Also:

resetModified(), toXML(org.w3c.dom.Node)

resetModified

public void resetModified()

Reset the modified flag for this instance such that hasBeenModified() will return false.

Specified by:

resetModified in interface ConfigElement

See Also:

hasBeenModified()

toXml

public Document toXml()
               throws GCVException

Return the DOM XML representation of this GCDefintions object and associated GCValue objects.

Returns:

DOM document containing XML representation of GCVs.

Throws:

GCVException - thrown if XML creation fails because one or more GCVs is incomplete.

toXML

public Element toXML(Node parent)

Construct a DOM XML representation of this GCDefinitions instance under the passed DOM Node.

Specified by:

toXML in interface ConfigElement

Parameters:

parent - Node under which to construct representation

Returns:

constructed <configuration-values> element

See Also:

ConfigElement.hasBeenModified(), ConfigElement.resetModified()

toBytes

public byte[] toBytes()
               throws GCVException,
                      IOException

Return the serialized XML representation of this GCDefinitions object and associated GCValue object.

Returns:

byte array containing serialized XML.

Throws:

GCVException - thrown if XML creation fails because one or more GCVs is incomplete.

IOException

getValue

public GCValue getValue(String name)

Get a GCValue object by name. This will do a deep search for the GCV, meaning it will look at all descendant GCVs.

Parameters:

name - the GCV name.

Returns:

GCValue object, or null if name not found.

appendValue

public void appendValue(GCValue value)
                 throws GCVArgumentException

Add a GCV to the end of the current list of GCVs.

Parameters:

value - GCValue object to add.

Throws:

GCVArgumentException - thrown if value has the same name as a GCV already in the list.

insertValue

public void insertValue(GCValue newValue,
                        String insertionPoint)
                 throws GCVArgumentException

Insert a GCV into the current list of GCVs.

Parameters:

newValue - GCValue object to add.

insertionPoint - name of GCV in front of which newValue is to be inserted.

Throws:

GCVArgumentException - thrown if insertionPoint doesn't match the name of any GCV in the list, or if the name of newValue matches the name of a GCV already in the list.

insertValue

public void insertValue(GCValue newValue,
                        GCValue insertionPoint)
                 throws GCVArgumentException

Insert a GCV into the current list of GCVs.

Parameters:

newValue - GCValue object to add.

insertionPoint - GCV in front of which newValue is to be inserted.

Throws:

GCVArgumentException - thrown if insertionPoint doesn't appear in the list, or if the name of newValue matches the name of a GCV already in the list.

removeValue

public boolean removeValue(String name)

Remove a GCV from the list of GCVs.

Parameters:

name - name of GCV to remove.

Returns:

true if name was found and removed, false otherwise.

removeValue

public boolean removeValue(GCValue value)

Remove a GCV from the list of GCVs.

Parameters:

value - the GCV to remove.

Returns:

true if the GCV was found and removed, false otherwise.

iterator

public Iterator iterator()

Return an Iterator instance that can be used to iterate through the list of GCVs. The iterator returned will iterate through all descendant GCValues, including those that are children of Groups.

The Iterator's next() method returns GCValue instances.

Returns:

an Iterator instance.

See Also:

shallowIterator()

shallowIterator

public Iterator shallowIterator()

Return an Iterator instance that can be used to iterate through the list of GCVs. The iterator returned will iterate through only GCValues that are direct children of the GCDefinitions.

The Iterator's next() method returns GCValue instances.

Returns:

an Iterator instance.

See Also:

iterator()

apply

public boolean apply(String[] target)
              throws GCValueNotFoundException

Replace GCV references in a String with values from GCVs in this GCDefinitions instance.

A GCV reference is the name of a GCV delimited by '~' (tilde) characters. For example:

~enable-password-sync~

Parameters:

target - array whose zeroth element is the String in which references are to be replaced.

Returns:

true if a new String was created with replacements, false otherwise.

Throws:

GCValueNotFoundException - thrown if the document contains a reference to a GCV that does not exist in this GCDefinitions instance.

apply

public boolean apply(Node target)
              throws GCValueNotFoundException

Replace GCV references in an XML document with the values from GCVs in this GCDefinitions instance.

A GCV reference is the name of a GCV delimited by '~' (tilde) characters. For example:

~enable-password-sync~

References may appear in the following locations:

• Element attribute values.
• Text nodes.
• Processing instruction data

Tilde characters may appear without being interpreted as delimiters if there is only a single tilde in the attribute value, text node, or pi data.

Double tilde characters ("~~") are interpreted as a single escaped tilde and are replaced by a single tilde.

Note that the middle two tilde characters in the following example are not interpreted as an escape sequence:

~value-name-1~~value-name-2~

Parameters:

target - the root of the subtree to which to apply the GCVs.

Returns:

true if anything was modified in the document, false otherwise.

Throws:

GCValueNotFoundException - thrown if the document contains a reference to a GCV that does not exist in this GCDefinitions instance.

merge

public void merge(GCDefinitions other)

Merge this GCDefinitions instance with another. GCValues with conflicting names are resolved by keeping the defintition of the value from this instance.

This method is intended for merging the GCVs from a DirXML-Driver object and its parent DirXML-DriverSet object. The DirXML-Driver GCVs must take precedence.

Note that references to GCValues from the other GCDefinitions instance are made, not copies.

Parameters:

other - instance with which to merge

localize

public void localize(LocalizedMessageSource messageSource)

Localize any display names and descriptions that have localization refs ("display-name-ref" and "description-ref") attributes.

Any display names or descriptions that have localization refs, but whose localized strings cannot be located in the passed LocalizedMessageSource are left unlocalized.

Parameters:

messageSource - Source for localized strings.

checkAllowedType

public boolean checkAllowedType(int type)

Check whether or not a particular GCV type is allowed in this collection of GCVs.

Classes derived from GCDefinitions (e.g., ShimParams) may allow more or fewer types.

Parameters:

type - GCValue.TYPE_STRING, etc.

Returns:

true if allowed, false otherwise