|
|
| (274 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 users homes. that supports file sharing | + | |
| − | 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.
| + | |
| − | | + | |
| − | 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 build on the top of the Jackrabbit web application. 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 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]]
| + | |
| − | | + | |
| − | ====Objects removed====
| + | |
| − | | + | |
| − | *AquaMapsItem
| + | |
| − | *Annotation
| + | |
| − | *DocumentLink
| + | |
| − | *ImageDocumentLink
| + | |
| − | *PDFDocumentLink
| + | |
| − | *Annotation
| + | |
| − | *TabularDataLink
| + | |
| − | *ExternalResourceLink
| + | |
| − | *WorkflowReport
| + | |
| − | *WorkflowTemplate
| + | |
| − | | + | |
| − | ====Objects mapped to gCubeItem====
| + | |
| − | | + | |
| − | *Document
| + | |
| − | *ImageDocument
| + | |
| − | *Metadata
| + | |
| − | *PDFDocument
| + | |
| − | *UrlDocument
| + | |
| − | | + | |
| − | | + | |
| − | Use the next section to keep code compatible with both old and new API.
| + | |
| − | | + | |
| − | ===Compatibility===
| + | |
| − | There is some pattern to know during the transition period to keep code base compatible with both old and new API.
| + | |
| − | | + | |
| − | If using old API 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
| + | |
| − | | + | |
| − | '''Home Library Model''' is a library to shared information between clients and Web App. It includes ACLType, FolderItemType, NodeProperty, WorkspaceItemType, etc.
| + | |
| − | | + | |
| − | == 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>
| + | |
