Revision as of 14:18, 15 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.

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.

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

Properties and Types

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

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

Using Home Library

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>

Retrieving the user Home

Firs of all is necessary to retrieve an instance of HomeManagerFactory, this can be done using the static methods from HomeLibrary class.

HomeManagerFactory factory = HomeLibrary.getHomeManagerFactory();

Obtained the factory you can retrieve the HomeManager:

HomeManager manager = factory.getHomeManager();

Then we retrieve the User home:

User user = manager.createUser(portalLogin);
Home home = manager.getHome(user);

Where portalLogin is the user username used to login into the portal (for test you can use any username).

At this point we can get the Workspace with his root:

Workspace ws = home.getWorkspace();
WorkspaceFolder root = ws.getRoot();

There are some example of HomeLibrary use.

Creating folders

Generate an unique name for a folder item

To generate an unique item name for a given folder:

// Get a destination folder
WorkspaceFolder destionationFolder = ...
 
String nameCandidate = "My first item";
 
String name = WorkspaceUtil.getUniqueName(nameCandidate, destionationFolder);

If an item with name My first item already exists, a new name My first item(n) will be assigned to the folder.

Create a workspace folder

// Get the user workspace
Workspace ws = ...
 
String name = "MyFolder";
String description = "description";
 
WorkspaceFolder folder;
if (!ws.exists(name, destinationFolderId))
	folder = ws.createFolder(name, description, destinationFolderId);
else
	folder = (WorkspaceFolder) ws.find(name, destinationFolderId);

If the folder "MyFolder" does not exist in the destination folder, it will be created. Otherwise "MyFolder" will be retrieved.

Creating files

Create a generic file into a folder

After retrieving the user workspace root:

// Get a destination folder
WorkspaceFolder destinationFolder = ...
 
String name = "filename";
String description = "description";
String mimeType = null;
InputStream is = new FileInputStream("/home/user/file.txt");	
FolderItem folderItem = WorkspaceUtil.createExternalFile(destinationFolder, name, description, mimeType, is);

If the mimetype is null, it will be automatically detected.

If the file is already in the Storage, the workspace item can be created by storageId:

String storageId = ...
FolderItem folderItem = WorkspaceUtil.createExternalFile(destinationFolder, name, description, mimeType, storageId);

Create an External File

TO DO

// Get a destination folder
WorkspaceFolder destinationFolder = ...
 
String name = "filename";
String description = "description";
String mimeType = null;
InputStream is = new FileInputStream("/home/user/file.txt");	
FolderItem folderItem = WorkspaceUtil.createExternalFile(destinationFolder, name, description, mimeType, is);

Create an External Image

TO DO

// Get a destination folder
WorkspaceFolder destinationFolder = ...
 
String name = "filename";
String description = "description";
String mimeType = null;
InputStream is = new FileInputStream("/home/user/file.txt");	
FolderItem folderItem = WorkspaceUtil.createExternalFile(destinationFolder, name, description, mimeType, is);

Create an External PDF File

TO DO

// Get a destination folder
WorkspaceFolder destinationFolder = ...
 
String name = "filename";
String description = "description";
String mimeType = null;
InputStream is = new FileInputStream("/home/user/file.txt");	
FolderItem folderItem = WorkspaceUtil.createExternalFile(destinationFolder, name, description, mimeType, is);

Create an External URL

TO DO

// Get a destination folder
WorkspaceFolder destinationFolder = ...
 
String name = "filename";
String description = "description";
String mimeType = null;
InputStream is = new FileInputStream("/home/user/file.txt");	
FolderItem folderItem = WorkspaceUtil.createExternalFile(destinationFolder, name, description, mimeType, is);

Add properties to an item

After retrieving the user workspace root:

String name = "key";
String value = "value";
 
// Get an item
FolderItem folderItem = ...
 
// Add properties
folderItem.getProperties().addProperty(name, value);

Create a gCubeItem

import org.gcube.common.homelibrary.home.workspace.WorkspaceItem;
import java.util.ArrayList;
import java.util.List;
import java.util.HashMap;
import java.util.Map;
 
String name = "name";
String description = "description";
List<String> scopes = new ArrayList<String>();
scopes.add("/myscope/");
 
String creator = "test.user";
String itemType = "myType";
 
Map<String, String> properties = new HashMap<String, String>();
properties.put("key00", "value00");
properties.put("key01", "value01");
 
// Get a destination folder id
String destinationFolderId = ...
 
WorkspaceItem item = ws.createGcubeItem(name, description, scopes, creator, itemType, properties, destinationFolderId);

Sharing items

Create a shared folder

// Get the user workspace
Workspace ws = ...
 
String name = "MySharedFolder";
String description = "description";
List<String> users = ...
String destinationFolderId = ...
 
WorkspaceSharedFolder sharedFolder = ws.createSharedFolder(name, description, users, destinationFolderId);
sharedFolder.setACL(users, ACLType.READ_ONLY);

Share an existing folder

//Get an existing folder
WorkspaceFolder folder = ...
 
List<String> users = ...
 
WorkspaceSharedFolder sharedFolder = folder.share(users);
sharedFolder.setACL(users, ACLType.READ_ONLY);

Unshare a folder

//Get an existing shared folder
WorkspaceSharedFolder sharedFolder = ...
 
WorkspaceItem folder = ws.unshare(sharedFolder.getId());

Unshare a folder for a single user

//Get an existing shared folder
WorkspaceSharedFolder sharedFolder = ...
String user = ...
 
WorkspaceFolder folder = sharedFolder.unShare(user);

Searching items

Search an item in a specific folder

// Get the user workspace
Workspace ws = ...
String name = "test";
String folderId = ws.getRoot().getId();
 
WorkspaceItem myItem = ws.find(name, folderId);

Subfolders are not included in the search.

Search items by name

To search items by name on a folder and all its subfolders:

import java.util.ArrayList;
import java.util.List;
import org.gcube.common.homelibrary.home.workspace.search.SearchItem;
 
// Get the user workspace
Workspace ws = ...
String name = ...
String folderId = ...
 
// Get SearchItems with a given name in a folder and subfolders
List<SearchItem> myList = ws.searchByName(name, folderId);

Search items by mime type

To search items by mime type on the user workspace:

import java.util.ArrayList;
import java.util.List;
import org.gcube.common.homelibrary.home.workspace.search.SearchFolderItem;
 
// Get the user workspace
Workspace ws = ...
String mimetype = "image/jpeg";
 
// Get SearchFolderItem with a given mimetype
List<SearchFolderItem> myList = ws.searchByMimeType(mimetype);

Search items by properties

To search items by properties:

import java.util.ArrayList;
import java.util.List;
import org.gcube.common.homelibrary.home.workspace.WorkspaceItem;
 
// Get the user workspace
Workspace ws = ...
 
List<String> keys = new ArrayList<String>();
keys.add("key00");
keys.add("key01");
 
// Get WorkspaceItem that contain certain keys
List<WorkspaceItem> properties = ws.searchByProperties(keys);

Advance Search on gCubeItems

To search gCubeItems by properties:

import java.util.ArrayList;
import java.util.List;
import org.gcube.common.homelibrary.home.workspace.search.util.SearchQueryBuilder;
 
// Get the user workspace
Workspace ws = ...
 
// Create a SearchQuery
SearchQueryBuilder query = new SearchQueryBuilder();
 
// Get gCubeItems that contain a certain key
query.contains("key00");
 
// Get gCubeItems where key01 = value01
query.contains("key01","value01");
 
// Get gCubeItems where type = myType
query.ofType("myType");
 
List<GCubeItem> myItems = ws.searchGCubeItems(query.build());

Retrieve information about user workspace

Get the disk usage

Get information about the disk space usage:

// Get the user workspace
Workspace ws = ...
 
long diskUsage = ws.getDiskUsage();

Get the total number of items

Get information about the total number of items in the user workspace:

// Get the user workspace
Workspace ws = ...
 
int totalItems = ws.getTotalItems();

Smart Folders

Create a Smart Folder

To create a smart folder, where the filename includes a certain query, in this case "test":

import org.gcube.common.homelibrary.home.workspace.WorkspaceSmartFolder;
 
// Get the user workspace
Workspace ws = ...
 
String name = "MySmartFolder";
String description = "My personal smart folder";
String query = "test";
String folderId = ...
 
WorkspaceSmartFolder mySmartFolder = ws.createSmartFolder(name, description, query, folderId);

If folderId is not null, "test" will be searched just in such folder and all its subfolders, otherwise, it will be searched in the whole workspace.

Get all Smart Folders

To get all smart folders in the user workspace:

import org.gcube.common.homelibrary.home.workspace.WorkspaceSmartFolder;
 
// Get the user workspace
Workspace ws = ...
 
List<WorkspaceSmartFolder> smartFolders = ws.getAllSmartFolders()

Get all items in a Smart Folder

To get all items in a smart folder:

import org.gcube.common.homelibrary.home.workspace.WorkspaceSmartFolder;
 
// Get the smart folder
WorkspaceSmartFolder mySmartFolder = ...
 
List<? extends SearchItem> list = mySmartFolder.getSearchItems();

Remove a Smart Folder

To remove a smart folder:

import org.gcube.common.homelibrary.home.workspace.WorkspaceSmartFolder;
 
// Get the smart folder to remove
WorkspaceSmartFolder mySmartFolder = ...
 
mySmartFolder.remove();

Trash Folder

Trash is a folder that allows to recover files and folders that have been deleted. By default, all deleted items will be moved the the Trash location of user account and will be purged on user request. There will be the option to recover or empty the entire Trash folder, or specific items as needed.

Get Trash

import org.gcube.common.homelibrary.home.workspace.Workspace;
import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
 
// Get the user workspace
Workspace ws = ...
 
WorkspaceTrashFolder trash = ws.getTrash();

List items in Trash and get their properties

import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
 
// Get the trash
WorkspaceTrashFolder trash = ...
 
List<WorkspaceTrashItem> trashItems = trash.listTrashItems();
for (WorkspaceTrashItem item: trashItems){
	System.out.println("item name: " + item.getName());
        System.out.println("mime type: " + item.getMimeType());
	System.out.println("deleted by: " + item.getDeletedBy());
	System.out.println("deleted from: " + item.getDeletedFrom());
	System.out.println("deletion time: " + item.getDeletedTime().getTime());
	System.out.println("original parent id: " + item.getOriginalParentId());
	System.out.println("is it folder?: " + item.isFolder());	
}

Empty trash

import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
 
// Get the trash
WorkspaceTrashFolder trash = ...
 
trash.emptyTrash();

Restore all

import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
 
// Get the trash
WorkspaceTrashFolder trash = ...
 
trash.restoreAll();

Recovered files and folders will be restored to the location they were deleted from, if the original folder still exists and a file with the same name is not there. Otherwise the user can move them from out of the Trash to where he wants them.

Restore a specific item

import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
 
// Get the trash
WorkspaceTrashFolder trash = ...
 
// ID item to restore
String id = ...
 
trash.restoreById(id);

@@ Line 710: / Line 710: @@
 </source>
-=== List items in Trash ===
+=== List items in Trash and get their properties===
 <source lang="java5">
@@ Line 724: / Line 724: @@
 	System.out.println("deleted by: " + item.getDeletedBy());
 	System.out.println("deleted from: " + item.getDeletedFrom());
-	System.out.println("deleted time: " + item.getDeletedTime().getTime());
+	System.out.println("deletion time: " + item.getDeletedTime().getTime());
 	System.out.println("original parent id: " + item.getOriginalParentId());
 	System.out.println("is it folder?: " + item.isFolder());

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

Revision as of 14:18, 15 March 2016

Contents

Introduction

Design Model

Workspace Items

Prior HL 2.0 Objects that have been removed

Prior HL 2.0 Objects that have been mapped to the new model (GCubeItem)

Compatibility

Document

ImageDocument

Metadata

PDFDocument

UrlDocument

Properties and Types

Implementation Framework

Management Model

Using Home Library

Retrieving the user Home

Creating folders

Generate an unique name for a folder item

Create a workspace folder

Creating files

Create a generic file into a folder

Create an External File

Create an External Image

Create an External PDF File

Create an External URL

Add properties to an item

Create a gCubeItem

Sharing items

Create a shared folder

Share an existing folder

Unshare a folder

Unshare a folder for a single user

Searching items

Search an item in a specific folder

Search items by name

Search items by mime type

Search items by properties

Advance Search on gCubeItems

Retrieve information about user workspace

Get the disk usage

Get the total number of items

Smart Folders

Create a Smart Folder

Get all Smart Folders

Get all items in a Smart Folder

Remove a Smart Folder

Trash Folder

Get Trash

List items in Trash and get their properties

Empty trash

Restore all

Restore a specific item

Navigation menu

Search