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

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

All Implemented Interfaces:

ConfigElement

Direct Known Subclasses:

GCBooleanValue, GCDnRefValue, GCDNValue, GCEnumValue, GCHeader, GCIntegerValue, GCListValue, GCParent, GCPasswordRefValue, GCRealValue, GCStringValue, GCStructuredValue, GCVRef

public abstract class GCValue
extends Object
implements ConfigElement

Base class for all Global Configuration Value types.

Nested Class Summary

static class	GCValue.IllegalCloneStateException Unchecked exception designed to be thrown when an "impossible" exception occurs during a cloneValue execution.
static class	GCValue.XmlComment Class for representing XML comments.
static class	GCValue.XmlItem Abstract class for representing XML processing instructions and comments.
static class	GCValue.XmlProcessingInstruction Class for representing XML processing instructions.

Field Summary

protected boolean	modified
protected GCParent	parent
static int	TYPE_BOOLEAN Integer constant representing "boolean" value type
static int	TYPE_DN Integer constant representing "dn" value type
static int	TYPE_DN_REF Integer constant representing "dn-ref" value type
static int	TYPE_ENUM Integer constant representing "enum" value type
static int	TYPE_GCV_REF Integer constant representing "gcv-ref" element
static int	TYPE_GROUP Integer constant representing "group" element
static int	TYPE_HEADER Integer constant representing "header" element
static int	TYPE_INTEGER Integer constant representing "integer" value type
static int	TYPE_LIST Integer constant representing "list" value type
static int	TYPE_PASSWORD_REF Integer constant representing "password-ref" value type
static int	TYPE_REAL Integer constant representing "real" value type
static int	TYPE_STRING Integer constant representing "string" value type
static int	TYPE_STRUCTURED
static int	TYPE_SUBORDINATES Integer constant representing "subordinates" element
protected List	xmlItems

Method Summary

void	addXmlComment(String data) Add an XML comment that will appear under the <definition> element when this GCValue is serialized.
protected void	addXmlItems(Element definition) Append any XML processing instructions or comments as children of the passed element.
void	addXmlProcessingInstruction(String target, String data) Add an XML processing instruction that will appear under the <definition> element when this GCValue is serialized.
protected void	cloneCommon(GCValue newValue) Helper function for derived classes to implement cloneValue.
abstract GCValue	cloneValue(String name) Clone this GCValue instance and return the cloned instance.
static GCValue	construct(String name, String displayName, int type) Construct a GCValue object given the name, display name, and type.
static GCValue	construct(String name, String displayName, String displayNameRef, int type) Construct a GCValue object given the name, display name, and type.
static GCValue	constructGCVRef(String name) Construct a GCVRef instance.
static GCValue	constructGCVRef(String name, String driverParamName) Construct a GCVRef instance.
static GCValue	constructGroup(GCOwner owner) Construct a GCGroup instance.
static GCValue	constructHeader(String displayName, GCOwner owner) Construct a GCHeader instance.
static GCValue	constructStructuredValue(String name, String displayName, GCOwner owner) Construct a GCStructuredValue instance.
static GCValue	constructSubordinates(String activeValue, GCOwner owner) Construct a GCSubordinates instance.
String	getDescription() Get the description, if any, of this value.
String	getDescriptionRef() Return the description localization reference, if any.
String	getDisplayName() Return the display name of this value.
String	getDisplayNameRef() Return the display name localization reference, if any.
boolean	getHidden() Get whether this GCV should be hidden in the user interface.
boolean	getMandatory() Return whether the UI should require a value be entered for this GCV.
String	getName() Return the name of this value.
GCOwner	getOwner() Return the owner, if any.
GCParent	getParent() Return the parent value, if any.
int	getType() Return the int value representing the type of this value.
String	getTypeString() Return the String identifying the type of this value.
abstract String	getValue() Get the current value for this instance.
Iterator	getXmlItemsIterator() Get an Iterator that will iterator through any processing instructions and comments that may be attached to this GCValue.
Node	getXMLValue(Document document) Return an XML node representing this GCV's value.
boolean	hasBeenModified() Return true if this instance has been modified.
void	localize(LocalizedMessageSource messageSource) Localize the display name and/or descriptions if there are localization refs for them.
abstract void	parseValue(String value) Parse the passed value based on the type and instance rules for this value.
void	resetModified() Reset the modified flag for this instance such that hasBeenModified() will return false.
void	setDescription(String description) Set the description for this value.
void	setDescriptionRef(String descriptionRef) Set the description localization reference.
void	setDisplayName(String displayName) Set the display name of this value.
void	setDisplayNameRef(String displayNameRef) Set the display name localization reference.
void	setHidden(boolean hidden) Set whether this GCV should be hidden in the user interface.
void	setMandatory(boolean mandatory) Set whether this GCV should require a value.
abstract void	setValue(String value) Set the value for this instance.
Element	toXML(Node parent) Create an XML representation for this instance under the passed Node.
static int	typeFromString(String typeString) Return an integer constant based on a type string.

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_STRING

public static final int TYPE_STRING

Integer constant representing "string" value type

See Also:

Constant Field Values

TYPE_BOOLEAN

public static final int TYPE_BOOLEAN

Integer constant representing "boolean" value type

See Also:

Constant Field Values

TYPE_INTEGER

public static final int TYPE_INTEGER

Integer constant representing "integer" value type

See Also:

Constant Field Values

TYPE_REAL

public static final int TYPE_REAL

Integer constant representing "real" value type

See Also:

Constant Field Values

TYPE_DN

public static final int TYPE_DN

Integer constant representing "dn" value type

See Also:

Constant Field Values

TYPE_ENUM

public static final int TYPE_ENUM

Integer constant representing "enum" value type

See Also:

Constant Field Values

TYPE_PASSWORD_REF

public static final int TYPE_PASSWORD_REF

Integer constant representing "password-ref" value type

See Also:

Constant Field Values

TYPE_GCV_REF

public static final int TYPE_GCV_REF

Integer constant representing "gcv-ref" element

See Also:

Constant Field Values

TYPE_HEADER

public static final int TYPE_HEADER

Integer constant representing "header" element

See Also:

Constant Field Values

TYPE_GROUP

public static final int TYPE_GROUP

Integer constant representing "group" element

See Also:

Constant Field Values

TYPE_SUBORDINATES

public static final int TYPE_SUBORDINATES

Integer constant representing "subordinates" element

See Also:

Constant Field Values

TYPE_LIST

public static final int TYPE_LIST

Integer constant representing "list" value type

See Also:

Constant Field Values

TYPE_DN_REF

public static final int TYPE_DN_REF

Integer constant representing "dn-ref" value type

See Also:

Constant Field Values

TYPE_STRUCTURED

public static final int TYPE_STRUCTURED

See Also:

Constant Field Values

modified

protected boolean modified

parent

protected GCParent parent

xmlItems

protected List xmlItems

Method Detail

construct

public static GCValue construct(String name,
                                String displayName,
                                int type)
                         throws GCVException

Construct a GCValue object given the name, display name, and type.

The constructed object may not be complete. For example, an "enum" object will not have any enum choices, nor will the value be set.

Parameters:

name - The name of the Global Configuration Value

displayName - The user-interface name of the GCV.

type - The type of value to construct (TYPE_STRING, TYPE_BOOLEAN, etc.).

Returns:

A newly-constructed GCValue-based object.

Throws:

GCVException - thrown if name or displayName is null or empty, or if the type is not valid.

constructHeader

public static GCValue constructHeader(String displayName,
                                      GCOwner owner)
                               throws GCVException

Construct a GCHeader instance.

Parameters:

displayName - display value for header

Returns:

GCHeader instance.

Throws:

GCVException - thrown if displayName is invalid

constructGroup

public static GCValue constructGroup(GCOwner owner)
                              throws GCVException

Construct a GCGroup instance.

Parameters:

owner - GCOwner instance that owns the group.

Returns:

GCGroup instance.

Throws:

GCVException - not thrown

constructSubordinates

public static GCValue constructSubordinates(String activeValue,
                                            GCOwner owner)
                                     throws GCVException

Construct a GCSubordinates instance.

Parameters:

owner - GCOwner instance that owns the group.

activeValue - "active-value" attribute value.

Returns:

GCSubordinates instance.

Throws:

GCVException - thrown if activeValue is incorrect.

constructGCVRef

public static GCValue constructGCVRef(String name)
                               throws GCVException

Construct a GCVRef instance.

Parameters:

name - name of GCV to reference.

Returns:

GCVRef instance.

Throws:

GCVException - thrown if name is null or empty.

constructGCVRef

public static GCValue constructGCVRef(String name,
                                      String driverParamName)
                               throws GCVException

Construct a GCVRef instance.

Parameters:

name - name of GCV to reference.

driverParamName - name of driver parameter to use (may be null). If non-null, the value must be a valid XML Name.

Returns:

GCVRef instance.

Throws:

GCVException - thrown if name is null or empty.

constructStructuredValue

public static GCValue constructStructuredValue(String name,
                                               String displayName,
                                               GCOwner owner)
                                        throws GCVException

Construct a GCStructuredValue instance.

Parameters:

name - of the Control Value.

displayName - The user-interface name of the Control Value.

owner - GCOwner instance that will own the GCStructuredValue instance

Returns:

GCStructuredValue instance

Throws:

GCVException

construct

public static GCValue construct(String name,
                                String displayName,
                                String displayNameRef,
                                int type)
                         throws GCVException

Construct a GCValue object given the name, display name, and type.

The constructed object may not be complete. For example, an "enum" object will not have any enum choices, nor will the value be set.

Parameters:

name - The name of the Global Configuration Value

displayName - The user-interface name of the GCV.

displayNameRef - A localized string identifier that can be used to obtain a localized version of the display name, given a LocalizedMessageSource instance.

type - The type of value to construct (TYPE_STRING, TYPE_BOOLEAN, etc.).

Returns:

A newly-constructed GCValue-based object.

Throws:

GCVException - thrown if the name or display name is null or empty, or if the type is not valid.

cloneValue

public abstract GCValue cloneValue(String name)

Clone this GCValue instance and return the cloned instance.

Parameters:

the - name for the cloned value.

Returns:

the cloned instance

cloneCommon

protected void cloneCommon(GCValue newValue)

Helper function for derived classes to implement cloneValue. Clones data common to all GCValue instances.

Parameters:

newValue - the value to which to copy

getParent

public GCParent getParent()

Return the parent value, if any.

Returns:

parent (may be null)

getOwner

public GCOwner getOwner()

Return the owner, if any.

Returns:

owner (may be null)

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()

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()

getName

public String getName()

Return the name of this value.

Returns:

name String (never null).

getType

public int getType()

Return the int value representing the type of this value.

Returns:

TYPE_STRING, TYPE_BOOLEAN, etc.

getTypeString

public String getTypeString()

Return the String identifying the type of this value.

Returns:

"string", "boolean", etc. (never null).

getDisplayName

public String getDisplayName()

Return the display name of this value.

Returns:

display name (never null).

setDisplayName

public void setDisplayName(String displayName)
                    throws GCVArgumentException

Set the display name of this value.

Parameters:

displayName - non-null, non-empty String for display purposes.

Throws:

GCVArgumentException - thrown if displayName is null or empty.

getDisplayNameRef

public String getDisplayNameRef()

Return the display name localization reference, if any.

Returns:

display name localization reference, or null.

setDisplayNameRef

public void setDisplayNameRef(String displayNameRef)

Set the display name localization reference.

Parameters:

displayNameRef - A string identifier in a Properties collection that can be used with LocalizedMessageSource.

getDescription

public String getDescription()

Get the description, if any, of this value. May return null, or an empty string.

Returns:

description String, or null

setDescription

public void setDescription(String description)

Set the description for this value.

Parameters:

description - Description String (may be empty or null).

getDescriptionRef

public String getDescriptionRef()

Return the description localization reference, if any.

Returns:

description name localization reference, or null.

setDescriptionRef

public void setDescriptionRef(String descriptionRef)

Set the description localization reference.

Parameters:

descriptionRef - A string identifier in a Properties collection that can be used with LocalizedMessageSource.

setHidden

public void setHidden(boolean hidden)

Set whether this GCV should be hidden in the user interface.

Parameters:

hidden - true or false

getHidden

public boolean getHidden()

Get whether this GCV should be hidden in the user interface.

Returns:

true or false

setMandatory

public void setMandatory(boolean mandatory)

Set whether this GCV should require a value.

Parameters:

true - or false

getMandatory

public boolean getMandatory()

Return whether the UI should require a value be entered for this GCV.

addXmlProcessingInstruction

public void addXmlProcessingInstruction(String target,
                                        String data)

Add an XML processing instruction that will appear under the <definition> element when this GCValue is serialized.

Parameters:

target - the target string for the processing instruction

data - the data string for the processing instruction

addXmlComment

public void addXmlComment(String data)

Add an XML comment that will appear under the <definition> element when this GCValue is serialized.

Parameters:

data - the comment string

getXmlItemsIterator

public Iterator getXmlItemsIterator()

Get an Iterator that will iterator through any processing instructions and comments that may be attached to this GCValue. The returned Iterator instance supports Iterator.remove().

Returns:

an Iterator

parseValue

public abstract void parseValue(String value)
                         throws GCVException

Parse the passed value based on the type and instance rules for this value.

The type rules are lexicographic and value-based. For example, an integer must consist of only characters '0' through '9', with an optional leading '-'. In addition, the integer value represented by the string must not exceed java.lang.Integer.MIN_VALUE and java.lang.Integer.MAX_VALUE.

The instance rules depend on the instance of the value. If, for example, this instance is an "integer" type and there is a range restriction, then the passed value must fall within the range restriction.

Parameters:

value - Value String to parse

Throws:

GCVException - thrown if value is not correct for this value instance.

getValue

public abstract String getValue()

Get the current value for this instance. This will never return null, but the value may not be correct if it has not yet been set. For example, a newly-constructed "enum" object will have an empty, invalid value of "".

Returns:

value String

setValue

public abstract void setValue(String value)
                       throws GCVException

Set the value for this instance. The passed string must be appropriate for the instance. In other words, parseValue() must not throw an exception when passed the value.

Parameters:

value - Value String for this instance.

Throws:

GCVException - thrown if value is not correct for this value instance.

getXMLValue

public Node getXMLValue(Document document)

Return an XML node representing this GCV's value. The default implementation simply returns a Text node containing the value returned by getValue(). Certain GCV types (e.g., "list") may return more structured data.

Parameters:

document - the Document to use to create nodes.

Returns:

the Node that is the root of the XML representation.

toXML

public Element toXML(Node parent)

Create an XML representation for this instance under the passed Node.

Note that the act of creating an XML representation does not reset this instance's modified flag. It must be reset by calling resetModified().

Specified by:

toXML in interface ConfigElement

Parameters:

parent - Node under which to construct XML representation.

Returns:

created Element

See Also:

hasBeenModified(), resetModified()

localize

public void localize(LocalizedMessageSource messageSource)

Localize the display name and/or descriptions if there are localization refs for them.

If the display name or description has a localization refs, but the localized string cannot be located in the passed LocalizedMessageSource they are left unlocalized.

Parameters:

messageSource - Source for localized strings.

typeFromString

public static int typeFromString(String typeString)

Return an integer constant based on a type string.

e.g., "integer" -> TYPE_INTEGER

Parameters:

typeString - string describing type ("string", "integer", "enum", etc.)

Returns:

integer value (TYPE_STRING, TYPE_INTEGER, TYPE_ENUM) or -1 if string is invalid.

addXmlItems

protected void addXmlItems(Element definition)

Append any XML processing instructions or comments as children of the passed element.

Parameters:

definition - the <definition> element (or <group>, <gcv-ref>, etc., element for derived classes)