Difference between revisions of "Metadata Manager"

Revision as of 17:37, 5 January 2010

Introduction

The Metadata Manager service manages the modelling of arbitrary metadata relationships (IDB-relationships) in accordance with the gCube Metadata Model. The only assumption it does is that the Metadata Objects are serialized as well-formed XML documents. The service has a two-fold role:

• to manage Metadata Objects and Metadata Collections
• to establish secondary role-typed links. Such relationships can be in place between any type of Information Object and in the scope of a Collection or not

The service relies on the Storage Management Service to persist the information handled.

Clients interacts also with the Metadata Manager library for a higher level of abstraction which simplifies clients interaction with the service.

The Metadata Manager Components

The main functionality of the Metadata Manager components is the management of Metadata Objects, Metadata Collection and their relationships. To deliver these functionalities, two components have been implemented:

• a service, which mainly incorporates the overall logic of the Metadata Manager;
• a client library, helping the service clients to create valid Metadata Objects.

Metadata Manager Service

From an architectural point of view, the Metadata Manager adopts the Factory pattern and Collection Managers are implemented as stateful WS-Resources. The service is composed by:

• MetadataManagerFactory, a portType that creates new Collection Managers and offers some cross-Collection operations
• MetadataManager, a portType that operates over Metadata Collections (MCs) and on Metadata Objects as Elements, i.e. members of a specific Metadata Collection

To operate over Metadata Collections, the service instantiates a Collection Manager (or shortly, Manager) for each collection. A Collection Manager is the access point to all the possible operations over a specific Metadata Collection.

MetadataManagerFactory portType

The MetadataManagerFactory creates new Collection Managers and offers some cross-Collection operations. Moreover, it operates on Metadata Objects as Information Objects related to other Information Objects and not as Members of Metadata Collections.

• EndPointReferenceType createManager(CollectionID, params): This operation takes as input a Content Collection ID and a set of creation parameters. Then, it creates a new Manager in order to manage a Metadata Collection bound to the given Content Collection. If a Metadata Collection with the specified Metadata characteristics does not exist, the Manager creates the Metadata Collection, binds it with the Content Collection and publishes its profile in the IS.

The Creation parameters are a set of key-value pairs; the following keys are defined in the MMLibrary (org.gcube.metadatamanagement.mmlibrary.descriptions.CollectionDescription.CreationParameters) and accepted as parameters:

Mandatory parameters:

• COLLECTIONNAME -> name of the collection
• METADATANAME -> metadata name (e.g. “dc”)
• METADATALANG -> metadata language (e.g. “English”), as specified by the ISO 639-2
• METADATAURI -> metadata URI: the XML Schema that defines the MO payloads
• ROLE -> secondary role
• RELATEDBY_COLLID -> the ID of the Content Collection (it must report the same value of the first parameter of the invocation, i.e. CollectionID)

Optional parameters:

• DESCRIPTION -> description
• INDEXABLE -> if the collection is indexable or not (“True”/”False”), default is true
• USER -> if the collection is a user collection or not (“True”/”False”), default is true
• RELATEDBY_ROLE -> the source XML Schema from which the current one has been generated, if any
• GENERATEDBY_COLLID -> the source Metadata Collection from which the current one has been generated (by the Metadata Broker), if any
• GENERATEDBY_URI -> the URI of the source schema of the collection from which it has been generated, if any

Among the others, two parameters can modify the way in which the Metadata Collection is managed:

• Indexable: if the new Metadata Collection is indexable, the Manager creates also a new XML Index for such a Collection using the XMLIndexer Service;
• User: a user Collection is shown in the Portals and an end-user can operate on it; a non-user Collection is intended for internal purposes (like to collect parts of persisted Indexes).

• ArrayOfMetadata[] getMetadata(MetadataSelector[])

...

• EndPointReferenceType createManagerFromCollection (MetadataCollectionID): This operation takes a Metadata Collection ID. It returns:
  • the related CollectionManager, if it already exists
  • creates a new CollectionManager and returns its EPR, if the Metadata Collection exists
  • an error, if the Collection ID is not valid

• MOID addMetadata(ObjectID, MO, SecondaryRole): This operation takes a new non-collectable Metadata Object and
  • completes the metadata header information (e.g. the MOID, if it is not specified)
  • stores (or updates if the MOID is already included in the MO header) the object on the Storage Management Service as Information Object
  • creates a <is-described-by, <SecondaryRole>> binding in the Storage Management Service between the Metadata Object and the Information Object identified by the given Object ID
  • returns the assigned MOID

• void deleteMetadata(MOID): This operation deletes from the Storage Management Service the Metadata Object identified by the given ID.

• (ObjectID, (MO, SecondaryRole)[])[] getMetadata ((ObjectID, SecondaryRole, CollectionID, Rank)[]): For each given ObjectID, this operation returns the Metadata Objets. They are:
  • bound with the specified secondary role (the primary role is, of course, is-described-by) to the Information Object identified by that ObjectID
  • members of the specified Metadata Collection

MetadataManager portType

The MetadataManager allows user to manipulate a MetadataCollection, the operation provided are:

• String getMetadataCollectionID(): Gets the Metadata Collection identifier
• void deleteCollection(): Deletes the Metadata Collection and destroys the related Collection Manager.
  • The elements are also removed from the storage service, if they do not belong to other Metadata Collections
  • If the MetadataCollection is indexable, it is also destroyed from the XMLIndexer service
• ListOfUpdateElementsResults updateElements(UpdateElements): Updates the given MOs either in the Storage Management and in the XMLIndexer (if the Collection is Indexable)
  • UpdateElements is a list of XML String representation of the MetadataObjects(MOs) to update
  • ListOfUpdateElementsResults is an array of the same cardinality of the input string. Each item is a boolean value reporting true if the MO in the same position in the input array was successfully updates, false otherwise.
• AddElementsResponse addElements(addElements): Adds the given elements to the MetadataCollection
  • addElements is a list, where each item of the list is a valid ID of an IO available in the Storage and a list of new MOs to bind to such IO
  • AddElementsResponse is a list, which is a map with the ID of the IO and the list of MOs bound to it in the operation
• GetElementResponse getElements(InformationObjectIDList):Gets the MOs bound to the by the given MOIDs
• GetElementsFromMOIDResponse getElementsFromMOID(MOIDList): Gets the MOs identified by the given MOIDs
  • MOIDList is a list of MO IDs
  • GetElementsFromMOIDResponse contains the MetadataObjects related to the given IDs
• MOIDList deleteElements(MOIDList): Deletes from storage service the Metadata Object identified by the given ID
  • If the MetadataCollection is indexable it deletes the Metadata Object from the related MetadataXMLIndexer using the XMLindexer service
  • MOIDList is a list with the IDs of MetadataObjects(MOs), in input the IDs to delete, in output it returns the ID of the elements not deleted
• GetAllElementsResponse getAllElements(void): returns all the MOs of the current Metadata Collection
• String addElementsRS(String): Adds the given elements to the MetadataCollection using the ResultSetService
  • the input string is the reference to a RSLocator with the MOs to store, each element of the RS must have the entire MO in its payload
  • the output string is the reference to an RSLocator with a list of the stored MOs' IDs
• String getAllElementsRS(): Returns all the MOs of the current Metadata Collection using the ResultSetService
  • the output String is a reference to an RSLocator with the retrieved elements
• String getElementsRS(String):Gets the list of MOs describing the Information Object included in the input list using the ResultSetService. The returned MOs belong the current Metadata Collection
  • the input string is the reference to an RSLocator with the OIDs
  • the output string is the reference to an RSLocator with the retrieved MOs

MMLibrary

The MMLibrary offers a number of facilities for interacting with the creation and manipulation of Metadata Objects. The library operates at client-side by moving some of the logic on that side avoiding unnecessary interactions between clients and the Metadata Manager service.

Basically, it offers a a set of method to easily wrap an XML documents in the model exchanged format as required by Metadata Manager service. i.e. support for wrapping the Objects with the appropriate metadata envelope, in order to create a valid Metadata Object that can be stored on the Metadata Manager Service.

In addition, the library provides some utility classes to extract the MO information from a string representing a serialized Metadata Object.

Dependencies

The MetadataManager Service depends by the following gCube components:

• MMLibrary
• XMLIndexer
• ResultSetService
• ResultSetLibrary
• ResultSetClientLibrary
• ContentManagement
• ContentManagementService
• ContentManagementLibrary

Usage Examples

This example shows how to create a MetadataManager:

package org.gcube.metadatamanagement.metadatamanager.testsuite;
 
import org.gcube.common.core.contexts.GCUBERemotePortTypeContext;
import org.gcube.common.core.scope.GCUBEScope;
import org.gcube.metadatamanagement.metadatamanager.stubs.CollectionParameter;
import org.gcube.metadatamanagement.metadatamanager.stubs.CreateCollectionParameters;
import org.gcube.metadatamanagement.metadatamanager.stubs.CreateManagerRequest;
import org.gcube.metadatamanagement.metadatamanager.stubs.CreateManagerResponse;
import org.gcube.metadatamanagement.metadatamanager.stubs.MetadataManagerFactoryPortType;
import org.gcube.metadatamanagement.metadatamanager.stubs.service.MetadataManagerFactoryServiceAddressingLocator;
import org.gcube.metadatamanagement.mmlibrary.descriptions.CollectionDescription.CreationParameters;
import org.apache.axis.message.addressing.Address;
import org.apache.axis.message.addressing.EndpointReferenceType;
 
public class CreateManagerTest {
 
	/**
	 * @param args 
	 * <OL>
	 * <LI> Factory URI
	 * <LI> Collection Name
	 * <LI> Scope
	 * <LI> Related Content Collection ID
	 * </OL>
	 */
	public static void main(String[] args) {
 
		if (args.length != 4) {
			System.err.println("Usage: CreateManagerTest <MMFactoryURI> <CollectionName> <Scope> <RelatedContentID>");
			return;
		}
		String factoryURI = args[0];
		String name = args[1];
		String scope = args[2];
		String relatedContentCollectionID = args[3];
 
		MetadataManagerFactoryServiceAddressingLocator factoryLocator = new MetadataManagerFactoryServiceAddressingLocator();
		MetadataManagerFactoryPortType mFactory;
		try {			
			EndpointReferenceType factoryEPR = new EndpointReferenceType();
			factoryEPR.setAddress(new Address(factoryURI));			
			System.out.println("Creating the new Factory portType..");
 
			mFactory= factoryLocator.getMetadataManagerFactoryPortTypePort(factoryEPR);			
 
			CreateManagerRequest request = new CreateManagerRequest();
			request.setCollectionID(relatedContentCollectionID);			
			CollectionParameter [] ss = new CollectionParameter[9];
			CreateCollectionParameters ccp = new CreateCollectionParameters();			
 
			for ( int i =0; i<ss.length; i++ )
				ss[i] = new CollectionParameter();
 
			ss[0].setName(CreationParameters.COLLECTIONNAME.toString());
			ss[0].setValue(name);
			System.out.println("COLLECTIONNAME: "+name);			
 
			// metadatalang, metadataname, metadataformat are all used for MetadataFormat 
			// they are mandatory
			ss[1].setName(CreationParameters.METADATALANG.toString());
			ss[1].setValue("en");
 
			ss[2].setName(CreationParameters.METADATANAME.toString());
			ss[2].setValue("dc");
 
			ss[3].setName(CreationParameters.METADATAURI.toString());
			ss[3].setValue("http://mail.google.com/mail");
 
			ss[4].setName(CreationParameters.ROLE.toString());
			ss[4].setValue("is-described-by");
 
 
			ss[5].setName(CreationParameters.INDEXABLE.toString());
			ss[5].setValue("false");
 
			ss[6].setName(CreationParameters.EDITABLE.toString());
			ss[6].setValue("true");
 
			//String relatedbyCollID = "3971d1a0-4771-11dd-8639-ae5f2f1f5aef";		
			//compulsory
			ss[7].setName(CreationParameters.RELATEDBY_COLLID.toString());
			ss[7].setValue(relatedContentCollectionID);
			System.out.println(CreationParameters.RELATEDBY_COLLID.toString()+": " +relatedContentCollectionID);			
			ss[8].setName(CreationParameters.RELATEDBY_ROLE.toString());
			ss[8].setValue("is-annotated-by");
 
			ccp.setParams(ss);
			request.setCollectionParameters(ccp);
			CreateManagerResponse response = new CreateManagerResponse();
 
			 mFactory = GCUBERemotePortTypeContext.getProxy(mFactory,GCUBEScope.getScope(scope));	 	               
			response = mFactory.createManager(request);
 
			System.out.println("Metadata Collection successfully created, at "+response.getEndpointReference().toString());
		} catch (Exception e) {
			e.printStackTrace();	
		}
	}
}