Bloomreach OAI-PMH Provider

Prerequisites

These instructions assume that you have a Hippo project based on the Hippo project archetype, i.e. a Maven multiproject consisting of submodules like cms, site and repository-data.

You should know on how to use the HST RESTful JAX-RS Component Support

You should know how the OAI-PMH protocol works; see the Protocol for Metadata Harvesting specification

Installation

1. In the main pom.xml of the project, in the repositories section, add this repository if it is not configured there yet.

                 
       <repository>
         <id>hippo-forge</id>
         <name>Bloomreach Forge maven 2 repository.</name>
         <url>https://maven.onehippo.com/maven2-forge/</url>
       </repository>
               

2. Add to the pom.xml of your cms module:

                 
   <dependency>
    <groupId>org.bloomreach.forge.oai-pmh-provider</groupId>
    <artifactId>oai-pmh-provider-repository</artifactId>
    <version>[version]</version>
   </dependency>
                           
               

   Note: before version 5.0.0, the artifact's groupId was org.onehippo.forge.

3. Add to the pom.xml of your site module:

                 
   <dependency>
    <groupId>org.bloomreach.forge.oai-pmh-provider</groupId>
    <artifactId>oai-pmh-provider-hst</artifactId>
    <version>[version]</version>
   </dependency>
                           
               

   Note: before version 5.0.0, the artifact's groupId was org.onehippo.forge.

4. Add to the web.xml of your site module:

                 
   <context-param>
       <param-name>hst-beans-annotated-classes</param-name>
       <param-value>.....,
         classpath*:org/onehippo/forge/oaipmh/provider/api/**/*.class,
       </param-value>
     </context-param>
                           
               

Configure your content beans

first implement the org.onehippo.forge.oaipmh.provider.api.OAIBean

There are 3 types of annotations you should use in your content beans:

1. @OAI: for setting the setName (on the bean class)
2. @OAIDelegate: for delegating different metadata prefixes (we currently only support "dc_oai" and/or "lom")
3. @OAIIdentifier: for generating the record identifier
4. example newsdocument:
5. example contentdocument:

Make sure you have the oai:document mixin on your document

Either in the CND (example):

          

<'oaipmh.demo'='http://www.onehippo.org/oaipmh.demo/nt/1.0'>
<'hippo'='http://www.onehippo.org/jcr/hippo/nt/2.0'>
<'hippostd'='http://www.onehippo.org/jcr/hippostd/nt/2.0'>
<'hippostdpubwf'='http://www.onehippo.org/jcr/hippostdpubwf/nt/1.0'>
<'oai'='http://www.hippoecm.org/hst/nt/oai/1.0'>

[oaipmh.demo:basedocument] > hippo:document, hippostd:publishableSummary, hippostdpubwf:document orderable

[oaipmh.demo:contentdocument] > oaipmh.demo:basedocument, hippostd:relaxed

[oaipmh.demo:newsdocument] > oaipmh.demo:basedocument, hippostd:relaxed, oai:document

              
        

Or in your prototype (best practice):

 /hipposysedit:prototype:
  jcr:primaryType: oaipmhdemo:contentdocument
  jcr:mixinTypes: ['mix:referenceable', 'oai:document']
        

Depending on your project, you might need to create a script which will add the mixin on all existing documents

Add the resource to the Custom Jaxrs Plain resource Pipeline (or to custom pipeline)

add oai-pmh.xml to META-INF.hst-assembly.overrides package of your site project. Example:

          
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

<import resource="classpath:/org/onehippo/forge/oaipmh/provider/resource/oai-pmh.xml"/>

<bean id="beanPackage" class="java.lang.String">
  <constructor-arg value="org.onehippo.demo"/>
</bean>

<bean id="customRestOAIPMHResourceProviders" class="org.springframework.beans.factory.config.ListFactoryBean">
  <property name="sourceList">
    <list>
      <bean class="org.apache.cxf.jaxrs.lifecycle.SingletonResourceProvider">
        <constructor-arg>
          <bean class="org.onehippo.demo.rest.OAIPMHResource">
            <property name="beansPackage" value="org.onehippo.beans"/>
            <!--milliseconds setting since versions 3.1.0 and 4.1.0 -->
            <property name="useMilliSecondsDatePrecision" value="false"/>
          </bean>
        </constructor-arg>
      </bean>
    </list>
  </property>
</bean>

</beans>

        

Configure usage of milliseconds date format

Since versions 3.1.1 and 4.1.1 you can configure using either second or millisecond precision on (publication)date (oai:pubdate) and resumption token properties.

Second-precision is used by default. To enable the use of millisecond-precision:

In oai-pmh.xml in the META-INF.hst-assembly.overrides package of your site project, set:

  <property name="useMilliSecondsDatePrecision" value="true"/> 

In the console, configure the oaipmh derivative configuration to use the OAIPMHDateFunctionMillis Class:

            
          definitions:
            config:
              /hippo:configuration/hippo:derivatives/oaipmh:
                hipposys:classname: org.onehippo.forge.oaipmh.repository.deriveddata.OAIPMHDateFunctionMillis
          

Documents that are touched by the derivative function will now have millisecond precision properties set. Existing documents will need to be updated using a groovy script.

Configure HST mount

Configure your HST mount to display the correct mount on the URL, e.g. http://localhost:8080/site/pmh

Automatically the oai-pmh project will set PMH mount on the hst:root mount

Try out the identify verb e.g. http://localhost:8080/site/pmh/oai?verb=Identify

You can configure metadata from the Identify by looking at the mount for the identify.path property which points to an Identify document.

Test

EDUREP NLLOM

Important for EDUREP!!

You should have the knowledge about the used xml formats and which elements and attributes are mandatory for edurep NLLOM

https://wiki.surfnet.nl/display/nllom/Home

All elements and attributes are already provided in the oai-pmh project under the following package: package

Plus we also provide a helper class which should get you going: NLLOM in combination with newsdocument:

Be aware you probably need to check your own metadata configuration for mandatory elements and properties