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

From Gcube Wiki
Jump to: navigation, search
(→‎Catalogue Folder)
(→‎Catalogue Folder)
Line 851: Line 851:
 
</source>
 
</source>
  
−
== Get an existing folder or file from catalogue ==
+
== Get a folder or file from catalogue by ID==
  
 
<source lang="java5">
 
<source lang="java5">
Line 862: Line 862:
  
 
WorkspaceCatalogue catalogue = ws.getCatalogue();
 
WorkspaceCatalogue catalogue = ws.getCatalogue();
 +
String catalogueItemID = ...
  
−
WorkspaceItem folder = getCatalogueItem("/MyFolder/MySubFolder");
+
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");
  
  

Revision as of 11:52, 9 September 2016

Contents

Introduction

The Home Library is a library to manage and persist the user home folder that supports file sharing.

Any Home Library user is presented with a personal Workspace, where users can collaborate, share information, and access project resources using special folders. This module describes the model of Home Library 2.0 and how to use the new API interface.

Design Model

The design model for Home Library identifies a core set of capabilities to work on Jackrabbit content. The goal of Home Library 2.0 is to expose content in the content repository as HTTP resources, fostering a RESTful style of application architecture. Home Library 2.0 is 10 times faster on average in comparison with the previous version.

The Home Library 2.0 is composed by:

  • HomeLibrary: the API interface.
  • HomeLibrary JCR: an HomeLibrary implementation based on JCR 2.0 (Java Content Repository JSR 283).
  • HomeLibrary WebApp: a webService built on the top of the Jackrabbit web application.
  • Home Library Model: a library to shared information between clients and Web App. It includes ACLType, FolderItemType, NodeProperty, WorkspaceItemType, etc.

WebApp.png

Workspace Items

Each element contained in a workspace area is a WorkspaceItem.The workspace items are the effective user objects.

The following figure shows the WorkspaceItem model. Areamodel.png

Prior HL 2.0 Objects that have been removed

  • AquaMapsItem
  • Annotation
  • DocumentLink
  • ImageDocumentLink
  • PDFDocumentLink
  • Annotation
  • TabularDataLink
  • ExternalResourceLink
  • WorkflowReport
  • WorkflowTemplate

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

  • Document
  • ImageDocument
  • Metadata
  • PDFDocument
  • UrlDocument


Use the next section to migrate your components to the new Home Library API.

Compatibility

There is some pattern to know to keep code compatible with new API.

If you were working on Document, ImageDocument, Metadata, PDFDocument or UrlDocument, using new API your are going to work on GCubeItem that is a generic gCube Object.

But old context and model are still available using the following sections.

Document

Home Library 2.0 API to retrieve Document Objects: 

import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.Document;
 
Document document = (Document) item;
 
becomes: 
 
import org.gcube.common.homelibary.model.items.type.NodeProperty;
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
 
GCubeItem document = (GCubeItem) item;

How to retrieve properties: 

document.getAlternatives(); -> document.getProperties().getProperties().get((NodeProperty.ALTERNATIVES.toString()); 
document.getAnnotation(); -> document.getProperties().getProperties().get((NodeProperty.ANNOTATIONS.toString()); 
document.getCollectionName(); -> document.getProperties().getProperties().get((NodeProperty.COLLECTION_NAME.toString()); 
document.getData(); -> document.getProperties().getProperties().get((NodeProperty.DATA.toString());
document.getFolderItemType(); -> document.getProperties().getProperties().get((NodeProperty.FOLDER_ITEM_TYPE.toString());
document.getLength(); -> document.getProperties().getProperties().get((NodeProperty.SIZE.toString());
document.getMetadata(); -> document.getProperties().getProperties().get((NodeProperty.METADATA.toString());
document.getMimeType(); -> document.getProperties().getProperties().get((NodeProperty.MIME_TYPE.toString());  
document.getParts(); -> document.getProperties().getProperties().get((NodeProperty.PARTS.toString()); 
document.getURI(); -> document.getProperties().getProperties().get((NodeProperty.OID.toString());  
document.getWorkflowData(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_DATA.toString());  
document.getWorkflowId(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_ID.toString());  
document.getWorkflowStatus(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_STATUS.toString());

ImageDocument

New Home Library API to retrieve ImageDocument Objects: 

import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.ImageDocument;
 
ImageDocument document = (ImageDocument) item;
 
becomes: 
 
import org.gcube.common.homelibary.model.items.type.NodeProperty;
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
 
GCubeItem document = (GCubeItem) item;

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

document.getHeight(); -> document.getProperties().getProperties().get((NodeProperty.IMAGE_HEIGHT.toString());  
document.getWidth(); -> document.getProperties().getProperties().get((NodeProperty.IMAGE_WIDTH.toString());  
document.getThumbnailHeight(); -> document.getProperties().getProperties().get((NodeProperty.THUMBNAIL_HEIGHT.toString());    
document.getThumbnailWidth(); -> document.getProperties().getProperties().get((NodeProperty.THUMBNAIL_WIDTH.toString());  
document.getThumbnail(); -> document.getProperties().getProperties().get((NodeProperty.THUMBNAIL_DATA.toString()); 
document.getThumbnailLength(); -> document.getThumbnail().getSize();

Metadata

New Home Library API to retrieve Metadata Objects: 

import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.Metadata;
 
Metadata document = (Metadata) item;
 
becomes: 
 
import org.gcube.common.homelibary.model.items.type.NodeProperty;
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
 
GCubeItem document = (GCubeItem) item;

To retrieve properties: 

document.getURI(); -> document.getProperties().getProperties().get((NodeProperty.OID.toString());  
document.getWorkflowData(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_DATA.toString());  
document.getWorkflowId(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_ID.toString());  
document.getWorkflowStatus(); -> document.getProperties().getProperties().get((NodeProperty.WORKFLOW_STATUS.toString());
 
document.getSchemaName(); -> document.getProperties().getProperties().get((NodeProperty.SCHEMA.toString()); 
document.getXML(); -> document.getProperties().getProperties().get((NodeProperty.ALTERNATIVES.toString()); 
document.getCollectionName(); -> document.getProperties().getProperties().get((NodeProperty.COLLECTION_NAME.toString()); 
document.getURI(); -> document.getProperties().getProperties().get((NodeProperty.OID.toString());

PDFDocument

New Home Library API to retrieve PDFDocument Objects: 

import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.PDFDocument;
 
PDFDocument document = (PDFDocument) item;
 
becomes: 
 
import org.gcube.common.homelibary.model.items.type.NodeProperty;
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
 
GCubeItem document = (GCubeItem) item;

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

document.getNumberOfPages(); -> document.getProperties().getProperties().get((NodeProperty.NUMBER_OF_PAGES.toString());  
document.getVersion(); -> document.getProperties().getProperties().get((NodeProperty.VERSION.toString());  
document.getAuthor(); -> document.getProperties().getProperties().get((NodeProperty.AUTHOR.toString());  
document.getTitle(); -> document.getProperties().getProperties().get((NodeProperty.PDF_TITLE.toString());  
document.getProducer(); -> document.getProperties().getProperties().get((NodeProperty.PRODUCER.toString());

UrlDocument

New Home Library API to retrieve UrlDocument Objects: 

import org.gcube.common.homelibrary.home.workspace.folder.items.gcube.UrlDocument;
 
UrlDocument document = (UrlDocument) item;
 
becomes: 
 
import org.gcube.common.homelibary.model.items.type.NodeProperty;
import org.gcube.common.homelibrary.home.workspace.folder.items.GCubeItem;
 
GCubeItem document = (GCubeItem) item;

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

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

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

Connecting

Add library to your project

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

<project>
<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>
 
</dependencies>
</project>

Retrieving the user Home

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.

Reading

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 files

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.


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.

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.

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

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)

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.

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