|
|
(257 intermediate revisions by 3 users not shown) |
Line 1: |
Line 1: |
− | = Home Library 2.0 API = | + | == 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>
| + | |
− | | + | |
− | == 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
| + | |
− | | + | |
− | == How to ==
| + | |
− | 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>
| + | |
− | | + | |
− | 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>
| + | |