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

From Gcube Wiki
Jump to: navigation, search
(Utility)
(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...")
 
(115 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Introduction =
+
== 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.
+
 
+
= 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 [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]]
+
 
+
== 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.
+
[[File: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:
+
 
+
<source lang="java">
+
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;
+
 
+
</source>
+
 
+
How to retrieve properties:
+
 
+
<source lang="java">
+
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()); 
+
 
+
</source>
+
 
+
===ImageDocument===
+
 
+
New Home Library API to retrieve ImageDocument Objects:
+
 
+
<source lang="java">
+
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;
+
 
+
</source>
+
 
+
To retrieve properties, use the API for Document Object and the following API:
+
 
+
<source lang="java">
+
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();
+
+
</source>
+
 
+
===Metadata===
+
New Home Library API to retrieve Metadata Objects:
+
 
+
<source lang="java">
+
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;
+
 
+
</source>
+
 
+
To retrieve properties:
+
 
+
<source lang="java">
+
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()); 
+
 
+
</source>
+
 
+
===PDFDocument===
+
New Home Library API to retrieve PDFDocument Objects:
+
 
+
<source lang="java">
+
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;
+
 
+
</source>
+
 
+
To retrieve properties, use the API for Document Object and the following API:
+
 
+
<source lang="java">
+
 
+
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()); 
+
+
</source>
+
 
+
===UrlDocument===
+
New Home Library API to retrieve UrlDocument Objects:
+
 
+
<source lang="java">
+
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;
+
 
+
</source>
+
 
+
To retrieve properties, use the API for Document Object and the following API:
+
 
+
<source lang="java">
+
 
+
document.getUrl(); -> document.getProperties().getProperties().get((NodeProperty.URL.toString()); 
+
+
</source>
+
 
+
=== Properties and Types ===
+
 
+
Properties and Types are in '''Home Library Model''', so update the package as follows:
+
<source lang="java">
+
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
+
</source>
+
 
+
== 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:
+
<source lang="xml">
+
<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>
+
</source>
+
 
+
== 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.
+
 
+
<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.
+
 
+
= Reading =
+
== 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 ===
+
<source lang="java5">
+
 
+
// Get the user workspace
+
Workspace ws = ...
+
 
+
String name = "MyFolder";
+
String description = "description";
+
 
+
WorkspaceFolder folder;
+
if (!ws.exists(name, destinationFolderId))
+
folder = ws.createFolder(name, description, destinationFolderId);
+
else
+
folder = (WorkspaceFolder) ws.find(name, destinationFolderId);
+
 
+
</source>
+
 
+
If the folder "MyFolder" does not exist in the destination folder, it will be created. Otherwise "MyFolder" will be retrieved.
+
 
+
== Creating files ==
+
=== Create a generic file 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:
+
 
+
<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
+
 
+
''org.gcube.common.homelibrary.home.workspace.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
+
 
+
''org.gcube.common.homelibrary.home.workspace.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
+
 
+
''org.gcube.common.homelibrary.home.workspace.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
+
 
+
''org.gcube.common.homelibrary.home.workspace.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 methods
+
 
+
''org.gcube.common.homelibrary.home.workspace.Workspace#createQuery(String name, String description, InputStream query, QueryType queryType, String destinationfolderId)''
+
''org.gcube.common.homelibrary.home.workspace.Workspace#createQuery(String name, String description, String query, QueryType queryType, String destinationfolderId)''
+
 
+
create a Query in a specified folder.
+
 
+
=== 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>
+
 
+
= Sharing items =
+
 
+
== Create a shared folder ==
+
<source lang="java5">
+
 
+
// Get the user workspace
+
Workspace ws = ...
+
 
+
String name = "MySharedFolder";
+
String description = "description";
+
List<String> users = ...
+
String destinationFolderId = ...
+
 
+
WorkspaceSharedFolder sharedFolder = ws.createSharedFolder(name, description, users, destinationFolderId);
+
sharedFolder.setACL(users, ACLType.READ_ONLY);
+
 
+
</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
+
Workspace ws = ...
+
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
+
Workspace ws = ...
+
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
+
Workspace ws = ...
+
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
+
Workspace ws = ...
+
 
+
List<String> keys = new ArrayList<String>();
+
keys.add("key00");
+
keys.add("key01");
+
 
+
// Get WorkspaceItem that contain certain keys
+
List<WorkspaceItem> properties = ws.searchByProperties(keys);
+
</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
+
Workspace ws = ...
+
 
+
// Create a SearchQuery
+
SearchQueryBuilder query = new SearchQueryBuilder();
+
 
+
// Get gCubeItems that contain a certain key
+
query.contains("key00");
+
 
+
// Get gCubeItems where key01 = value01
+
query.contains("key01","value01");
+
 
+
// Get gCubeItems where type = myType
+
query.ofType("myType");
+
 
+
List<GCubeItem> myItems = ws.searchGCubeItems(query.build());
+
</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
+
Workspace ws = ...
+
 
+
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
+
Workspace ws = ...
+
String scope = ...
+
 
+
WorkspaceSharedFolder vre = ws.getVREFolderByScope(scope);
+
 
+
</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
+
Workspace ws = ...
+
 
+
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
+
Workspace ws = ...
+
 
+
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
+
Workspace ws = ...
+
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>
+
 
+
= Utility =
+
== 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)
+
File ZipUtil.zipFolder(WorkspaceFolder folder, boolean skipRoot, List<String> idsToExclude)
+
File ZipUtil.zipWorkspaceItems(List<WorkspaceItem> items, List<String> idsToExclude)
+
</source>
+
 
+
== UnZip a folder ==
+
 
+
To unzip a folder:
+
 
+
<source lang="java5">
+
import org.gcube.common.homelibrary.util.zip.UnzipUtil
+
File UnzipUtil.zipFolder(WorkspaceFolder destinationFolder, InputStream is, String zipName)
+
File UnzipUtil.unzip(WorkspaceFolder destinationFolder, String zipPath)
+
</source>
+

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