| 2 | | |
| 3 | | = CLARIN Virtual Collection Registry= |
| 4 | | |
| 5 | | == Description == |
| 6 | | |
| 7 | | From the [[./Requirements|requirements description]]: |
| 8 | | |
| 9 | | 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. |
| 10 | | |
| 11 | | 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, and get assigned a persistent identifier by means of the [[EPIC|EPIC service]]. |
| 12 | | |
| 13 | | These components are available at the following locations '''(currently referencing the alpha deployment!)''': |
| 14 | | |
| 15 | | * [http://catalog-clarin.esc.rzg.mpg.de/vcr/app /vcr/app]: GUI |
| 16 | | * [http://catalog-clarin.esc.rzg.mpg.de/vcr/service /vcr/service]: REST service |
| 17 | | * [http://catalog-clarin.esc.rzg.mpg.de/vcr/oai /vcr/oai]: OAI-PMH endpoint |
| | 30 | == People == |
| | 31 | |
| | 32 | * [[People/twagoo|Twan Goosen]] - current maintainer |
| | 33 | * [[People/willem.elbers|Willem Elbers]] |
| | 34 | * ([[People/oschonef|Oliver Schonefeld]] - original developer) |
| | 35 | |
| | 36 | ---- |
| | 37 | == Getting code == |
| | 38 | |
| | 39 | * You can browse the code [source:/VirtualCollectionRegistry] |
| | 40 | * Check out from: {{{https://trac.clarin.eu/VirtualCollectionRegistry}}} |
| | 41 | |
| | 42 | ---- |
| | 43 | == Usage == |
| | 44 | |
| | 45 | The components of the VCR are available at the following locations '''(currently referencing the alpha deployment!)''': |
| | 46 | |
| | 47 | * [http://clarin.ids-mannheim.de/vcr/app /vcr/app]: GUI |
| | 48 | * [http://clarin.ids-mannheim.de/vcr/service /vcr/service]: REST service |
| | 49 | * [http://clarin.ids-mannheim.de/vcr/oai /vcr/oai]: OAI-PMH endpoint |
| | 52 | |
| | 53 | ---- |
| | 54 | == System Requirements == |
| | 55 | |
| | 56 | The following requirements apply to development environment as well as testing/production environments: |
| | 57 | |
| | 58 | * MySQL server |
| | 59 | * A dedicated schema is required; a connection resource needs to be configured (with write permissions) in the servlet container, and available to the application; the application will create/update the database schema automatically, see [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/doc/README.txt README file] for more details |
| | 60 | |
| | 61 | ---- |
| | 62 | == Dependencies == |
| | 63 | |
| | 64 | **TODO** |
| | 65 | |
| | 66 | What does this project depend on? Which other projects use (part of) this project? |
| | 67 | |
| | 68 | |
| | 69 | ---- |
| | 70 | == Building and Deploying == |
| | 71 | |
| | 72 | === Development === |
| | 73 | |
| | 74 | Additional requirements for building the application from source: |
| | 75 | |
| | 76 | * JDK 7 or higher |
| | 77 | * Maven 3 or higher |
| | 78 | |
| | 79 | 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. |
| | 80 | |
| | 81 | ==== VCR core ==== |
| | 82 | |
| | 83 | 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. |
| | 84 | |
| | 85 | 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. It also calls the configured PID service to register and link a '''persistent identifier''' upon publication of a collection. These methods are used by the REST service, OAI provider and Wicket application classes to access and manipulate the stored collections. |
| | 86 | |
| | 87 | 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''. |
| | 88 | In addition, some beans are defined in configuration classes (annotated with ''@Configuration''), by methods annoted ''@Bean''. Note that all beans are singleton by default - so called 'prototype beans' are not used in the VCR. |
| | 89 | |
| | 90 | There are a number of application context '''profiles''', the activity of which determine which beans get instantiated by Spring. The context parameter ''spring.profiles.active'' can be used to activate one or more profiles. The profiles are defined by means of the ''@Profile'' annotation. At the moment one profile exists for each PID provider implementation; for example, the ''vcr.pid.epic'' profile activates the ''EPICPersistentIdentifierProvider'' implementation and the ''EPICPersistentIdentifierConfiguration'' configuration. It is technically valid to activate multiple profiles but in this case this will lead to a clash of service implementations. See deployment information for more details on using profiles to select the PID provider for a VCR instance after deployment. |
| | 91 | |
| | 92 | 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). |
| | 93 | |
| | 94 | More info: |
| | 95 | * [http://docs.oracle.com/javaee/6/tutorial/doc/bnbpz.html JPA introduction] |
| | 96 | * [http://stackoverflow.com/questions/438146/hibernate-hbm2ddl-auto-possible-values-and-what-they-do Hibernate hbm2ddl.auto (stackoverflow)] |
| | 97 | * [http://www.mkyong.com/spring/spring-auto-scanning-components/ Spring component scanning and autowiring example and explanation] |
| | 98 | |
| | 99 | ==== JAX-RS REST service ==== |
| | 100 | |
| | 101 | 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''': |
| | 102 | * /virtualcollections (class ''!VirtualCollectionsResource'') allows listing (GET) of published collections and POSTing of new collections |
| | 103 | * /virtualcollections/{id} (class ''!VirtualCollectionResource'') is a subresource that allows GETting, PUTting and DELETEing individual collections |
| | 104 | * /my-virtualcollections (class ''!MyVirtualCollectionsResource'') only allows retrieval (GET) the list of private and published collections owned by the authenticated user |
| | 105 | * / (class ''!BaseResource'') is a dummy resource that renders an informative HTML page (if content negotiation allows) about the service |
| | 106 | |
| | 107 | 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. |
| | 108 | |
| | 109 | The '''CMDI output''' is generated by marshalling instances of the classes generated by the JAX-B Maven plugin at build time (XJC), based on the [http://catalog.clarin.eu/ds/ComponentRegistry/rest/registry/profiles/clarin.eu:cr1:p_1404130561238/xsd VirtualCollection profile schema], a copy of which is included in the sources. |
| | 110 | |
| | 111 | The collections space can be queried by means of a domain specific '''query language''', as described in the [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/doc/Protocol.txt REST documentation]. The grammar is defined in the file [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/jjtree/eu/clarin/cmdi/virtualcollectionregistry/query/QueryParser.jjt QueryParser.jjt]. The ''javacc-maven-plugin'' generates the parser at build time (with the JJTree preprocessor). Query strings (as optional GET parameters) are passed from the REST resources to the ''VirtualCollectionRegistry'' service, which uses a static method to get it parsed into a ''!ParsedQuery'' object, which in turn is used to obtain JPA query objects that can be used to retrieve concrete results. |
| | 112 | |
| | 113 | More info: |
| | 114 | * [https://jersey.java.net/documentation/latest/jaxrs-resources.html JAX-RS resources documentation from Jersey] |
| | 115 | * [https://jersey.java.net/documentation/latest/message-body-workers.html information on custom body providers from Jersey] |
| | 116 | * [http://mojo.codehaus.org/jaxb2-maven-plugin/ jaxb2-maven-plugin] |
| | 117 | * [http://mojo.codehaus.org/javacc-maven-plugin/ javacc-maven plugin] with links to information about JavaCC and JJTree |
| | 118 | |
| | 119 | ==== Wicket application (UI) ==== |
| | 120 | |
| | 121 | The graphical user interface is implemented as a [http://wicket.apache.org 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). |
| | 122 | |
| | 123 | 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, [http://jquery.com/ JQuery] is used for enhanced client side interaction. There is some custom JQuery based code, which is integrated with the Wicket components using the [https://code.google.com/p/wiquery/ WiQuery] library. The base page includes the [http://getbootstrap.com/ Bootstrap] Javascript library to support some out-of-the-box layout niceness. |
| | 124 | |
| | 125 | 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 ([http://sass-lang.com/ SASS]) files that get compiled to CSS at build time. The main file is [/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/webapp/css/vcr.scss vcr.scss], which include the base [[CLARIN style]] and includes a number of VCR-specific style definitions. |
| | 126 | |
| | 127 | More info: |
| | 128 | * [https://github.com/Jasig/sass-maven-plugin SASS Maven Plugin] |
| | 129 | |
| | 130 | ==== OAI provider ==== |
| | 131 | |
| | 132 | The VCR OAI provider is using the [source:/OAIProvider OAIProvider library], which consists of an out-of-the-box singleton ''OAIProvider'' instance and a servlet, in addition to an application specific ''Repository''. The repository is implemented by ''VirtualColletionRegistryOAIRepository'' in the ''eu.clarin.cmdi.virtualcollectionregistry.oai'' package, which also contains a Spring configuration class that links the repository with a ''!VirtualCollectionRegistry'' service instance on the one hand and the ''OAIProvider'' on the other. The servlet is mounted (via web.xml) at ''/oai'' and picks up the OAI provider instance automatically. |
| | 133 | |
| | 134 | The provider supports Dublin Core (DC) and CMDI output. The DC is generated by the provider based on information provided by the ''Repository'' implementation. The CMDI output is generated via the same methods as the CMDI output of the REST service (see above). |
| | 135 | |
| | 136 | ==== Troubleshooting ==== |
| | 137 | When building using JDK8, you may get an error like this: |
| | 138 | {{{ |
| | 139 | org.xml.sax.SAXParseException; systemId: file:/[..]/VirtualCollection.xsd; lineNumber: 1; columnNumber: 659; schema_reference: Failed to read schema document 'xml.xsd', because 'http' access is not allowed due to restriction set by the accessExternalSchema property. |
| | 140 | }}} |
| | 141 | |
| | 142 | To fix this, add the following parameter to the ''mvn'' command: '''-Djavax.xml.accessExternalSchema=all''' (or add it to the [http://docs.alfresco.com/4.2/tasks/dev-extensions-maven-sdk-maven-opts.html MAVEN_OPTS environment variable]). |
| | 143 | [http://stackoverflow.com/questions/23011547/webservice-client-generation-error-with-jdk8 More info on this error] |
| | 144 | |
| | 145 | === Deployment === |
| | 146 | |
| | 147 | The VCR builds into a single WAR file that can be deployed onto a servlet container (tested on and developed for Tomcat 7). There exists an alternative '''build profile''' called ''development'' (use ''mvn install -Pdevelopment'') which makes logging output go to the console and enables Tomcat user realm authentication. By default, however, the application is enabled for Shibboleth authentication and logging to a file on disk. To allow for the switch between authentication mechanism, the web.xml file is duplicated and one of the two is selected at package time - see [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/webapp/WEB-INF]. |
| | 148 | |
| | 149 | Building the VCR at least up to the ''package'' phase (preferably ''mvn install'') will result in the creation of a .tar.gz file in the ''target'' directory that contains the deployable WAR file as well as the project documentation and licensing information in a directory that contains the artifact name and version number. |
| | 150 | |
| | 151 | Further deployment instructions (primarily adding a datasource and a number of parameters to ''context.xml'') can be found in the [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/doc/README.txt README file]. |
| | 152 | |
| | 153 | ==== Beta ==== |
| | 154 | In case of a beta deployment, uncomment the following section in the base page HTML template at ''WEB-INF/classes/eu/clarin/cmdi/virtualcollectionregistry/gui/pages/BasePage.html'': |
| | 155 | {{{#!xml |
| | 156 | <div id="betabadge"> |
| | 157 | <span>BETA</span> |
| | 158 | </div> |
| | 159 | }}} |
| | 160 | |
| | 161 | This will add a 'BETA' marker in the topleft corner of the page. |
| | 162 | |
| | 163 | ---- |
| | 164 | == Interfaces == |
| 52 | | == Technical notes == |
| 53 | | |
| 54 | | === Requirements === |
| 55 | | |
| 56 | | The following requirements apply to development environment as well as testing/production environments: |
| 57 | | |
| 58 | | * MySQL server |
| 59 | | * A dedicated schema is required; a connection resource needs to be configured (with write permissions) in the servlet container, and available to the application; the application will create/update the database schema automatically, see [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/doc/README.txt README file] for more details |
| 60 | | |
| 61 | | === Development === |
| 62 | | |
| 63 | | Additional requirements for building the application from source: |
| 64 | | |
| 65 | | * JDK 7 or higher |
| 66 | | * Maven 3 or higher |
| 67 | | |
| 68 | | 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. |
| 69 | | |
| 70 | | Source code: [source:/VirtualCollectionRegistry] |
| 71 | | |
| 72 | | ==== VCR core ==== |
| 73 | | |
| 74 | | 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. |
| 75 | | |
| 76 | | 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. It also calls the configured PID service to register and link a '''persistent identifier''' upon publication of a collection. These methods are used by the REST service, OAI provider and Wicket application classes to access and manipulate the stored collections. |
| 77 | | |
| 78 | | 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''. |
| 79 | | In addition, some beans are defined in configuration classes (annotated with ''@Configuration''), by methods annoted ''@Bean''. Note that all beans are singleton by default - so called 'prototype beans' are not used in the VCR. |
| 80 | | |
| 81 | | There are a number of application context '''profiles''', the activity of which determine which beans get instantiated by Spring. The context parameter ''spring.profiles.active'' can be used to activate one or more profiles. The profiles are defined by means of the ''@Profile'' annotation. At the moment one profile exists for each PID provider implementation; for example, the ''vcr.pid.epic'' profile activates the ''EPICPersistentIdentifierProvider'' implementation and the ''EPICPersistentIdentifierConfiguration'' configuration. It is technically valid to activate multiple profiles but in this case this will lead to a clash of service implementations. See deployment information for more details on using profiles to select the PID provider for a VCR instance after deployment. |
| 82 | | |
| 83 | | 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). |
| 84 | | |
| 85 | | More info: |
| 86 | | * [http://docs.oracle.com/javaee/6/tutorial/doc/bnbpz.html JPA introduction] |
| 87 | | * [http://stackoverflow.com/questions/438146/hibernate-hbm2ddl-auto-possible-values-and-what-they-do Hibernate hbm2ddl.auto (stackoverflow)] |
| 88 | | * [http://www.mkyong.com/spring/spring-auto-scanning-components/ Spring component scanning and autowiring example and explanation] |
| 89 | | |
| 90 | | ==== JAX-RS REST service ==== |
| 91 | | |
| 92 | | 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''': |
| 93 | | * /virtualcollections (class ''!VirtualCollectionsResource'') allows listing (GET) of published collections and POSTing of new collections |
| 94 | | * /virtualcollections/{id} (class ''!VirtualCollectionResource'') is a subresource that allows GETting, PUTting and DELETEing individual collections |
| 95 | | * /my-virtualcollections (class ''!MyVirtualCollectionsResource'') only allows retrieval (GET) the list of private and published collections owned by the authenticated user |
| 96 | | * / (class ''!BaseResource'') is a dummy resource that renders an informative HTML page (if content negotiation allows) about the service |
| 97 | | |
| 98 | | 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. |
| 99 | | |
| 100 | | The '''CMDI output''' is generated by marshalling instances of the classes generated by the JAX-B Maven plugin at build time (XJC), based on the [http://catalog.clarin.eu/ds/ComponentRegistry/rest/registry/profiles/clarin.eu:cr1:p_1404130561238/xsd VirtualCollection profile schema], a copy of which is included in the sources. |
| 101 | | |
| 102 | | The collections space can be queried by means of a domain specific '''query language''', as described in the [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/doc/Protocol.txt REST documentation]. The grammar is defined in the file [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/jjtree/eu/clarin/cmdi/virtualcollectionregistry/query/QueryParser.jjt QueryParser.jjt]. The ''javacc-maven-plugin'' generates the parser at build time (with the JJTree preprocessor). Query strings (as optional GET parameters) are passed from the REST resources to the ''VirtualCollectionRegistry'' service, which uses a static method to get it parsed into a ''!ParsedQuery'' object, which in turn is used to obtain JPA query objects that can be used to retrieve concrete results. |
| 103 | | |
| 104 | | More info: |
| 105 | | * [https://jersey.java.net/documentation/latest/jaxrs-resources.html JAX-RS resources documentation from Jersey] |
| 106 | | * [https://jersey.java.net/documentation/latest/message-body-workers.html information on custom body providers from Jersey] |
| 107 | | * [http://mojo.codehaus.org/jaxb2-maven-plugin/ jaxb2-maven-plugin] |
| 108 | | * [http://mojo.codehaus.org/javacc-maven-plugin/ javacc-maven plugin] with links to information about JavaCC and JJTree |
| 109 | | |
| 110 | | ==== Wicket application (UI) ==== |
| 111 | | |
| 112 | | The graphical user interface is implemented as a [http://wicket.apache.org 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). |
| 113 | | |
| 114 | | 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, [http://jquery.com/ JQuery] is used for enhanced client side interaction. There is some custom JQuery based code, which is integrated with the Wicket components using the [https://code.google.com/p/wiquery/ WiQuery] library. The base page includes the [http://getbootstrap.com/ Bootstrap] Javascript library to support some out-of-the-box layout niceness. |
| 115 | | |
| 116 | | 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 ([http://sass-lang.com/ SASS]) files that get compiled to CSS at build time. The main file is [/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/webapp/css/vcr.scss vcr.scss], which include the base [[CLARIN style]] and includes a number of VCR-specific style definitions. |
| 117 | | |
| 118 | | More info: |
| 119 | | * [https://github.com/Jasig/sass-maven-plugin SASS Maven Plugin] |
| 120 | | |
| 121 | | ==== OAI provider ==== |
| 122 | | |
| 123 | | The VCR OAI provider is using the [source:/OAIProvider OAIProvider library], which consists of an out-of-the-box singleton ''OAIProvider'' instance and a servlet, in addition to an application specific ''Repository''. The repository is implemented by ''VirtualColletionRegistryOAIRepository'' in the ''eu.clarin.cmdi.virtualcollectionregistry.oai'' package, which also contains a Spring configuration class that links the repository with a ''!VirtualCollectionRegistry'' service instance on the one hand and the ''OAIProvider'' on the other. The servlet is mounted (via web.xml) at ''/oai'' and picks up the OAI provider instance automatically. |
| 124 | | |
| 125 | | The provider supports Dublin Core (DC) and CMDI output. The DC is generated by the provider based on information provided by the ''Repository'' implementation. The CMDI output is generated via the same methods as the CMDI output of the REST service (see above). |
| 126 | | |
| 127 | | ==== Troubleshooting ==== |
| 128 | | When building using JDK8, you may get an error like this: |
| 129 | | {{{ |
| 130 | | org.xml.sax.SAXParseException; systemId: file:/[..]/VirtualCollection.xsd; lineNumber: 1; columnNumber: 659; schema_reference: Failed to read schema document 'xml.xsd', because 'http' access is not allowed due to restriction set by the accessExternalSchema property. |
| 131 | | }}} |
| 132 | | |
| 133 | | To fix this, add the following parameter to the ''mvn'' command: '''-Djavax.xml.accessExternalSchema=all''' (or add it to the [http://docs.alfresco.com/4.2/tasks/dev-extensions-maven-sdk-maven-opts.html MAVEN_OPTS environment variable]). |
| 134 | | [http://stackoverflow.com/questions/23011547/webservice-client-generation-error-with-jdk8 More info on this error] |
| 135 | | |
| 136 | | === Deployment === |
| 137 | | |
| 138 | | The VCR builds into a single WAR file that can be deployed onto a servlet container (tested on and developed for Tomcat 7). There exists an alternative '''build profile''' called ''development'' (use ''mvn install -Pdevelopment'') which makes logging output go to the console and enables Tomcat user realm authentication. By default, however, the application is enabled for Shibboleth authentication and logging to a file on disk. To allow for the switch between authentication mechanism, the web.xml file is duplicated and one of the two is selected at package time - see [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/src/main/webapp/WEB-INF]. |
| 139 | | |
| 140 | | Building the VCR at least up to the ''package'' phase (preferably ''mvn install'') will result in the creation of a .tar.gz file in the ''target'' directory that contains the deployable WAR file as well as the project documentation and licensing information in a directory that contains the artifact name and version number. |
| 141 | | |
| 142 | | Further deployment instructions (primarily adding a datasource and a number of parameters to ''context.xml'') can be found in the [source:/VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/doc/README.txt README file]. |
| 143 | | |
| 144 | | ==== Beta ==== |
| 145 | | In case of a beta deployment, uncomment the following section in the base page HTML template at ''WEB-INF/classes/eu/clarin/cmdi/virtualcollectionregistry/gui/pages/BasePage.html'': |
| 146 | | {{{#!xml |
| 147 | | <div id="betabadge"> |
| 148 | | <span>BETA</span> |
| 149 | | </div> |
| 150 | | }}} |
| 151 | | |
| 152 | | This will add a 'BETA' marker in the topleft corner of the page. |
| 153 | | == Tickets == |
| | 197 | ---- |
| | 198 | == Design == |
| | 199 | |
| | 200 | **TODO** |
| | 201 | |
| | 202 | Internal design of the project; class diagrams etc. |
| | 203 | |
| | 204 | ---- |
| | 205 | == Tickets and milestones == |
