org.glite.data.catalog.service.replica
Interface ReplicaCatalog

All Superinterfaces:
FASBase, ServiceBase
All Known Subinterfaces:
FiremanCatalog

public interface ReplicaCatalog
extends FASBase

The middleware level API for the SURLStat Catalog component. This is the interface that this service exposes to the other middleware components, not directly to the user.

Invariant for RCEntry

Stereotype:
simple-interface

Method Summary
 void addGuidReplica(java.lang.String guid, SURLEntry[] newSurls)
          Adds a list of new SURLs for existing entry in the catalog, keyed on the GUID.
 void createGuid(RCEntry[] entries)
          Creates a set of new mappings in the Replica catalog.
 Permission getDefaultGlobalPermission()
          Gets the global default permissions.
 Permission getDefaultPrincipalPermission(java.lang.String principal)
          Get the default permissions for user.
 StringPair[] getGuidForSurl(java.lang.String[] surls)
          Returns the {SURL,GUID} pair for a given SURL.
 GUIDStat[] getGuidStat(java.lang.String[] guids)
          Gets list of GUIDStat {see @GUIDStat} objects for given GUID.
 StringPair[] getMasterReplica(java.lang.String[] guids)
          Returns the master SURL for a given GUID.
 SURLEntry[] getSurlStat(java.lang.String[] surls)
          Gets list of SURLStat objects for given SURLs
 StringBoolean[] hasGuid(java.lang.String[] guids)
          Convenience method to check the existence of a GUID in the catalog.
 RCEntry[] listReplicasByGuid(java.lang.String[] guids, boolean withPermissions)
          Returns list of all valid RCEntry for given list of GUIDs.
 StringPair[] listSurlsByGuid(java.lang.String[] guids)
          Returns list {GUID,SURL} pairs for given GUIDs.
 void removeGuid(java.lang.String[] guids)
          Removes GUID with all existing mappings from the catalog.
 void removeGuidReplica(StringPair[] guidSurls, boolean removeGuidOnLastReplica)
          Removes specified mappings.
 void setDefaultGlobalPermission(Permission defaultPermission)
          Sets the global default permissions.
 void setDefaultPrincipalPermission(java.lang.String principal, Permission defaultPermission)
          Default permissions for user.
 void setMasterReplica(StringPair[] guidSurls)
          Sets one of existing SURLs as master for a given guid.
 void updateGuidStat(java.lang.String[] guids, GUIDStat[] stats)
          Bulk method to update GUID stat objects.
 void updateStatus(java.lang.String[] guids, int status, int mask)
          Set the status flags for the given GUID.
 void updateSurlStat(java.lang.String guid, SURLEntry[] surlStats)
          Sets SURLStat objects on a given GUID.
 
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

createGuid

public void createGuid(RCEntry[] entries)
                throws InternalException,
                       AuthorizationException,
                       ExistsException,
                       InvalidArgumentException
Creates a set of new mappings in the Replica catalog. The RCEntry object contains the GUID, its stat and a list of SURLEntry objects giving all information about the SURLs associated with the given GUID.
Permissions are set in the GUIDStat object of the entry. If they are kept empty, defaults are taken.

Parameters:
entries - list of mapping entities (RCEntry)
Throws:
AuthorizationException - No right to add new entries.
ExistsException - A SURL or GUID already exists in the catalog.
InvalidArgumentException - The status information in the entry is invalid.
InternalException -

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

addGuidReplica

public void addGuidReplica(java.lang.String guid,
                           SURLEntry[] newSurls)
                    throws InternalException,
                           AuthorizationException,
                           ExistsException,
                           InvalidArgumentException
Adds a list of new SURLs for existing entry in the catalog, keyed on the GUID.

Parameters:
guid - existing GUID we add SURLS for
newSurls - list of new SurlStats for an already existing GUID
Throws:
AuthorizationException - No right to add new SURLs to an existing replica.
ExistsException - The GUID-SURL pair already exists.
InvalidArgumentException - The status information for the new SURL is invalid.
InternalException -

Semantic description of the method:
The following steps are performed:
  • Checks if GUID and SURL'S are valid
    if it is not valid, throws InvalidArgumentException
  • Check if GUID exist;
    if it does not exist, throws NotExistsException.
  • Check SET_METADATA permission on GUID;
    if permission is not granted, throws AuthorizationException.
  • For each SURL entries, check if it exists;
    if it exists, throws ExistsException.
  • Check if there is maximum one master replica among the new SURLs;
    if there is more, throws InvalidArgumentException
  • Update catalog by adding surls to GUID in the catalog.
    Master replica setting overrides the setting of the existing SURLs in the catalog.

updateGuidStat

public void updateGuidStat(java.lang.String[] guids,
                           GUIDStat[] stats)
                    throws InternalException,
                           AuthorizationException,
                           InvalidArgumentException,
                           NotExistsException
Bulk method to update GUID stat objects.

Parameters:
guids - list of GUIDs to update
stats - list of GUIDStat containing the update
Throws:
AuthorizationException - No right to update the replica status information.
InvalidArgumentException - The status information for the GUID is invalid.
NotExistsException - The GUID does not exists.
InternalException -

Semantic description of the method:
The following steps are performed for each Entry:
  • Checks if GUIDStat is valid
    if it is not valid, throws InvalidArgumentException
  • Check if GUID exists;
    if it does not exist, throws NotExistsException
  • Check SET_METADATA permissions for the GUID;
    if permission is not granted, throws AuthorizationException.
  • Update GUIDStat in the catalog; creationTime is ignored (not updated in the catalog).

updateSurlStat

public void updateSurlStat(java.lang.String guid,
                           SURLEntry[] surlStats)
                    throws InternalException,
                           AuthorizationException,
                           InvalidArgumentException,
                           NotExistsException
Sets SURLStat objects on a given GUID.

Parameters:
guid - GUID to set SURLStat for
surlStats - generic properties of a lsit of SURLs to be set
Throws:
AuthorizationException - No right to update the replica status information.
InvalidArgumentException - The status information for the SURL is invalid.
NotExistsException - The GUID or a SURL does not exists.
InternalException -

Semantic description of the method:
The following steps are performed:

setMasterReplica

public void setMasterReplica(StringPair[] guidSurls)
                      throws InternalException,
                             AuthorizationException,
                             NotExistsException,
                             InvalidArgumentException
Sets one of existing SURLs as master for a given guid.

Parameters:
guidSurls - list of StringPair objects. The first string is the GUID, the second the master SURL to be set.
Throws:
AuthorizationException - No right to update the replica status information.
NotExistsException - Either the GUID does not exist or the given SURL is not a registered replica of the GUID.
InvalidArgumentException - The GUID or SURL of an entry is malformed.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check if GUID and corresponding SURL exist;
    if either one of them does not exist, throws NotExistsException.
  • Check if GUID and corresponding SURL are valid;
    if either one of them is not valid, throws InvalidArgumentException
  • Check SET_METADATA permission on GUID;
    if permission is not granted, throws AuthorizationException.
  • Update catalog, set SURL to be the master replica of the given GUID.

updateStatus

public void updateStatus(java.lang.String[] guids,
                         int status,
                         int mask)
                  throws InternalException,
                         AuthorizationException,
                         InvalidArgumentException,
                         NotExistsException
Set the status flags for the given GUID.

Parameters:
guids - GUIDs to set status for.
status - The status flag to set or cleared.
mask - The mask for the status bits to be set or cleared.
Throws:
AuthorizationException - No right to update the replica status information.
InvalidArgumentException - The status information for the SURL is invalid.
NotExistsException - The GUID to update does not exist.
InternalException -

Semantic description of the method:
The following steps are performed for each Entry:
  • Check if GUID is valid;
    if it is not valid, throws InvalidArgumentException.
  • Check if GUID exists;
    if it does not exist, throws NotExistsException.
  • Check SET_METADATA permissions for the GUID;
    if permission is not granted, throws AuthorizationException.
  • Get current Status from the catalog.
  • Mask status bits.
  • Update GUID Status in the catalog.

removeGuidReplica

public void removeGuidReplica(StringPair[] guidSurls,
                              boolean removeGuidOnLastReplica)
                       throws InternalException,
                              AuthorizationException,
                              NotExistsException,
                              InvalidArgumentException
Removes specified mappings. Each string pair contains a mapping to be removed.

Parameters:
guidSurls - list of StringPair objects. The first string is the GUID, the second is the SURL to be removed.
removeGuidOnLastReplica - tells the catalog whether the GUID should be removed if the last SURL is removed.
Throws:
AuthorizationException - No right to remove a replica from the given GUID.
NotExistsException - Either the GUID does not exist or the given SURL is not a registered replica of the GUID.
InvalidArgumentException - The GUID or SURL of an entry is malformed.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check if GUID and corresponding SURL are valid;
    if either one of them is not valid, throws InvalidArgumentException.
  • Check if GUID and corresponding SURL exist;
    if any of them does not exist, throws NotExistsException.
  • Check SET_METADATA permission on GUID;
    if permission is not granted, throws AuthorizationException.
  • Check if the SURL in the list is the Master one;
    if it is the Master and it is not the last replica, throws InvalidArgumentException.
  • Remove SURL of GUID from the catalog.
  • Check if the removeGuidOnLastReplica is set;
    if it is set and it was the last replica, then continue, otherwise return.
  • Check REMOVE permission on GUID;
    if permission is not granted, throws AuthorizationException.
  • Remove GUID.

removeGuid

public void removeGuid(java.lang.String[] guids)
                throws InternalException,
                       AuthorizationException,
                       NotExistsException,
                       InvalidArgumentException
Removes GUID with all existing mappings from the catalog.

Parameters:
guids - The replica entries to be removed.
Throws:
AuthorizationException - No right to remove the replica entry from the catalog.
NotExistsException - The GUID does not exist.
InternalException -

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

setDefaultPrincipalPermission

public void setDefaultPrincipalPermission(java.lang.String principal,
                                          Permission defaultPermission)
                                   throws InternalException,
                                          AuthorizationException,
                                          InvalidArgumentException
Default permissions for user. Defaults to be used for newly created GUIDs where the GUIDStat object does not contain any permissions. If the user does not have default user permissions set, the global permissions are used, see setDefaultGlobalPermission. Sets permission policy for a user used while creating new RCEntries with no permissions specified.
For detailed description of the default permimssions semantics see Virtual Directory Tree of Permissions.

Parameters:
defaultPermission - - permission object to be used while no permissions are specified
Throws:
AuthorizationException - No access right to update the default user permissions.
InvalidArgumentException - The permission settings are invalid.
InternalException -

Semantic description of the method:
The following steps are performed:
  • Check the validity of permission settings;
    if it is invalid, throws InvalidArgumentException.
  • Check WRITE permission on default user permission entry;
    if permission is not granted, throws AuthorizationException.
  • Set new user default permission details in the catalog.
See Also:
Virtual Directory Tree of Permissions

setDefaultGlobalPermission

public void setDefaultGlobalPermission(Permission defaultPermission)
                                throws InternalException,
                                       AuthorizationException,
                                       InvalidArgumentException
Sets the global default permissions. If a user does not have its own default permissions, these global permissions are used for new entries if no permission is specified. For detailed description of the default permimssions semantics see Virtual Directory Tree of Permissions.

Parameters:
defaultPermission - - permission object to be used while no permissions are specified and user in a context has not defaults set
Throws:
AuthorizationException - No access right to update the default permissions.
InvalidArgumentException - The permission settings are invalid.
InternalException -

Semantic description of the method:
The following steps are performed:
  • Check the validity of permission settings;
    if it is invalid, throws InvalidArgumentException.
  • Check WRITE permission on default global permission entry;
    if permission is not granted, throws AuthorizationException.
  • Update global default permission details in the catalog.

getGuidForSurl

public StringPair[] getGuidForSurl(java.lang.String[] surls)
                            throws InternalException,
                                   AuthorizationException,
                                   NotExistsException,
                                   InvalidArgumentException
Returns the {SURL,GUID} pair for a given SURL.

Returns:
the {SURL,GUID} pair for a given SURL.
Throws:
AuthorizationException - No access right to list the GUID for a given SURL.
NotExistsException - The SURL does not exist.
InvalidArgumentException - Invalid SURL.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check the format of the SURL;
    if it is invalid, throws InvalidArgumentException.
  • Check if SURL exist;
    if it does not exist, throws NotExistsException.
  • Check LIST permission on the corresponding GUID;
    if permission is not granted, throws AuthorizationException.
  • Query GUID for the surl from the catalog and add it to the list to be returned.

getMasterReplica

public StringPair[] getMasterReplica(java.lang.String[] guids)
                              throws InternalException,
                                     AuthorizationException,
                                     NotExistsException,
                                     InvalidArgumentException
Returns the master SURL for a given GUID.

Parameters:
guids - the list of GUIDs to get the master SURL for
Returns:
the Master SURL of a given GUID, as String Pairs. First string is the GUID, second the master SURL.
Throws:
AuthorizationException - No access right to list SURLs for a given GUID.
NotExistsException - The GUID does not exist.
InvalidArgumentException - Invalid GUID.
InternalException -

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

listSurlsByGuid

public StringPair[] listSurlsByGuid(java.lang.String[] guids)
                             throws InternalException,
                                    AuthorizationException,
                                    NotExistsException,
                                    InvalidArgumentException
Returns list {GUID,SURL} pairs for given GUIDs.

Parameters:
guids - - GUID strings we want surls for
Returns:
list of StringPair objects. The first string is the GUID, the second the SURL corresponding to that GUID. If the GUID has more than one SURL, it will be repeated.
Throws:
AuthorizationException - No access right to list SURLs for a given GUID.
NotExistsException - The GUID does not exist.
InvalidArgumentException - Invalid GUID.
InternalException -

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

listReplicasByGuid

public RCEntry[] listReplicasByGuid(java.lang.String[] guids,
                                    boolean withPermissions)
                             throws InternalException,
                                    AuthorizationException,
                                    NotExistsException,
                                    InvalidArgumentException
Returns list of all valid RCEntry for given list of GUIDs.

Parameters:
guids - - list of GUIDs we want valid RCEntries for
Returns:
RCEntry array, only valid SURLs.
Throws:
AuthorizationException - No access right to list SURLs for a given GUID.
NotExistsException - The GUID does not exist.
InvalidArgumentException - Invalid format of GUID.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check the format of the GUID;
    if it is invalid, throws InvalidArgumentException.
  • Check if GUID exists;
    if it does not exist, throws NotExistsException.
  • Check LIST permission on GUID;
    if permission is not granted, throws AuthorizationException.
  • Add permission to RCEntry if 'withPermissions' flag is set to true;
  • Add all the replica data from the catalog and add them to the RCEntry list to be returned;

hasGuid

public StringBoolean[] hasGuid(java.lang.String[] guids)
                        throws InternalException,
                               InvalidArgumentException,
                               AuthorizationException
Convenience method to check the existence of a GUID in the catalog.

Parameters:
guids - the list of GUIDs to check
Returns:
true or false depending whether the GUID exists or not
Throws:
AuthorizationException - No access right to list the catalog.
InvalidArgumentException - Invalid format of GUID.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check the format of the GUID;
    if it is invalid, throws InvalidArgumentException.
  • Check if GUID exists and check LIST permission on GUID;
    if it exists and permission is granted add true to the list to be returned.
    if it does not exist or permission is not granted add false to the list to be returned.

getGuidStat

public GUIDStat[] getGuidStat(java.lang.String[] guids)
                       throws InternalException,
                              AuthorizationException,
                              NotExistsException,
                              InvalidArgumentException
Gets list of GUIDStat {see @GUIDStat} objects for given GUID.

Parameters:
guids - GUID we want stats for
Returns:
GUIDStat object
Throws:
AuthorizationException - No access right get status information for a given GUID.
InvalidArgumentException - Invalid format of GUID.
NotExistsException - The GUID does not exist.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check the format of the GUID;
    if it is invalid, throws InvalidArgumentException.
  • Check if GUID exists;
    if it does not exist, throws NotExistsException.
  • Check LIST permission on GUID;
    if permission is not granted, throws AuthorizationException.
  • Fill up the GUIDStat object with GUID stats and add it to the list to be returned.

getSurlStat

public SURLEntry[] getSurlStat(java.lang.String[] surls)
                        throws InternalException,
                               AuthorizationException,
                               NotExistsException,
                               InvalidArgumentException
Gets list of SURLStat objects for given SURLs

Parameters:
surls - list of SURLs we want stats for
Returns:
SURLEntry list
Throws:
InvalidArgumentException - Invalid format of SURL
AuthorizationException - No access right to list the GUID for a given SURL.
NotExistsException - Either the GUID does not exist or the given SURL is not a registered replica of the GUID.
InternalException -

Semantic description of the method:
The following steps are performed for each entry:
  • Check the format of the SURL;
    if it is invalid, throws InvalidArgumentException.
  • Check if SURL exists;
    if it does not exist, throws NotExistsException.
  • Check LIST permission on corresponding GUID;
    if permission is not granted, throws AuthorizationException.
    Query stat details of SURL from the catalog and add it to the list to be returned;

getDefaultPrincipalPermission

public Permission getDefaultPrincipalPermission(java.lang.String principal)
                                         throws InternalException,
                                                AuthorizationException,
                                                InvalidArgumentException
Get the default permissions for user. Defaults to be used for newly created GUIDs where the GUIDStat object does not contain any permissions. If the user does not have is default user permissions set, the global permissions are used. If the user cannot be detected, default global permissions are used. For detailed description of the default permimssions semantics see Virtual Directory Tree of Permissions

Returns:
defaultPermission - permission object to be used while no permissions are specified
Throws:
AuthorizationException - No access right to get the default user permissions.
InternalException -

Semantic description of the method:
The following steps are performed:
  • Check READ permission on default user permission entry;
    if permission is not granted, throws AuthorizationException.
  • Query user default permission details from the catalog and return it.
InvalidArgumentException
See Also:
getDefaultGlobalPermission()

getDefaultGlobalPermission

public Permission getDefaultGlobalPermission()
                                      throws InternalException,
                                             AuthorizationException
Gets the global default permissions. If a user does not have its own default permissions, these global permissions are used for new entries if no permission is specified. For detailed description of the default permimssions semantics see Virtual Directory Tree of Permissions

Returns:
defaultPermission - permission object to be used while no permissions are specified and user in a context has not defaults set
Throws:
AuthorizationException - No access right to get the default permissions.
InternalException -

Semantic description of the method:
The following steps are performed:
  • Check READ permission on default global permission entry;
    if permission is not granted, throws AuthorizationException.
  • Query global default permission details from the catalog and return it.


Copyright © 2004 EU-EGEE