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 first part
{@link org.glite.data.catalog.service} contains the base interface
{@link org.glite.data.catalog.service.ServiceBase}
which contains all methods common to all catalog
interfaces (like getting the catalog version) and all complex types
that are common to all catalog interfaces (like permissions). Also the
exceptions (which are mapped to SOAP faults) are listed in this part.
- Package {@link org.glite.data.catalog.service.file} contains the
{@link org.glite.data.catalog.service.file.FileCatalog} interface and some associated structures.
- Package {@link org.glite.data.catalog.service.replica} contains the
{@link org.glite.data.catalog.service.replica.ReplicaCatalog} interface and some associated structures.
- Package {@link org.glite.data.catalog.service.meta} contains the interfaces
associated with the {@link org.glite.data.catalog.service.meta.MetadataCatalog Metadata Catalog}.
- Package {@link org.glite.data.catalog.service.fas} contains the
{@link org.glite.data.catalog.service.fas.FAS File Access Service} interface and some associated structures.
- Package {@link org.glite.data.catalog.service.composite} contains the
composite catalog interface called {@link org.glite.data.catalog.service.composite.FiremanCatalog}
(short for FIle REplica catalog MANager). This interface adds functionality to
the file and replica catalog interfaces by coordinating their use.
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
directory
0
file
1
symlink
2
virtual directory
3
system object
4, internal
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.
- limit for listing operations
- admin DN or attribute
- exception handling policy (bulk, simple batch, greedy batch -- see below)
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:
- query methods return at the first error/exception
- update methods has no return value, and may define exception handling policy
Exception Handling Policies
There are three possible expection handling policies in a service implementation:
- 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.
- 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.
- 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
- owner is DN
- if copyPermFromParent is set, then group is inherited from the parent directory
- otherwise, group is first VOMS attribute
- if no VOMS attribute, then group from user default
- if no user default, then group from global default
Permission on new entry
- if copyPermFromParent is set, then copy permissions from the parent directory
(e.g. 'true' for HOME and 'false' for /tmp)
- otherwise, permissions from the user default
- if there is no user default, then permissions from global default
Global defaults
- If no GUID is given, a new one is created (create operations).
- If time is zero, then use the current system time (same for every element in bulk operations).
- If time is less than 1000 (time is given in miliseconds), then throws {@link org.glite.data.catalog.service.InvalidArgumentException}.
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
- First step is to check if there is a
/sys/DN
virtual
directory, which describes the defaults for the user.
- 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
.
- 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 permission | Catalog permission |
read | read |
list |
getMetadata |
write | write |
permission |
remove |
setMetadata |
execute | execute |
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}.