001: /*
002: * This file or a portion of this file is licensed under the terms of
003: * the Globus Toolkit Public License, found in file ../GTPL, or at
004: * http://www.globus.org/toolkit/download/license.html. This notice must
005: * appear in redistributions of this file, with or without modification.
006: *
007: * Redistributions of this Software, with or without modification, must
008: * reproduce the GTPL in: (1) the Software, or (2) the Documentation or
009: * some other similar material which is provided with the Software (if
010: * any).
011: *
012: * Copyright 1999-2004 University of Chicago and The University of
013: * Southern California. All rights reserved.
014: */
015: package org.griphyn.vdl.dbschema;
016:
017: import java.sql.*;
018: import org.griphyn.vdl.classes.Definition;
019: import org.griphyn.vdl.annotation.QueryTree;
020: import org.griphyn.vdl.annotation.Tuple;
021:
022: /**
023: * This common schema interface defines the schemas in which the
024: * abstraction layers access the metadata associated with VDC elements.
025: * This layer is independent of the implementing database, and does so
026: * by going via the database driver class API.
027: *
028: * @author Jens-S. Vöckler
029: * @author Yong Zhao
030: * @version $Revision: 50 $
031: * @see org.griphyn.vdl.dbschema.DatabaseSchema
032: * @see org.griphyn.vdl.dbdriver
033: */
034: public interface Annotation extends Catalog {
035: /**
036: * Annotations for transformations.
037: */
038: public static final int CLASS_TRANSFORMATION = 0;
039:
040: /**
041: * Annotations for derivations.
042: */
043: public static final int CLASS_DERIVATION = 1;
044:
045: /**
046: * Annotations for call statements.
047: */
048: public static final int CLASS_CALL = 2;
049:
050: /**
051: * Annotations for formal arguments.
052: */
053: public static final int CLASS_DECLARE = 3;
054:
055: /**
056: * Annotations for logical filenames.
057: */
058: public static final int CLASS_FILENAME = 4;
059:
060: /**
061: * Annotates any of the annotatable classes with the specified tuple.
062: * This is an interface method to the various class-specific methods.
063: *
064: * @param primary is the primary object specifier for the class.
065: * According to the type, this is either the FQDI, or the filename.
066: * @param secondary is a helper argument for annotations to calls
067: * and formal arguments, and should be null for all other classes.
068: * For calls, the argument must be packed into {@link java.lang.Integer}.
069: * @param kind defines the kind/class of object to annotate.
070: * @param annotation is the value to place into the class.
071: * @param overwrite is a predicate on replace or maintain.
072: * @return the insertion id, or -1, if the database was untouched
073: * @see #saveAnnotationTransformation( String, Tuple, boolean )
074: * @see #saveAnnotationDerivation( String, Tuple, boolean )
075: * @see #saveAnnotationCall( String, int, Tuple, boolean )
076: * @see #saveAnnotationDeclare( String, String, Tuple, boolean )
077: * @see #saveAnnotationFilename( String, Tuple, boolean )
078: */
079: public long saveAnnotation(String primary, Object secondary,
080: int kind, Tuple annotation, boolean overwrite)
081: throws SQLException, IllegalArgumentException;
082:
083: /**
084: * Annotates a transformation with a tuple.
085: *
086: * @param fqdi is the FQDI to annotate
087: * @param annotation is the value to place
088: * @param overwrite is a predicate on replace or maintain.
089: * @return the insertion id, or -1, if the database was untouched
090: * @see org.griphyn.vdl.classes.Transformation
091: */
092: public long saveAnnotationTransformation(String fqdi,
093: Tuple annotation, boolean overwrite) throws SQLException,
094: IllegalArgumentException;
095:
096: /**
097: * Annotates a derivation with a tuple.
098: *
099: * @param fqdi is the FQDI to annotate
100: * @param annotation is the value to place
101: * @param overwrite is a predicate on replace or maintain.
102: * @return the insertion id, or -1, if the database was untouched
103: * @see org.griphyn.vdl.classes.Derivation
104: */
105: public long saveAnnotationDerivation(String fqdi, Tuple annotation,
106: boolean overwrite) throws SQLException,
107: IllegalArgumentException;
108:
109: /**
110: * Annotates a transformation argument with a tuple.
111: *
112: * @param fqdi is the FQDI to annotate
113: * @param formalname is the name of the formal argument to annotoate.
114: * @param annotation is the value to place
115: * @param overwrite is a predicate on replace or maintain.
116: * @return the insertion id, or -1, if the database was untouched
117: * @see org.griphyn.vdl.classes.Declare
118: */
119: public long saveAnnotationDeclare(String fqdi, String formalname,
120: Tuple annotation, boolean overwrite) throws SQLException,
121: IllegalArgumentException;
122:
123: /**
124: * Annotates a transformation call with a tuple.
125: *
126: * @param fqdi is the FQDI to annotate
127: * @param index is the number of the call to annotate.
128: * @param annotation is the value to place
129: * @param overwrite is a predicate on replace or maintain.
130: * @return the insertion id, or -1, if the database was untouched
131: * @see org.griphyn.vdl.classes.Call
132: */
133: public long saveAnnotationCall(String fqdi, int index,
134: Tuple annotation, boolean overwrite) throws SQLException,
135: IllegalArgumentException;
136:
137: /**
138: * Annotates a logical filename with a tuple.
139: *
140: * @param filename is the FQDI to annotate
141: * @param annotation is the value to place
142: * @param overwrite is a predicate on replace or maintain.
143: * @return the insertion id, or -1, if the database was untouched
144: * @see org.griphyn.vdl.classes.LFN
145: */
146: public long saveAnnotationFilename(String filename,
147: Tuple annotation, boolean overwrite) throws SQLException,
148: IllegalArgumentException;
149:
150: /**
151: * Retrieves a specific annotation from an annotatable classes with
152: * the specified tuple. This is an interface method to the various
153: * class-specific methods.
154: *
155: * @param primary is the primary object specifier for the class.
156: * According to the type, this is either the FQDI, or the filename.
157: * @param secondary is a helper argument for annotations to calls
158: * and formal arguments, and should be null for all other classes.
159: * For calls, the argument must be packed into {@link java.lang.Integer}.
160: * @param kind defines the kind/class of object to annotate.
161: * @param key is the key to look for.
162: * @return null if not found, otherwise the annotation tuple.
163: * @see #loadAnnotationTransformation( String, String )
164: * @see #loadAnnotationDerivation( String, String )
165: * @see #loadAnnotationCall( String, int, String )
166: * @see #loadAnnotationDeclare( String, String, String )
167: * @see #loadAnnotationFilename( String, String )
168: */
169: public Tuple loadAnnotation(String primary, Object secondary,
170: int kind, String key) throws SQLException,
171: IllegalArgumentException;
172:
173: /**
174: * Obtains the value to a specific key in an annotated transformation.
175: *
176: * @param fqdi is the FQDI of the transformation
177: * @param key is the key to search for
178: * @return the annotated value, or null if not found.
179: * @see org.griphyn.vdl.classes.Transformation
180: */
181: public Tuple loadAnnotationTransformation(String fqdi, String key)
182: throws SQLException, IllegalArgumentException;
183:
184: /**
185: * Obtains the value to a specific key in an annotated derivation.
186: *
187: * @param fqdi is the FQDI of the derivation
188: * @param key is the key to search for
189: * @return the annotated value, or null if not found.
190: * @see org.griphyn.vdl.classes.Derivation
191: */
192: public Tuple loadAnnotationDerivation(String fqdi, String key)
193: throws SQLException, IllegalArgumentException;
194:
195: /**
196: * Obtains the value to a specific key in an annotated formal argument.
197: *
198: * @param fqdi is the FQDI of the transformation
199: * @param farg is the name of the formal argument
200: * @param key is the key to search for
201: * @return the annotated value, or null if not found
202: * @see org.griphyn.vdl.classes.Declare
203: */
204: public Tuple loadAnnotationDeclare(String fqdi, String farg,
205: String key) throws SQLException, IllegalArgumentException;
206:
207: /**
208: * Obtains the value to a specific key for a call statement.
209: *
210: * @param fqdi is the FQDI of the transformation
211: * @param index is the number of the call to annotate.
212: * @param key is the key to search for
213: * @return the annotated value, or null if not found
214: * @see org.griphyn.vdl.classes.Call
215: */
216: public Tuple loadAnnotationCall(String fqdi, int index, String key)
217: throws SQLException, IllegalArgumentException;
218:
219: /**
220: * Obtains the value to a specific key in an annotated filename.
221: *
222: * @param filename is the name of the file that was annotated.
223: * @param key is the key to search for
224: * @return the annotated value, or null if not found.
225: * @see org.griphyn.vdl.classes.LFN
226: */
227: public Tuple loadAnnotationFilename(String filename, String key)
228: throws SQLException, IllegalArgumentException;
229:
230: /**
231: * Retrieves all annotations from an annotatable classes with
232: * the specified tuple. This is an interface method to the various
233: * class-specific methods.
234: *
235: * @param primary is the primary object specifier for the class.
236: * According to the type, this is either the FQDI, or the filename.
237: * @param secondary is a helper argument for annotations to calls
238: * and formal arguments, and should be null for all other classes.
239: * For calls, the argument must be packed into {@link java.lang.Integer}.
240: * @param kind defines the kind/class of object to annotate.
241: *
242: * @return null if not found, otherwise the annotation tuple.
243: * @see #loadAnnotationTransformation( String )
244: * @see #loadAnnotationDerivation( String )
245: * @see #loadAnnotationCall( String, int )
246: * @see #loadAnnotationDeclare( String, String )
247: * @see #loadAnnotationFilename( String )
248: */
249: public java.util.List loadAnnotation(String primary,
250: Object secondary, int kind) throws SQLException,
251: IllegalArgumentException;
252:
253: /**
254: * Lists all annotations for a transformation.
255: *
256: * @param fqdi is the FQDI of the transformation
257: * @return a list of tuples, which may be empty.
258: * @see org.griphyn.vdl.classes.Transformation
259: */
260: public java.util.List loadAnnotationTransformation(String fqdi)
261: throws SQLException, IllegalArgumentException;
262:
263: /**
264: * Lists all annotations for a derivation.
265: *
266: * @param fqdi is the FQDI of the derivation
267: * @return a list of tuples, which may be empty.
268: * @see org.griphyn.vdl.classes.Derivation
269: */
270: public java.util.List loadAnnotationDerivation(String fqdi)
271: throws SQLException, IllegalArgumentException;
272:
273: /**
274: * Lists all annotations for a formal argument.
275: *
276: * @param fqdi is the FQDI of the transformation
277: * @param farg is the name of the formal argument
278: * @return a list of tuples, which may be empty.
279: * @see org.griphyn.vdl.classes.Declare
280: */
281: public java.util.List loadAnnotationDeclare(String fqdi, String farg)
282: throws SQLException, IllegalArgumentException;
283:
284: /**
285: * Lists all annotations for a call statement.
286: *
287: * @param fqdi is the FQDI of the transformation
288: * @param index is the number of the call to annotate.
289: * @return a list of tuples, which may be empty.
290: * @see org.griphyn.vdl.classes.Call
291: */
292: public java.util.List loadAnnotationCall(String fqdi, int index)
293: throws SQLException, IllegalArgumentException;
294:
295: /**
296: * Lists all annotations for a logical filename.
297: *
298: * @param filename is the logical filename.
299: * @return a list of tuples, which may be empty.
300: * @see org.griphyn.vdl.classes.LFN
301: */
302: public java.util.List loadAnnotationFilename(String filename)
303: throws SQLException, IllegalArgumentException;
304:
305: /**
306: * Search for LFNs or Definitions that has certain annotations
307: *
308: * @param kind defines the kind/class of object annotated.
309: * @param arg is used only for TR ARG and TR CALL. For the former
310: * it is the name of the argument (String), for the latter the position of
311: * the call (Integer).
312: * @param tree stores the query tree to query the annotation
313: * @return a list of LFNs if search for filenames, otherwise a list of
314: * definitions.
315: * @exception SQLException if something goes wrong with the database.
316: * @see org.griphyn.vdl.annotation.QueryTree
317: */
318: public abstract java.util.List searchAnnotation(int kind,
319: Object arg, QueryTree tree) throws java.sql.SQLException;
320:
321: /**
322: * Deletes an annotation with the specified key.
323: *
324: * @param primary is the primary object specifier for the class.
325: * According to the type, this is either the FQDI, or the filename.
326: * @param secondary is a helper argument for annotations to calls
327: * and formal arguments, and should be null for all other classes.
328: * For calls, the argument must be packed into {@link java.lang.Integer}.
329: * @param kind defines the kind/class of object to annotate.
330: * @param key is the annotation key.
331: * @return true, if the database was modified, false otherwise.
332: * @exception SQLException, if something went wrong during database
333: * access.
334: */
335: public boolean deleteAnnotation(String primary, Object secondary,
336: int kind, String key) throws SQLException,
337: IllegalArgumentException;
338:
339: /**
340: * Deletes a specific key in an annotated transformation.
341: *
342: * @param fqdi is the FQDI of the transformation
343: * @param key is the key to search for
344: * @return true, if the database was modified, false otherwise.
345: * @see org.griphyn.vdl.classes.Transformation
346: */
347: public boolean deleteAnnotationTransformation(String fqdi,
348: String key) throws SQLException, IllegalArgumentException;
349:
350: /**
351: * Deletes a specific key in an annotated derivation.
352: *
353: * @param fqdi is the FQDI of the derivation
354: * @param key is the key to search for
355: * @return true, if the database was modified, false otherwise.
356: * @see org.griphyn.vdl.classes.Derivation
357: */
358: public boolean deleteAnnotationDerivation(String fqdi, String key)
359: throws SQLException, IllegalArgumentException;
360:
361: /**
362: * Deletes a specific key in an annotated formal argument.
363: *
364: * @param fqdi is the FQDI of the transformation
365: * @param farg is the name of the formal argument
366: * @param key is the key to search for
367: * @return true, if the database was modified, false otherwise.
368: * @see org.griphyn.vdl.classes.Declare
369: */
370: public boolean deleteAnnotationDeclare(String fqdi, String farg,
371: String key) throws SQLException, IllegalArgumentException;
372:
373: /**
374: * Deletes a specific key for a call statement.
375: *
376: * @param fqdi is the FQDI of the transformation
377: * @param index is the number of the call to annotate.
378: * @param key is the key to search for
379: * @return true, if the database was modified, false otherwise.
380: * @see org.griphyn.vdl.classes.Call
381: */
382: public boolean deleteAnnotationCall(String fqdi, int index,
383: String key) throws SQLException, IllegalArgumentException;
384:
385: /**
386: * Deletes a specific key in an annotated filename.
387: *
388: * @param filename is the name of the file that was annotated.
389: * @param key is the key to search for
390: * @return true, if the database was modified, false otherwise.
391: * @see org.griphyn.vdl.classes.LFN
392: */
393: public boolean deleteAnnotationFilename(String filename, String key)
394: throws SQLException, IllegalArgumentException;
395: }
|