org.griphyn.vdl.classes
Class Definitions

java.lang.Object
  org.griphyn.vdl.Chimera
      org.griphyn.vdl.classes.VDL
          org.griphyn.vdl.classes.Definitions

All Implemented Interfaces:

Serializable

public class Definitions
extends VDL
implements Serializable

This class implements the container to carry any number of Transformation and Derivation instances. In addition, it captures some attributes from the root element of the XML document.

Version:

$Revision: 50 $

Author:

Jens-S. V??ckler, Yong Zhao

See Also:

Definition, Transformation, Derivation, Serialized Form

Field Summary

private ArrayList	m_definitionList children are either Transformations or Derivations, both of which are Derivations.
private int[][]	m_state updating old Use.linkage with new Use.linkage.
private String	m_vdlns Capture the global namespace given to all child elements that do not set their own namespace definition.
private String	m_version Capture the version of the XML document.
static String	SCHEMA_LOCATION The "not-so-official" location URL of the VDLx schema definition.
static String	SCHEMA_NAMESPACE The "official" namespace URI of the VDLx schema.

Constructor Summary

Definitions()
ctor.

Definitions(String vdlns)
ctor: Create a new container, using the given namespace.

Definitions(String vdlns, String version)
ctor: Create a new container, using a namespace and version.

Method Summary

void	addDefinition(Definition d) Accessor: Appends a Definition to the container.
void	addDefinition(int index, Definition d) Accessor: Inserts a Definition at a particular place.
private void	checkLinkage(Map use, Use u, Transformation tr) Checks the linkage of a transformation between a declared, previously used and currently used variable of the same name.
Enumeration	enumerateDefinition() Deprecated. Use the new Collection based interfaces
Definition[]	getDefinition() Deprecated. Use the new Collection based interfaces
Definition	getDefinition(int index) Accessor: Obtains a Definition at a particular place in this container.
int	getDefinitionCount() Accessor: Counts the number of Transformation and Derivation definitions.
List	getDefinitionList() Accessor: Obtains all Definitions available.
List	getDefinitionOfAKind(int type) Obtains a vector of all definition instances that share the same instance type.
String	getVdlns() Accessor: Obtains the document namespace.
String	getVersion() Accessor: Obtains the document version number.
Iterator	iterateDefinition() Accessor: Provides an iterator for the list of Transformation and Derivation references.
ListIterator	listIterateDefinition() Accessor: Provides an iterator for the list of Transformation and Derivation references.
ListIterator	listIterateDefinition(int start) Accessor: Provides an iterator for the list of Transformation and Derivation references.
int	positionOfDefinition(Definition d) Accessor: Search the database for the existence of a Definition with the same primary keys and type as the parameter.
void	removeAllDefinition() Accessor: Removes all definitions we know about.
boolean	removeDefinition(Definition d) Accessor: Removes a definition named by its reference.
Definition	removeDefinition(int index) Accessor: Removes a definition.
protected void	sanitizeDefinition(Definition d) Clean-up definition and perform abstract type checks before submitting them into the document.
void	setDefinition(Collection definitions) Accessor: Replace all Definitions with a new list.
void	setDefinition(Definition[] definitionArray) Deprecated. Use the new Collection based interfaces
Definition	setDefinition(int index, Definition d) Accessor: Sets the component at the specified index of this vector to be the specified object.
void	setVdlns(String vdlns) Accessor: Sets the document default namespace.
void	setVersion(String version) Accessor: Replaces the version number of the document.
void	toString(Writer stream) Dumps the content of the given element into a string.
void	toXML(Writer stream, String indent, String namespace) Dump the state of the current element as XML output.
void	writeXMLHeader(Writer stream, String indent, String namespace) Writes the header of the XML output.

Methods inherited from class org.griphyn.vdl.Chimera

escape, quote, toString, toXML, toXML, writeAttribute

Methods inherited from class java.lang.Object

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

Field Detail

SCHEMA_NAMESPACE

public static final String SCHEMA_NAMESPACE

The "official" namespace URI of the VDLx schema.

See Also:

Constant Field Values

SCHEMA_LOCATION

public static final String SCHEMA_LOCATION

The "not-so-official" location URL of the VDLx schema definition.

See Also:

Constant Field Values

m_vdlns

private String m_vdlns

Capture the global namespace given to all child elements that do not set their own namespace definition.

m_version

private String m_version

Capture the version of the XML document.

m_definitionList

private ArrayList m_definitionList

children are either Transformations or Derivations, both of which are Derivations.

m_state

private int[][] m_state

updating old Use.linkage with new Use.linkage. This table uses the old/stored linkage in the top row, and the new/found linkage in the first column. (-) denotes no action to be taken, and # an illegal combination.

       | -1  | NONE| IN  | OUT | IO
   ----+-----+-----+-----+-----+----
    -1 | (-) | (-) | (-) | (-) | (-)
   NONE| NONE| (-) |  #  |  #  |  # 
     IN| IN  |  #  | (-) | IO  | (-)
    OUT| OUT |  #  | IO  | (-) | (-)
     IO| IO  |  #  | IO  | IO  | (-)
   ----+-----+-----+-----+-----+----
 

The table uses -1 for no action to do, and -2 for an illegal state.

Constructor Detail

Definitions

public Definitions()

ctor. It is strongly suggested that you set the namespace and version of the object before adding any other Definition objects.

Definitions

public Definitions(String vdlns)

ctor: Create a new container, using the given namespace. It is highly recommended that you set the version number before you add any Definition instance.

Parameters:

vdlns - is the namespace to use for elements w/o namespace.

Definitions

public Definitions(String vdlns,
                   String version)

ctor: Create a new container, using a namespace and version.

Parameters:

vdlns - is the namespace to propagate to children w/o namespace.

version - is a version of the XML document used to transport the data.

Method Detail

checkLinkage

private void checkLinkage(Map use,
                          Use u,
                          Transformation tr)

Checks the linkage of a transformation between a declared, previously used and currently used variable of the same name.

Parameters:

use - is a table of previously used variables and their linkage

u - is the variable at the "cursor position".

tr - is the transformation to be checked.

sanitizeDefinition

protected void sanitizeDefinition(Definition d)
                           throws IllegalArgumentException,
                                  IncompatibleLinkageException,
                                  UndeclaredVariableException,
                                  IllegalTransformationException

Clean-up definition and perform abstract type checks before submitting them into the document.

Throws:

IllegalArgumentException - will be thrown if the Definition is neither a Derivation nor a Transformation. This should not happen.

UndeclaredVariableException - will be thrown, if a Transformation uses a bound variable via Use, but fails to declare the formal argument with Declare.

IncompatibleLinkageException - will be thrown, if the declared linkage of a formal argument is incompatible with the usage of such a bound variable within a Transformation.

IllegalTransformationException - will be thrown, if the Transformation has simultaneously Call and Argument items. This exception is bound to vanish with the next major re-design.

See Also:

Transformation, Derivation, Use, Declare

addDefinition

public void addDefinition(Definition d)
                   throws IndexOutOfBoundsException

Accessor: Appends a Definition to the container. The namespace and version information will be, in case they are missing, updated from the definitions namespace and version respectively.

Parameters:

d - is the Transformation or Derivation to append to the internal container.

Throws:

IndexOutOfBoundsException - if the definition does not fit into the container.

addDefinition

public void addDefinition(int index,
                          Definition d)
                   throws IndexOutOfBoundsException

Accessor: Inserts a Definition at a particular place. The namespace and version information will be, in case they are missing, updated from the definitions namespace and version respectively.

Each component in this vector with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

Parameters:

index - is the position to insert a Definition

d - is the Transformation or Derivation to append to the internal container.

Throws:

IndexOutOfBoundsException - if the definition does not fit into the container.

positionOfDefinition

public int positionOfDefinition(Definition d)

Accessor: Search the database for the existence of a Definition with the same primary keys and type as the parameter.

Parameters:

d - is the Definition to search for

Returns:

the position of the selfsame Definition, or -1 if not found.

enumerateDefinition

public Enumeration enumerateDefinition()

Deprecated. Use the new Collection based interfaces

Accessor: Provides an iterator for the list of Transformation and Derivation.

Returns:

the iterator to traverse the container of Definitions.

See Also:

Enumeration

getDefinitionOfAKind

public List getDefinitionOfAKind(int type)

Obtains a vector of all definition instances that share the same instance type. Please note that the definitions below may change after the vector is obtained.

Returns:

a vector with all Transformation or Derivation objects. The vector may have zero size, if no such instances exist.

getDefinition

public Definition getDefinition(int index)
                         throws IndexOutOfBoundsException

Accessor: Obtains a Definition at a particular place in this container.

Parameters:

index - is the place to look up the element.

Returns:

the Definition at the specified place.

Throws:

IndexOutOfBoundsException - if the referenced position does not exist.

See Also:

Definition

getDefinition

public Definition[] getDefinition()

Deprecated. Use the new Collection based interfaces

Accessor: Obtains all Definitions available. This array is a copy to avoid write-through modifications.

Returns:

an array containing either a Transformation or Derivation at each position.

getDefinitionCount

public int getDefinitionCount()

Accessor: Counts the number of Transformation and Derivation definitions.

Returns:

item count.

getDefinitionList

public List getDefinitionList()

Accessor: Obtains all Definitions available. This list is read-only.

Returns:

an array containing either a Transformation or Derivation at each position.

getVdlns

public String getVdlns()

Accessor: Obtains the document namespace.

Returns:

the namespace of the document, or null, if not used.

See Also:

setVdlns(java.lang.String)

getVersion

public String getVersion()

Accessor: Obtains the document version number.

Returns:

the version number from the document header, or null, if unset. Since the version number is a required attribute, it should never return null, only an empty string.

iterateDefinition

public Iterator iterateDefinition()

Accessor: Provides an iterator for the list of Transformation and Derivation references.

Returns:

a list iterator to traverse the container of Definitions.

See Also:

ListIterator

listIterateDefinition

public ListIterator listIterateDefinition()

Accessor: Provides an iterator for the list of Transformation and Derivation references.

Returns:

a list iterator to traverse the container of Definitions.

See Also:

ListIterator

listIterateDefinition

public ListIterator listIterateDefinition(int start)

Accessor: Provides an iterator for the list of Transformation and Derivation references.

Parameters:

start - is the starting point of the iteration.

Returns:

a list iterator to traverse the container of Definitions.

See Also:

ListIterator

removeAllDefinition

public void removeAllDefinition()

Accessor: Removes all definitions we know about.

See Also:

Definition

removeDefinition

public Definition removeDefinition(int index)

Accessor: Removes a definition. Each component in this vector with an index greater or equal to the specified index is shifted downward to have an index one smaller than the value it had previously. The size of this vector is decreased by 1.

Parameters:

index - is the position to remove the argument fragment from.

Returns:

the removed Definition.

Throws:

ArrayIndexOutOfBoundsException - if the index was invalid.

See Also:

Definition

removeDefinition

public boolean removeDefinition(Definition d)

Accessor: Removes a definition named by its reference. Removes the first occurrence of the specified element in this Vector.

Parameters:

d - is a definition instance that originated from this list.

Returns:

true, if the first occurance of the element was deleted, false, if there was nothing found to be removed.

See Also:

Definition

setDefinition

public Definition setDefinition(int index,
                                Definition d)
                         throws IndexOutOfBoundsException

Accessor: Sets the component at the specified index of this vector to be the specified object. The previous component at that position is discarded. The index must be a value greater than or equal to 0 and less than the current size of the vector.

Parameters:

index - is the postion at which to replace a Definition.

d - is either a Transformation or Derivation to use for replacement.

Throws:

IndexOutOfBoundsException - if the index was invalid.

setDefinition

public void setDefinition(Definition[] definitionArray)

Deprecated. Use the new Collection based interfaces

Accessor: Replace all Definitions with a new list.

Parameters:

definitionArray - is an array of possibly mixed Transformation and Derivation elements.

setDefinition

public void setDefinition(Collection definitions)

Accessor: Replace all Definitions with a new list.

Parameters:

definitions - is an collection of possibly mixed Transformation and Derivation elements.

setVdlns

public void setVdlns(String vdlns)

Accessor: Sets the document default namespace.

Parameters:

vdlns - is the new namespace to use. Note that the change will not be propagated to contained elememts.

See Also:

getVdlns()

setVersion

public void setVersion(String version)

Accessor: Replaces the version number of the document.

Parameters:

version - is the new version number.

See Also:

getVersion()

toString

public void toString(Writer stream)
              throws IOException

Dumps the content of the given element into a string. This function traverses all sibling classes as necessary and converts the data into textual output.

Specified by:

toString in class Chimera

Parameters:

stream - is a stream opened and ready for writing. This can also be a string stream for efficient output.

Throws:

IOException - if something fishy happens to the stream.

writeXMLHeader

public void writeXMLHeader(Writer stream,
                           String indent,
                           String namespace)
                    throws IOException

Writes the header of the XML output. The output contains the special strings to start an XML document, some comments, and the root element. The latter points to the XML schema via XML Instances.

Parameters:

stream - is a stream opened and ready for writing. This can also be a string stream for efficient output.

indent - is a String of spaces used for pretty printing. The initial amount of spaces should be an empty string. The parameter is used internally for the recursive traversal.

namespace - is the XML schema namespace prefix. If neither empty nor null, each element will be prefixed with this prefix, and the root element will map the XML namespace.

Throws:

IOException - if something fishy happens to the stream.

toXML

public void toXML(Writer stream,
                  String indent,
                  String namespace)
           throws IOException

Dump the state of the current element as XML output. This function traverses all sibling classes as necessary, and converts the data into pretty-printed XML output. The stream interface should be able to handle large output efficiently, if you use a buffered writer.

Specified by:

toXML in class Chimera

Parameters:

stream - is a stream opened and ready for writing. This can also be a string stream for efficient output.

indent - is a String of spaces used for pretty printing. The initial amount of spaces should be an empty string. The parameter is used internally for the recursive traversal.

namespace - is the XML schema namespace prefix. If neither empty nor null, each element will be prefixed with this prefix, and the root element will map the XML namespace.

Throws:

IOException - if something fishy happens to the stream.

See Also:

BufferedWriter