Difference between revisions of "Home Library 2.0 API Framework Specification"

From Gcube Wiki
Jump to: navigation, search
(Design Model)
(Replaced content with "== The Home Library has been deprecated by the new [https://wiki.gcube-system.org/gcube/StorageHub_REST_API StorageHub Service] == Please use the StorageHub service for fu...")
 
(264 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Home Library  2.0 API =
+
== The Home Library has been deprecated by the new [https://wiki.gcube-system.org/gcube/StorageHub_REST_API StorageHub Service] ==
 
+
Please use the StorageHub service for future developments: https://wiki.gcube-system.org/gcube/StorageHub_REST_API
The Home Library is a library to manage and persist the user home folder that supports file sharing.
+
 
+
Any Home Library user is presented with a personal Workspace [Add link to the workspace portlet], where users can collaborate, share information, and access project resources using special folders. This module describes the model of Home Library 2.0 and how to use the new API interface.
+
 
+
== Design Model ==
+
 
+
The '''design model''' for Home Library identifies a core set of capabilities to work on Jackrabbit content.
+
The goal of Home Library 2.0 is to expose content in the content repository as HTTP resources, fostering a RESTful style of application architecture.
+
 
+
The Home Library 2.0 is composed by:
+
* '''HomeLibrary''': the API interface.
+
* '''HomeLibrary JCR''': an HomeLibrary implementation based on JCR 2.0 (Java Content Repository [http://jcp.org/en/jsr/detail?id=283 JSR 283]).
+
* '''HomeLibrary WebApp''': a webService built on the top of the Jackrabbit web application. The goal of Home Library 2.0 is to expose content in the content repository as HTTP resources, fostering a RESTful style of application architecture.
+
* '''Home Library Model''': a library to shared information between clients and Web App. It includes ACLType, FolderItemType, NodeProperty, WorkspaceItemType, etc.
+
 
+
===Workspace Items===
+
 
+
Each element contained in a workspace area is a WorkspaceItem.The workspace items are the effective user objects.
+
 
+
The following figure shows the WorkspaceItem model.
+
[[File:areamodel.png]]
+
 
+
==== Prior HL 2.0 Objects that have been removed====
+
 
+
*AquaMapsItem
+
*Annotation
+
*DocumentLink
+
*ImageDocumentLink
+
*PDFDocumentLink
+
*Annotation
+
*TabularDataLink
+
*ExternalResourceLink
+
*WorkflowReport
+
*WorkflowTemplate
+
 
+
==== Prior HL 2.0 Objects that have been mapped to the new model (gCubeItem) ====
+
 
+
*Document
+
*ImageDocument
+
*Metadata
+
*PDFDocument
+
*UrlDocument
+
 
+
 
+
Use the next section to keep code compatible with both old and new API.
+
 
+
===Compatibility===
+
There is some pattern to know to keep code compatible with new API.
+
 
+
If you were working on '''Document, ImageDocument, Metadata, PDFDocument or UrlDocument''', using new API your are going to work on '''GCubeItem''' that is a generic gCube Object.
+
 
+
But old context and model are still available using the following sections.
+
 
+
====Document====
+
 
+
Home Library 2.0 API to retrieve Document Objects:
+
 
+
<source lang="java">
+
import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.Document;
+
 
+
Document document = (Document) item;
+
 
+
becomes:
+
 
+
import org.gcube.common.homelibary.model.items.type.NodeProperty;
+
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
+
 
+
GCubeItem document = (GCubeItem) item;
+
 
+
</source>
+
 
+
How to retrieve properties:
+
 
+
<source lang="java">
+
document.getAlternatives(); -> document.getProperties().getProperties().get((NodeProperty.ALTERNATIVES.toString());
+
document.getAnnotation(); -> document.getProperties().getProperties().get((NodeProperty.ANNOTATIONS.toString());
+
document.getCollectionName(); -> document.getProperties().getProperties().get((NodeProperty.COLLECTION_NAME.toString());
+
document.getData(); -> document.getProperties().getProperties().get((NodeProperty.DATA.toString());
+
document.getFolderItemType(); -> document.getProperties().getProperties().get((NodeProperty.FOLDER_ITEM_TYPE.toString());
+
document.getLength(); -> document.getProperties().getProperties().get((NodeProperty.SIZE.toString());
+
document.getMetadata(); -> document.getProperties().getProperties().get((NodeProperty.METADATA.toString());
+
document.getMimeType(); -> document.getProperties().getProperties().get((NodeProperty.MIME_TYPE.toString()); 
+
document.getParts(); -> document.getProperties().getProperties().get((NodeProperty.PARTS.toString());
+
document.getURI(); -> document.getProperties().getProperties().get((NodeProperty.OID.toString()); 
+
document.getWorkflowData(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_DATA.toString()); 
+
document.getWorkflowId(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_ID.toString()); 
+
document.getWorkflowStatus(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_STATUS.toString()); 
+
 
+
</source>
+
 
+
====ImageDocument====
+
 
+
New Home Library API to retrieve ImageDocument Objects:
+
 
+
<source lang="java">
+
import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.ImageDocument;
+
 
+
ImageDocument document = (ImageDocument) item;
+
 
+
becomes:
+
 
+
import org.gcube.common.homelibary.model.items.type.NodeProperty;
+
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
+
 
+
GCubeItem document = (GCubeItem) item;
+
 
+
</source>
+
 
+
To retrieve properties, use the API for Document Object and the following API:
+
 
+
<source lang="java">
+
document.getHeight(); -> document.getProperties().getProperties().get((NodeProperty.IMAGE_HEIGHT.toString()); 
+
document.getWidth(); -> document.getProperties().getProperties().get((NodeProperty.IMAGE_WIDTH.toString()); 
+
document.getThumbnailHeight(); -> document.getProperties().getProperties().get((NodeProperty.THUMBNAIL_HEIGHT.toString());   
+
document.getThumbnailWidth(); -> document.getProperties().getProperties().get((NodeProperty.THUMBNAIL_WIDTH.toString()); 
+
document.getThumbnail(); -> document.getProperties().getProperties().get((NodeProperty.THUMBNAIL_DATA.toString());
+
document.getThumbnailLength(); -> document.getThumbnail().getSize();
+
+
</source>
+
 
+
====Metadata====
+
New Home Library API to retrieve Metadata Objects:
+
 
+
<source lang="java">
+
import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.Metadata;
+
 
+
Metadata document = (Metadata) item;
+
 
+
becomes:
+
 
+
import org.gcube.common.homelibary.model.items.type.NodeProperty;
+
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
+
 
+
GCubeItem document = (GCubeItem) item;
+
 
+
</source>
+
 
+
To retrieve properties:
+
 
+
<source lang="java">
+
document.getURI(); -> document.getProperties().getProperties().get((NodeProperty.OID.toString()); 
+
document.getWorkflowData(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_DATA.toString()); 
+
document.getWorkflowId(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_ID.toString()); 
+
document.getWorkflowStatus(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_STATUS.toString());
+
 
+
document.getSchemaName(); -> document.getProperties().getProperties().get((NodeProperty.SCHEMA.toString());
+
document.getXML(); -> document.getProperties().getProperties().get((NodeProperty.ALTERNATIVES.toString());
+
document.getCollectionName(); -> document.getProperties().getProperties().get((NodeProperty.COLLECTION_NAME.toString());
+
document.getURI(); -> document.getProperties().getProperties().get((NodeProperty.OID.toString()); 
+
 
+
</source>
+
 
+
====PDFDocument====
+
New Home Library API to retrieve PDFDocument Objects:
+
 
+
<source lang="java">
+
import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.PDFDocument;
+
 
+
PDFDocument document = (PDFDocument) item;
+
 
+
becomes:
+
 
+
import org.gcube.common.homelibary.model.items.type.NodeProperty;
+
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
+
 
+
GCubeItem document = (GCubeItem) item;
+
 
+
</source>
+
 
+
To retrieve properties, use the API for Document Object and the following API:
+
 
+
<source lang="java">
+
 
+
document.getNumberOfPages(); -> document.getProperties().getProperties().get((NodeProperty.NUMBER_OF_PAGES.toString()); 
+
document.getVersion(); -> document.getProperties().getProperties().get((NodeProperty.VERSION.toString()); 
+
document.getAuthor(); -> document.getProperties().getProperties().get((NodeProperty.AUTHOR.toString()); 
+
document.getTitle(); -> document.getProperties().getProperties().get((NodeProperty.PDF_TITLE.toString()); 
+
document.getProducer(); -> document.getProperties().getProperties().get((NodeProperty.PRODUCER.toString()); 
+
+
</source>
+
 
+
====UrlDocument====
+
New Home Library API to retrieve UrlDocument Objects:
+
 
+
<source lang="java">
+
import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.UrlDocument;
+
 
+
UrlDocument document = (UrlDocument) item;
+
 
+
becomes:
+
 
+
import org.gcube.common.homelibary.model.items.type.NodeProperty;
+
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
+
 
+
GCubeItem document = (GCubeItem) item;
+
 
+
</source>
+
 
+
To retrieve properties, use the API for Document Object and the following API:
+
 
+
<source lang="java">
+
 
+
document.getUrl(); -> document.getProperties().getProperties().get((NodeProperty.URL.toString()); 
+
+
</source>
+
 
+
== Implementation Framework ==
+
 
+
The '''Home Library 2.0 API''' is a set of components that uses Apache Jackrabbit, to store and manage content.
+
 
+
Home Library 2.0 uses Java servlets to process HTTP requests in a RESTful way.
+
 
+
Home Library is implemented in terms of the JCR API. The default implementation for Apache Jackrabbit is provided out of the box.
+
 
+
Through code sharing, the framework reduces development costs and ensures the consistency and correctness of library implementations.
+
 
+
== Management Model ==
+
The core of Home Library 2.0 is a web application built on top of Jackrabbit.
+
 
+
'''Home Library WebApp''' uses Java servlets to process HTTP requests coming from clients.
+
The servlets are a frontend to the actual operations and they support the following operations:
+
*retrieve content
+
*create content
+
*modify existing content
+
*remove existing content
+
*move existing content to a new location
+
*copy existing content to a new location
+
 
+
[[File:WebApp.png]]
+
 
+
== How to ==
+
To use Home Library 2.0, import the following dependencies:
+
<source lang="xml">
+
<dependency>
+
<groupId>org.gcube.common</groupId>
+
<artifactId>home-library-jcr</artifactId>
+
<version>[2.0.0-SNAPSHOT,3.0.0-SNAPSHOT)</version>
+
</dependency>
+
+
<dependency>
+
<groupId>org.gcube.common</groupId>
+
<artifactId>home-library</artifactId>
+
<version>[2.0.0-SNAPSHOT,3.0.0-SNAPSHOT)</version>
+
</dependency>
+
</source>
+
 
+
Properties and Types are in '''Home Library Model''', so update the package as follows:
+
<source lang="java">
+
org.gcube.common.homelibrary.home.workspace.WorkspaceItemType -> org.gcube.common.homelibary.model.items.type.WorkspaceItemType
+
org.gcube.common.homelibrary.home.workspace.folder.FolderItemType -> org.gcube.common.homelibary.model.items.type.FolderItemType
+
org.gcube.common.homelibrary.home.workspace.accessmanager.ACLType -> org.gcube.common.homelibary.model.items.type.ACLType
+
</source>
+

Latest revision as of 10:52, 18 January 2019

The Home Library has been deprecated by the new StorageHub Service

Please use the StorageHub service for future developments: https://wiki.gcube-system.org/gcube/StorageHub_REST_API