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

All Superinterfaces:
FASBase, ServiceBase
All Known Subinterfaces:
MetadataCatalog

public interface MetadataSchema
extends FASBase

The middleware level API for handling schemas 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 addSchemaAttributes(java.lang.String schemaName, Attribute[] attributes)
          Adds new attributes to an existing schema.
 void createSchema(java.lang.String schemaName, Attribute[] attributes)
          Creates a new schema in the catalog.
 Attribute[] describeSchema(java.lang.String schemaName)
          Get the full description of an existing schema in the catalog.
 void dropSchema(java.lang.String schemaName)
          Drops an existing schema from the catalog.
 java.lang.String[] listSchemas()
          Lists all existing schemas in the catalog.
 void removeSchemaAttributes(java.lang.String schemaName, java.lang.String[] attributeNames)
          Removes attributes from an existing schema.
 
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

createSchema

public void createSchema(java.lang.String schemaName,
                         Attribute[] attributes)
                  throws AuthorizationException,
                         ExistsException,
                         InvalidArgumentException,
                         InternalException
Creates a new schema in the catalog.

A schema is a group of attributes. A schema has a name so that this group can be easily refered to. Each of this attributes will have its own name, type and value.

Schemas MUST be unique within the catalog.

An item/entry inside the catalog is associated with a schema. When a client queries or updates the attributes of an item/entry, these must be contained in the associated schema.

Parameters:
schemaName - The name of the new schema.
attributes - The list of attributes to associate with the new schema. This is a list of Attribute objects. Each object MUST have the name and type fields filled in. The value field in the MAY be used for having default values.
Throws:
AuthorizationException - No access for client to create new schemas.
ExistsException - A schema with the same name already exists in the catalog, or there is more than one attribute with the same name in the list of attributes given.
InvalidArgumentException - One of the attributes given is invalid. It may be due to an invalid attribute name (i.e. empty), or the type given not being supported in the catalog.
InternalException - Any other error on the server side (i.e. database down).

Semantic description of the method:
First steps performed:
  • Check if client is authorized to create new schemas:
    if it is not, throw AuthorizationException.
  • Check if a schema with the same name already exists in the catalog:
    if it does, throw ExistsException.
The following additional steps should be performed for each attribute:
  • Check if the attribute type given is supported by the backend:
    if it is not, throw InvalidArgumentException.
  • Check if the attribute name given already exists in the same schema in the request - this is a check for repeated attributes:
    if it does, throw ExistsException.
Create the new schema in the catalog.
See Also:
Attribute, org.glite.data.catalog.service.meta

addSchemaAttributes

public void addSchemaAttributes(java.lang.String schemaName,
                                Attribute[] attributes)
                         throws AuthorizationException,
                                NotExistsException,
                                ExistsException,
                                InvalidArgumentException,
                                InternalException
Adds new attributes to an existing schema.

Attributes MUST be unique within the whole catalog, so there is no way of creating an attribute with a different type than an attribute with the same name in another schema.

The schemaName is the name of the schema where attributes should be added. The attributes parameter is simply a list of Attribute objects where the name and type field MUST be filled in, and the value field MAY be used by the implementation to have default values for attributes in the schema.

Parameters:
schemaName - The name of the schema to add the attributes.
attributes - The attributes to be added to the schema. The name and type fields MUST to be specified. The value field in the Attribute object MAY be used if a default value is to exist.
Throws:
AuthorizationException - No access for client to add attributes to the schema.
NotExistsException - The given schema does not exist in the catalog.
ExistsException - There is already one attribute in the schema with the same name as one of the attributes in the list given. Or there is more than one attribute with the same name in the list.
InvalidArgumentException - One of the attributes given is invalid. It may be due to an invalid attribute name (i.e. empty), or the type given is not supported in the catalog.
InternalException - Any other error on the server side (i.e. database down).

Semantic description of the method:
First steps performed:
  • Check if client is authorized to add attributes to the schema:
    if it is not, throw AuthorizationException.
  • Check if the given schema name exists in the catalog:
    if it does not, throw NotExistsException.
The following additional steps are performed for each attribute:
  • Check if an attribute with the same name already exists in the schema or on of the other attributes in the request:
    if it does, throw ExistsException.
  • Check if the name and type given for the attribute are valid in the catalog:
    if one of them is not, throw InvalidArgumentException.
Add the new attributes to the schema.
See Also:
Attribute, org.glite.data.catalog.service.meta

removeSchemaAttributes

public void removeSchemaAttributes(java.lang.String schemaName,
                                   java.lang.String[] attributeNames)
                            throws AuthorizationException,
                                   NotExistsException,
                                   InternalException
Removes attributes from an existing schema.

The semantics of the removal process are up to the implementation to decide. It can remove the attribute from the schema even if there are items/entries in the catalog with values set for it. Or it can decide to remove only if there are no items/entries actually using this attribute at the time - none has the value set. It can also decide to remove an attribute from a schema when no item/entry in the catalog is associated with that same schema at the time of the request.

The schemaName is the name of the schema where the attributes will be removed. The attributeNames is simply a list of the names of the attributes that should be removed from the schema.

Parameters:
schemaName - The name of the schema where the attributes should be removed.
attributeNames - The names of the attributes to be removed from the schema.
Throws:
AuthorizationException - No access for removing attributes from the schema.
NotExistsException - The given schema or one of the attributes given does not exist in the catalog.
InternalException - Any other error on the server side (i.e. database down).

Semantic description of the method:
First steps performed:
  • Check if client is authorized to remove attributes from the schema:
    if it is not, throw AuthorizationException.
  • Check if the given schema exists in the catalog:
    if it does not, throw NotExistsException.

The following additional steps are performed for each attribute:
  • Check if the attribute exists in the given schema:
    if it does not, throw NotExistsException.
Remove the attributes from the schema.
See Also:
org.glite.data.catalog.service.meta

dropSchema

public void dropSchema(java.lang.String schemaName)
                throws AuthorizationException,
                       NotExistsException,
                       InternalException
Drops an existing schema from the catalog.

The semantics of this operation are up to the implementation. It may be that a schema can only be droped if no items/entries in the catalog are associated with it at the time of the request. Or it may be that schemas are dropped even when there are items/entries associated with them. This would mean the existing metadata would be lost.

The schemaName is the name of the schema to be droped from the catalog.

Parameters:
schemaName - The name of the schema that should be droped from the catalog.
Throws:
AuthorizationException - No access for client to drop the schema.
NotExistsException - The given schema does not exist in the catalog.
InternalException - Any other error on the server side (i.e. database down).

Semantic description of the method:
The following steps are performed:
  • Check if the client is authorized to drop schemas:
    if it is not, throw AuthorizationException.
  • Check if the given schema name exists in the catalog:
    if it does not, throw NotExistsException.
  • Remove the schema from the catalog.
See Also:
org.glite.data.catalog.service.meta

listSchemas

public java.lang.String[] listSchemas()
                               throws AuthorizationException,
                                      InternalException
Lists all existing schemas in the catalog.

The list returned contains only the names of the schemas, not the whole description. To get the details on each of the schemas in the catalog, an additional request should be made to describeSchema(java.lang.String), where all the attributes and their descriptions will be returned.

Returns:
An array with the name of each existing schema in the catalog. null if there are no schemas in the catalog.
Throws:
AuthorizationException - No access to list schemas for the client.
InternalException - Any other error on the server side (i.e. database down).

Semantic description of the method:
The following steps are performed:
  • Check if client is authorized to list the existing schemas in the catalog:
    if she is not, throw AuthorizationException.
  • Return the list of schemas.
  • See Also:
    describeSchema(String), org.glite.data.catalog.service.meta

    describeSchema

    public Attribute[] describeSchema(java.lang.String schemaName)
                               throws AuthorizationException,
                                      NotExistsException,
                                      InternalException
    Get the full description of an existing schema in the catalog.

    A schema is described by the attributes it contains. Each of these attributes is represented as a Attribute object, so the description of a schema is simply a list of Attribute objects.

    The schemaName is the name of the schema to return the description.

    Parameters:
    schemaName - The name of the schema to return the description.
    Returns:
    A list of Attribute objects fully describing all elements of the schema. Each of these objects MUST have the name and type fields filled in. The value type MAY also be used, but only when the implementation wants to get default values for attributes in schemas. Returns null when the schema contains no attributes.
    Throws:
    AuthorizationException - No access for client to get the schema description.
    NotExistsException - The schema requested does not exist in the catalog.
    InternalException - Any other error on the server side (i.e. database down).

    Semantic description of the method:
    The following steps are performed:
    • Check if the client is authorized to get the schema description:
      if it is not, throw AuthorizationException.
    • Check if the given schema exists in the catalog:
      if it does not, throw NotExistsException.
    • Return the list of attributes for the schema.


    Copyright © 2004 EU-EGEE