org.griphyn.vdl.classes
Class Derivation

java.lang.Object
  org.griphyn.vdl.Chimera
      org.griphyn.vdl.classes.VDL
          org.griphyn.vdl.classes.Definition
              org.griphyn.vdl.classes.Derivation

All Implemented Interfaces:

Serializable, Comparable, HasPass

public class Derivation
extends Definition
implements HasPass, Serializable

Derivation is an implementation of an abstract VDL Definition. A derivation describes the mutable part concerning input, processing, and output (IPO) when calling an application. The environment is part of the capture. A derivation parametrizes the template provided by a Transformation with actual values. Think of a derivation as something akin to a C function call. The derivation provides the actual parameter to a job. The immutable parts are hidden in a Transformation.

Version:

$Revision: 50 $

Author:

Jens-S. V??ckler, Yong Zhao

See Also:

Definition, Definitions, Transformation, Serialized Form

Field Summary

private String	m_maxIncludeVersion Any Transformation may exist in multiple versions.
private String	m_minIncludeVersion Any Transformation may exist in multiple versions.
private TreeMap	m_passMap Actual arguments used when calling a Transformation are matched up with the formal arguments of the transformation by their names.
private String	m_uses Though most Derivations may have a name of their own, most of the times, though, derivations are anonymous.
private String	m_usesspace The namespace in which a derivation resides can differ from the namespace that the transformation lives in.

Fields inherited from class org.griphyn.vdl.classes.Definition

DERIVATION, TRANSFORMATION

Constructor Summary

Derivation()
ctor.

Derivation(String name, String uses)
Convenience ctor: Names a derivation and the used Transformation

Derivation(String name, String uses, Pass firstChild)
Convenience ctor: Names the derivation and supplies the used Transformation, and the first actual argument.

Derivation(String name, String uses, String min, String max)
Convenience ctor: Names a derivation and supplies the used Transformation as well as the permissable version range.

Derivation(String ns, String name, String version, String us, String uses, String min, String max)
Complete ctor: Constructs the full three part Derivation identifier, and four part Transformation mapper.

Method Summary

void	addPass(Pass vPass) Accessor: Adds an actual argument to the bag of arguments.
boolean	containsLFN(String filename, int linkage) Determines if the list contains an LFN of the specified linkage.
Enumeration	enumeratePass() Deprecated. Use the new Collection based interfaces
List	getLFNList(int linkage) Determines all LFN instances from the actual arguments of a given derivation that match the specified linkage.
String	getMaxIncludeVersion() Accessor: Obtains the maximum inclusive version permissable for binding to a Transformation.
String	getMinIncludeVersion() Accessor: Obtains the minimum inclusive version permissable for binding to a Transformation.
Pass[]	getPass() Deprecated. Use the new Collection based interfaces
Pass	getPass(String name) Accessor: Obtains an actual argument identified by the bound variable.
int	getPassCount() Accessor: Counts the number of actual arguments.
List	getPassList() Accessor: Gets an array of all values that constitute the current content.
Map	getPassMap() Accessor: Obtains all actual arguments.
int	getType() Type accessor for quick distinction between definitions.
String	getUses() Accessor: Obtains the name of the logical Transformation that this derivation refers to.
String	getUsesspace() Accessor: Obtains the namespace of the logical Transformation that this derivation refers to.
String	identify() Constructs dynamically a short descriptive, hopefully unique identifier for this derivation.
Iterator	iteratePass() Accessor: Provides an iterator for the bag of actual arguments.
boolean	match(String version) Instance method for matching an external version against the inclusive version range.
static boolean	match(String version, String minInc, String maxInc) Matches an external version string against the internal range.
void	removeAllPass() Accessor: Removes all actual arguments.
Pass	removePass(String name) Accessor: Removes a specific actual argument.
void	setMaxIncludeVersion(String miv) Accessor: Sets the maximum inclusive permissable version of a logical transformation to run with.
void	setMinIncludeVersion(String miv) Accessor: Sets the minimum inclusive permissable version of a logical transformation to run with.
void	setPass(Collection passes) Accessor: Replaces the bag of actual argument with a bag of new arguments.
void	setPass(Map passes) Accessor: Replaces the bag of actual argument with a map of new arguments.
void	setPass(Pass vPass) Accessor: Adds a new or overwrites an existing actual argument.
void	setPass(Pass[] passArray) Deprecated. Use the new Collection based interfaces
void	setUses(String uses) Accessor: Sets a new name for a logical Transformation to call.
void	setUsesspace(String usesspace) Accessor: Sets a new namespace identifier for a logical Transformation to call.
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.

Methods inherited from class org.griphyn.vdl.classes.Definition

compareTo, equals, getDescription, getKeyword, getName, getNamespace, getTitle, getUrl, getVersion, hashCode, match, setDescription, setKeyword, setName, setNamespace, setTitle, setUrl, setVersion, shortID, shortID, toXML, toXML

Methods inherited from class org.griphyn.vdl.Chimera

escape, quote, toString, toXML, toXML, writeAttribute

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.griphyn.vdl.classes.HasPass

shortID

Field Detail

m_uses

private String m_uses

Though most Derivations may have a name of their own, most of the times, though, derivations are anonymous. A derivation must provide the name of the Transformation that it calls, though.

See Also:

Definition, Transformation

m_usesspace

private String m_usesspace

The namespace in which a derivation resides can differ from the namespace that the transformation lives in. This argument provides the namespace of the Transformation to call.

See Also:

Definition, Transformation

m_maxIncludeVersion

private String m_maxIncludeVersion

Any Transformation may exist in multiple versions. This argument specifies the minimum permissable version that can be used. FIXME: versioning is not really supported.

m_minIncludeVersion

private String m_minIncludeVersion

Any Transformation may exist in multiple versions. This argument specifies the maximum permissable version that can be used. FIXME: versioning is not really supported.

m_passMap

private TreeMap m_passMap

Actual arguments used when calling a Transformation are matched up with the formal arguments of the transformation by their names.

Constructor Detail

Derivation

public Derivation()

ctor.

Derivation

public Derivation(String name,
                  String uses)

Convenience ctor: Names a derivation and the used Transformation

Parameters:

name - is the name of the Derivation

uses - is the name of the Transformation

See Also:

Transformation

Derivation

public Derivation(String name,
                  String uses,
                  String min,
                  String max)

Convenience ctor: Names a derivation and supplies the used Transformation as well as the permissable version range.

Parameters:

name - is the name of the Derivation.

uses - is the name of the Transformation.

min - is the minimum inclusive permissable version.

max - is the maximum inclusive permissable version.

See Also:

Transformation

Derivation

public Derivation(String ns,
                  String name,
                  String version,
                  String us,
                  String uses,
                  String min,
                  String max)

Complete ctor: Constructs the full three part Derivation identifier, and four part Transformation mapper.

Parameters:

ns - is then namespace of the Derivation.

name - is the name of the Derivation.

version - is the version of the Derivation.

us - is the namespace to search for a Transformation.

uses - is the name of the Transformation.

min - is the minimum inclusive permissable version.

max - is the maximum inclusive permissable version.

See Also:

Transformation

Derivation

public Derivation(String name,
                  String uses,
                  Pass firstChild)

Convenience ctor: Names the derivation and supplies the used Transformation, and the first actual argument.

Parameters:

name - is the name of the Derivation.

uses - is the name of the Transformation.

firstChild - is a first (possibly only) actual argument.

See Also:

Transformation, Pass

Method Detail

getType

public int getType()

Type accessor for quick distinction between definitions.

Specified by:

getType in class Definition

Returns:

the value of Definition.DERIVATION

addPass

public void addPass(Pass vPass)

Accessor: Adds an actual argument to the bag of arguments.

Specified by:

addPass in interface HasPass

Parameters:

vPass - is the new actual argument to add.

See Also:

Pass

enumeratePass

public Enumeration enumeratePass()

Deprecated. Use the new Collection based interfaces

Accessor: Provides an iterator for the bag of actual arguments.

Specified by:

enumeratePass in interface HasPass

Returns:

the iterator for Pass elements.

See Also:

Pass, Enumeration

getLFNList

public List getLFNList(int linkage)

Determines all LFN instances from the actual arguments of a given derivation that match the specified linkage. This is a higher-level method employing the given interface. Note that also linkage of NONE will not be found in wildcard search mode.

Specified by:

getLFNList in interface HasPass

Parameters:

linkage - is the linkage type to match against, -1 for all files.

Returns:

a list of logical filenames from the given derivation which match the given linkage. For a linkage of -1, complete LFNs will be returned, for any other linkage, just the filename will be returned.

See Also:

Value.getLFNList( int ), LFN

containsLFN

public boolean containsLFN(String filename,
                           int linkage)

Determines if the list contains an LFN of the specified linkage. The logic uses short-circuit evaluation, thus finding things is faster than not finding things. Searching a list is a potentially expensive method.

Specified by:

containsLFN in interface HasPass

Parameters:

filename - is the name of the LFN

linkage - is the linkage to check for, -1 for any linkage type.

Returns:

true if the LFN is contained in the scalar, false otherwise.

See Also:

Value.containsLFN( String, int ), LFN

getMaxIncludeVersion

public String getMaxIncludeVersion()

Accessor: Obtains the maximum inclusive version permissable for binding to a Transformation.

Specified by:

getMaxIncludeVersion in interface HasPass

Returns:

the maximum inclusive version number.

See Also:

setMaxIncludeVersion( java.lang.String )

getMinIncludeVersion

public String getMinIncludeVersion()

Accessor: Obtains the minimum inclusive version permissable for binding to a Transformation.

Specified by:

getMinIncludeVersion in interface HasPass

Returns:

the minimum inclusive version number.

See Also:

setMinIncludeVersion( java.lang.String )

getPass

public Pass getPass(String name)

Accessor: Obtains an actual argument identified by the bound variable.

Specified by:

getPass in interface HasPass

Parameters:

name - is the binding name.

Returns:

the bound value to the given name.

See Also:

Pass

getPass

public Pass[] getPass()

Deprecated. Use the new Collection based interfaces

Accessor: Obtains the bag of actual arguments as array. Note that the order is arbitrary.

Specified by:

getPass in interface HasPass

Returns:

an array containing all bound variables.

See Also:

Pass

getPassCount

public int getPassCount()

Accessor: Counts the number of actual arguments.

Specified by:

getPassCount in interface HasPass

Returns:

the number of actual arguments in the internal bag.

getPassList

public List getPassList()

Accessor: Gets an array of all values that constitute the current content. This list is read-only.

Returns:

an array with Pass elements.

See Also:

Pass

getPassMap

public Map getPassMap()

Accessor: Obtains all actual arguments. The map is a read-only map to avoid modifications outside the API.

Returns:

a map will all actual arguments.

See Also:

Pass

getUses

public String getUses()

Accessor: Obtains the name of the logical Transformation that this derivation refers to.

Specified by:

getUses in interface HasPass

See Also:

setUses( java.lang.String )

getUsesspace

public String getUsesspace()

Accessor: Obtains the namespace of the logical Transformation that this derivation refers to.

Specified by:

getUsesspace in interface HasPass

See Also:

setUsesspace( java.lang.String )

iteratePass

public Iterator iteratePass()

Accessor: Provides an iterator for the bag of actual arguments.

Returns:

an iterator to walk the Pass list with.

See Also:

Pass

match

public static boolean match(String version,
                            String minInc,
                            String maxInc)

Matches an external version string against the internal range. This predicate function uses inclusive matches. Special interpretation will be applied to null values, internally as well as an external null value.

   vers.   min    max     result
   -----   ----   -----   ------
   null    null   null    true
   null    *      null    true
   null    null   *       true
   null    *      *       true

   *       null   null    true

   "A"     "B"    null    false
   "B"     "B"    null    true
   "C"     "B"    null    true
   "A"     null   "B"     true
   "B"     null   "B"     true
   "C"     null   "B"     false
   "A"     "B"    "B"     false 
   "B"     "B"    "B"     true
   "C"     "B"    "B"     false 
 

Parameters:

version - is an externally supplied version to be checked, if it is within the inclusive interval of min and max.

minInc - is the minimum inclusive version of the range.

maxInc - is the maximum inclusive version of the range.

Returns:

true, if the version is in range, false otherwise.

match

public boolean match(String version)

Instance method for matching an external version against the inclusive version range.

Parameters:

version - is an externally supplied version to be checked, if it is within the inclusive interval of min and max.

Returns:

true, if the version is in range, false otherwise.

See Also:

match( String, String, String )

removeAllPass

public void removeAllPass()

Accessor: Removes all actual arguments. Effectively empties the bag.

Specified by:

removeAllPass in interface HasPass

removePass

public Pass removePass(String name)

Accessor: Removes a specific actual argument.

Specified by:

removePass in interface HasPass

Parameters:

name - is the bound variable name of the argument to remove.

Returns:

the object that was removed, or null, if not found.

See Also:

Pass

setMaxIncludeVersion

public void setMaxIncludeVersion(String miv)

Accessor: Sets the maximum inclusive permissable version of a logical transformation to run with.

Parameters:

miv - is the (new) maximum inclusive version.

See Also:

getMaxIncludeVersion()

setMinIncludeVersion

public void setMinIncludeVersion(String miv)

Accessor: Sets the minimum inclusive permissable version of a logical transformation to run with.

Parameters:

miv - is the (new) minimum inclusive version.

See Also:

getMinIncludeVersion()

setPass

public void setPass(Pass vPass)

Accessor: Adds a new or overwrites an existing actual argument.

Specified by:

setPass in interface HasPass

Parameters:

vPass - is a new actual argument with bound name and value.

See Also:

Pass

setPass

public void setPass(Pass[] passArray)

Deprecated. Use the new Collection based interfaces

Accessor: Replaces the bag of actual argument with new arguments.

Specified by:

setPass in interface HasPass

Parameters:

passArray - is the new actual argument list.

See Also:

Pass

setPass

public void setPass(Collection passes)

Accessor: Replaces the bag of actual argument with a bag of new arguments.

Parameters:

passes - is the new actual argument collection.

See Also:

Pass

setPass

public void setPass(Map passes)

Accessor: Replaces the bag of actual argument with a map of new arguments.

Parameters:

passes - is the new actual argument map.

See Also:

Pass

setUses

public void setUses(String uses)

Accessor: Sets a new name for a logical Transformation to call.

Parameters:

uses - is the new name of the Transformation to use.

See Also:

getUses(), Transformation

setUsesspace

public void setUsesspace(String usesspace)

Accessor: Sets a new namespace identifier for a logical Transformation to call.

Parameters:

usesspace - is the new namespace of the Transformation.

See Also:

getUsesspace(), Transformation

identify

public String identify()

Constructs dynamically a short descriptive, hopefully unique identifier for this derivation. Recent modification add the complete identification in terms of derivation name, namespace, and version as well as the called transformation name, namespace and version range. FIXME: Anonymous derivations get their hash code, which is well for the first versions working without database. Later versions with database must use some unique sequence mechanism instead.

Specified by:

identify in interface HasPass

Specified by:

identify in class Definition

Returns:

a string describing the derivation

See Also:

Object.hashCode()

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. Note that order of the actual arguments is not preserved.

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.

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. If a null value is specified, no indentation nor linefeeds will be generated.

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:

Chimera.writeAttribute( Writer, String, String )