org.griphyn.vdl.classes
Class Call

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

All Implemented Interfaces:

Serializable, HasPass

public class Call
extends VDL
implements HasPass, Serializable

Call is an implementation of an anonymous Derivation. A call describes the mutable part concerning input, processing, and output (IPO). Calls can only be part of a CompoundTransformation.

A call parametrizes the template provided by a Transformation with actual values. Think of a call as something akin to a C function call. The call provides the actual parameter to a job. The immutable parts are hidden in a Transformation.

FIXME: A Call is essentially an anonymous Derivation that occurs within a CompoundTransformation. Thus, the first two should share code. Also, the latter two already share code. Therefore, the class hierarchies need to be re-designed, and attribute groups should be out-sourced.

Version:

$Revision $

Author:

Jens-S. V??ckler, Yong Zhao

See Also:

Definition, Definitions, Transformation, Derivation, Serialized Form

Field Summary

private String	m_id This is the sequence number assigned by the c'tor to this call.
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 Calls may have a name of their own, most of the times, though, calls are anonymous.
private String	m_usesspace The namespace in which a call resides can differ from the namespace that the transformation lives in.
private static SequenceGenerator	s_sequence Since Call is an anonymous Derivation, we still need some unique identifiers for the call.

Constructor Summary

Call()
ctor.

Call(String uses)
Convenience ctor: Names the used Transformation

Call(String uses, String min, String max)
Convenience ctor: Supplies the used Transformation as well as the permissable version range.

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 of a given scalar 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.
String	getUses() Accessor: Obtains the name of the logical Transformation that this call refers to.
String	getUsesspace() Accessor: Obtains the namespace of the logical Transformation that this call refers to.
String	identify() Since calls are anonymous derivations, this function can only construct the mapped transformation
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.
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.
String	shortID() Generates a pseudo id for this 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.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

m_uses

private String m_uses

Though most Calls may have a name of their own, most of the times, though, calls are anonymous. A call 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 call 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.

s_sequence

private static SequenceGenerator s_sequence

Since Call is an anonymous Derivation, we still need some unique identifiers for the call. This is a sequence generator.

m_id

private String m_id

This is the sequence number assigned by the c'tor to this call.

Constructor Detail

Call

public Call()

ctor.

Call

public Call(String uses)

Convenience ctor: Names the used Transformation

Parameters:

uses - is the name of the Transformation

See Also:

Transformation

Call

public Call(String uses,
            String min,
            String max)

Convenience ctor: Supplies the used Transformation as well as the permissable version range.

Parameters:

uses - is the name of the Transformation.

min - is the minimum inclusive permissable version.

max - is the maximum inclusive permissable version.

See Also:

Transformation

Method Detail

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 of a given scalar that match the specified linkage. This is a higher-level method employing the given API. 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 to check for, -1 for any linkage.

Returns:

a set of all logical filenames that match the linkage and were part of the scalar. The result may be an empty set, if no such result were to be found. 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

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

getUses

public String getUses()

Accessor: Obtains the name of the logical Transformation that this call 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 call refers to.

Specified by:

getUsesspace in interface HasPass

See Also:

setUsesspace( java.lang.String )

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:

Derivation.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

shortID

public String shortID()

Generates a pseudo id for this Call. FIXME: With the advent of a database, we'll need to fix this to something like the primary key.

Specified by:

shortID in interface HasPass

Returns:

a string describing the derivation

See Also:

Object.hashCode()

identify

public String identify()

Since calls are anonymous derivations, this function can only construct the mapped transformation

Specified by:

identify in interface HasPass

Returns:

a string describing the call

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 )