[[PageOutline(2-5)]] = CLARIN Virtual Collection Registry= == Description == From the [[./Requirements|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!)''': * [http://catalog-clarin.esc.rzg.mpg.de/vcr/app /vcr/app]: GUI * [http://catalog-clarin.esc.rzg.mpg.de/vcr/service /vcr/service]: REST service * [http://catalog-clarin.esc.rzg.mpg.de/vcr/oai /vcr/oai]: OAI-PMH endpoint The [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/java/eu/clarin/cmdi/virtualcollectionregistry/gui/pages/HelpPage.html help page] explains the core concepts and terminology relevant to the VCR (based on the information gathered on [[./Help|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 [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/resources/META-INF/VirtualCollection.xsd 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 [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/doc/Protocol.txt 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 [[CmdiVirtualLanguageObservatory|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 [source:/vlo/branches/vlo-3.1-vcr/vlo-web-app/src/main/java/eu/clarin/cmdi/vlo/wicket/pages '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 [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/resources/META-INF/persistence.xml 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 [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/webapp/WEB-INF/applicationContext.xml 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''. More info: * [http://docs.oracle.com/javaee/6/tutorial/doc/bnbpz.html JPA introduction] * [http://stackoverflow.com/questions/438146/hibernate-hbm2ddl-auto-possible-values-and-what-they-do Hibernate hbm2ddl.auto (stackoverflow)] * [http://www.mkyong.com/spring/spring-auto-scanning-components/ Spring component scanning and autowiring example and explanation] ==== JAX-RS REST service ==== Jersey ==== Wicket application (UI) ==== ==== OAI provider ==== === Deployment === == Tickets == Milestones: * [milestone:VirtualCollectionRegistry-1.0] Open tickets: [[TicketQuery(status=accepted|assigned|new|reopened), component=VCRegistry, order=priority, format=table, col=summary|priority|owner|reporter)]]