org.griphyn.vdl.dbschema
Class AnnotationSchema

java.lang.Object
  org.griphyn.vdl.dbschema.DatabaseSchema
      org.griphyn.vdl.dbschema.AnnotationSchema

All Implemented Interfaces:

Advanced, Annotation, Catalog, VDC

public class AnnotationSchema
extends DatabaseSchema
implements Advanced, Annotation

This class provides basic functionalities to interact with the backend database, such as insertion, deletion, and search. While the main database layout for storing definitions is derived from the "chunk" schema with minor improvements, the database layout of the annotations is shown in the following figure:

The central five elements that can receive annotations, all depend on the same sequence generator for their primary key. Their secondary key references the definition in question, or otherwise qualifies the element to annotate. Note that logical filenames can be annotated outside of any definitions.

Grouped along the outer edges, five primary data type tables store annotations efficiently. The distinction into separate data types is necessary to enable efficient searches and appropriate operations. Their primary key is also a foreign key referencing the five central elements.

Version:

$Revision: 50 $

Author:

Jens-S. V??ckler, Yong Zhao

Field Summary

protected static String[]	c_lfn_names Name of the four parameter tables in human readable format.
protected Cache	m_cache A cache for definitions to avoid reloading from the database.
protected boolean	m_deferDeleteCommit Communication between saveDefinition and deleteDefinition in update mode.
private VDLxParser	m_parser An instance of the VDLx XML parser.

Fields inherited from class org.griphyn.vdl.dbschema.DatabaseSchema

m_dbdriver, m_dbschemaprops

Fields inherited from interface org.griphyn.vdl.dbschema.VDC

PROPERTY_PREFIX

Fields inherited from interface org.griphyn.vdl.dbschema.Annotation

CLASS_CALL, CLASS_DECLARE, CLASS_DERIVATION, CLASS_FILENAME, CLASS_TRANSFORMATION

Constructor Summary

AnnotationSchema(String dbDriverName)
Default constructor for the "chunk" schema.

Method Summary

ResultSet	backdoor(String query) A too generic method to search annotation (and anything) in the database.
boolean	containsDefinition(Definition definition) Search the database for the existence of a definition.
boolean	deleteAnnotation(String primary, Object secondary, int kind, String key) Deletes an annotation with the specified key.
boolean	deleteAnnotationCall(String fqdi, int index, String key) Deletes a specific key for a call statement.
boolean	deleteAnnotationDeclare(String fqdi, String farg, String key) Deletes a specific key in an annotated formal argument.
boolean	deleteAnnotationDerivation(String fqdi, String key) Deletes a specific key in an annotated derivation.
boolean	deleteAnnotationFilename(String filename, String key) Deletes a specific key in an annotated filename.
private List	deleteAnnotationFromDefinition(long id) Deletes the joined annotations when a definition is being deleted.
private boolean	deleteAnnotationKey(long id, int kind) Deletes an annotation in a type table with the specified annotation id.
boolean	deleteAnnotationTransformation(String fqdi, String key) Deletes a specific key in an annotated transformation.
private boolean	deleteAnnotationValue(long id) Deletes an annotation value with the specified annotation id.
private boolean	deleteAnnotationValue(long id, Tuple annotation) Deletes an annotation in a type table with the specified annotation id.
boolean	deleteDefinition(Definition definition) Delete a specific Definition objects from the database.
List	deleteDefinition(String namespace, String name, String version, int type) Delete Definition objects from the database.
List	deleteDefinitionEx(String namespace, String name, String version, int type) Delete one or more definitions from the backend database.
private int	deleteLFNsForDefinitionId(long did) Deletes all logical filenames that are associated with a particular definition.
private long	getAnnotationIdCall(long did, int pos, String key) Retrieves the annotation id of a given call within a transformation.
private long	getAnnotationIdDeclare(long did, String farg, String key) Retrieves the annotation id of a given transformation formal argument.
private long	getAnnotationIdDerivation(long did, String key) Retrieves the annotation id of a given derivation id.
private long	getAnnotationIdFilename(String lfn, String key) Retrieves the annotation id of a given logical filename.
private long	getAnnotationIdTransformation(long did, String key) Retrieves the annotation id of a given transformation.
protected Long	getDefinitionId(Definition d) Obtains the primary key id for a given definition.
protected List	getDefinitionId(String namespace, String name, String version, int type) Obtains the list of primary key ids for a matching definitions.
protected List	getDefinitionIdEx(String namespace, String name, String version, int type) Obtains the list of primary key ids for a matching definitions.
List	getFQDNList(int type) Searches the database for a list of fully-qualified names of the definitions sorted in ascending order.
List	getNamespaceList(int type) Searches the database for a list of namespaces of the definitions Sorted in ascending order.
protected Long	getSpecificDefinitionId(String namespace, String name, String version, int type) Obtains the primary key id for a given definition.
List	loadAnnotation(String primary, Object secondary, int kind) Retrieves all annotations from an annotatable classes with the specified tuple.
Tuple	loadAnnotation(String primary, Object secondary, int kind, String key) Retrieves a specific annotation from an annotatable classes with the specified tuple.
private TupleBoolean	loadAnnotationBoolean(long id, String key) Obtains the value at a specific id from the boolean annotations.
List	loadAnnotationCall(String fqdi, int index) Lists all annotations for a call statement.
Tuple	loadAnnotationCall(String fqdi, int index, String key) Obtains the value to a specific key for a call statement.
private TupleDate	loadAnnotationDate(long id, String key) Obtains the value at a specific id from the date annotations.
List	loadAnnotationDeclare(String fqdi, String farg) Lists all annotations for a formal argument.
Tuple	loadAnnotationDeclare(String fqdi, String farg, String key) Obtains the value to a specific key in an annotated formal argument.
List	loadAnnotationDerivation(String fqdi) Lists all annotations for a derivation.
Tuple	loadAnnotationDerivation(String fqdi, String key) Obtains the value to a specific key in an annotated derivation.
List	loadAnnotationFilename(String filename) Lists all annotations for a logical filename.
Tuple	loadAnnotationFilename(String filename, String key) Obtains the value to a specific key in an annotated filename.
private Tuple	loadAnnotationFinal(long id, String key) Tries to retrieve a tuple value from its annotation id by walking over all tables, most likely one first.
private TupleFloat	loadAnnotationFloat(long id, String key) Obtains the value at a specific id from the float annotations.
private TupleInteger	loadAnnotationInteger(long id, String key) Obtains the value at a specific id from the integer annotations.
private TupleString	loadAnnotationString(long id, String key) Obtains the value at a specific id from the string annotations.
List	loadAnnotationTransformation(String fqdi) Lists all annotations for a transformation.
Tuple	loadAnnotationTransformation(String fqdi, String key) Obtains the value to a specific key in an annotated transformation.
private Definition	loadDefinition(long id) Load a single Definition from the backend database into a Java object by its primary key id.
Definition	loadDefinition(String namespace, String name, String version, int type) Loads a single Definition from the backend database into an Java object.
private VDLxParser	parserInstance() Instantiates an XML parser for VDLx on demand.
long	saveAnnotation(String primary, Object secondary, int kind, Tuple annotation, boolean overwrite) Annotates any of the annotatable classes with the specified tuple.
long	saveAnnotationCall(String fqdi, int index, Tuple annotation, boolean overwrite) Annotates a transformation call with a tuple.
long	saveAnnotationDeclare(String fqdi, String formalname, Tuple annotation, boolean overwrite) Annotates a transformation argument with a tuple.
long	saveAnnotationDerivation(String fqdi, Tuple annotation, boolean overwrite) Annotates a derivation with a tuple.
long	saveAnnotationFilename(String filename, Tuple annotation, boolean overwrite) Annotates a logical filename with a tuple.
long	saveAnnotationTransformation(String fqdi, Tuple annotation, boolean overwrite) Annotates a transformation with a tuple.
private boolean	saveAnnotationValue(long id, Tuple annotation) Inserts a tuple into the correct type-table for annotations.
boolean	saveDefinition(Definition definition, boolean overwrite) Saves a Definition, that is either a Transformation or Derivation, into the backend database.
private void	saveScalar(long id, Scalar scalar, Set already, PreparedStatement[] stmt, int[] count) Saves all logical filenames from a Scalar object.
List	searchAnnotation(int kind, Object arg, QueryTree tree) Search for LFNs or Definitions that has certain annotations
ResultSet	searchAnnotation(List select, String table, Map where, String order) A not very generic method to search annotation (and anything) in the database.
List	searchDefinition(String namespace, String name, String version, int type) Search the database for definitions by ns::name:version triple and by type (either Transformation or Derivation).
List	searchDefinitionEx(String namespace, String name, String version, int type) Search the database for definitions by ns::name:version triple and by type (either Transformation or Derivation).
List	searchFilename(String lfn, int link) Searches the database for all derivations that contain a certain LFN.
List	searchLFN(String lfn, int link) Searches the database for all LFNs that match a certain pattern.
private String	what(Definition d) Compiles the name of a DV/TR for log messages.

Methods inherited from class org.griphyn.vdl.dbschema.DatabaseSchema

cachingMakesSense, close, finalize, loadSchema, loadSchema, longOrNull, makeNotNull, stringOrNull

Methods inherited from class java.lang.Object

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

Field Detail

c_lfn_names

protected static final String[] c_lfn_names

Name of the four parameter tables in human readable format.

m_deferDeleteCommit

protected boolean m_deferDeleteCommit

Communication between saveDefinition and deleteDefinition in update mode.

m_parser

private VDLxParser m_parser

An instance of the VDLx XML parser.

m_cache

protected Cache m_cache

A cache for definitions to avoid reloading from the database.

Constructor Detail

AnnotationSchema

public AnnotationSchema(String dbDriverName)
                 throws ClassNotFoundException,
                        NoSuchMethodException,
                        InstantiationException,
                        IllegalAccessException,
                        InvocationTargetException,
                        SQLException,
                        IOException

Default constructor for the "chunk" schema.

Parameters:

dbDriverName - is the database driver name

Throws:

ClassNotFoundException

NoSuchMethodException

InstantiationException

IllegalAccessException

InvocationTargetException

SQLException

IOException

Method Detail

parserInstance

private VDLxParser parserInstance()

Instantiates an XML parser for VDLx on demand. Since XML parsing and parser instantiation is an expensive business, the reader will only be generated on demand, and only once.

Returns:

a valid VDLx parser instance.

loadDefinition

public Definition loadDefinition(String namespace,
                                 String name,
                                 String version,
                                 int type)
                          throws SQLException

Loads a single Definition from the backend database into an Java object. This method does not allow wildcarding!

Specified by:

loadDefinition in interface VDC

Parameters:

namespace - namespace, null will be converted into empty string

name - name, null will be converted into empty string

version - version, null will be converted into empty string

type - type of the definition (TR or DV), must not be -1.

Returns:

the Definition as specified, or null if not found.

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION, saveDefinition( Definition, boolean )

loadDefinition

private Definition loadDefinition(long id)
                           throws SQLException

Load a single Definition from the backend database into a Java object by its primary key id. This is an internal helper function.

Parameters:

id - is a long which represent the primary id.

Returns:

the Definitions that was matched by the id.

Throws:

SQLException

See Also:

loadDefinition( String, String, String, int ), saveDefinition( Definition, boolean )

what

private String what(Definition d)

Compiles the name of a DV/TR for log messages.

Parameters:

d - is a definition

Returns:

the type plus FQDN of the definition

saveDefinition

public boolean saveDefinition(Definition definition,
                              boolean overwrite)
                       throws SQLException

Saves a Definition, that is either a Transformation or Derivation, into the backend database. This method, of course, does not allow wildcarding. The definition has to be completely specified and valid.

Please note that updating a definition will remove all the meta- data that was defined for the definition.

Specified by:

saveDefinition in interface VDC

Parameters:

definition - is the new Definition to store.

overwrite - true, if existing defitions will be overwritten by new ones with the same primary (or secondary) key (-set), or false, if a new definition will be rejected on key matches.

Returns:

true, if the backend database was changed, or false, if the definition was not accepted into the backend.

Throws:

SQLException

See Also:

Definition, Transformation, Derivation, loadDefinition( String, String, String, int )

saveScalar

private void saveScalar(long id,
                        Scalar scalar,
                        Set already,
                        PreparedStatement[] stmt,
                        int[] count)
                 throws SQLException

Saves all logical filenames from a Scalar object. This is a helper function to save a single definition.

Parameters:

id - is the definition id in the DEFINITION table

scalar - is a Scalar instance of which the LFNs are to be saved.

already - is a set of filenames that were already added during this session

stmt - is an array of the ids of the prepared statements for the different tables.

count - count the number of entries in a prepared statement.

Throws:

SQLException

See Also:

saveDefinition( Definition, boolean )

getSpecificDefinitionId

protected Long getSpecificDefinitionId(String namespace,
                                       String name,
                                       String version,
                                       int type)
                                throws SQLException

Obtains the primary key id for a given definition. "Fake" definitions are NOT permissable. This is an internal helper function.

Parameters:

namespace - is the specific namespace, null will be mapped to ""

name - is the specific name, null will be mapped to ""

version - is the specific version, null will be mapped to ""

type - is the type identifier, -1 is not allowed.

Returns:

the id of the definition, or null if not found.

Throws:

SQLException

See Also:

getDefinitionId( String, String, String, int )

getDefinitionId

protected Long getDefinitionId(Definition d)
                        throws SQLException

Obtains the primary key id for a given definition. "Fake" definitions are permissable. This is an internal helper function.

Parameters:

d - is a definition specification.

Returns:

the id of the definition, or null if not found.

Throws:

SQLException

See Also:

getSpecificDefinitionId( String, String, String, int ), getDefinitionId( String, String, String, int )

getDefinitionId

protected List getDefinitionId(String namespace,
                               String name,
                               String version,
                               int type)
                        throws SQLException

Obtains the list of primary key ids for a matching definitions. This method allows for wildcards in the usual fashion. Use null for strings as wildcards, and -1 for the type wildcard. This method may return an empty list, but it will not return null. This is an internal helper function.

Parameters:

namespace - namespace, null to match any namespace

name - name, null to match any name

version - version, null to match any version

type - definition type (TR or DV)

Returns:

a possibly empty list containing all matching definition ids as Longs.

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION, getDefinitionId( Definition )

getDefinitionIdEx

protected List getDefinitionIdEx(String namespace,
                                 String name,
                                 String version,
                                 int type)
                          throws SQLException

Obtains the list of primary key ids for a matching definitions. This method allows for wildcards in the usual fashion. Use null for strings as wildcards, and -1 for the type wildcard. It also allows special characters '%' and '_' in strings. This method may return an empty list, but it will not return null. This is an internal helper function.

Parameters:

namespace - namespace, null to match any namespace

name - name, null to match any name

version - version, null to match any version

type - definition type (TR or DV)

Returns:

a possibly empty list containing all matching definition ids as Longs.

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION, getDefinitionId( Definition )

containsDefinition

public boolean containsDefinition(Definition definition)
                           throws SQLException

Search the database for the existence of a definition.

Specified by:

containsDefinition in interface VDC

Parameters:

definition - the definition object to search for

Returns:

true, if the definition exists, false if not found

Throws:

SQLException

deleteAnnotationFromDefinition

private List deleteAnnotationFromDefinition(long id)
                                     throws SQLException

Deletes the joined annotations when a definition is being deleted.

Parameters:

id - is the definition id to remove

Returns:

list of all annotation ids that were removed

Throws:

SQLException

deleteLFNsForDefinitionId

private int deleteLFNsForDefinitionId(long did)
                               throws SQLException

Deletes all logical filenames that are associated with a particular definition. Note that this method does not commit the changes, as it is supposed to be called from other methods.

Parameters:

did - is the definition id to remove LFNs for

Returns:

number of rows affected, may be zero.

Throws:

SQLException

deleteDefinition

public boolean deleteDefinition(Definition definition)
                         throws SQLException

Delete a specific Definition objects from the database. No wildcard matching will be done. "Fake" definitions are permissable, meaning it just has the secondary key triple.

Specified by:

deleteDefinition in interface VDC

Parameters:

definition - is the definition specification to delete

Returns:

true is something was deleted, false if non existent.

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION

deleteDefinition

public List deleteDefinition(String namespace,
                             String name,
                             String version,
                             int type)
                      throws SQLException

Delete Definition objects from the database. This method allows for wildcards in the usual fashion. Use null for strings as wildcards, and -1 for the type wildcard. For efficiency reasons, this method will return an empty list.

Specified by:

deleteDefinition in interface VDC

Parameters:

namespace - namespace, null to match any namespace

name - name, null to match any name

version - version, null to match any version

type - definition type (TR or DV)

Returns:

a list containing all Definitions that were deleted

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION

searchDefinition

public List searchDefinition(String namespace,
                             String name,
                             String version,
                             int type)
                      throws SQLException

Search the database for definitions by ns::name:version triple and by type (either Transformation or Derivation). This version of the search allows for jokers expressed as null value

Specified by:

searchDefinition in interface VDC

Parameters:

namespace - namespace, null to match any namespace

name - name, null to match any name

version - version, null to match any version

type - type of definition (TR/DV, or both)

Returns:

a list of definitions

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION

searchFilename

public List searchFilename(String lfn,
                           int link)
                    throws SQLException

Searches the database for all derivations that contain a certain LFN. The linkage is an additional constraint. This method does not allow jokers.

Specified by:

searchFilename in interface VDC

Parameters:

lfn - the LFN name

link - the linkage type of the LFN

Returns:

a list of Definition items that match the criterion.

Throws:

SQLException

See Also:

LFN.NONE, LFN.INPUT, LFN.OUTPUT, LFN.INOUT

getAnnotationIdTransformation

private long getAnnotationIdTransformation(long did,
                                           String key)
                                    throws SQLException

Retrieves the annotation id of a given transformation.

Parameters:

did - is the definition id of the transformation

key - is the key to search for.

Returns:

-1 if not found, or the correction annotation id.

Throws:

SQLException - if some database operation fails.

getAnnotationIdDerivation

private long getAnnotationIdDerivation(long did,
                                       String key)
                                throws SQLException

Retrieves the annotation id of a given derivation id.

Parameters:

did - is the definition id of the derivation

key - is the key to search for.

Returns:

-1 if not found, or the correction annotation id.

Throws:

SQLException - if some database operation fails.

getAnnotationIdDeclare

private long getAnnotationIdDeclare(long did,
                                    String farg,
                                    String key)
                             throws SQLException

Retrieves the annotation id of a given transformation formal argument.

Parameters:

did - is the definition id of the transformation

farg - is the formal argument name

key - is the key to search for.

Returns:

-1 if not found, or the correction annotation id.

Throws:

SQLException - if some database operation fails.

getAnnotationIdCall

private long getAnnotationIdCall(long did,
                                 int pos,
                                 String key)
                          throws SQLException

Retrieves the annotation id of a given call within a transformation.

Parameters:

did - is the definition id of the transformation

pos - is the position of the call statement

key - is the key to search for.

Returns:

-1 if not found, or the correction annotation id.

Throws:

SQLException - if some database operation fails.

getAnnotationIdFilename

private long getAnnotationIdFilename(String lfn,
                                     String key)
                              throws SQLException

Retrieves the annotation id of a given logical filename.

Parameters:

lfn - is the logical filename.

key - is the key to search for.

Returns:

-1 if not found, or the correction annotation id.

Throws:

SQLException - if some database operation fails.

deleteAnnotation

public boolean deleteAnnotation(String primary,
                                Object secondary,
                                int kind,
                                String key)
                         throws SQLException,
                                IllegalArgumentException

Deletes an annotation with the specified key.

Specified by:

deleteAnnotation in interface Annotation

Parameters:

primary - is the primary object specifier for the class. According to the type, this is either the FQDI, or the filename.

secondary - is a helper argument for annotations to calls and formal arguments, and should be null for all other classes. For calls, the argument must be packed into Integer.

kind - defines the kind/class of object to annotate.

key - is the annotation key.

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException, - if something went wrong during database access.

SQLException

IllegalArgumentException

deleteAnnotationValue

private boolean deleteAnnotationValue(long id)
                               throws SQLException

Deletes an annotation value with the specified annotation id.

Parameters:

id - is the annotation id for which to delete

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException, - if something went wrong during database access.

SQLException

deleteAnnotationKey

private boolean deleteAnnotationKey(long id,
                                    int kind)
                             throws SQLException

Deletes an annotation in a type table with the specified annotation id. The table is determined from the type of the annotational tuple.

Parameters:

id - is the annotation id for which to delete

kind - is the class of object.

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException, - if something went wrong during database access.

SQLException

deleteAnnotationValue

private boolean deleteAnnotationValue(long id,
                                      Tuple annotation)
                               throws SQLException

Deletes an annotation in a type table with the specified annotation id. The table is determined from the type of the annotational tuple.

Parameters:

id - is the annotation id for which to delete

annotation - is the annotation which determines the type

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException, - if something went wrong during database access.

SQLException

deleteAnnotationTransformation

public boolean deleteAnnotationTransformation(String fqdi,
                                              String key)
                                       throws SQLException,
                                              IllegalArgumentException

Deletes a specific key in an annotated transformation.

Specified by:

deleteAnnotationTransformation in interface Annotation

Parameters:

fqdi - is the FQDI of the transformation

key - is the key to search for

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException

IllegalArgumentException

See Also:

Transformation

deleteAnnotationDerivation

public boolean deleteAnnotationDerivation(String fqdi,
                                          String key)
                                   throws SQLException,
                                          IllegalArgumentException

Deletes a specific key in an annotated derivation.

Specified by:

deleteAnnotationDerivation in interface Annotation

Parameters:

fqdi - is the FQDI of the derivation

key - is the key to search for

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException

IllegalArgumentException

See Also:

Derivation

deleteAnnotationDeclare

public boolean deleteAnnotationDeclare(String fqdi,
                                       String farg,
                                       String key)
                                throws SQLException,
                                       IllegalArgumentException

Deletes a specific key in an annotated formal argument.

Specified by:

deleteAnnotationDeclare in interface Annotation

Parameters:

fqdi - is the FQDI of the transformation

farg - is the name of the formal argument

key - is the key to search for

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException

IllegalArgumentException

See Also:

Declare

deleteAnnotationCall

public boolean deleteAnnotationCall(String fqdi,
                                    int index,
                                    String key)
                             throws SQLException,
                                    IllegalArgumentException

Deletes a specific key for a call statement.

Specified by:

deleteAnnotationCall in interface Annotation

Parameters:

fqdi - is the FQDI of the transformation

index - is the number of the call to annotate.

key - is the key to search for

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException

IllegalArgumentException

See Also:

Call

deleteAnnotationFilename

public boolean deleteAnnotationFilename(String filename,
                                        String key)
                                 throws SQLException,
                                        IllegalArgumentException

Deletes a specific key in an annotated filename.

Specified by:

deleteAnnotationFilename in interface Annotation

Parameters:

filename - is the name of the file that was annotated.

key - is the key to search for

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException

IllegalArgumentException

See Also:

LFN

saveAnnotationValue

private boolean saveAnnotationValue(long id,
                                    Tuple annotation)
                             throws SQLException

Inserts a tuple into the correct type-table for annotations.

Parameters:

id - is the annotation id for which to insert.

annotation - is the annotation to insert. Only the type and value will be taken, as the key was inserted elsewhere.

Returns:

true, if the database was modified, false otherwise.

Throws:

SQLException - if something during the database access went awry.

saveAnnotationTransformation

public long saveAnnotationTransformation(String fqdi,
                                         Tuple annotation,
                                         boolean overwrite)
                                  throws SQLException,
                                         IllegalArgumentException

Annotates a transformation with a tuple.

Specified by:

saveAnnotationTransformation in interface Annotation

Parameters:

fqdi - is the FQDI to annotate

annotation - is the value to place

overwrite - is a predicate on replace or maintain.

Returns:

the insertion id, or -1, if the database was untouched

Throws:

SQLException

IllegalArgumentException

See Also:

Transformation

saveAnnotationDerivation

public long saveAnnotationDerivation(String fqdi,
                                     Tuple annotation,
                                     boolean overwrite)
                              throws SQLException,
                                     IllegalArgumentException

Annotates a derivation with a tuple.

Specified by:

saveAnnotationDerivation in interface Annotation

Parameters:

fqdi - is the FQDI to annotate

annotation - is the value to place

overwrite - is a predicate on replace or maintain.

Returns:

the insertion id, or -1, if the database was untouched

Throws:

SQLException

IllegalArgumentException

See Also:

Derivation

saveAnnotationDeclare

public long saveAnnotationDeclare(String fqdi,
                                  String formalname,
                                  Tuple annotation,
                                  boolean overwrite)
                           throws SQLException,
                                  IllegalArgumentException

Annotates a transformation argument with a tuple.

Specified by:

saveAnnotationDeclare in interface Annotation

Parameters:

fqdi - is the FQDI to annotate

formalname - is the name of the formal argument to annotoate.

annotation - is the value to place

overwrite - is a predicate on replace or maintain.

Returns:

the insertion id, or -1, if the database was untouched

Throws:

SQLException

IllegalArgumentException

See Also:

Declare

saveAnnotationCall

public long saveAnnotationCall(String fqdi,
                               int index,
                               Tuple annotation,
                               boolean overwrite)
                        throws SQLException,
                               IllegalArgumentException

Annotates a transformation call with a tuple.

Specified by:

saveAnnotationCall in interface Annotation

Parameters:

fqdi - is the FQDI to annotate

index - is the number of the call to annotate.

annotation - is the value to place

overwrite - is a predicate on replace or maintain.

Returns:

the insertion id, or -1, if the database was untouched

Throws:

SQLException

IllegalArgumentException

See Also:

Call

saveAnnotationFilename

public long saveAnnotationFilename(String filename,
                                   Tuple annotation,
                                   boolean overwrite)
                            throws SQLException,
                                   IllegalArgumentException

Annotates a logical filename with a tuple.

Specified by:

saveAnnotationFilename in interface Annotation

Parameters:

filename - is the FQDI to annotate

annotation - is the value to place

overwrite - is a predicate on replace or maintain.

Returns:

the insertion id, or -1, if the database was untouched

Throws:

SQLException

IllegalArgumentException

See Also:

LFN

saveAnnotation

public long saveAnnotation(String primary,
                           Object secondary,
                           int kind,
                           Tuple annotation,
                           boolean overwrite)
                    throws SQLException,
                           IllegalArgumentException

Annotates any of the annotatable classes with the specified tuple. This is an interface method to the various class-specific methods.

Specified by:

saveAnnotation in interface Annotation

Parameters:

primary - is the primary object specifier for the class. According to the type, this is either the FQDI, or the filename.

secondary - is a helper argument for annotations to calls and formal arguments, and should be null for all other classes. For calls, the argument must be packed into Integer.

kind - defines the kind/class of object to annotate.

annotation - is the value to place into the class.

overwrite - is a predicate on replace or maintain.

Returns:

the insertion id, or -1, if the database was untouched

Throws:

SQLException

IllegalArgumentException

See Also:

saveAnnotationTransformation( String, Tuple, boolean ), saveAnnotationDerivation( String, Tuple, boolean ), saveAnnotationCall( String, int, Tuple, boolean ), saveAnnotationDeclare( String, String, Tuple, boolean ), saveAnnotationFilename( String, Tuple, boolean )

loadAnnotationBoolean

private TupleBoolean loadAnnotationBoolean(long id,
                                           String key)
                                    throws SQLException

Obtains the value at a specific id from the boolean annotations.

Parameters:

id - is the annotation id

key - is used to create the tuple

Returns:

null if not found, or a valid tuple otherwise.

Throws:

SQLException

loadAnnotationInteger

private TupleInteger loadAnnotationInteger(long id,
                                           String key)
                                    throws SQLException

Obtains the value at a specific id from the integer annotations.

Parameters:

id - is the annotation id

key - is used to create the tuple

Returns:

null if not found, or a valid tuple otherwise.

Throws:

SQLException

loadAnnotationFloat

private TupleFloat loadAnnotationFloat(long id,
                                       String key)
                                throws SQLException

Obtains the value at a specific id from the float annotations.

Parameters:

id - is the annotation id

key - is used to create the tuple

Returns:

null if not found, or a valid tuple otherwise.

Throws:

SQLException

loadAnnotationDate

private TupleDate loadAnnotationDate(long id,
                                     String key)
                              throws SQLException

Obtains the value at a specific id from the date annotations.

Parameters:

id - is the annotation id

key - is used to create the tuple

Returns:

null if not found, or a valid tuple otherwise.

Throws:

SQLException

loadAnnotationString

private TupleString loadAnnotationString(long id,
                                         String key)
                                  throws SQLException

Obtains the value at a specific id from the string annotations.

Parameters:

id - is the annotation id

key - is used to create the tuple

Returns:

null if not found, or a valid tuple otherwise.

Throws:

SQLException

loadAnnotationFinal

private Tuple loadAnnotationFinal(long id,
                                  String key)
                           throws SQLException

Tries to retrieve a tuple value from its annotation id by walking over all tables, most likely one first. This is an internal function helping to keep common code common.

Parameters:

id - is the annotation id to search for

key - is the key for tuple creation.

Returns:

null, if the id was -1 (no such id), or if nothing was found.

Throws:

SQLException

loadAnnotationTransformation

public Tuple loadAnnotationTransformation(String fqdi,
                                          String key)
                                   throws SQLException,
                                          IllegalArgumentException

Obtains the value to a specific key in an annotated transformation.

Specified by:

loadAnnotationTransformation in interface Annotation

Parameters:

fqdi - is the FQDI of the transformation

key - is the key to search for

Returns:

the annotated value, or null if not found.

Throws:

SQLException

IllegalArgumentException

See Also:

Transformation

loadAnnotationDerivation

public Tuple loadAnnotationDerivation(String fqdi,
                                      String key)
                               throws SQLException,
                                      IllegalArgumentException

Obtains the value to a specific key in an annotated derivation.

Specified by:

loadAnnotationDerivation in interface Annotation

Parameters:

fqdi - is the FQDI of the derivation

key - is the key to search for

Returns:

the annotated value, or null if not found.

Throws:

SQLException

IllegalArgumentException

See Also:

Derivation

loadAnnotationDeclare

public Tuple loadAnnotationDeclare(String fqdi,
                                   String farg,
                                   String key)
                            throws SQLException,
                                   IllegalArgumentException

Obtains the value to a specific key in an annotated formal argument.

Specified by:

loadAnnotationDeclare in interface Annotation

Parameters:

fqdi - is the FQDI of the transformation

farg - is the name of the formal argument

key - is the key to search for

Returns:

the annotated value, or null if not found

Throws:

SQLException

IllegalArgumentException

See Also:

Declare

loadAnnotationCall

public Tuple loadAnnotationCall(String fqdi,
                                int index,
                                String key)
                         throws SQLException,
                                IllegalArgumentException

Obtains the value to a specific key for a call statement.

Specified by:

loadAnnotationCall in interface Annotation

Parameters:

fqdi - is the FQDI of the transformation

index - is the number of the call to annotate.

key - is the key to search for

Returns:

the annotated value, or null if not found

Throws:

SQLException

IllegalArgumentException

See Also:

Call

loadAnnotationFilename

public Tuple loadAnnotationFilename(String filename,
                                    String key)
                             throws SQLException,
                                    IllegalArgumentException

Obtains the value to a specific key in an annotated filename.

Specified by:

loadAnnotationFilename in interface Annotation

Parameters:

filename - is the name of the file that was annotated.

key - is the key to search for

Returns:

the annotated value, or null if not found.

Throws:

SQLException

IllegalArgumentException

See Also:

LFN

loadAnnotation

public Tuple loadAnnotation(String primary,
                            Object secondary,
                            int kind,
                            String key)
                     throws SQLException,
                            IllegalArgumentException

Retrieves a specific annotation from an annotatable classes with the specified tuple. This is an interface method to the various class-specific methods.

Specified by:

loadAnnotation in interface Annotation

Parameters:

primary - is the primary object specifier for the class. According to the type, this is either the FQDI, or the filename.

secondary - is a helper argument for annotations to calls and formal arguments, and should be null for all other classes. For calls, the argument must be packed into Integer.

kind - defines the kind/class of object to annotate.

key - is the key to look for.

Returns:

null if not found, otherwise the annotation tuple.

Throws:

SQLException

IllegalArgumentException

See Also:

loadAnnotationTransformation( String, String ), loadAnnotationDerivation( String, String ), loadAnnotationCall( String, int, String ), loadAnnotationDeclare( String, String, String ), loadAnnotationFilename( String, String )

loadAnnotationTransformation

public List loadAnnotationTransformation(String fqdi)
                                  throws SQLException,
                                         IllegalArgumentException

Lists all annotations for a transformation.

Specified by:

loadAnnotationTransformation in interface Annotation

Parameters:

fqdi - is the FQDI of the transformation

Returns:

a list of tuples, which may be empty.

Throws:

SQLException

IllegalArgumentException

See Also:

Transformation

loadAnnotationDerivation

public List loadAnnotationDerivation(String fqdi)
                              throws SQLException,
                                     IllegalArgumentException

Lists all annotations for a derivation.

Specified by:

loadAnnotationDerivation in interface Annotation

Parameters:

fqdi - is the FQDI of the derivation

Returns:

a list of tuples, which may be empty.

Throws:

SQLException

IllegalArgumentException

See Also:

Derivation

loadAnnotationDeclare

public List loadAnnotationDeclare(String fqdi,
                                  String farg)
                           throws SQLException,
                                  IllegalArgumentException

Lists all annotations for a formal argument.

Specified by:

loadAnnotationDeclare in interface Annotation

Parameters:

fqdi - is the FQDI of the transformation

farg - is the name of the formal argument

Returns:

a list of tuples, which may be empty.

Throws:

SQLException

IllegalArgumentException

See Also:

Declare

loadAnnotationCall

public List loadAnnotationCall(String fqdi,
                               int index)
                        throws SQLException,
                               IllegalArgumentException

Lists all annotations for a call statement.

Specified by:

loadAnnotationCall in interface Annotation

Parameters:

fqdi - is the FQDI of the transformation

index - is the number of the call to annotate.

Returns:

a list of tuples, which may be empty.

Throws:

SQLException

IllegalArgumentException

See Also:

Call

loadAnnotationFilename

public List loadAnnotationFilename(String filename)
                            throws SQLException,
                                   IllegalArgumentException

Lists all annotations for a logical filename.

Specified by:

loadAnnotationFilename in interface Annotation

Parameters:

filename - is the logical filename.

Returns:

a list of tuples, which may be empty.

Throws:

SQLException

IllegalArgumentException

See Also:

LFN

loadAnnotation

public List loadAnnotation(String primary,
                           Object secondary,
                           int kind)
                    throws SQLException,
                           IllegalArgumentException

Retrieves all annotations from an annotatable classes with the specified tuple. This is an interface method to the various class-specific methods.

Specified by:

loadAnnotation in interface Annotation

Parameters:

primary - is the primary object specifier for the class. According to the type, this is either the FQDI, or the filename.

secondary - is a helper argument for annotations to calls and formal arguments, and should be null for all other classes. For calls, the argument must be packed into Integer.

kind - defines the kind/class of object to annotate.

Returns:

null if not found, otherwise the annotation tuple.

Throws:

SQLException

IllegalArgumentException

See Also:

loadAnnotationTransformation( String ), loadAnnotationDerivation( String ), loadAnnotationCall( String, int ), loadAnnotationDeclare( String, String ), loadAnnotationFilename( String )

searchAnnotation

public List searchAnnotation(int kind,
                             Object arg,
                             QueryTree tree)
                      throws SQLException

Search for LFNs or Definitions that has certain annotations

Specified by:

searchAnnotation in interface Annotation

Parameters:

kind - defines the kind/class of object annotated.

arg - is used only for TR ARG and TR CALL. For the former it is the name of the argument (String), for the latter the position of the call (Integer).

tree - stores the query tree to query the annotation

Returns:

a list of LFNs if search for filenames, otherwise a list of definitions.

Throws:

SQLException - if something goes wrong with the database.

See Also:

QueryTree

searchAnnotation

public ResultSet searchAnnotation(List select,
                                  String table,
                                  Map where,
                                  String order)
                           throws SQLException

A not very generic method to search annotation (and anything) in the database. Selects any rows in one or more colums from one or more tables restricted by some condition, possibly ordered.

WARNING: This is a method for internal use only.

Parameters:

select - is the ordered set of column names to select, or simply a one-value list with an asterisk.

table - is the name of the table to select from.

where - is a collection of column names and values they must equal.

order - is an optional ordering string.

Returns:

something to search for results in.

Throws:

SQLException - if something goes wrong with the database.

See Also:

DatabaseDriver.select( java.util.List, String, java.util.Map, String )

deleteDefinitionEx

public List deleteDefinitionEx(String namespace,
                               String name,
                               String version,
                               int type)
                        throws SQLException

Delete one or more definitions from the backend database. The key triple parameters may be wildcards. Wildcards are expressed as null value, or have special characters '%' and '_'.

Specified by:

deleteDefinitionEx in interface Advanced

Parameters:

namespace - namespace

name - name

version - version

type - definition type (TR or DV)

Returns:

a list of definitions that were deleted.

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION

searchDefinitionEx

public List searchDefinitionEx(String namespace,
                               String name,
                               String version,
                               int type)
                        throws SQLException

Search the database for definitions by ns::name:version triple and by type (either Transformation or Derivation). This version of the search allows for jokers expressed as null value

Specified by:

searchDefinitionEx in interface Advanced

Parameters:

namespace - namespace, null to match any namespace

name - name, null to match any name

version - version, null to match any version

type - type of definition, see below, or -1 as wildcard

Returns:

a list of Definition items, which may be empty

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION, loadDefinition( String, String, String, int )

searchLFN

public List searchLFN(String lfn,
                      int link)
               throws SQLException

Searches the database for all LFNs that match a certain pattern. The linkage is an additional constraint. This method allows joker characters such as '%' and '_'.

Specified by:

searchLFN in interface Advanced

Parameters:

lfn - the LFN name

link - the linkage type of the LFN

Returns:

a list of filenames that match the criterion.

Throws:

SQLException

See Also:

LFN.NONE, LFN.INPUT, LFN.OUTPUT, LFN.INOUT

getNamespaceList

public List getNamespaceList(int type)
                      throws SQLException

Searches the database for a list of namespaces of the definitions Sorted in ascending order.

Specified by:

getNamespaceList in interface Advanced

Parameters:

type - type of definition, see below, or -1 for both

Returns:

a list of namespaces

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION

getFQDNList

public List getFQDNList(int type)
                 throws SQLException

Searches the database for a list of fully-qualified names of the definitions sorted in ascending order.

Specified by:

getFQDNList in interface Advanced

Parameters:

type - type of definition, see below, or -1 for both

Returns:

a list of FQDNs

Throws:

SQLException

See Also:

Definition.TRANSFORMATION, Definition.DERIVATION

backdoor

public ResultSet backdoor(String query)
                   throws SQLException

A too generic method to search annotation (and anything) in the database. This method is also responsible for breaking any no-database-based backends.

WARNING: This is a method for internal use only.

Parameters:

query - is an SQL query statement.

Returns:

something to search for results in.

Throws:

SQLException - if something goes wrong with the database.