org.glite.data.catalog.service.file
Interface FileCatalog

All Superinterfaces:
FASBase, ServiceBase
All Known Subinterfaces:
FiremanCatalog

public interface FileCatalog
extends FASBase

The middleware level API for the File Catalog component. This is the interface that this service exposes to the other middleware components, which is not necessarily the final API seen by the user.

Symlink Semantics


Stereotype:
simple-interface

Method Summary
 void createFile(FCEntry[] entries)
          Registers a new File Catalog entry with all status information specified.
 FCEntry[] getFileCatalogEntry(java.lang.String[] lfns)
          Get the detailed metadata about LFNs.
 StringPair[] getGuidForLfn(java.lang.String[] lfns)
          Retrieves list of guids for given Lfns.
 StringPair[] getLfnForGuid(java.lang.String[] guids)
          Retrieves list of lfns for given guid.
 java.lang.String[] locate(java.lang.String startDir, java.lang.String pattern, long limit)
          Returns list of matching LFNs from all subdirectories of the path given in the first argument.
 void mkdir(java.lang.String[] directories, boolean createParents, boolean copyPermFromParent)
          Make a set of new directories.
 void mv(StringPair[] entries)
          Renames a set of LFNs, symlinks or directories.
 FCEntry[] readDir(java.lang.String path, java.lang.String pattern, long limit, long offset, boolean withPermissions)
          Read the directory given in the path argument, restricted to the pattern given in the second argument.
 void rmdir(java.lang.String[] directories)
          Remove a directory.
 void symlink(StringPair[] symlinks, boolean copyPermFromParent)
          Create symlinks by passing source LFN (string1) and target LFN (string2) pairs.
 void unlink(java.lang.String[] lfns)
          Delete an LFN, symlink or virtual directory.
 void updateModifyTime(java.lang.String[] lfns, long time)
          Update the modification time for the given entries.
 void updateValidityTime(java.lang.String[] lfns, long time)
          Update the validity time for the given entries.
 
Methods inherited from interface org.glite.data.catalog.service.fas.FASBase
checkPermission, getPermission, setPermission
 
Methods inherited from interface org.glite.data.catalog.service.ServiceBase
getInterfaceVersion, getSchemaVersion, getServiceMetadata, getVersion
 

Method Detail

mkdir

public void mkdir(java.lang.String[] directories,
                  boolean createParents,
                  boolean copyPermFromParent)
           throws InternalException,
                  InvalidArgumentException,
                  AuthorizationException,
                  ExistsException,
                  NotExistsException
Make a set of new directories. If the parent directories are not set yet, the createParents flag will decide whether the parents should be created automatically.

Parameters:
directories - The entries in the directory. This may be null for normal directories but is mandatory for virtual directories. The entry names may also be 'short', i.e. not start with a '/' in which case they will be treated as names in the local directory.
createParents - If set to true, instead of giving an error if the parent directories do not exist, they will be created if possible
Throws:
AuthorizationException - No access right to create a directory or one of the parents.
ExistsException - The path or directory already exists.
NotExistsException - One of the parent directories does not exists and 'createParents' is false.
InvalidArgumentException - The path format is invalid
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check format of the path;
    if it is invalid, throws InvalidArgumentException.
  • Check if directory already exists;
    if it exists, throws ExistsException.
  • Check if Parents exists
    if it does not exit, behaviour depends on createParents argument :
    createParents==0 > throws NotExistsException.
    createParents==1 > create parent directories recursively;
  • Check WRITE permissions on parent directory;
    if permission is not granted, throws AuthorizationException.
  • Insert new LFNEntry in the catalog
  • Insert new GUID to associate with the LFN
    Permissions to the Guid are set by Principal Default, or Global Default

rmdir

public void rmdir(java.lang.String[] directories)
           throws InternalException,
                  AuthorizationException,
                  ExistsException,
                  NotExistsException
Remove a directory.

Parameters:
directories - The directory LFN to remove.
Throws:
AuthorizationException - No access right to remove a directory or an entry in it.
ExistsException - The directory, to be removed, is not empty and 'recursive' flag is false.
NotExistsException - The directory, to be removed, does not exits.
InvalidArgumentException - The LFN format is not valid.

Semantic description of the method:
The following steps are performed for each entry:
  • Check the format of the directory LFN;
    if it is not correct, throws InvalidArgumentException.
  • Check if directory exists;
    if it does not exist, throws NotExistsException.
  • Check REMOVE permission on the directory (in POSIX filesystems it is usually WRITE permission on the parent directory);
    if permission is not granted, throws AuthorizationException.
  • Check if directory is empty;
    if it is empty, removes the directory from the catalog.
    if it is not empty, throws ExistsException.
InternalException

createFile

public void createFile(FCEntry[] entries)
                throws InternalException,
                       AuthorizationException,
                       ExistsException,
                       NotExistsException,
                       InvalidArgumentException
Registers a new File Catalog entry with all status information specified.

Parameters:
entries - FCEntry to register
Throws:
AuthorizationException - No access right to create new entry in the parent directory.
ExistsException - The file or guid already exists.
NotExistsException - One of the parent path elemenets does not exists.
InvalidArgumentException - The status information on the new entry is invalid.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check if FCEntry[] argument is valid;
    if it is invalid, throws InvalidArgumentException.
  • Check type in LFNStat to be file;
    if not, throws InvalidArgumentException.
  • Check if LFN already exists
    if it exists, throws ExistsException.
  • Check if GUID already exists (if given)
    if it exists, throws ExistsException.
  • Check if parent directory exists
    if it does not exist, throws NotExistsException.
  • Check WRITE permissions on parent directory;
    if permission is not granted, throws AuthorizationException.
  • Insert the GUID information in the catalog
    if it is not given, then create a GUID.
  • Insert new LFNEntry in the catalog.

symlink

public void symlink(StringPair[] symlinks,
                    boolean copyPermFromParent)
             throws InternalException,
                    AuthorizationException,
                    ExistsException,
                    NotExistsException,
                    InvalidArgumentException
Create symlinks by passing source LFN (string1) and target LFN (string2) pairs. Example: ln -s b a would be implemented as symlink({"a", "b"}, true).

Parameters:
symlinks - Symlinks to register.
Throws:
AuthorizationException - No access right to create new entry in the parent directory.
ExistsException - The file or Guid already exists.
NotExistsException - One of the parent path elemenets does not exists.
InvalidArgumentException - The status information on the new entry is invalid, e.g. type is not symlink.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check if the format of the source and target LFNs are valid,
    if not, throws InvalidArgumentException.
  • Check if source LFN (string1) already exists
    if it exists, throws ExistsException.
  • The target LFN (string2) does not have to exist at creation time (dangling symlink).
  • Check if parent directory exists
    if it does not exist, throws NotExistsException.
  • Check WRITE permissions on parent directory;
    if permission is not granted, throws AuthorizationException.
  • See the applied permissions in the global description.
  • Insert the symlink into the catalog.

unlink

public void unlink(java.lang.String[] lfns)
            throws InternalException,
                   AuthorizationException,
                   NotExistsException
Delete an LFN, symlink or virtual directory. Use rmdir for normal directories.

Parameters:
lfns - The lfn to unlink
Throws:
AuthorizationException - No access right to delete the entry.
NotExistsException - One of lfns does not exists.
InvalidArgumentException
InternalException -

Semantic description of the method:
The following steps are performed for each entry:

mv

public void mv(StringPair[] entries)
        throws InternalException,
               AuthorizationException,
               ExistsException,
               NotExistsException
Renames a set of LFNs, symlinks or directories.

Parameters:
entries - StringPair object, containing the old name as string1 and the new name as string2.
Throws:
AuthorizationException - No access right to create the new entry.
ExistsException - The destination entry already exists.
InvalidArgumentException - Some part of the argument is invalid.
NotExistsException - The source entry does not exist.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check format of source and destination entry;
    if any of them is invalid, throws InvalidArgumentException.
  • If the destination is a link, then it has to be resolved and used as the target LFN (restart).
  • Check if source entry exists;
    if it does not exist, throws NotExistsException.
  • Check REMOVE permission on the source;
    if permission is not granted, throws AuthorizationException.
  • Check WRITE permission on the (parent directory of) destination entry;
    if permission is not granted, throws AuthorizationException.
  • Check if the type of source entry is directory;
    if it is a directory and destination is an existing directory, the directory is moved to the destination directory as a subdirectory.
    if it is a directory and destination is an existing directory + a non-existing entryname and parent directories of the entries are different, the source directory is moved to the destination and source directory is renamed.
    if it is a directory and destination is an existing file/link, throws ExistsException.
  • Check if the type of source entry is file or link;
    if it is a file/link and destination is an existing directory, the file/link is moved to the destination directory.
    if it is a file/link and destination is an existing directory + a non-existing entryname and parent directories of the entries are different, the source file/link is moved to the destination directory and it is renamed.
    if it is a file/link and destination is an existing file/link, throws ExistsException.

updateModifyTime

public void updateModifyTime(java.lang.String[] lfns,
                             long time)
                      throws InternalException,
                             AuthorizationException,
                             NotExistsException,
                             InvalidArgumentException
Update the modification time for the given entries.

Parameters:
lfns - The LFNs to change the time on
time - the new modification time to set
Returns:
previous modification time
Throws:
AuthorizationException - No access right to update the status information.
InvalidArgumentException - The specified time or the format of LFN is invalid.
NotExistsException - The LFN does not exist.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:

updateValidityTime

public void updateValidityTime(java.lang.String[] lfns,
                               long time)
                        throws InternalException,
                               AuthorizationException,
                               NotExistsException,
                               InvalidArgumentException
Update the validity time for the given entries.
When current time ellapses creation time plus validity time the file would be scheduled for removal by an additional service. This means that setting validity time is implicitly making decision on the removal of the file, therefor the operation requires the REMOVE permission as well.

Parameters:
lfns - The LFNs to change the time on
time - the new validity time to set
Returns:
previous validity time
Throws:
AuthorizationException - No access right to update the status information.
InvalidArgumentException - The specified time or thw format of lfn is invalid.
NotExistsException - The LFN does not exist.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:

readDir

public FCEntry[] readDir(java.lang.String path,
                         java.lang.String pattern,
                         long limit,
                         long offset,
                         boolean withPermissions)
                  throws InternalException,
                         AuthorizationException,
                         NotExistsException,
                         InvalidArgumentException
Read the directory given in the path argument, restricted to the pattern given in the second argument. The second argument may be null, in which case all the directory is listed.
The result contains a list of File Catalog entries, up to 'limit' of them (given as the third argument). If limit is 0, an exception is thrown. The offset is used to skip the first offset entries and start listing with entry number offset+1.
If withPermissions is not specified then FCEntry will not have a Permission object (null) included, which speeds up listing considerably.
pattern allows glob like '?' and '*' characters, but no '/', ranges, sets or other complex queries. Example: listing all files starting with 'f', having at least 4 charactes is f???*.

Parameters:
path - The path of the directory to query.
pattern - The pattern to be mached. May be null.
limit - Up to limit result entries to be returned. May not be 0.
offset - Start with result entry at index offset+1. Offset starts with 0.
withPermissions - fill permission field too
Returns:
The returned structure contains an array of FCEntry objects.
Throws:
AuthorizationException - No access right to list the entries or status information.
NotExistsException - The path does not exist.
InvalidArgumentException
InternalException - The offset or limit is larget than the absolute maximum allowed.

Semantic description of the method:
The following steps are performed:
  • Check format of the pattern;
    if it is invalid, throw InvalidArgumentException.
  • Check the limit;
    if it is not valid, throw InvalidArgumentException.
  • Check format of directory;
    if it is invalid, throw InvalidArgumentException.
  • Check if directory exists;
    if it does not exist, throw NotExistsException.
  • Check READ permission on the directory;
    if permission is not granted, throw AuthorizationException.
  • Iterate through the directory entries and match it against the pattern.
  • Check LIST permission on each entry;
    if permission is not granted, throw AuthorizationException.
  • Query directories and add them to the list to be returned. It is non-recursive.
  • Query files and add them to the list to be returned.
  • Query links and add them to the list to be returned.
  • Return maximum limit number of entries starting from offset.

locate

public java.lang.String[] locate(java.lang.String startDir,
                                 java.lang.String pattern,
                                 long limit)
                          throws InternalException,
                                 AuthorizationException,
                                 NotExistsException
Returns list of matching LFNs from all subdirectories of the path given in the first argument.
This method does not resolve * symlinks.
This method doesn not have offset, because traversal of a directory tree is ambiquous, therefor the order of the returned entries cannot defined.

Parameters:
startDir - is for startDir
pattern - is the element we are looking for.
limit - Up to limit result entries to be returned. May not be 0.
Returns:
list of matching entries
Throws:
AuthorizationException - No access right to list the entries or status information.
NotExistsException - The startDir does not exist.
InvalidArgumentException
InternalException -

Semantic description of the method:
The following steps are performed:
  • Check format of the pattern;
    if it is invalid, throw InvalidArgumentException.
  • Check the limit;
    if it is not valid, throw InvalidArgumentException.
  • Check if the path startDir is valid
  • if it is not valid, throws InvalidArgumentException.
  • Check if directory exists
    if it does not exist, throws NotExistsException.
  • Check READ permission on startDir and on each sub-directory;
    if permission is not granted, throw AuthorizationException.
  • Get directories recursively under startDir and query their content.
  • Query files and add them to the list to be returned.
  • Return maximum limit number of entries.

getGuidForLfn

public StringPair[] getGuidForLfn(java.lang.String[] lfns)
                           throws InternalException,
                                  AuthorizationException,
                                  NotExistsException,
                                  InvalidArgumentException
Retrieves list of guids for given Lfns. Both directories and files have guids.

Parameters:
lfns - - lfns we want guid for
Returns:
list of guids
Throws:
AuthorizationException - No access right to list the entries or status information.
NotExistsException - The LFN does not exist.
InvalidArgumentException
InternalException -

Semantic description of the method:
The following steps are performed for each entry::

getLfnForGuid

public StringPair[] getLfnForGuid(java.lang.String[] guids)
                           throws InternalException,
                                  AuthorizationException,
                                  NotExistsException,
                                  InvalidArgumentException
Retrieves list of lfns for given guid. Does reverse lookup, returns full path.

Parameters:
guids - list of guids we want lfns for
Returns:
list of lfns/guids
Throws:
AuthorizationException - No access right to list the entries or status information.
NotExistsException - The GUID does not exist.

Semantic description of the method:
The following steps are performed for each entry::
InternalException
InvalidArgumentException

getFileCatalogEntry

public FCEntry[] getFileCatalogEntry(java.lang.String[] lfns)
                              throws InternalException,
                                     AuthorizationException,
                                     NotExistsException
Get the detailed metadata about LFNs.

Parameters:
lfns - the array of strings to get the full status of
Returns:
An array of FCEntry objects
Throws:
AuthorizationException - No access right to list the entries or status information.
NotExistsException - The LFN does not exist.
InternalException -

Semantic description of the method:
The following steps are performed for each entry::
  • Check if format of LFN is valid
    if it is not valid, throws InvalidArgumentException.
  • Check if LFN exists
    if it does not exist, throws NotExistsException.
  • Check LIST permission on the LFN;
    if permission is not granted, throw AuthorizationException.
  • Query catalog for Stat information.
  • Query catalog for Permissions.
  • Return the FCEntry objects.


Copyright © 2004 EU-EGEE