|
|
| (142 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
| + | |
| − | | + | |
| − | = Using Home Library =
| + | |
| − | | + | |
| − | To use Home Library 2.0, import the following dependencies:
| + | |
| − | <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>
| + | |
| − | </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.
| + | |
| − | | + | |
| − | == Creating folders ==
| + | |
| − | | + | |
| − | ===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.
| + | |
| − | | + | |
| − | === 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#ccreateExternalUrl(String name, String description, String url, String destinationFolderId)''
| + | |
| − | | + | |
| − | create an external URL in a specified folder.
| + | |
| − | | + | |
| − | === Add properties to an item ===
| + | |
| − | | + | |
| − | After retrieving the user workspace root:
| + | |
| − | | + | |
| − | <source lang="java5">
| + | |
| − | | + | |
| − | String name = "key";
| + | |
| − | String value = "value";
| + | |
| − | | + | |
| − | // Get an item
| + | |
| − | FolderItem folderItem = ...
| + | |
| − | | + | |
| − | // Add properties
| + | |
| − | folderItem.getProperties().addProperty(name, value);
| + | |
| − | | + | |
| − | </source>
| + | |
| − | | + | |
| − | === 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>
| + | |
| − | | + | |
| − | == 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>
| + | |
| − | | + | |
| − | == Retrieve information about user workspace ==
| + | |
| − | === Get the disk usage ===
| + | |
| − | Get information about the disk space usage:
| + | |
| − | <source lang="java5">
| + | |
| − | // Get the user workspace
| + | |
| − | Workspace ws = ...
| + | |
| − | | + | |
| − | long diskUsage = ws.getDiskUsage();
| + | |
| − | | + | |
| − | </source>
| + | |
| − | | + | |
| − | === Get the total number of items ===
| + | |
| − | Get information about the total number of items in the user workspace:
| + | |
| − | <source lang="java5">
| + | |
| − | // Get the user workspace
| + | |
| − | Workspace ws = ...
| + | |
| − | | + | |
| − | int totalItems = ws.getTotalItems();
| + | |
| − | | + | |
| − | </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 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>
| + | |
