org.griphyn.vdl.dbschema
Interface Annotation

All Superinterfaces:

Catalog

All Known Subinterfaces:

XDC

All Known Implementing Classes:

AnnotationSchema, NXDSchema

public interface Annotation
extends Catalog

This common schema interface defines the schemas in which the abstraction layers access the metadata associated with VDC elements. This layer is independent of the implementing database, and does so by going via the database driver class API.

Version:

$Revision: 50 $

Author:

Jens-S. V??ckler, Yong Zhao

See Also:

DatabaseSchema, org.griphyn.vdl.dbdriver

Field Summary

static int	CLASS_CALL Annotations for call statements.
static int	CLASS_DECLARE Annotations for formal arguments.
static int	CLASS_DERIVATION Annotations for derivations.
static int	CLASS_FILENAME Annotations for logical filenames.
static int	CLASS_TRANSFORMATION Annotations for transformations.

Method Summary

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.
boolean	deleteAnnotationTransformation(String fqdi, String key) Deletes a specific key in an annotated transformation.
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.
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.
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.
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.
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.
List	searchAnnotation(int kind, Object arg, QueryTree tree) Search for LFNs or Definitions that has certain annotations

Field Detail

CLASS_TRANSFORMATION

static final int CLASS_TRANSFORMATION

Annotations for transformations.

See Also:

Constant Field Values

CLASS_DERIVATION

static final int CLASS_DERIVATION

Annotations for derivations.

See Also:

Constant Field Values

CLASS_CALL

static final int CLASS_CALL

Annotations for call statements.

See Also:

Constant Field Values

CLASS_DECLARE

static final int CLASS_DECLARE

Annotations for formal arguments.

See Also:

Constant Field Values

CLASS_FILENAME

static final int CLASS_FILENAME

Annotations for logical filenames.

See Also:

Constant Field Values

Method Detail

saveAnnotation

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.

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 )

saveAnnotationTransformation

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

Annotates a transformation with a tuple.

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

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

Annotates a derivation with a tuple.

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

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

Annotates a transformation argument with a tuple.

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

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

Annotates a transformation call with a tuple.

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

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

Annotates a logical filename with a tuple.

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

loadAnnotation

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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 )

loadAnnotationTransformation

List loadAnnotationTransformation(String fqdi)
                                  throws SQLException,
                                         IllegalArgumentException

Lists all annotations for a transformation.

Parameters:

fqdi - is the FQDI of the transformation

Returns:

a list of tuples, which may be empty.

Throws:

SQLException

IllegalArgumentException

See Also:

Transformation

loadAnnotationDerivation

List loadAnnotationDerivation(String fqdi)
                              throws SQLException,
                                     IllegalArgumentException

Lists all annotations for a derivation.

Parameters:

fqdi - is the FQDI of the derivation

Returns:

a list of tuples, which may be empty.

Throws:

SQLException

IllegalArgumentException

See Also:

Derivation

loadAnnotationDeclare

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

Lists all annotations for a formal argument.

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

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

Lists all annotations for a call statement.

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

List loadAnnotationFilename(String filename)
                            throws SQLException,
                                   IllegalArgumentException

Lists all annotations for a logical filename.

Parameters:

filename - is the logical filename.

Returns:

a list of tuples, which may be empty.

Throws:

SQLException

IllegalArgumentException

See Also:

LFN

searchAnnotation

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

Search for LFNs or Definitions that has certain annotations

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

deleteAnnotation

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

Deletes an annotation with the specified key.

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

deleteAnnotationTransformation

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

Deletes a specific key in an annotated transformation.

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

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

Deletes a specific key in an annotated derivation.

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

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

Deletes a specific key in an annotated formal argument.

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

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

Deletes a specific key for a call statement.

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

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

Deletes a specific key in an annotated filename.

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