documentation on oai-pmh

diff --git a/.gitattributes b/.gitattributes
index 1aac59e860a5cab9ef7eb405cfcf31501933b449..c3d7da29693cd12c6239639b0453b58f816b53f1 100644 (file)
--- a/.gitattributes
+++ b/.gitattributes
@@ -1846,11 +1846,13 @@ src/docbkx/versioning.xml -text
 src/site/apt/download.apt -text
 src/site/apt/getting-started.apt -text
 src/site/apt/index.apt -text
+src/site/apt/oai-pmh.apt -text
 src/site/apt/overview.apt -text
 src/site/apt/reference.apt -text
 src/site/apt/rest-api.apt -text
 src/site/fml/faq.fml -text
 src/site/fml/troubleshooting.fml -text
+src/site/resources/images/cdm-server-oai-pmh.png -text
 src/site/resources/images/cdmlib-arch4.png -text
 src/site/resources/images/cdmlib_overview.png -text
 src/site/site.xml -text

diff --git a/src/site/apt/oai-pmh.apt b/src/site/apt/oai-pmh.apt
new file mode 100644 (file)
index 0000000..eb6a7e9
--- /dev/null
+++ b/src/site/apt/oai-pmh.apt
@@ -0,0 +1,57 @@
+OAI-PMH
+
+* General
+
+  In order to allow central aggregators harvesting the CDM Community Stores the {{{http://www.openarchives.org/OAI/openarchivesprotocol.html}OAI-PMH protocol}} with selective date based harvesting has been implemented in to the CDM Community Stores. {{{http://www.biodiversitylibrary.org/}BHL}}, {{{http://www.gbif.net}GBIF}}, {{{http://www.eol.org/}EOL}} or any other data aggregator therefore are able to easily pool CDM data selectively and keep their copy up to date by accessing incremental changes only.
+
+  The CDM Community Store an an OAI-PMH disseminates different types {{{http://www.openarchives.org/OAI/openarchivesprotocol.html#Item }items}} like taxa, references, and so on. Therefore the CDM OAI-PMH interface is split in to sub repositories which exist at different base URL. For each type another URL. The implementation of the OAI-PMH is equipped with a XSLT which renders a humane user interface when accessed with a browser. 
+
+  Currently the following sub repositories exist (All URL are relative to the specific root of the CDM Community Server):
+
+** Reference sub repository
+
+  base URL: <<<reference/oai>>>
+
+  Metadata Formats:
+  
+  * <<oai_dc>> = {{http://www.openarchives.org/OAI/2.0/oai_dc.xsd}}
+  
+  * <<dwc>> = {{http://rs.tdwg.org/dwc/xsd/simpledarwincore/}} Requesting for an item in the '''dwc (Simple Darwin Core)''' metadata format will not return metadata on the reference item itself, but on all taxa (acceptend taxa and synonyms) covered by the specific reference and by all subordinary references.
+
+  Sets:
+    * Any kind of reference 
+ 
+
+** Taxon sub repository
+
+  base URL: <<<taxon/oai>>>
+
+  Metadata Formats:
+  
+   * <<oai_dc>> = {{http://www.openarchives.org/OAI/2.0/oai_dc.xsd}}
+   
+   * <<rdf>> = {{http://rs.tdwg.org/ontology/voc/TaxonConcept}}
+
+  Sets:
+  
+   * Synonyms
+   
+   * Accepted Taxon Concepts
+
+
+
+* OAI-PMH Registry
+
+  Those CDM DataStores willing to expose their data via the OAI-PMH interface can register at an {{{http://wp5.e-taxonomy.eu/registry/oai/providers.php }OAI-PMH provider registry}}. The registry process can be triggered from the administrative overview page of the CDM Servers, which is usually available at http://my.server.name:8080/ .
+
+  
+[images/cdm-server-oai-pmh.png] CDM Server Screenshot
+
+
+  This overview page shows a table listing all CDM Community Stores which are exposed by this specific CDM Community Server. CDM Community Stores which are not yet registered offer a <Request for registration> link. Clicking this link allows sending an email to the EDIT OAI-PMH provider registration service. Once a server has been registered this link is being replaced by a text indicating the registration state and the CDM Community Store is listed by the {{{http://wp5.e-taxonomy.eu/registry/oai/providers.php OAI-PMH }provider registry}} with according metadata. This list is returned in XML if not specified differently, whereas the data structure is defined by the {{{http://wp5.e-taxonomy.eu/registry/oai/1.0/providers.xsd}}} XML schema. The OAI-PMH provider registry is a simple RESTful web service, all parameters are provided as URL parameters added to the base URL:
+
+   * <<find=<baseURL> >> : Search for an entry in the list of providers which matches the specified <baseURL>. Example: {{http://wp5.e-taxonomy.eu/registry/oai/providers.php?find=http%3a%2f%2fsome.cdmserver.com%3a8080%2fcdmStoreName providers.php?find=http://some.cdmserver.com:8080/cdmStoreName}}
+   
+   * <<format=<fomat name> >> : Send the response data in a specific format. Valid format names are: <<json>> (application/json), <<xml>> (application/xml). Xml is being used as default format. Example: {{http://wp5.e-taxonomy.eu/registry/oai/providers.php?format=json providers.php?format=json}}
+   
+   * <<callback=<jsonp callback> >> : This parameter allows specifying a JSONP callback, for an explanation of this feature please refer to {{http://www.ibm.com/developerworks/library/wa-aj-jsonp1/}}
\ No newline at end of file

diff --git a/src/site/resources/images/cdm-server-oai-pmh.png b/src/site/resources/images/cdm-server-oai-pmh.png
new file mode 100644 (file)
index 0000000..f97424b
Binary files /dev/null and b/src/site/resources/images/cdm-server-oai-pmh.png differ

diff --git a/src/site/site.xml b/src/site/site.xml
index 97c03418b4cd31d6f5d7d0f344b144f1cc8cfc2a..f2086d23fcc3ecb03835450a6e38d116cefe3ba0 100644 (file)
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -18,6 +18,7 @@
                        <item name="UML" href="http://wp5.e-taxonomy.eu/cdm-uml"/>
                        <item name="API" href="apidocs/index.html"/>
                        <item name="REST API" href="rest-api.html"/>
+                       <item name="OAI-PMH" href="oai-pmh.html"/>
                        <item name="Troubleshooting" href="troubleshooting.html"/>
                        <item name="Wiki" href="http://dev.e-taxonomy.eu/trac/wiki/CdmLibraryDev"/>
                </menu>