feat(data): add OAI XSLT support #15

Inspired by Zenodo, ePrint and others, this library
may now serve implementing applications an XSLT to
transfrom OAI-PMH responses into nice HTML.

Browsing an OAI-PMH endpoint with a cleaner UI makes
way more fun.

This commit includes a copy of https://github.com/eprints/eprints/blob/3.3/lib/static/oai2.xsl
which is licensed under GPL-3. As this library does
not interfere with its content and has not performed
any non-whitespace changes, it should not conflict with
this library shipping under a BSD 3-clause license.

An issue has been opened to reach out and avoid any
conflicts.

See also: eprints/eprints#521

docs/README.md

@@ -148,6 +148,13 @@ It happily accepts an `InputStream`, being read and written as a raw response to
 and serve from the main application (Dataverse) without jumping through the
 loops of the XML transformer for each item, which is MUCH faster.
 
+Using `DataProvider.getOaiXslt()` an implementing application can retrieve a local copy
+of https://github.com/eprints/eprints/blob/3.3/lib/static/oai2.xsl to serve it
+from a local (servlet) endpoint. It allows for a much nicer UI experience when
+accessing the OAI-PMH endpoint with a browser. Applications may provide a hyperref
+to the endpoint (or other static location) by using `xmlWriter.writeStylesheet()`
+in their OAI servlet.
+
 ## Advanced Configuration
 
 **NOTE: THE FOLLOWING HAS BEEN COPIED FROM THE DSPACE WIKI AND IS OF LIMITED USE

xoai-common/src/main/java/io/gdcc/xoai/xml/XmlWriter.java

@@ -160,4 +160,13 @@ public void write(ResumptionToken.Value value) throws XmlWriteException {
             throw new XmlWriteException(e);
         }
     }
+
+    public void writeStylesheet(String href) throws XMLStreamException {
+        if (href == null) {
+            throw new XMLStreamException(
+                    "May not pass a null hyper reference to the XSLT processing instruction");
+        }
+        super.writeProcessingInstruction(
+                "xml-stylesheet", "type=\"text/xsl\" href=\"" + href + "\"");
+    }
 }

xoai-data-provider/src/main/java/io/gdcc/xoai/dataprovider/DataProvider.java

@@ -27,6 +27,10 @@
 import io.gdcc.xoai.model.oaipmh.ResumptionToken;
 import io.gdcc.xoai.model.oaipmh.verbs.Verb.Type;
 import io.gdcc.xoai.services.api.DateProvider;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URL;
+import java.nio.charset.StandardCharsets;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
@@ -189,4 +193,31 @@ public OAIPMH handle(Request request) {
             return this.errorsHandler.handle(oaipmh, e);
         }
     }
+
+    /**
+     * Let an implementing application retrieve the OAI XSLT for nicer UI of results. The app needs
+     * to create some endpoint to serve the content and reference that endpoint in {@link
+     * io.gdcc.xoai.xml.XmlWriter#writeStylesheet(String)}. The app might also choose to cache the
+     * String instead of re-reading it.
+     *
+     * @return The XSLT document as complete String
+     */
+    public static final String getOaiXSLT() {
+        // get resource from classpath
+        ClassLoader classLoader = DataProvider.class.getClassLoader();
+        URL oaiXsltResource = classLoader.getResource("oai2.xsl");
+
+        // Prevent errors if file not found or could not be loaded
+        if (oaiXsltResource == null) {
+            log.warn("Could not find or load OAI XSLT file, class loader returned null");
+            return "";
+        }
+
+        try (InputStream inStream = oaiXsltResource.openStream()) {
+            return new String(inStream.readAllBytes(), StandardCharsets.UTF_8);
+        } catch (IOException e) {
+            log.warn("Could not read OAI XSLT file", e);
+            return "";
+        }
+    }
 }