org.glite.data.catalog.service.meta
Interface MetadataBase

All Superinterfaces:
ServiceBase
All Known Subinterfaces:
FiremanCatalog, MetadataCatalog

public interface MetadataBase
extends ServiceBase

The middleware level API for handling attributes of individual items/entries in the Metadata Catalog component. This is the interface that the service exposes to the other middleware components, which is not necessarily the final API seen by the user.


Method Summary
 void clearAttributes(java.lang.String item, java.lang.String[] attributeNames)
          Clears the values for a group of attributes.
 Attribute[] getAttributes(java.lang.String item, java.lang.String[] attributeNames)
          Gets a group of attributes of a given item/entry.
 Attribute[] listAttributes(java.lang.String item)
          List all attributes associated with an entry.
 java.lang.String[] query(java.lang.String query, java.lang.String type, int limit, int offset)
          Performs a generic query on the catalog, returning the corresponding item's identifiers.
 void setAttributes(java.lang.String item, Attribute[] attributes)
          Sets the values for a group of attributes of an item/entry.
 
Methods inherited from interface org.glite.data.catalog.service.ServiceBase
getInterfaceVersion, getSchemaVersion, getServiceMetadata, getVersion
 

Method Detail

setAttributes

public void setAttributes(java.lang.String item,
                          Attribute[] attributes)
                   throws AuthorizationException,
                          NotExistsException,
                          InvalidArgumentException,
                          InternalException
Sets the values for a group of attributes of an item/entry.

The item is the string that uniquely identifies the entry in the catalog. It can be a GUID, an LFN, or any other type of identifier. The attributes parameter is a list (array) of Attribute objects, each containing the necessary information to set the new values.

An implementation can choose to offer pure POSIX xattrs semantics, allowing on the fly creation of attributes when they do not yet exist. The type field in each Attribute object should be filled in this case. Or it may not support this feature, and the type field can be left null.

Parameters:
item - The item/entry in the catalog where the values should be set.
attributes - A list of Attribute objects containing the name/type/value to be set. Both the name and value fields in the Attribute object MUST be given.
Throws:
AuthorizationException - No access right to update values of attributes.
NotExistsException - The entry/item or one of the attributes specified does not exist.
InvalidArgumentException - One of the name/type pairs given for an attribute is invalid - case of on-the-fly creation of attributes, where the type given is unsupported by the backend. Or one of the attribute's values is invalid - while trying to update values.
InternalException - Any other error on the server side (i.e. database down).

Semantic description of the method:
First steps performed: The following additional steps are performed for each attribute:
  • Check if attribute exists in the catalog. If it does not, what happens next depends on the implementation:
    if on-the-fly creation of attributes is supported, an additional step for checking if the attribute's type is supported by the backend should be done. If it is not, throw InvalidArgumentException.
    if this feature is not supported, throw NotExistsException.
  • Check validity of value given for the attribute (depends on the type):
    if invalid, throw InvalidArgumentException.
Set the values of the attributes.
See Also:
Attribute, org.glite.data.catalog.service.meta

clearAttributes

public void clearAttributes(java.lang.String item,
                            java.lang.String[] attributeNames)
                     throws AuthorizationException,
                            NotExistsException,
                            InternalException
Clears the values for a group of attributes.

The item is the unique identifier of items/entries in the catalog. It can be a GUID, an LFN, or any other kind of string identifier. The attributeNames is a list of the names of the attributes inside the catalog.

Parameters:
item - The item/entry where attributes should be cleared.
attributeNames - An array containing the names of the attributes to be cleared.
Throws:
AuthorizationException - No access right to update values of attributes.
NotExistsException - The item/entry or one of the attributes specified does not exist.
InternalException - Any other error on the server side (i.e. database down).

Semantic description of the method:
First steps performed: The following steps are performed for each attribute name:
  • Check if there is an attribute in the catalog with the given name:
    if there is none, throw NotExistsException.
Clear the values of the attributes.
See Also:
org.glite.data.catalog.service.meta

getAttributes

public Attribute[] getAttributes(java.lang.String item,
                                 java.lang.String[] attributeNames)
                          throws AuthorizationException,
                                 NotExistsException,
                                 InternalException
Gets a group of attributes of a given item/entry.

The item is the unique identifier of items/entries in the catalog. It can be a GUID, an LFN, or any other kind of string identifier. The attributeNames is a list of the names of the attributes inside the catalog.

Parameters:
item - The item/entry in the catalog for which the given attributes should be returned.
attributeNames - The names of the attributes to return the values.
Returns:
A list of Attribute objects containing the requested values. Each Attribute object MUST contain the name and value filled in, and MAY contain the type filled in - but not necessarily. Returns null if there is no attribute in the catalog with any of the given names.
Throws:
AuthorizationException - No access right to access attributes for this item.
NotExistsException - The item/entry or one of the attributes specified does not exist.
InternalException - Any other error on the server side (i.e. database down).

Semantic description of the method:
First steps performed: The following steps are performed for each attribute name requested and are implementation dependent:
  • If an implementation decided to ignore attribute names for which there is no corresponding attribute in the catalog:
    no exception is thrown when one is found.
  • If an implementation restricts queries for existing attributes only:
    throw NotExistsException.

  • There is no inconsistence here, as the method returns Attribute objects, which MUST have both name and value filled. The index in the list of the attribute names given and the one in the list of Attribute objects returned need not be the same.
    The reason for having different semantics is to allow implementation to do one-shot queries in the backend, where the result is either all values for the attributes or an error if at least one of the attributes does not exist.
Return the attributes requested.
See Also:
Attribute, org.glite.data.catalog.service.meta

listAttributes

public Attribute[] listAttributes(java.lang.String item)
                           throws AuthorizationException,
                                  NotExistsException,
                                  InternalException
List all attributes associated with an entry.

The item passed in the request is the unique identifier of the entry in the catalog.

Although the semantics of the method involve returning the names and types of the attributes inside the catalog associated with a given entry, an implementation MAY decide to include the values of the attributes inside each Attribute object in the returned list.

All attributes associated with the entry MUST be returned - including the ones with no value set.

Parameters:
item - The item/entry to list the attributes.
Returns:
An array of Attribute objects where the name and the type MUST be filled. Optionally, the value MAY also be filled, allowing a behaviour similar to a single-shot getAllAttributes operation - that does not exist in this interface. Returns null if the item/entry has no attributes.
Throws:
AuthorizationException - No access right to access attributes for this entry/item.
NotExistsException - The item/entry specified does not exist.
InternalException - Any other error on the server side (i.e. database down).

Semantic description of the method:
The following steps are performed: Return the attributes.
See Also:
Attribute, org.glite.data.catalog.service.meta

query

public java.lang.String[] query(java.lang.String query,
                                java.lang.String type,
                                int limit,
                                int offset)
                         throws InternalException,
                                AuthorizationException,
                                InvalidArgumentException
Performs a generic query on the catalog, returning the corresponding item's identifiers.

The query is simply a string that has to be understood by the service. For example, if the catalog has a backend talking SQL, then this string should be a valid SQL query. The limit is the number of records to be returned in a single request. The offset is the number of records that should be ignored from the beginning of the whole resultset of the query.

The method returns the identifiers of all items corresponding to the given query. These identifiers are strings, each being a GUID, an LFN, or any other unique string identifier. The number of these items returned in each call to the service can be:
the limit provided in the query, if the number of items corresponding to the query minus the offset is bigger than this limit.
the number of items left, when the total number of items corresponding to the query minus the offset is smaller than the limit provided.

The service also enforces its own limits, so the maximum number of items returned in each single call can be checked by calling ServiceBase.getServiceMetadata(java.lang.String) and asking for the query limit parameter.

Finally, if the service has the ability to handle schemas, the query string MUST contain the scope of the query. In example, for a SQL backend, where the schemas are mapped to tables in the database, the scope of the query is defined in the FROM part of the SQL query.

Parameters:
query - The query itself, which is simply a string that the catalog understands (SQL query, XPATH query, ...).
type - The type of query presented in the query string. This has to correspond to one of the query types the catalog understands, and will typically be 'SQL', 'XPATH', . It is up to the implementation to define which query types it supports.
limit - The maximum number of items to be returned. Should always be above or equal to 0 and below the service limit. A value of 0 means no limit, which in practice means only the system limit should be enforced.
offset - The offset for the items returned, used to iterate between results when doing repetitive calls with the same query.
Returns:
The string identifiers of all items corresponding to the given query. null if there are no items to be returned. This happens when the offset is above the total number of items corresponding to the query, and is the condition for checking the end of the iteration through the results.
Throws:
AuthorizationException - No access right to list the entries.
InvalidArgumentException - The query string given is invalid, or the query type is invalid, or the limit given is invalid (below 0 or above the system limit), or the offset is invalid (below 0).
InternalException - Any other error on the server side (i.e. database down).

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


Copyright © 2004 EU-EGEE