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:
016: package org.griphyn.common.catalog;
017:
018: import java.util.*;
019:
020: /**
021: * This interface describes a minimum set of essential tasks required
022: * from a replica catalog. The method verbs have a steering meaning
023: * associated with them:
024: *
025: * <dl>
026: * <dt>lookup</dt>
027: * <dd>retrieves physical filenames or replica entries</dd>
028: * <dt>list</dt>
029: * <dd>retrieves only lists of logical filenames</dd>
030: * <dt>delete</dt>
031: * <dd>removes an entry specified by LFN and PFN</dd>
032: * <dt>remove</dt>
033: * <dd>removes en-bulk by LFN</dd>
034: * </dl>
035: *
036: * @author Jens-S. Vöckler
037: * @author Karan Vahi
038: * @version $Revision: 83 $
039: */
040: public interface ReplicaCatalog extends Catalog {
041: /**
042: * Prefix for the property subset to use with this catalog.
043: */
044: public static final String c_prefix = "pegasus.catalog.replica";
045:
046: /**
047: * The DB Driver properties prefix.
048: */
049: public static final String DB_PREFIX = "pegasus.catalog.replica.db";
050:
051: /**
052: * The suffix for the property that if set, specifies the size of the chunk
053: * in which the implementations handle multiple queries. The property that
054: * needs to be specified is vds.rc.chunk.size.
055: */
056: public static final String BATCH_KEY = "chunk.size";
057:
058: /**
059: * Retrieves the entry for a given filename and resource handle from
060: * the replica catalog.
061: *
062: * @param lfn is the logical filename to obtain information for.
063: * @param handle is the resource handle to obtain entries for.
064: * @return the (first) matching physical filename, or
065: * <code>null</code> if no match was found.
066: */
067: public String lookup(String lfn, String handle);
068:
069: /**
070: * Retrieves all entries for a given LFN from the replica catalog.
071: * Each entry in the result set is a tuple of a PFN and all its
072: * attributes.
073: *
074: * @param lfn is the logical filename to obtain information for.
075: * @return a collection of replica catalog entries
076: * @see ReplicaCatalogEntry
077: */
078: public Collection lookup(String lfn);
079:
080: /**
081: * Retrieves all entries for a given LFN from the replica catalog.
082: * Each entry in the result set is just a PFN string. Duplicates
083: * are reduced through the set paradigm.
084: *
085: * @param lfn is the logical filename to obtain information for.
086: * @return a set of PFN strings
087: */
088: public Set lookupNoAttributes(String lfn);
089:
090: /**
091: * Retrieves multiple entries for a given logical filename, up to the
092: * complete catalog. Retrieving full catalogs should be harmful, but
093: * may be helpful in an online display or portal.
094: *
095: * @param lfns is a set of logical filename strings to look up.
096: * @return a map indexed by the LFN. Each value is a collection
097: * of replica catalog entries for the LFN.
098: * @see ReplicaCatalogEntry
099: */
100: public Map lookup(Set lfns);
101:
102: /**
103: * Retrieves multiple entries for a given logical filename, up to the
104: * complete catalog. Retrieving full catalogs should be harmful, but
105: * may be helpful in an online display or portal.
106: *
107: * @param lfns is a set of logical filename strings to look up.
108: * @return a map indexed by the LFN. Each value is a set
109: * of PFN strings.
110: */
111: public Map lookupNoAttributes(Set lfns);
112:
113: /**
114: * Retrieves multiple entries for a given logical filename, up to the
115: * complete catalog. Retrieving full catalogs should be harmful, but
116: * may be helpful in online display or portal.<p>
117: *
118: * @param lfns is a set of logical filename strings to look up.
119: * @param handle is the resource handle, restricting the LFNs.
120: * @return a map indexed by the LFN. Each value is a collection
121: * of replica catalog entries (all attributes).
122: * @see ReplicaCatalogEntry
123: */
124: public Map lookup(Set lfns, String handle);
125:
126: /**
127: * Retrieves multiple entries for a given logical filename, up to the
128: * complete catalog. Retrieving full catalogs should be harmful, but
129: * may be helpful in online display or portal.<p>
130: *
131: * @param lfns is a set of logical filename strings to look up.
132: * @param handle is the resource handle, restricting the LFNs.
133: * @return a map indexed by the LFN. Each value is a set of
134: * physical filenames.
135: */
136: public Map lookupNoAttributes(Set lfns, String handle);
137:
138: /**
139: * Retrieves multiple entries for a given logical filename, up to the
140: * complete catalog. Retrieving full catalogs should be harmful, but
141: * may be helpful in online display or portal.
142: *
143: * @param constraints is mapping of keys 'lfn', 'pfn', or any
144: * attribute name, e.g. the resource handle 'site', to a string that
145: * has some meaning to the implementing system. This can be a SQL
146: * wildcard for queries, or a regular expression for Java-based memory
147: * collections. Unknown keys are ignored. Using an empty map requests
148: * the complete catalog.
149: * @return a map indexed by the LFN. Each value is a collection
150: * of replica catalog entries.
151: * @see ReplicaCatalogEntry
152: */
153: public Map lookup(Map constraints);
154:
155: /**
156: * Lists all logical filenames in the catalog.
157: *
158: * @return A set of all logical filenames known to the catalog.
159: */
160: public Set list();
161:
162: /**
163: * Lists a subset of all logical filenames in the catalog.
164: *
165: * @param constraint is a constraint for the logical filename only. It
166: * is a string that has some meaning to the implementing system. This
167: * can be a SQL wildcard for queries, or a regular expression for
168: * Java-based memory collections.
169: * @return A set of logical filenames that match. The set may be empty
170: */
171: public Set list(String constraint);
172:
173: /**
174: * Inserts a new mapping into the replica catalog.
175: *
176: * @param lfn is the logical filename under which to book the entry.
177: * @param tuple is the physical filename and associated PFN attributes.
178: *
179: * @return number of insertions, should always be 1. On failure,
180: * throw an exception, don't use zero.
181: */
182: public int insert(String lfn, ReplicaCatalogEntry tuple);
183:
184: /**
185: * Inserts a new mapping into the replica catalog. This is a
186: * convenience function exposing the resource handle. Internally,
187: * the <code>ReplicaCatalogEntry</code> element will be contructed, and passed to
188: * the appropriate insert function.
189: *
190: * @param lfn is the logical filename under which to book the entry.
191: * @param pfn is the physical filename associated with it.
192: * @param handle is a resource handle where the PFN resides.
193: * @return number of insertions, should always be 1. On failure,
194: * throw an exception, don't use zero.
195: * @see #insert( String, ReplicaCatalogEntry )
196: * @see ReplicaCatalogEntry
197: */
198: public int insert(String lfn, String pfn, String handle);
199:
200: // ^^ MARKER ^^
201:
202: /**
203: * Inserts multiple mappings into the replica catalog. The input is a
204: * map indexed by the LFN. The value for each LFN key is a collection
205: * of replica catalog entries.
206: *
207: * @param x is a map from logical filename string to list of replica
208: * catalog entries.
209: * @return the number of insertions.
210: * @see ReplicaCatalogEntry
211: */
212: public int insert(Map x);
213:
214: /**
215: * Deletes multiple mappings into the replica catalog. The input is a
216: * map indexed by the LFN. The value for each LFN key is a collection
217: * of replica catalog entries. On setting matchAttributes to false, all entries
218: * having matching lfn pfn mapping to an entry in the Map are deleted.
219: * However, upon removal of an entry, all attributes associated with the pfn
220: * also evaporate (cascaded deletion).
221: *
222: * @param x is a map from logical filename string to list of
223: * replica catalog entries.
224: * @param matchAttributes whether mapping should be deleted only if all
225: * attributes match.
226: *
227: * @return the number of deletions.
228: * @see ReplicaCatalogEntry
229: */
230: public int delete(Map x, boolean matchAttributes);
231:
232: /**
233: * Deletes a specific mapping from the replica catalog. We don't care
234: * about the resource handle. More than one entry could theoretically
235: * be removed. Upon removal of an entry, all attributes associated
236: * with the PFN also evaporate (cascading deletion).
237: *
238: * @param lfn is the logical filename in the tuple.
239: * @param pfn is the physical filename in the tuple.
240: * @return the number of removed entries.
241: */
242: public int delete(String lfn, String pfn);
243:
244: /**
245: * Deletes a very specific mapping from the replica catalog. The LFN
246: * must be matches, the PFN, and all PFN attributes specified in the
247: * replica catalog entry. More than one entry could theoretically be
248: * removed. Upon removal of an entry, all attributes associated with
249: * the PFN also evaporate (cascading deletion).
250: *
251: * @param lfn is the logical filename in the tuple.
252: * @param tuple is a description of the PFN and its attributes.
253: * @return the number of removed entries, either 0 or 1.
254: */
255: public int delete(String lfn, ReplicaCatalogEntry tuple);
256:
257: /**
258: * Deletes all PFN entries for a given LFN from the replica catalog
259: * where the PFN attribute is found, and matches exactly the object
260: * value. This method may be useful to remove all replica entries that
261: * have a certain MD5 sum associated with them. It may also be harmful
262: * overkill.
263: *
264: * @param lfn is the logical filename to look for.
265: * @param name is the PFN attribute name to look for.
266: * @param value is an exact match of the attribute value to match.
267: * @return the number of removed entries.
268: */
269: public int delete(String lfn, String name, Object value);
270:
271: // ^^ MARKER ^^
272:
273: /**
274: * Deletes all PFN entries for a given LFN from the replica catalog
275: * where the resource handle is found. Karan requested this
276: * convenience method, which can be coded like
277: * <pre>
278: * delete( lfn, RESOURCE_HANDLE, handle )
279: * </pre>
280: *
281: * @param lfn is the logical filename to look for.
282: * @param handle is the resource handle
283: * @return the number of entries removed.
284: */
285: public int deleteByResource(String lfn, String handle);
286:
287: /**
288: * Removes all mappings for an LFN from the replica catalog.
289: *
290: * @param lfn is the logical filename to remove all mappings for.
291: * @return the number of removed entries.
292: */
293: public int remove(String lfn);
294:
295: /**
296: * Removes all mappings for a set of LFNs.
297: *
298: * @param lfns is a set of logical filename to remove all mappings for.
299: * @return the number of removed entries.
300: */
301: public int remove(Set lfns);
302:
303: /**
304: * Removes all entries from the replica catalog where the PFN attribute
305: * is found, and matches exactly the object value.
306: *
307: * @param name is the PFN attribute name to look for.
308: * @param value is an exact match of the attribute value to match.
309: * @return the number of removed entries.
310: */
311: public int removeByAttribute(String name, Object value);
312:
313: /**
314: * Removes all entries associated with a particular resource handle.
315: * This is useful, if a site goes offline. It is a convenience method,
316: * which calls the generic <code>removeByAttribute</code> method.
317: *
318: * @param handle is the site handle to remove all entries for.
319: * @return the number of removed entries.
320: * @see #removeByAttribute( String, Object )
321: */
322: public int removeByAttribute(String handle);
323:
324: // ^^ MARKER ^^
325:
326: /**
327: * Removes everything. Use with caution!
328: *
329: * @return the number of removed entries.
330: */
331: public int clear();
332: }
|