Revision as of 14:33, 4 November 2016

Overview

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.

Key features

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

Use cases

Users can:

organize and share their files through Internet
save results from other gCube software
manage messages
publish files and folders to the Catalogue

Design

The Home Library 2.0 API is a set of components that uses Apache Jackrabbit, to store and manage content.

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.

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

The basic element of the HomeLibrary is a WorkspaceItem. The workspace items are the effective user objects.

The following figure shows the WorkspaceItem model.

API

Get started

To use Home Library 2.0, add the following to your pom.xml file:

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

Reading

Retrieving the user Workspace

Firs of all it 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 its root:

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

There are some example of HomeLibrary use.

Retrieve information about user workspace

Get the disk usage

Get information about the disk space usage:

long Workspace.getDiskUsage();

Get the total number of items

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

int Workspace.getTotalItems()

Get an item by identifier

An item can be retrieved by its identifier with:

WorkspaceItem Workspace.getItem(String itemId);

Get an item by absolute path

An item can be acquired by absolute path with:

WorkspaceItem Workspace.getItemByPath(String path);

Writing

Create a workspace folder

To create a folder in a destination folder:

WorkspaceFolder Workspace.createFolder(name, description, destinationFolderId);

Create a generic file by Inputstream

The methods

org.gcube.common.homelibrary.util.WorkspaceUtil#createExternalFile(WorkspaceFolder destinationFolder, String name, String description, InputStream is)

org.gcube.common.homelibrary.util.WorkspaceUtil#createExternalFile(WorkspaceFolder destinationFolder, String name, String description, String mimeType, InputStream is)

org.gcube.common.homelibrary.util.WorkspaceUtil#createExternalFile(WorkspaceFolder destinationFolder, String name, String description, InputStream is, Map<String, String> properties)

org.gcube.common.homelibrary.util.WorkspaceUtil#createExternalFile(WorkspaceFolder destinationFolder, String name, String description, InputStream is, Map<String, String> properties, String mimeType, long size)

create an external file in the specified folder, by inputstream.

Example:

import org.gcube.common.homelibrary.util.WorkspaceUtil;
// 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.

Create a generic file by StorageId

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

org.gcube.common.homelibrary.util.WorkspaceUtil#createExternalFile(WorkspaceFolder destinationFolder, String name, String description, String storageId)

org.gcube.common.homelibrary.util.WorkspaceUtil#createExternalFile(WorkspaceFolder destinationFolder, String name, String description, String storageId, Map<String, String> properties)

org.gcube.common.homelibrary.util.WorkspaceUtil#createExternalFile(WorkspaceFolder destinationFolder, String name, String description, String storageId, Map<String, String> properties, String mimeType, long size)

org.gcube.common.homelibrary.util.WorkspaceUtil#createExternalFile(WorkspaceFolder destinationFolder, String name, String description, String mimeType, String storageId)

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

Create an External File

The methods

org.gcube.common.homelibrary.home.workspace.Workspace#createExternalFile(String name, String description, String mimeType, InputStream fileData, String destinationFolderId)

org.gcube.common.homelibrary.home.workspace.Workspace#createExternalFile(String name, String description, String mimeType, InputStream fileData, String destinationFolderId, Map<String, String> properties)

create an external file in a specified folder.

Example:

// Get a destination folder
WorkspaceFolder destinationFolder = ...
Workspace workspace = ..
String name = "filename";
String description = "description";
String mimeType = null;
InputStream is = new FileInputStream("/home/user/file.txt");	
ExternalFile externalFile = workspace.createExternalFile(name, description, mimeType, is, destinationFolderId);

Create an External Image

The methods

org.gcube.common.homelibrary.home.workspace.Workspace#createExternalImage(String name, String description, String mimeType, InputStream imageData, String destinationFolderId)

org.gcube.common.homelibrary.home.workspace.Workspace#createExternalImage(String name, String description, String mimeType, InputStream imageData, String destinationFolderId, Map<String, String> properties)

create an external image in a specified folder.

Create an External PDF File

The methods

org.gcube.common.homelibrary.home.workspace.Workspace#createExternalPDFFile(String name, String description, String mimeType, InputStream fileData, String destinationFolderId)

org.gcube.common.homelibrary.home.workspace.Workspace#createExternalPDFFile(String name, String description, String mimeType, InputStream fileData, String destinationFolderId, Map<String, String> properties)

create an external PDF in a specified folder.

Create an External URL

The methods

org.gcube.common.homelibrary.home.workspace.Workspace#createExternalUrl(String name, String description, InputStream url, String destinationfolderId)

org.gcube.common.homelibrary.home.workspace.Workspace#createExternalUrl(String name, String description, String url, String destinationFolderId)

create an external URL in a specified folder.

Create a Report

The method

Report Workspace.createReport(String name, String description, Calendar created, Calendar lastEdit, String author, String lastEditBy, 
			String templateName, int numberOfSections, String status, InputStream reportData, String destinationfolderId)

creates a Report in a specified folder.

Create a ReportTemplate

The method

ReportTemplate Workspace.createReportTemplate(String name, String description, Calendar created, Calendar lastEdit, String author,
			String lastEditBy, int numberOfSections, String status, InputStream templateData, String destinationfolderId)

creates a ReportTemplate in a specified folder.

Create a TimeSeries

The method

TimeSeries Workspace.createTimeSeries(String name, String description, String timeseriesId, String title, String creator, String timeseriesDescription,
			String timeseriesCreationDate, String publisher, String sourceId, String sourceName, String rights, long dimension, 
			List<String> headerLabels, InputStream compressedCSV,
			String destinationfolderId)

creates a TimeSeries in a specified folder.

Create a WorkflowReport

The method

WorkflowReport Workspace.createWorkflowReport(String name, String description, String workflowId, String workflowStatus, String workflowData, String destinationfolderId)

creates a WorkflowReport in a specified folder.

Create a Query

The method

Query Workspace.createQuery(String name, String description, InputStream query, QueryType queryType, String destinationfolderId)

creates a Query in a specified folder by inputstream

Query Workspace.createQuery(String name, String description, String query, QueryType queryType, String destinationfolderId)

or by query string.

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

Setting properties

Properties can be set during creation time, but they can also be added to an existing item:

After retrieving the user workspace root:

Map<String, String> properties = ..
 
// Get an item
FolderItem folderItem = ...
 
// Add properties
folderItem.getProperties().addProperties(properties);

Copy an item

To copy an item from a folder to another folder. The copy has the same name of the original.

WorkspaceItem Workspace.copy(String itemId, String destinationFolderId)

or to assignee a new name to the the copy:

WorkspaceItem Workspace.copy(String itemId, String newName, String destinationFolderId)

Move an item

To move a workspaceItem to a specified destination.

WorkspaceItem Workspace.moveItem(String itemId, String destinationFolderId)

Rename an item

To rename a workspaceItem:

Workspace.renameItem(String itemId, String newName)

Remove an item

To remove a workspaceItem from a folder by name:

Workspace.remove(String itemName, String folderId)

or to remove an item from a specific folder by ID:

Workspace.removeChild(String childId, String folderId)

or in the whole workspace by ID:

Workspace.removeItem(String itemId)

To remove a list of workspaceItem from the user workspace:

Map<String, String> Workspace.removeItems(String... id)

Sharing items

Access Control Policy

The repository supports 4 standard privileges identified by the string constants of org.gcube.common.homelibrary.home.workspace.accessmanager.ACLType:

READ_ONLY: this permission grants the ability to read the files in the shared folder.
WRITE_OWNER: this permission grants the ability to create and modify their own files. This includes the creating, deleting, moving and renaming, just for the own files.
WRITE_ALL: this permission grants the ability to modify the content of a shared folder. This includes creating files, deleting files, moving files and renaming files. It will not be allow to delete the shared folder root.
ADMINISTRATOR: this permission grants the ability to perform every actions on the shared folder. An administrator can also delete the shared folder root.

Guest Access to Workspace Folders

Home Library allows guest access to workspace folders in ready-only mode. Guest privileges can be set and removed through the user workspace. Public Folders are visible in a special smart folder. The workspace item history stores information about public access.

The method

boolean org.gcube.common.homelibrary.home.workspace.WorkspaceFolder#isPublic()

returns true if the folder is public, false otherwise.

The method

void org.gcube.common.homelibrary.home.workspace.WorkspaceFolder#setPublic(boolean flag)

sets and removes public access.

Create a shared folder

// Get the user workspace
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
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
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
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
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
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
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
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
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
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 workspaceItems

To search workspaceItems by properties:

import java.util.ArrayList;
import java.util.List;
import org.gcube.common.homelibrary.home.workspace.search.util.SearchQueryBuilder;
 
// Get the user workspace
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
// 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<WorkspaceItem> myItems = ws.searchByProperties(query.build());

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
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
// 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());

My Special Folders

My Special Folders are VRE folders automatically saved in "/Home/username/Workspace/MySpecialFolders/".

Get VRE Folders

// Get the user workspace
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
WorkspaceFolder folder = ws.getMySpecialFolders();
List<WorkspaceItem> specialFolders = folder.getChildren();
for (WorkspaceItem vreFolder : specialFolders){
	...
}

Get a VRE folder by scope

// Get the user workspace
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
String scope = ...
 
WorkspaceSharedFolder vre = ws.getVREFolderByScope(scope);

Catalogue Folder

Home Library provides methods to copy workspace files/folders in an ".catalogue" area before publishing such files on gCube Data Catalogue. In addition, Home Library allows users to get a workspace item by catalogue ID and to get a list of catalogue items by workspace item ID.

Get the user catalogue

import org.gcube.common.homelibrary.home.workspace.Workspace;
import org.gcube.common.homelibrary.home.workspace.catalogue.WorkspaceCatalogue;
 
// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
WorkspaceCatalogue catalogue = ws.getCatalogue();

Get a folder or file from catalogue by ID

import org.gcube.common.homelibrary.home.workspace.Workspace;
import org.gcube.common.homelibrary.home.workspace.catalogue.WorkspaceCatalogue;
 
// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
WorkspaceCatalogue catalogue = ws.getCatalogue();
String catalogueItemID = ...
 
WorkspaceItem folder = getCatalogueItem(catalogueItemID);

Get a folder or file from catalogue by path

import org.gcube.common.homelibrary.home.workspace.Workspace;
import org.gcube.common.homelibrary.home.workspace.catalogue.WorkspaceCatalogue;
 
// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
WorkspaceCatalogue catalogue = ws.getCatalogue();
 
WorkspaceItem folder = getCatalogueItemByPath("/MyFolder/MySubFolder");

Add a workspace item to the catalogue

import org.gcube.common.homelibrary.home.workspace.Workspace;
import org.gcube.common.homelibrary.home.workspace.catalogue.WorkspaceCatalogue;
 
// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
WorkspaceCatalogue catalogue = ws.getCatalogue();
 
WorkspaceItem workspaceItem = ws.getItemByPath("/Workspace/MyFolder/MyFile.txt");
 
WorkspaceItem catalogueFolder = catalogue.getCatalogueItem("/MyFolder/MySubFolder");
 
WorkspaceFolder newCatalogueFolder = catalogue.addWorkspaceItem(workspaceItem.getId(), catalogueFolder.getId());

Get a WorkspaceItem by Catalogue ID

import org.gcube.common.homelibrary.home.workspace.Workspace;
import org.gcube.common.homelibrary.home.workspace.catalogue.WorkspaceCatalogue;
 
// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
WorkspaceCatalogue catalogue = ws.getCatalogue();
 
WorkspaceItem catalogueItem = catalogue.getCatalogueItem("/MyFolder/MySubFolder");
 
WorkspaceItem workspaceItem = catalogue.getWorkspaceItemByCatalogueID(catalogueItem.getId());

Get Catalogue Items by Workspace ID

import org.gcube.common.homelibrary.home.workspace.Workspace;
import org.gcube.common.homelibrary.home.workspace.catalogue.WorkspaceCatalogue;
 
// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
WorkspaceCatalogue catalogue = ws.getCatalogue();
 
WorkspaceItem workspaceItem = ws.getItemByPath("/Workspace/MyFolder/MyFile.txt");
 
List<WorkspaceItem> catalogueItem = catalogue.getCatalogueItemByWorkspaceID(workspaceItem.getId());

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
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
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
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
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. It's possible 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
String user = ...
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
WorkspaceTrashFolder trash = ws.getTrash();

List items in Trash and their properties

import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
 
WorkspaceTrashFolder trash = ws.getTrash();
 
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 a folder?: " + item.isFolder());	
}

Empty trash

import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
 
WorkspaceTrashFolder trash = ws.getTrash();
trash.emptyTrash();

Delete permanently a specific item

import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
 
// ID item to delete permanently from the trash
String id = ...
 
WorkspaceTrashFolder trash = ws.getTrash();
trash.deletePermanentlyById(id);

Restore all

import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
 
WorkspaceTrashFolder trash = ws.getTrash();
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;
 
// ID item to restore
String id = ...
 
WorkspaceTrashFolder trash = ws.getTrash();
trash.restoreById(id);

WorkspaceItem

WorkspaceItem is the basic element of Home Library. A WorkspaceItem is either a file or a folder. A folder can have zero or more child items.

Identifier

The method

String WorkspaceItem.getId()

returns the identifier of the item.

Path

The method

String WorkspaceItem.getPath()

returns the absolute path of the item.

Description

The method

String WorkspaceItem.getDescription()

returns the description of the item.

Owner

The method

User WorkspaceItem.getOwner()

returns the owner of the item.

Creation Time

The method

Calendar WorkspaceItem.getCreationTime()

returns the item creation time.

Last update by

The method

String WorkspaceItem.getLastUpdatedBy()

returns the last user to update this item.

Last update time

The method

Calendar WorkspaceItem.getLastModificationTime()

returns the date of the last update.

Parent Folder

The method

WorkspaceFolder WorkspaceItem.isTrashed()

returns the parent folder of the current item.

Public Link

Generate a Public Link to quickly share any workspace file with a short or long URL and other people would be able to view your files straight from their browser.

The method

String WorkspaceItem.getPublicLink(boolean shortUrl)

returns the public link of the item. If shortUrl is true, a short URL will be generated.

Is Folder

The method

boolean WorkspaceItem.isFolder()

returns true if the item is a folder.

Is Hidden

The method

boolean WorkspaceItem.isHidden()

returns true if the item is a hidden file.

Is Shared

The method

boolean WorkspaceItem.isShared()

returns true if the item is shared.

Is Trashed

The method

boolean WorkspaceItem.isTrashed()

returns true if the item is in the Trash.

Get Children

The method

List<? extends WorkspaceItem> WorkspaceItem.getChildren()

returns all child items of a folder.

Utility

Check if a file exists

The existence of an item with a particular name in a given folder can be tested with:

boolean Workspace.exists(String name, String folderId)

or in the root folder:

boolean Workspace.exists(String itemId)

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.

Zip a folder

To zip a folder:

import org.gcube.common.homelibrary.util.zip.ZipUtil
File ZipUtil.zipFolder(WorkspaceFolder folder)

To zip a folder, excluding the root folder and some ids:

File ZipUtil.zipFolder(WorkspaceFolder folder, boolean skipRoot, List<String> idsToExclude)

To zip a list of items, excluding some ids:

File ZipUtil.zipWorkspaceItems(List<WorkspaceItem> items, List<String> idsToExclude)

UnZip a folder

To unzip a file in a specific folder, using a given name:

import org.gcube.common.homelibrary.util.zip.UnzipUtil
File UnzipUtil.zipFolder(WorkspaceFolder destinationFolder, InputStream is, String zipName)

To unzip a file in a specific folder, by path:

File UnzipUtil.unzip(WorkspaceFolder destinationFolder, String zipPath)

Usage/Examples

Creating folders

// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
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.

Get an item by identifier

To get the item with id "a42fbe8e-99cd-4f76-9e7f-47c933df243d":

// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
String itemId= "a42fbe8e-99cd-4f76-9e7f-47c933df243d";
WorkspaceItem item = ws.getItem(itemId);

Get an item by absolute path

To get the file "myFile.txt" from the folder "/Workspace/myFolder" of the user "test.user":

// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
String path = "/Workspace/myFolder/myFile.txt"
WorkspaceItem item = ws.getItemByPath(path);

List items of a folder

To get all child items of the folder "/Workspace/myFolder" in test.user's workspace:

// Get the user workspace
String user = "test.user";
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
 
String path = "/Workspace/myFolder"
(WorkspaceFolder) folder = (WorkspaceFolder) ws.getItemByPath(path);
List<WorkspaceItem> children = folder.getChildren();
for(WorkspaceItem child:children){
  System.out.println(child.getPublicLink(true));
}

This code returns a list of public link of all files in the folder myFolder.

Deployment

Home Library Web App Deployment

Deploy Home Library Web App to a Tomcat 7.x installation can be done by following these steps:

Get the Home Library Web App
Build Home Library Web App
Make sure Tomcat isn't running
Copy the file home-library-webapp.war to the <tomcat>/webapps/ directory.
Start Tomcat
You should now be able to access Home Library Web App at http://localhost:8080/home-library-webapp

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

Revision as of 14:33, 4 November 2016

Contents

Overview

Key features

Use cases

Design

Architecture

API

Get started

Reading

Retrieving the user Workspace

Retrieve information about user workspace

Get the disk usage

Get the total number of items

Get an item by identifier

Get an item by absolute path

Writing

Create a workspace folder

Create a generic file by Inputstream

Create a generic file by StorageId

Create an External File

Create an External Image

Create an External PDF File

Create an External URL

Create a Report

Create a ReportTemplate

Create a TimeSeries

Create a WorkflowReport

Create a Query

Create a gCubeItem

Setting properties

Copy an item

Move an item

Rename an item

Remove an item

Sharing items

Access Control Policy

Guest Access to Workspace Folders

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 workspaceItems

Advance Search on gCubeItems

My Special Folders

Get VRE Folders

Get a VRE folder by scope

Catalogue Folder

Get the user catalogue

Get a folder or file from catalogue by ID

Get a folder or file from catalogue by path

Add a workspace item to the catalogue

Get a WorkspaceItem by Catalogue ID

Get Catalogue Items by Workspace ID

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

Empty trash

Delete permanently a specific item

Restore all

Restore a specific item

WorkspaceItem

Identifier

Path

Description

Owner

Creation Time

Last update by

Last update time