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

From Gcube Wiki
Jump to: navigation, search
(→‎Home Library 2.0 API)
(→‎Introduction)
Line 5: Line 5:
 
Any Home Library user is presented with a personal [https://gcube.wiki.gcube-system.org/gcube/index.php/Workspace Workspace], 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.
 
Any Home Library user is presented with a personal [https://gcube.wiki.gcube-system.org/gcube/index.php/Workspace Workspace], 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 ==
+
= Design Model =
  
 
The '''design model''' for Home Library identifies a core set of capabilities to work on Jackrabbit content.  
 
The '''design model''' for Home Library identifies a core set of capabilities to work on Jackrabbit content.  
Line 18: Line 18:
 
[[File:WebApp.png]]
 
[[File:WebApp.png]]
  
−
=== Workspace Items ===
+
== Workspace Items ==
  
 
Each element contained in a workspace area is a WorkspaceItem.The workspace items are the effective user objects.
 
Each element contained in a workspace area is a WorkspaceItem.The workspace items are the effective user objects.
Line 25: Line 25:
 
[[File:areamodel.png]]
 
[[File:areamodel.png]]
  
−
==== Prior HL 2.0 Objects that have been removed====
+
=== Prior HL 2.0 Objects that have been removed===
  
 
*AquaMapsItem
 
*AquaMapsItem
Line 38: Line 38:
 
*WorkflowTemplate
 
*WorkflowTemplate
  
−
==== Prior HL 2.0 Objects that have been mapped to the new model (GCubeItem) ====
+
=== Prior HL 2.0 Objects that have been mapped to the new model (GCubeItem) ===
  
 
*Document
 
*Document
Line 49: Line 49:
 
Use the next section to migrate your components to the new Home Library API.
 
Use the next section to migrate your components to the new Home Library API.
  
−
===Compatibility===
+
==Compatibility==
 
There is some pattern to know to keep code compatible with new API.
 
There is some pattern to know to keep code compatible with new API.
  
Line 56: Line 56:
 
But old context and model are still available using the following sections.
 
But old context and model are still available using the following sections.
  
−
====Document====
+
===Document===
  
 
Home Library 2.0 API to retrieve Document Objects:
 
Home Library 2.0 API to retrieve Document Objects:
Line 93: Line 93:
 
</source>
 
</source>
  
−
====ImageDocument====
+
===ImageDocument===
  
 
New Home Library API to retrieve ImageDocument Objects:
 
New Home Library API to retrieve ImageDocument Objects:
Line 123: Line 123:
 
</source>
 
</source>
  
−
====Metadata====
+
===Metadata===
 
New Home Library API to retrieve Metadata Objects:
 
New Home Library API to retrieve Metadata Objects:
  
Line 155: Line 155:
 
</source>
 
</source>
  
−
====PDFDocument====
+
===PDFDocument===
 
New Home Library API to retrieve PDFDocument Objects:
 
New Home Library API to retrieve PDFDocument Objects:
  
Line 184: Line 184:
 
</source>
 
</source>
  
−
====UrlDocument====
+
===UrlDocument===
 
New Home Library API to retrieve UrlDocument Objects:
 
New Home Library API to retrieve UrlDocument Objects:
  

Revision as of 15:48, 10 March 2016

Introduction

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, 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. Home Library 2.0 is 10 times faster on average in comparison with the previous version.

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 JSR 283).
  • HomeLibrary WebApp: a webService built on the top of the Jackrabbit web application.
  • Home Library Model: a library to shared information between clients and Web App. It includes ACLType, FolderItemType, NodeProperty, WorkspaceItemType, etc.

WebApp.png

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. 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 migrate your components to the new Home Library 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: 

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;

How to retrieve properties: 

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());

ImageDocument

New Home Library API to retrieve ImageDocument Objects: 

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;

To retrieve properties, use the API for Document Object and the following API: 

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();

Metadata

New Home Library API to retrieve Metadata Objects: 

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;

To retrieve properties: 

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());

PDFDocument

New Home Library API to retrieve PDFDocument Objects: 

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;

To retrieve properties, use the API for Document Object and the following API: 

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());

UrlDocument

New Home Library API to retrieve UrlDocument Objects: 

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;

To retrieve properties, use the API for Document Object and the following API: 

document.getUrl(); -> document.getProperties().getProperties().get((NodeProperty.URL.toString());

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

How to

To use Home Library 2.0, import the following dependencies: 

<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>

Properties and Types are in Home Library Model, so update the package as follows: 

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

Using the Home Library

How to retrieve the user Home

Examples

WorkspaceArea examples

Create a generic item into a workspace folder

Create a gCubeItem into a workspace folder

Search by properties

Retrieved from "https://wiki.gcube-system.org/index.php?title=Home_Library_2.0_API_Framework_Specification&oldid=23991"