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

From Gcube Wiki
Jump to: navigation, search
(Deployment)
(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...")
 
(42 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Overview =
+
== 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 [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.
+
 
+
= 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 =
+
 
+
= Design =
+
 
+
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.
+
 
+
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 [http://jcp.org/en/jsr/detail?id=283 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.
+
[[File:WebApp.png]]
+
 
+
The basic element of the HomeLibrary is a WorkspaceItem. The workspace items are the effective user objects.
+
 
+
The following figure shows the WorkspaceItem model.
+
[[File:areamodel.png]]
+
 
+
== API ==
+
 
+
=== 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.
+
 
+
<source lang="java5">
+
HomeManagerFactory factory = HomeLibrary.getHomeManagerFactory();
+
</source>
+
 
+
Obtained the factory you can retrieve the HomeManager:
+
<source lang="java5">
+
HomeManager manager = factory.getHomeManager();
+
</source>
+
 
+
Then we retrieve the User home:
+
<source lang="java5">
+
User user = manager.createUser(portalLogin);
+
Home home = manager.getHome(user);
+
</source>
+
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:
+
<source lang="java5">
+
Workspace ws = home.getWorkspace();
+
WorkspaceFolder root = ws.getRoot();
+
</source>
+
 
+
There are some example of HomeLibrary use.
+
 
+
==== Retrieve information about user workspace ====
+
===== Get the disk usage =====
+
Get information about the disk space usage:
+
<source lang="java5">
+
 
+
long Workspace.getDiskUsage();
+
 
+
</source>
+
 
+
===== Get the total number of items =====
+
Get information about the total number of items in the user workspace:
+
<source lang="java5">
+
 
+
int Workspace.getTotalItems()
+
 
+
</source>
+
 
+
==== Get an item by identifier ====
+
 
+
An item can be retrieved by its identifier with:
+
<source lang="java5">
+
 
+
WorkspaceItem Workspace.getItem(String itemId);
+
</source>
+
 
+
==== Get an item by absolute path ====
+
 
+
An item can be acquired by absolute path with:
+
<source lang="java5">
+
 
+
WorkspaceItem Workspace.getItemByPath(String path);
+
 
+
</source>
+
 
+
=== Writing ===
+
 
+
===== Create a workspace folder =====
+
 
+
To create a folder in a destination folder:
+
<source lang="java5">
+
 
+
WorkspaceFolder Workspace.createFolder(name, description, destinationFolderId);
+
 
+
</source>
+
 
+
===== 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:
+
 
+
<source lang="java5">
+
 
+
// 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);
+
 
+
</source>
+
 
+
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)''
+
 
+
 
+
<source lang="java5">
+
 
+
String storageId = ...
+
FolderItem folderItem = WorkspaceUtil.createExternalFile(destinationFolder, name, description, mimeType, storageId);
+
 
+
</source>
+
 
+
===== 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:
+
<source lang="java5">
+
 
+
// 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);
+
 
+
</source>
+
 
+
===== 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
+
<source lang="java5">
+
 
+
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)
+
 
+
</source>
+
 
+
creates a Report in a specified folder.
+
 
+
===== Create a ReportTemplate =====
+
The method
+
<source lang="java5">
+
 
+
ReportTemplate Workspace.createReportTemplate(String name, String description, Calendar created, Calendar lastEdit, String author,
+
String lastEditBy, int numberOfSections, String status, InputStream templateData, String destinationfolderId)
+
 
+
</source>
+
 
+
creates a ReportTemplate in a specified folder.
+
 
+
===== Create a TimeSeries =====
+
The method
+
 
+
<source lang="java5">
+
 
+
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)
+
 
+
</source>
+
 
+
creates a TimeSeries in a specified folder.
+
 
+
===== Create a WorkflowReport =====
+
The method
+
 
+
<source lang="java5">
+
 
+
WorkflowReport Workspace.createWorkflowReport(String name, String description, String workflowId, String workflowStatus, String workflowData, String destinationfolderId)
+
 
+
</source>
+
 
+
creates a WorkflowReport in a specified folder.
+
 
+
===== Create a Query =====
+
The method
+
<source lang="java5">
+
 
+
Query Workspace.createQuery(String name, String description, InputStream query, QueryType queryType, String destinationfolderId)
+
</source>
+
creates a Query in a specified folder by inputstream
+
 
+
<source lang="java5">
+
 
+
Query Workspace.createQuery(String name, String description, String query, QueryType queryType, String destinationfolderId)
+
 
+
</source>
+
 
+
or by query string.
+
 
+
===== Create a gCubeItem =====
+
 
+
<source lang="java5">
+
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);
+
</source>
+
 
+
===== 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:
+
 
+
<source lang="java5">
+
 
+
Map<String, String> properties = ..
+
 
+
// Get an item
+
FolderItem folderItem = ...
+
 
+
// Add properties
+
folderItem.getProperties().addProperties(properties);
+
 
+
</source>
+
 
+
===== Copy an item =====
+
 
+
To copy an item from a folder to another folder. The copy has the same name of the original.
+
<source lang="java5">
+
 
+
WorkspaceItem Workspace.copy(String itemId, String destinationFolderId)
+
 
+
</source>
+
 
+
or to assignee a new name to the the copy:
+
<source lang="java5">
+
 
+
WorkspaceItem Workspace.copy(String itemId, String newName, String destinationFolderId)
+
 
+
</source>
+
 
+
===== Move an item =====
+
 
+
To move a workspaceItem to a specified destination.
+
 
+
<source lang="java5">
+
 
+
WorkspaceItem Workspace.moveItem(String itemId, String destinationFolderId)
+
 
+
</source>
+
 
+
===== Rename an item =====
+
To rename a workspaceItem:
+
 
+
<source lang="java5">
+
 
+
Workspace.renameItem(String itemId, String newName)
+
 
+
</source>
+
 
+
===== Remove an item =====
+
To remove a workspaceItem from a folder by name:
+
 
+
<source lang="java5">
+
 
+
Workspace.remove(String itemName, String folderId)
+
</source>
+
 
+
or to remove an item from a specific folder by ID:
+
<source lang="java5">
+
 
+
Workspace.removeChild(String childId, String folderId)
+
 
+
</source>
+
 
+
or in the whole workspace by ID:
+
<source lang="java5">
+
 
+
Workspace.removeItem(String itemId)
+
 
+
</source>
+
 
+
 
+
To remove a list of workspaceItem from the user workspace:
+
 
+
<source lang="java5">
+
 
+
Map<String, String> Workspace.removeItems(String... id)
+
 
+
</source>
+
 
+
==== 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.
+
 
+
===== Create a shared folder =====
+
<source lang="java5">
+
 
+
// 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);
+
 
+
</source>
+
 
+
===== Share an existing folder =====
+
<source lang="java5">
+
 
+
//Get an existing folder
+
WorkspaceFolder folder = ...
+
 
+
List<String> users = ...
+
+
WorkspaceSharedFolder sharedFolder = folder.share(users);
+
sharedFolder.setACL(users, ACLType.READ_ONLY);
+
 
+
</source>
+
 
+
===== Unshare a folder =====
+
 
+
<source lang="java5">
+
 
+
//Get an existing shared folder
+
WorkspaceSharedFolder sharedFolder = ...
+
 
+
WorkspaceItem folder = ws.unshare(sharedFolder.getId());
+
 
+
</source>
+
 
+
===== Unshare a folder for a single user =====
+
<source lang="java5">
+
 
+
//Get an existing shared folder
+
WorkspaceSharedFolder sharedFolder = ...
+
String user = ...
+
 
+
WorkspaceFolder folder = sharedFolder.unShare(user);
+
 
+
</source>
+
 
+
=== Searching items ===
+
 
+
==== Search an item in a specific folder ====
+
 
+
<source lang="java5">
+
 
+
// 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);
+
</source>
+
 
+
Subfolders are not included in the search.
+
 
+
==== Search items by name ====
+
To search items by name on a folder and all its subfolders:
+
 
+
<source lang="java5">
+
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);
+
</source>
+
 
+
==== Search items by mime type ====
+
 
+
To search items by mime type on the user workspace:
+
 
+
<source lang="java5">
+
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);
+
</source>
+
 
+
==== Search items by properties ====
+
To search items by properties:
+
 
+
<source lang="java5">
+
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);
+
</source>
+
 
+
==== Advance Search on workspaceItems ====
+
To search workspaceItems by properties:
+
 
+
<source lang="java5">
+
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());
+
</source>
+
 
+
==== Advance Search on gCubeItems ====
+
 
+
To search gCubeItems by properties:
+
 
+
<source lang="java5">
+
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());
+
</source>
+
 
+
=== My Special Folders ===
+
My Special Folders are VRE folders automatically saved in "/Home/username/Workspace/MySpecialFolders/".
+
 
+
==== Get VRE Folders ====
+
<source lang="java5">
+
 
+
// 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){
+
...
+
}
+
 
+
</source>
+
 
+
==== Get a VRE folder by scope ====
+
<source lang="java5">
+
 
+
// Get the user workspace
+
String user = ...
+
Workspace ws = HomeLibrary.getHomeManagerFactory().getHomeManager().getHome(user).getWorkspace();
+
 
+
String scope = ...
+
 
+
WorkspaceSharedFolder vre = ws.getVREFolderByScope(scope);
+
 
+
</source>
+
 
+
=== Catalogue Folder ===
+
 
+
==== Get the user catalogue ====
+
 
+
<source lang="java5">
+
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();
+
 
+
</source>
+
 
+
==== Get a folder or file from catalogue by ID====
+
 
+
<source lang="java5">
+
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);
+
 
+
 
+
</source>
+
 
+
==== Get a folder or file from catalogue by path====
+
 
+
<source lang="java5">
+
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");
+
 
+
 
+
</source>
+
 
+
==== Add a workspace item to the catalogue ====
+
 
+
<source lang="java5">
+
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());
+
 
+
</source>
+
 
+
==== Get a WorkspaceItem by Catalogue ID ====
+
<source lang="java5">
+
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());
+
 
+
</source>
+
 
+
==== Get Catalogue Items by Workspace ID ====
+
 
+
<source lang="java5">
+
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());
+
 
+
</source>
+
 
+
=== Smart Folders ===
+
 
+
==== Create a Smart Folder ====
+
To create a smart folder, where the filename includes a certain query, in this case "test":
+
 
+
<source lang="java5">
+
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);
+
 
+
</source>
+
 
+
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:
+
 
+
<source lang="java5">
+
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()
+
 
+
</source>
+
 
+
==== Get all items in a Smart Folder ====
+
To get all items in a smart folder:
+
 
+
<source lang="java5">
+
import org.gcube.common.homelibrary.home.workspace.WorkspaceSmartFolder;
+
 
+
// Get the smart folder
+
WorkspaceSmartFolder mySmartFolder = ...
+
 
+
List<? extends SearchItem> list = mySmartFolder.getSearchItems();
+
 
+
</source>
+
 
+
==== Remove a Smart Folder ====
+
 
+
To remove a smart folder:
+
 
+
<source lang="java5">
+
import org.gcube.common.homelibrary.home.workspace.WorkspaceSmartFolder;
+
 
+
// Get the smart folder to remove
+
WorkspaceSmartFolder mySmartFolder = ...
+
 
+
mySmartFolder.remove();
+
 
+
</source>
+
 
+
=== 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 ====
+
 
+
<source lang="java5">
+
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();
+
 
+
</source>
+
 
+
==== List items in Trash and their properties====
+
 
+
<source lang="java5">
+
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());
+
}
+
 
+
</source>
+
 
+
==== Empty trash ====
+
<source lang="java5">
+
import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
+
 
+
WorkspaceTrashFolder trash = ws.getTrash();
+
trash.emptyTrash();
+
 
+
</source>
+
 
+
==== Delete permanently a specific item ====
+
 
+
<source lang="java5">
+
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);
+
 
+
</source>
+
 
+
==== Restore all ====
+
 
+
<source lang="java5">
+
import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
+
 
+
WorkspaceTrashFolder trash = ws.getTrash();
+
trash.restoreAll();
+
 
+
</source>
+
 
+
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 ====
+
<source lang="java5">
+
import org.gcube.common.homelibrary.home.workspace.trash.WorkspaceTrashFolder;
+
 
+
// ID item to restore
+
String id = ...
+
 
+
WorkspaceTrashFolder trash = ws.getTrash();
+
trash.restoreById(id);
+
 
+
</source>
+
 
+
=== 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:
+
<source lang="java5">
+
boolean Workspace.exists(String name, String folderId)
+
</source>
+
 
+
or in the root folder:
+
<source lang="java5">
+
boolean Workspace.exists(String itemId)
+
</source>
+
 
+
==== Generate an unique name for a folder item ====
+
To generate an unique item name for a given folder:
+
 
+
<source lang="java5">
+
 
+
// Get a destination folder
+
WorkspaceFolder destionationFolder = ...
+
 
+
String nameCandidate = "My first item";
+
+
String name = WorkspaceUtil.getUniqueName(nameCandidate, destionationFolder);
+
</source>
+
 
+
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:
+
 
+
<source lang="java5">
+
import org.gcube.common.homelibrary.util.zip.ZipUtil
+
File ZipUtil.zipFolder(WorkspaceFolder folder)
+
</source>
+
 
+
 
+
To zip a folder, excluding the root folder and some ids:
+
 
+
<source lang="java5">
+
File ZipUtil.zipFolder(WorkspaceFolder folder, boolean skipRoot, List<String> idsToExclude)
+
</source>
+
 
+
 
+
To zip a list of items, excluding some ids:
+
 
+
<source lang="java5">
+
File ZipUtil.zipWorkspaceItems(List<WorkspaceItem> items, List<String> idsToExclude)
+
</source>
+
 
+
==== UnZip a folder ====
+
 
+
To unzip a file in a specific folder, using a given name:
+
 
+
<source lang="java5">
+
import org.gcube.common.homelibrary.util.zip.UnzipUtil
+
File UnzipUtil.zipFolder(WorkspaceFolder destinationFolder, InputStream is, String zipName)
+
</source>
+
 
+
 
+
To unzip a file in a specific folder, by path:
+
 
+
<source lang="java5">
+
File UnzipUtil.unzip(WorkspaceFolder destinationFolder, String zipPath)
+
</source>
+
 
+
== Usage/Examples ==
+
=== Creating folders ===
+
<source lang="java5">
+
 
+
// 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);
+
 
+
</source>
+
 
+
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":
+
 
+
<source lang="java5">
+
 
+
// 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);
+
 
+
</source>
+
 
+
=== Get an item by absolute path ===
+
 
+
To get the file "myFile.txt" from the folder "/Workspace/myFolder" of the user "test.user":
+
 
+
<source lang="java5">
+
 
+
// 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);
+
 
+
</source>
+
 
+
=== List items of a folder ===
+
 
+
To get all child items of the folder "/Workspace/myFolder" in test.user's workspace:
+
 
+
<source lang="java5">
+
 
+
// 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));
+
}
+
</source>
+
 
+
This code returns a list of public link of all files in the folder myFolder.
+
 
+
= Deployment =
+
 
+
To use Home Library 2.0, add the following to your pom.xml file:
+
<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>
+

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