Installation
Compatibility
This plugin will work with an ICAT version of 4.9.0 or greater.
The setup.properties file
- container
-
Values must be chosen from:
TargetServer
Though only Glassfish is working properly at the moment.
- home
-
is the top level of the container installation.
For Glassfish it must contain "glassfish/domains" and
for JBoss (wildfly) it must contain jboss-modules.jar.
- port
-
is the administration port of the container
which is typically 4848 for Glassfish and 9990 for JBoss.
- secure
-
must be set to true or false.
If true then only https and not http connections will be allowed.
The logback.xml file
If you wish to modify the provided logging levels then rename
logback.xml.example to logback.xml and edit it to suit your needs.
The run.properties file
Note: When you are using non-ASCII characters for one or more properties
(e.g. for the repositoryName), the run.properties file must
either be encoded as ISO 8859-1 (Latin-1), or non-ASCII characters must be represented
using Unicode escapes (e.g. \u00fc for the character ü).
- icat.url
-
The url of the machine hosting the icat service.
It should normally just have the scheme, the hostname and the port.
-
Example value: "https://example.org:443"
- icat.auth
-
Space separated icat plugin name and credentials for a user
permitted to read all the ICAT tables that are of interest.
-
Example value: "simple username nick password 123456"
- repositoryName
-
A human readable name for the repository.
The name will be returned as part of the OAI-PMH "Identify" response.
-
Example value: "Example experimental data repository"
- adminEmails
-
A space separated list of e-mail addresses of the repository administrator.
The email addresses will be returned as part of the OAI-PMH "Identify" response.
-
Example value: "someone@example.org another@example.org"
- requestUrl
-
The Base URL of the OAI-PMH interface.
Must be a well-formed URL.
This will be returned as part of the OAI-PMH "Identify" response,
and is being used for the unique identifiers of records.
-
Example value: "https://www.example.org/oaipmh/request"
- maxResults
-
The maximum number of results per page for incomplete responses.
Must be an integer greater than 0.
-
Example value: "50"
- icatDateTimeFormat
-
A pattern for the Java
DateTimeFormatter.
-
Example values: "yyyy-MM-dd HH:mm:ss Z" or "MM/dd/yyyy HH:mm.ss Z"
-
This will be used to format date/time values when querying ICAT
(see icatDateTimeZone below for details).
- icatDateTimeZone
-
A zoneId (or time zone offset) for the of(String zoneId) method of the Java
ZoneId.
-
Example values: "Z" or "Europe/Berlin" or "+02:00"
-
This will be used to format date/time values when querying ICAT.
Make sure both the icatDateTimeFormat and the icatDateTimeZone
match with the way date/time values are stored in your ICAT.
-
For example, when a harvester requests the records from 2018-08-31 07:45:20 (UTC),
-
if icatDateTimeFormat is set to "MM/dd/yyyy HH:mm.ss Z",
and icatDateTimeZone is set to "+02:00",
the query sent to ICAT by icat.oaipmh would use the following condition:
"WHERE a.modTime >= '08/31/2018 09:45.20 +0200'".
-
if icatDateTimeFormat is set to "yyyy-MM-dd HH:mm:ss Z",
and icatDateTimeZone is set to "Z",
the query sent to ICAT by icat.oaipmh would use the following condition:
"WHERE a.modTime >= '2018-08-31 07:45:20 +0000'".
- metadataPrefixes
-
A space separated list of metadata formats to be supported.
-
At minimum, support for the Dublin Core format ("oai_dc") is required.
-
Example value: "oai_dc oai_datacite"
- <metadataPrefix>.xslt
-
For each metadata format, specify the absolute path to an XSLT definition.
This XSLT file must be able to transform metadata from the generic XML format
(as defined by the data.* properties below)
into some other well defined metadata format (such as Dublin Core).
-
For more information, see the example files located at "src/main/config/".
-
Example: "oai_dc.xslt = /home/icat/xslt/dublin_core.xsl"
- <metadataPrefix>.namespace
-
For each metadata format, specify the namespace.
-
Example (official Dublin Core namespace): "oai_dc.namespace =
http://www.openarchives.org/OAI/2.0/oai_dc/"
- <metadataPrefix>.schema
-
For each metadata format, specify the link to a schema definition.
-
Example (official Dublin Core schema definition): "oai_dc.schema =
http://www.openarchives.org/OAI/2.0/oai_dc.xsd"
- data.configurations
-
A space separated list of identifiers for the configuration of
metadata to be retrieved from ICAT.
-
Each listed data configuration must use a unique identifier.
It is recommended to use short human readable identifiers, such as
'inv' for the data object Investigation, or 'stud' for Study.
-
Example value: "inv stud"
- data.<configuration>.metadataPrefixes
-
For each data configuration, specify a space separated list of supported metadata formats
(as defined in the list of metadataPrefixes above).
-
At minimum, support for the Dublin Core format ("oai_dc") is required.
-
For example, if the metadataPrefixes are "oai_dc oai_datacite", and
the data.configurations are "inv stud", one might use:
-
"data.inv.metadataPrefixes = oai_dc oai_datacite", and
-
"data.stud.metadataPrefixes = oai_dc"
- data.<configuration>.mainObject
-
For each data configuration, specify the ICAT object (from the ICAT metadata schema)
which will be the main source of information when retrieving metadata from ICAT.
-
For example, if the data.configurations are "inv stud", one might use:
-
"data.inv.mainObject = Investigation", and
-
"data.stud.mainObject = Study"
- data.<configuration>.<icatObject>.subPropertyLists
-
A space separated list of ICAT sub-objects which are to be included in the property hierarchy
below the <icatObject> for the respective <configuration>.
-
For example, if the data.configurations include "inv", and
data.inv.mainObject is set to "Investigation", one might use:
-
"data.inv.subPropertyLists = datasets"
to include the datasets as part an investigation, and
-
"data.inv.datasets.subPropertyLists = datafiles parameters"
to include the datafiles and parameters as part of a dataset.
- data.<configuration>.<icatObject>.<dataTypeProperties>
-
A space separated list of ICAT properties to be retrieved from ICAT
for the <icatObject> when retrieving metadata from ICAT.
-
Possible <dataTypeProperties> are:
"stringProperties", "numericProperties", or "dateProperties",
depending on the data type within ICAT.
-
For example, if the data.configurations include "inv",
data.inv.mainObject is set to "Investigation",
data.inv.subPropertyLists is set to "investigationUsers", and
data.inv.investigationUsers.subPropertyLists is set to "user",
one might use:
-
"data.inv.stringProperties = doi title summary" and
"data.inv.dateProperties = startDate endDate" as properties for the investigation,
-
"data.inv.investigationUsers.stringProperties = role"
as properties for the investigationUser, and
-
"data.inv.investigationUsers.user.stringProperties = fullName orcidId"
as properties for the user.
- responseDebug
-
If this (optional) parameter is included and set to "true", the metadata
received when making OAI-PMH calls won't be transformed into another format.
-
This means, the metadata will stay in the generic XML format
(as defined by the data.* properties above),
and the defined metadataPrefixes properties are ignored.
-
This is particularly helpful for the development of custom XSLT files,
in order to understand the structure of the generic XML format before
attempting to transform it into some other metadata format.
- responseStyle
-
Set this (optional) parameter to the URL of an XSL document which you
want to apply to all XML responses.
-
One particular use for this would be to have the XML responses transform
into HTML documents when making OAI-PMH calls from a web browser.
Check that icat.oaipmh works
A simple standalone test is to run:
curl -k https://localhost:8181/oaipmh/request?verb=Identify -w "\n"
which should return the OAI-PMH Identify response