| Version 11 (modified by , 10 years ago) (diff) |
|---|
CLARIN Virtual Collection Registry
Description
From the requirements description:
A virtual collection (VC) is a collection that is the result of browsing or searching repositories rather than being the result of construction and first-time publication by an organisation. Another characterisation is that the resources in a VC are already available in other collections, and the VC can be considered a derived collection. Nevertheless these VCs may need to be citable for future use and should therefore be able to be registered in a register, the VCR.
The Virtual Collection Registry (VCR) is an online registry that provides a RESTful web service (REST service) as well as a web based graphical user interface for the creation, publication, management and retrieval of virtual collections. Published collections are made available as CMDI records over OAI-PMH.
These components are available at the following locations (currently referencing the alpha deployment!):
- /vcr/app: GUI
- /vcr/service: REST service
- /vcr/oai: OAI-PMH endpoint
The help page explains the core concepts and terminology relevant to the VCR (based on the information gathered on this page).
REST service
The VCR REST service provides CRUD operations on a 'virtualcollection' resource. Its internal XML format for input and output is defined by an XML schema. In addition, it supports JSON for input and output and CMDI and HTML output for individual collections (via content negotiation).
A full description of the service can be found in Protocol.txt.
Form submission service
A special endpoint of the VCR REST service allows input from HMTL forms to create new virtual collections. This way, other web applications (such as the VLO) can prepare a collection based on resources gathered in their workflows, and allow the user to send them to the VCR with a single click while preserving the ability to authenticate via Shibboleth.
The submission endpoint is /vcr/service/submit. It accepts the following form parameters:
- type (required)
- name (required)
- metadataUri (list, required)
- resourceUri (list, required)
- description (required)
- keyword
- purpose
- reproducibility
- reproducibilityNotice
- creationDate
- queryDescription
- queryUri
- queryProfile
- queryValue
An example implementation (based on Wicket) can be found in the 'VirtualCollectionSubmissionPage' in the experimental branch of the VLO.
Technical notes
Development
The VCR sources are contained in a single Maven project. Most of the code is written in Java, complemented by HTML, (S)CSS and some images for the graphical user interface and a number of XML documents. Structurally, it consists of three largely independent functional components, each providing an interface to a shared 'VirtualCollectionRegistry' core service. The sections below describe the shared 'core' and the individual components.
VCR core
The core of the VCR is the collection store, which is implemented through JPA with annotated classes in the eu.clarin.cmdi.virtualcollectionregistry.model package. The persistence.xml file configures the Hibernate Persistence Provider to use a MySQL datasource for storage. The 'update' value of the hibernate.hbm2ddl.auto property instructs Hibernate to update the database schema at runtime if needed. A singleton object of the DataStore class provides access to the JPA Entity Manager.
The DataStore is primarily used in the service implemented by the VirtualCollectionRegistry class, which provides high level CRUD methods, using the VirtualCollection model class for the representation of individual collections. These methods are used by the REST service, OAI provider and Wicket application classes to access and manipulate the stored collections.
The Spring framework is used to define beans for singleton service objects, which are injected into various components throughout the application. The applicationContext.xml file bootstraps the bean definition, while most beans are discovered en constructed by means of 'component scanning'. For example, a singleton bean for DataStore exists because it is annotated @Repository. The instance is made available in the VirtualCollectionRegistry and Application (for the Wicket UI) instances because both are managed by Spring too (annotated with @Service and @Component respectively) and contain a DataStore field annotated with @Autowired.
A number of core services for marshalling, validation, etcetera can be found in eu.clarin.cmdi.virtualcollectionregistry.service package (generally interfaces with implementations in the .impl subpackage).
More info:
- JPA introduction
- Hibernate hbm2ddl.auto (stackoverflow)
- Spring component scanning and autowiring example and explanation
JAX-RS REST service
The package eu.clarin.cmdi.virtualcollectionregistry.rest defines a RESTful web service by means of JAX-RS annotations. It uses https://jersey.java.net/ Jersey as an implementation and depends on a number of Jersey extensions, primarily injection of beans. Four classes define the following (sub)resources:
- /virtualcollections (class VirtualCollectionsResource) allows listing (GET) of published collections and POSTing of new collections
- /virtualcollections/{id} (class VirtualCollectionResource) is a subresource that allows GETting, PUTting and DELETEing individual collections
- /my-virtualcollections (class MyVirtualCollectionsResource) only allows retrieval (GET) the list of private and published collections owned by the authenticated user
- / (class BaseResource) is a dummy resource that renders an informative HTML page (if content negotiation allows) about the service
Two BodyWriter classes are implemented and registered, taking care of the rendering of VirtualCollection object as CMDI or XML/JSON respectively, by means of different methods of the (injected) VirtualCollectionMarshaller service. This way, a single method in VirtualCollectionResource can handle these various serialisation options (depending on the HTTP Accept header in the client request). An additional method handles requests accepting HTML by returning a redirect ('see other') response pointing to the collection details page of the Wicket UI.
More info:
Wicket application (UI)
The graphical user interface is implemented as a Wicket (version 1.4) web application, which can be found in eu.clarin.cmdi.virtualcollectionregistry.gui and subpackages. The Application class is the entry point to the application, and is registered as a bean that gets picked up by the SpringWebApplicationFactory defined in the web.xml. Each page is defined by a tuple consisting of a class and HTML template of the same name (minus extension). Most pages consist of components, many of which are custom to the VCR and are also defined by a class and HTML template. Each page and component typically represents a model; the VCR has a number of custom Wicket component model implementations in the gui package. All pages extend a BasePage, which defines the common layout (header, footer including some common components).
The VCR user interface makes quite intensive use of Javascript. First of all, it uses Wicket's out-of-the-box functionalities for partial updates via AJAX. In addition, JQuery is used for enhanced client side interaction. There is some custom JQuery based code, which is integrated with the Wicket components using the WiQuery library. The base page includes the Bootstrap Javascript library to support some out-of-the-box layout niceness.
The style of the UI is defined by a combination of Bootstrap CSS classes (like the Javascript, the style is included in the base page) and a number of .scss (SASS) files that get compiled to CSS at build time. The main file is vcr.scss, which include the base CLARIN style and includes a number of VCR-specific style definitions.
More info:
OAI provider
Deployment
web.xml variations
build profiles
deployment package
Tickets
Milestones:
Open tickets:
Attachments (1)
- VCR-architecture.png (25.0 KB) - added by 8 years ago.
Download all attachments as: .zip
