File and Replica Catalogs.

This section contains all catalog interfaces and structures (complex types) used in the interface. The catalogs are structured into several sub-namespaces. These are The end-user will only use the composite catalog interface (Fireman interface). The other interfaces may be used by power-users who want to implement rich interfaces on top of these existing ones.

Description of Aspects

Predefined values

LFNStat types

Method Call Semanitcs

Return conventions

The key is always returned with the data, and it is string1 if the returned type is {@link org.glite.data.catalog.service.StringPair}.

Limit and Offset

Methods returning an unknown number of elements have limit and offset parameters, which can be used to iterate through all elements in a stateless way.
To iterate through all elements one has to call the method repeatedly until it returns less elements than the specified limit. It may occur that the list operation throws an exception if the user specified limit exceeds the system's internal limit.
The limit cannot be zero, otherwise an exception is thrown.

System metadata

This information can be retrieved using getSystemMetadata() call, but some can be changed only by reconfiguring the service.

Exception Handling

There is a fundamental problem with bulk operations regarding errors or e exceptional conditions: either an exception or (some) result is returned. To solve this problem a simple rule was applied on the methods of the interfaces:

Exception Handling Policies

There are three possible expection handling policies in a service implementation:
  1. bulk operation with transactional semantics: at the first error the whole operation is rolled back; the bulk operation is treated as a single transaction. A method call following this policy may succeed or throw a single exception.
  2. simple batch operation: at the first error the last, unsuccesfull operation is rolled back; each individual operation in the bulk is treated as a separate transaction. A method call following this policy may succeed with some or all of its operations and throw a single exception.
  3. greedy batch operation: it does not stop at the first error, but keeps executing the following operations; each individual operation in the bulk is treated as a single transaction and all of them is executed. A method call following this policy may throw a bulk exception, containing all individual exception, which occured during the bulk operation.
Simple services probably implement bulk or simple batch policy, what they could advertise in their metadata description. More sophisticated services may implement greedy batch policy, or even make the policy a configurable parameter in the service.

Permissions and Ownership

The catalog interfaces utilize a rich set of permission bits (see {@link org.glite.data.catalog.service.Perm}), instead of the simple read, write and execute permissions.

Ownership on new entry

  1. owner is DN
  2. if copyPermFromParent is set, then group is inherited from the parent directory
  3. otherwise, group is first VOMS attribute
  4. if no VOMS attribute, then group from user default
  5. if no user default, then group from global default

Permission on new entry

  1. if copyPermFromParent is set, then copy permissions from the parent directory (e.g. 'true' for HOME and 'false' for /tmp)
  2. otherwise, permissions from the user default
  3. if there is no user default, then permissions from global default

Global defaults


Virtual Directory Tree of Permissions

When a new object (e.g. dangling GUID in ReplicaCatalog) is created without a "parent" object (i.e. directory), then the permission for creation cannot be checked and no defaults could be applied on the new object. The problem is solved by introducing a virtual directory tree of permissions (called /sys).
The root of this tree (/sys) is created at configuration/ installation time, when the backend database is initialized. Initially it only contains the administrator's principal with full permissions. This object can be accessed from the {@link org.glite.data.catalog.service.replica.ReplicaCatalog} by the get/setDefaultGlobalPermission() methods.
Subdirectories in this tree (e.g. /sys/VO or /sys/DN) are created by explicit calls get/setDefaultPrincipalPermission() methods.
Before the new object is created the catalog locates the appropriate virtual parent directory in this tree and uses its permissions to authorize the creation.
After the new object is created the catalog copies the permissions of the parent to the newly created object (see also 'copyFromParent' in mkdir()).
Locating the parent
  1. First step is to check if there is a /sys/DN virtual directory, which describes the defaults for the user.
  2. If there is no such directory and the user has a VOMS credential, then the first VOMS attribute is taken to look for a virtual directory: /sys/VOMS-attribute.
  3. If neither of the above steps succeed, then use the /sys virtual directory as parent.

Mapping to POSIX Permissions

There are differences in semantics, but a simple recommendation is given on how to map permissions from a POSIX implementation to the detailed permissions of the catalog interfaces. The first and simple rule is that the execute permission is being copied, but not used for authorization in the catalogs.
For the rest this table should help:
POSIX permissionCatalog permission
readread
list
getMetadata
writewrite
permission
remove
setMetadata
executeexecute
Setting or clearing a POSIX permission means setting or clearing all coresponding catalog permissions.
Similarly a query for a POSIX permission will only result with a granted permission, if all of the coresponding catalog permissions are set.
See more at {@link org.glite.data.catalog.service.Perm}.