GCube Document Library

Design Overview

The gCube Document Library (gDL) is a library that works on top of the Content Manager. This library offers a simpler way for client to access documents in the d4science system. The major change in the ContentManager is the document model (more generic, more extensible), the gDL reduces the development costs for using this new feature.

Document Model

Implementation Overview

The gDL is composed by tree types of access interfaces:

• the CMReader is used to read document from a collection. it offers methods to get a document or part of it (Metadata, Annotations, Parts, Alternatives);
• the CMWriter is used to add document or update it or a part of it;
• the CMView is used to get documents from a specific view of a collection.

Configuring the environment

Supporting the SMS protocol

The Storage Management Service introduces a new protocol, called sms, with an handler implementation.

To let know the JVM about the existence of a new protocol handler you can use one of this solutions:

• Specify a new java property at JVM startup: -Djava.protocol.handler.pkgs=org.gcube.contentmanagement.storagelayer.storagemanagementservice.stubs.protocol
  • if you are developing a service and are you using the last distribution you don't have to change anything because the new GHN distribution already do it.
  • if you are developing a portlet or a portal library check if your portal instance have the option specified in the environment variable CATALINA_OPTS.
  • if you are running your client locally on Eclipse you can specify the options on run configuration, Arguments tab, VM arguments section.
• Use this sentence in your client testing program:

System.setProperty("java.protocol.handler.pkgs", "org.gcube.contentmanagement.storagelayer.storagemanagementservice.stubs.protocol");

Examples

Here some examples on CML use. More examples are on examples folder in CML project on SVN.

Reading examples

We shows some examples on reading documents.

Get a single document

This example shows how to get a single document using his id.

 //we instantiate the CMReader
 CMReader cmReader = new CMReader(collectionId, scope);
 
 //then we retrieve the document, we are not specifying projections, therefore the entire document is returned.
 GCubeDocument document = cmReader.getDocument(documentId);
 
 System.out.println("Retrieved document:");
 System.out.println("id: " + document.getId());
 System.out.println("name: " + document.getName());
 System.out.println("mimeType: " + document.getMimeType());

Get all documents in a collection

This example shows how to get all documents from a collection.

 //we instantiate the CMReader
 CMReader cmReader = new CMReader(collectionId, scope);
 
 //then we retrieve all collection documents
 //we are not specifying projections, therefore the entire document is returned.
 Iterator<GCubeDocument> documentIterator = cmReader.getDocuments();
 
 int i = 0;
 System.out.println("Collection documents:");
 
 //finally we iterate over the collection
 while(documentIterator.hasNext()){
    GCubeDocument document = documentIterator.next();
 
    String id = document.getId();
    int parts = document.getParts().size();
    int alternatives = document.getAlternatives().size();
    int metadata = document.getMetadata().size();
    int annotations = document.getAnnotations().size();
 
    System.out.printf("%d id: %s parts: %d alternatives: %d metadata: %d annotations: %d %n", i, id, parts, alternatives, metadata, annotations);
    i++;
 }

Get a document using projections

This example shows how to use projections during document retrieving.

 //we instantiate the CMReader
 CMReader cmReader = new CMReader(collectionId, scope);
 
 //then we retrieve the document, 
 //we are specifying the MAIN_DOCUMENT and the METADATA projections, the document returned will have main document data and all related metadata	
 GCubeDocument document = cmReader.getDocument(documentId, Projections.MAIN_DOCUMENT, Projections.METADATA);
 
 System.out.println("Retrieved document:");
 System.out.println("id: " + document.getId());
 System.out.println("name: " + document.getName());
 System.out.println("mimeType: " + document.getMimeType());
 System.out.println("length: " + document.getLength());
 System.out.println("contentURL: " + document.getContentURL());
 System.out.println();
 
 for (GCubeMetadata metadata:document.getMetadata()){
    System.out.println("Metadata:");
    System.out.println(" id: " + metadata.getId());
    System.out.println(" mimeType: " + metadata.getMimeType());
    System.out.println(" length: " + metadata.getLength());
    System.out.println(" Metadata info:");
    System.out.println("  name: " + metadata.getMetadataName());
    System.out.println("  schema: " + metadata.getMetadataSchema());
    System.out.println("  language: " + metadata.getMetadataLanguage());
    System.out.println();
 }

Get a document content

This example shows how to get a document content.

 //we instantiate the CMReader
 CMReader cmReader = new CMReader(collectionId, scope);
 
 //then we retrieve the document, we are requesting only the main document
 GCubeDocument document = cmReader.getDocument(documentId, Projections.MAIN_DOCUMENT);
 
 System.out.println("Retrieved document:");
 System.out.println("id: " + document.getId());
 System.out.println("name: " + document.getName());
 System.out.println("contentURL: " + document.getContentURL());
 System.out.println();
 
 System.out.println("Retrieving content...");
 //the content is retrieved by the CML library through the content URL
 InputStream is = document.getContent();
 
 //finally we copy the content to a tmp file
 File tmpFile = File.createTempFile("mycontent", ".tmp");
 IOUtils.copy(is, new FileOutputStream(tmpFile));
 
 System.out.println("Content saved in tmp file: " + tmpFile.getAbsolutePath());

Writing examples

We shows some examples on manipulating collections.

Add a new document to a collection

Add a new document to a collection.

 //we instantiate the CMWriter
 CMWriter cmWriter = new CMWriter(collectionId, scope);
 
 //we create an instance of gcube document
 GCubeDocument myNewDocument = new GCubeDocument("My Test Document", Calendar.getInstance(), Calendar.getInstance(), "application/octet-stream", 100l);
 
 //then we ask for adding the new document
 String myNewDocumentId = cmWriter.add(myNewDocument);
 System.out.println("document created, id: " + myNewDocumentId);
 
 
 //finally we retrieve the created document
 CMReader cmReader = new CMReader(collectionId, scope);
 GCubeDocument document = cmReader.getDocument(myNewDocumentId);
 
 System.out.println("Created document:");
 System.out.println("id: " + document.getId());
 System.out.println("name: " + document.getName());
 System.out.println("mimeType: " + document.getMimeType());
 System.out.println("length: " + document.getLength());
 System.out.println("contentURL: " + document.getContentURL());
 
 System.out.println("parts: " + document.getParts().size());
 System.out.println("alternatives:" + document.getAlternatives().size());
 System.out.println("metadata: " + document.getMetadata().size());
 System.out.println("annotations: " + document.getAnnotations().size());

Remove a document from a collection

Remove a document from a collection.

 //we instantiate the CMWriter
 CMWriter cmWriter = new CMWriter(collectionId, scope);
 
 writer.remove(documentId);
 
 System.out.println("document removed.");

Views examples

We shows some examples on handling views.

List collection views

List all the views for a certain collection.

 //we instantiate a collection manager.
 CollectionManager collectionManager = new CollectionManager(collectionId, scope);
 
 //then we ask for all the available views
 List<CMView<?>> views = collectionManager.findViews();
 
 System.out.println("found "+views.size()+" views:");
 for (CMView<?> view:views) System.out.println(view);

Get Metadata elements

Get a metadata view for a collection and the all the elements of the view.

 //first we instantiate a collection manager
 CollectionManager collectionManager = new CollectionManager(collectionId, scope);
 
 //then we create a view kind, in this case a MetadataView without specifying any property
 MetadataView myMedataView = new MetadataView();
 
 //finally we ask to the collection manager to list all views of the kind specified.
 List<MetadataView> views = collectionManager.findViews(myMedataView);
 System.out.println("Found views: "+views.size());
 
 //in case we not found views
 if (views.size()==0) throw new Exception("No views found");
 
 //we get the first of the list
 MetadataView view = views.get(0);
 
 //we instantiate the view reader
 MetadataViewReader metadataReader = new MetadataViewReader(view, scope);
 
 //we request all the elements
 Iterator<GCubeMetadata> metadata = metadataReader.getAll();
 
 //and print it
 while (metadata.hasNext()) System.out.println(" >"+metadata.next());

F.A.Q.

• Running the examples I get the following exception:

[main] FATAL contexts.GHNClientContext  - [0.0s] GHNClientContext: gHN could not complete initialisation
java.io.FileNotFoundException: null/config/GHNConfig.xml (No such file or directory)
	at java.io.FileInputStream.open(Native Method)
	at java.io.FileInputStream.<init>(FileInputStream.java:106)
	at org.gcube.common.core.contexts.GHNContext.configureGHN(GHNContext.java:314)
	at org.gcube.common.core.contexts.GHNClientContext.configureGHN(GHNClientContext.java:35)
	at org.gcube.common.core.contexts.GHNClientContext.initialise(GHNClientContext.java:27)
	at org.gcube.common.core.contexts.GHNContext.<clinit>(GHNContext.java:252)
	at org.gcube.common.core.utils.calls.WSCall.getInitQuery(WSCall.java:55)
	at org.gcube.common.core.utils.calls.WSCall.getInitQuery(WSCall.java:25)
	at org.gcube.common.core.utils.calls.GCUBECall.<init>(GCUBECall.java:72)
	at org.gcube.common.core.utils.calls.GCUBECall.<init>(GCUBECall.java:84)
	at org.gcube.common.core.utils.calls.WSCall.<init>(WSCall.java:43)
	at org.gcube.contentmanagement.contentmanager.stubs.calls.BaseCall.<init>(BaseCall.java:25)
	at org.gcube.contentmanagement.contentmanager.stubs.calls.ManagerCall.<init>(ManagerCall.java:24)
	at org.gcube.contentmanagement.contentmanager.stubs.calls.ManagerCall.<init>(ManagerCall.java:35)
	at org.gcube.contentmanagement.contentmanager.stubs.calls.ReadManagerCall.<init>(ReadManagerCall.java:97)
	at org.gcube.contentmanagement.contentmanagerlibrary.CMReader.<init>(CMReader.java:62)
	at org.gcube.contentmanager.contentmanagerlibrary.GetDocumentsWithProjections.main(GetDocumentsWithProjections.java:34)
Exception in thread "main" java.lang.NullPointerException
	at org.gcube.common.core.utils.calls.WSCall.getInitQuery(WSCall.java:55)
	at org.gcube.common.core.utils.calls.WSCall.getInitQuery(WSCall.java:25)
	at org.gcube.common.core.utils.calls.GCUBECall.<init>(GCUBECall.java:72)
	at org.gcube.common.core.utils.calls.GCUBECall.<init>(GCUBECall.java:84)
	at org.gcube.common.core.utils.calls.WSCall.<init>(WSCall.java:43)
	at org.gcube.contentmanagement.contentmanager.stubs.calls.BaseCall.<init>(BaseCall.java:25)
	at org.gcube.contentmanagement.contentmanager.stubs.calls.ManagerCall.<init>(ManagerCall.java:24)
	at org.gcube.contentmanagement.contentmanager.stubs.calls.ManagerCall.<init>(ManagerCall.java:35)
	at org.gcube.contentmanagement.contentmanager.stubs.calls.ReadManagerCall.<init>(ReadManagerCall.java:97)
	at org.gcube.contentmanagement.contentmanagerlibrary.CMReader.<init>(CMReader.java:62)
	...

In this case you have to configure your eclipse running configuration properly [1].

• Trying to get the document content I get this exception:

Exception in thread "main" java.net.MalformedURLException: unknown protocol: sms
	at java.net.URL.<init>(URL.java:574)
	at java.net.URL.<init>(URL.java:464)
	at java.net.URL.<init>(URL.java:413)
	at org.gcube.contentmanagement.contentmanagerlibrary.model.GCubeDocument.getContent(GCubeDocument.java:227)
        ...

Check your configuration about SMS protocol