org.quattor.pan.dml.data
Class Element

java.lang.Object
  org.quattor.pan.dml.data.Element

All Implemented Interfaces:

Operation

Direct Known Subclasses:

PersistentElement, TransientElement

@Immutable
public abstract class Element
extends java.lang.Object
implements Operation

Represents the most general data element in the Data Manipulation Language (DML). This class adds some utility methods which are useful for implementing some of the built-in functions.

Author:

loomis

Constructor Summary

Element()

Method Summary

void	checkInvalidSelfContext() The default implementation does nothing.
void	checkRange(Range range) Determine if the element satisfies the given range constraint.
void	checkRestrictedContext() The default implementation does nothing.
void	checkValidReplacement(Element newValue) Check that the newValue is a valid replacement for the this value.
boolean	defined() Determine if the given Element is defined.
Element	duplicate() This method does a "clone" of the given Element.
abstract boolean	equals(java.lang.Object o) Require that all Elements implement an equals method.
Element	execute(Context context) All Elements are Operations and can be executed, but each just returns a reference to itself.
boolean	exists() Returns true for all Element objects except Null.
abstract java.lang.String	getTypeAsString() All Elements must return a string describing its type.
abstract int	hashCode() Require that all Elements implement the hashCode method.
boolean	isBoolean() Determine if the given Element is a Boolean.
boolean	isDouble() Determine if the given Element is a Double.
boolean	isList() Determine if the given Element is a List.
boolean	isLong() Determine if the given Element is a Long.
boolean	isNlist() Determine if the given Element is an Nlist.
boolean	isPersistent() Determine if the given Element is Persistent.
boolean	isProperty() Determine if the given Element is a Property.
boolean	isProtected() This method indicates if the given Element is protected.
boolean	isResource() Determine if the given Element is a Resource.
boolean	isString() Determine if the given Element is a String.
boolean	isTransient() Determine if the given Element is Transient.
java.lang.String	locateUndefinedElement() Determine if the element contains any undefined (transient) elements.
Element	protect() Return a protected version of this Element.
Element	rget(Term[] terms, int index, boolean protect, boolean lookupOnly) Dereference the Element to return the value of a child.
ListResource	rgetList(Term[] terms, int index) This is a special lookup function that will retrieve a list from the resource.
void	rput(Term[] terms, int index, Element value) Add the given child to this resource, creating intermediate resources as necessary.
abstract java.lang.String	toString() Require that all Elements implement a reasonable toString method.
Element	writableCopy() This method returns a writable copy of this Element.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Element

public Element()

Method Detail

exists

public boolean exists()

Returns true for all Element objects except Null.

Returns:

true unless object is Null

defined

public boolean defined()

Determine if the given Element is defined. This will return true for all Elements except Null and Undef.

isProperty

public boolean isProperty()

Determine if the given Element is a Property.

isLong

public boolean isLong()

Determine if the given Element is a Long.

isDouble

public boolean isDouble()

Determine if the given Element is a Double.

isBoolean

public boolean isBoolean()

Determine if the given Element is a Boolean.

isString

public boolean isString()

Determine if the given Element is a String.

isResource

public boolean isResource()

Determine if the given Element is a Resource.

isNlist

public boolean isNlist()

Determine if the given Element is an Nlist.

isList

public boolean isList()

Determine if the given Element is a List.

isPersistent

public boolean isPersistent()

Determine if the given Element is Persistent. Persistent Elements are valid entries in a final configuration tree.

isTransient

public boolean isTransient()

Determine if the given Element is Transient. Transient Elements are only valid while building the tree. They may not appear in the final configuration tree.

locateUndefinedElement

public java.lang.String locateUndefinedElement()

Determine if the element contains any undefined (transient) elements. The call will return null if no undefined elements are found; it will return a string indicating the relative path if an undefined element is found. Subclasses MUST override this method appropriately. This default method will work only for elements which are not containers and not a transient element.

Returns:

String representation of the path of the undefined element, null otherwise

checkRange

public void checkRange(Range range)
                throws ValidationException

Determine if the element satisfies the given range constraint. This is used in the validation of the element. By default, this method with throw a ValidationException indicating that range checking of this element is not appropriate.

Parameters:

range - Range to check Element against

Throws:

ValidationException - if the element cannot be compared to a range or if the element doesn't meet the range requirement

execute

public Element execute(Context context)
                throws EvaluationException

All Elements are Operations and can be executed, but each just returns a reference to itself. Subclasses should not need to override this method.

Specified by:

execute in interface Operation

Parameters:

context - evaluation context for the statement

Returns:

reference to the same Element

Throws:

EvaluationException - if an error occurs during processing

duplicate

public Element duplicate()

This method does a "clone" of the given Element. Immutable Elements may return a reference to the same object. Mutable Elements (i.e. Resources) must provide an actual deep-copy of the Element. This method simply returns a reference to the same object and is suitable only for immutable subclasses. Mutable subclasses (i.e. Resources) must override this method to provide an appropriate deep copy. This is not actually named "clone" because it violates the conditions of that method for creating a duplicate of the instance in all cases.

Returns:

deep-copy of Element for mutable elements, self-reference for immutable objects

writableCopy

public Element writableCopy()

This method returns a writable copy of this Element. The default implementation just returns a reference to the same Element. This is the correct behavior for any object that returns false for the isProtected method. Objects that return true for isProtected, must override this method.

Returns:

returns a writable copy of this element; if the current element is not protected, then a reference to this object is returned

checkRestrictedContext

public void checkRestrictedContext()
                            throws SyntaxException

The default implementation does nothing. This should not need to be overridden as all data elements can appear anywhere within a DML block. (Although placement may cause other errors during evaluation.)

Specified by:

checkRestrictedContext in interface Operation

Throws:

SyntaxException - if this operation cannot be run within a restricted context

checkInvalidSelfContext

public void checkInvalidSelfContext()
                             throws SyntaxException

The default implementation does nothing. This should not need to be overridden as all data elements explicitly make no reference to SELF.

Specified by:

checkInvalidSelfContext in interface Operation

Throws:

SyntaxException - if this operation references SELF

isProtected

public boolean isProtected()

This method indicates if the given Element is protected. A protected element may not be written to and concerns just resources. The default implementation just returns false. This should be sufficient except for protected resources.

checkValidReplacement

public void checkValidReplacement(Element newValue)
                           throws EvaluationException

Check that the newValue is a valid replacement for the this value. This implementation will check if the newValue is assignable from the current value or that the newValue is either undef or null. If not, an evaluation exception will be thrown. This implementation should be overridden if more liberal replacements are allowed.

Parameters:

newValue - the new value for the replacement

Throws:

EvaluationException - if the new value is not a valid replacement of the existing value

protect

public Element protect()

Return a protected version of this Element. The default implementation just returns to "this". Only unprotected resources will have to override this implementation.

Returns:

protected version of the resource

rget

public Element rget(Term[] terms,
                    int index,
                    boolean protect,
                    boolean lookupOnly)
             throws InvalidTermException

Dereference the Element to return the value of a child. Any resource should return the value of the given child. The default implementation of this method will throw an EvaluationException indicating that this Element cannot be dereferenced.

Parameters:

terms - list of terms to use for dereference

index - the term to use in the given list of term

protect - flag to indicate that the return value should be a protected (if value is a resource)

lookupOnly - indicates that only a lookup is required, return null if the element doesn't exist

Throws:

InvalidTermException - thrown if an trying to dereference a list with a key or a hash with an index

rgetList

public ListResource rgetList(Term[] terms,
                             int index)
                      throws InvalidTermException

This is a special lookup function that will retrieve a list from the resource. If the resource does not exist, an empty list will be created. All necessary parent resources are created. The returned list is guaranteed to be a writable resource.

Parameters:

terms - list of terms to use for dereference

index - the term to use in the given list of term

Returns:

writable list

Throws:

InvalidTermException

rput

public void rput(Term[] terms,
                 int index,
                 Element value)
          throws InvalidTermException

Add the given child to this resource, creating intermediate resources as necessary. If this Element is not a resource, then this will throw an InvalidTermException. The default implementation of this method throws such an exception. This resource must be a writable resource, otherwise an exception will be thrown.

Throws:

InvalidTermException - thrown if an trying to dereference a list with a key or a hash with an index

getTypeAsString

public abstract java.lang.String getTypeAsString()

All Elements must return a string describing its type. This value used in the serialization to machine profiles.

Returns:

String representation of Element's type

toString

public abstract java.lang.String toString()

Require that all Elements implement a reasonable toString method.

Overrides:

toString in class java.lang.Object

hashCode

public abstract int hashCode()

Require that all Elements implement the hashCode method.

Overrides:

hashCode in class java.lang.Object

equals

public abstract boolean equals(java.lang.Object o)

Require that all Elements implement an equals method.

Overrides:

equals in class java.lang.Object