#----
# Installation/Compiling
#----

Installation of this extension follows the usual pattern:

    ./CASCADE-MAKE.sh

[ Currently we need to compile up Ruby, as Apache Jena uses this
  scripting language to implement s-put, s-get, and related scripts.
  These scripts are fairly simple, and an improvement would be to to
  remove any GS3 dependencies on these, at which point Ruby (and
  openssl) can be removed as dependencies ]

Successful execution of ./CASCADE-MAKE.sh installs the Fuseki3 WAR
file as:

    $GSDL3SRCHOME/packages/tomcat/webapps/fuseki3.war

Now run:

    ./CREATE-GREENSTONE-DATASET.sh

This restarts the Greenstone3 server to pick up on the newly installed
fuseki3.war file.  This, in turn means, that the next URL request
(to run a ping test to see if /greenstone as a dataset already exists)
can take a while.

#--
# Test Your SPARQL Endpoint
#--

In your web browser, visit:

    http://localhost:8383/fuseki3/index.html

Adapt URL as need for your installation.

If you are unsure, run:

    ant get-external-servlet-url
  

If you encounter issues, view the Tomcat's catalina.out log file:

    packages/tomcat/logs/catalina.out

You should seen logged entires similar to:

    [2023-02-04 03:01:49] Config     INFO  FUSEKI_HOME=/home/greenstone3-svn/gs2build/ext/apache-jena
    [2023-02-04 03:01:49] Config     INFO  FUSEKI_BASE=/home/greenstone3-svn/gs2build/ext/apache-jena/run3
    [2023-02-04 03:01:49] Config     INFO  Shiro file: file:///home/greenstone3-svn/gs2build/ext/apache-jena/run3/shiro.ini
    [2023-02-04 03:01:50] Config     INFO  Context path = /fuseki3
    [2023-02-04 03:01:50] Config     INFO  Configuration file: /home/greenstone3-svn/gs2build/ext/apache-jena/run3/config.ttl
    [2023-02-04 03:01:51] Server     INFO  Configuration file: /home/greenstone3-svn/gs2build/ext/apache-jena/run3/config.ttl
    [2023-02-04 03:01:51] Server     INFO  System
    [2023-02-04 03:01:51] Server     INFO    Memory: 800.0 MiB
    [2023-02-04 03:01:51] Server     INFO    Java:   11.0.16.1
    [2023-02-04 03:01:51] Server     INFO    OS:     Linux 4.19.0-20-cloud-amd64 amd64
    [2023-02-04 03:01:51] Server     INFO    PID:    24253


Currently there is no content in the triplestore.  For that, you need to adjust and then
build a collection.


#----
# Building collections with Linked Open Data
#----

To include Linked Data triples of the documents metadata to a collection,
add the following to its collectionConfig.xml file, and rebuild.


    <search type="jenaTDB" orthogonal="true"/>

#----
# Confirming Linked Open Data has been ingested
#----

For interative experiments with the Triplestore, you can then visit
the home page:

    http://localhost:8383/fuseki3/

and from there explore the interactive interface Fuseki provides to
the Jena TDB store.

For production use, it is common to be operating Greenstone3 through a
Reverse Proxy web server, such as Apache2 Assuming you are running
Greenstone3 through as:

  http://mydomain.org/greenstone3/library

which, using Apache Rewrite rules, is redirected
to the packages/tomcat instance that ships with Greenstone3 with:

#----
 # Make sure web sockets get passed on to 'ws://...'
        RewriteEngine on
        #
        RewriteCond %{HTTP:Upgrade} =websocket
        RewriteRule /(.*) ws://localhost:8383/$1 [P,L]
        RewriteRule ^/$ https://%{SERVER_NAME}/greenstone3/library [R,L]
        #
        RewriteCond %{HTTP:Upgrade} !=websocket
        RewriteRule /(greenstone3|webswing-server|gs-cantaloupe|simpleAnnotationStore|rdf-editor)/(.*) http://localhost:8383/$1/$2 [P,L]
#----


For this type of setup, the Fuseki triplstore can be accessed via:

  http://mydomain.org/fuseki3


A useful page to visit to test out your triple store is:

    https://mydomain.org/fuseki3/dataset.html

Make sure for 'dataset' you have the drop-down menu on:

  /greenstone

In normal use of Greenstone3 with the apache-jena extension, this will
be the only item in the drop-down menu

By default it has the default SPARQL query loaded:

    SELECT ?subject ?predicate ?object
    WHERE {
      ?subject ?predicate ?object
    }
    LIMIT 25


Press the 'play' button to run the query.

Then you will get output similar to the following:


      subject	predicate	object
    1	
    <http://127.0.0.1:4343/greenstone3/library/collection/programmes-and-performers/document/D0272>
    <http://purl.org/dc/elements/1.1/Relation.isPartOf>
    <http://127.0.0.1:4343/greenstone3/library/collection/programmes-and-performers>
    2	
    <http://127.0.0.1:4343/greenstone3/library/collection/programmes-and-performers/document/D0272>
    <http://greenstone.org/gsdlextracted#gsdlsourcefilename>
    "import/HMS-Catalogue-SMALL.csv"



#----
# Adding in sparql.xsl to a collection
#----

If needed:

    mkdir $GSDL3HOME/sites/<yoursite>/collect/<yourcollection>/transform
    mkdir $GSDL3HOME/sites/<yoursite>/collect/<yourcollection>/transform/pages

Then:
    /bin/cp transform/pages/sparql.xsl $GSDL3HOME/sites/<yoursite>/collect/<yourcollection>/transform/pages/.
    
If using a reverse-proxy web server:

    emacs packages/apache-jena-fuseki-3.17.0/webapp/xml-to-html-links.xsl

Then change:

    <a href="?query={$query}&amp;output=xml&amp;stylesheet=%2Fxml-to-html-links.xsl">
=>
    <a href="?query={$query}&amp;output=xml&amp;stylesheet=/fuseki3/%2Fxml-to-html-links.xsl">

Then copy:

    cp packages/apache-jena-fuseki-3.17.0/webapp/xml-to-html-links.xsl $GSDL3SRCHOME/packages/tomcat/webapps/fuseki3/.


Also make sure you have set the reverse-proxy web server settings needed for Greenstone3 in:

    emacs $GSDL3SRCHOME/build.properties


#----
# SPARQL quieries
#----

To run a SPARQL query directly, you would do:

  http://localhost:8383/fuseki3/greenstone/query?query=select+*+where+%7B+%3Fs+%3Fo+%3Fp+%7D+limit+100&output=text&stylesheet=

For a proxied install you would (continuing the example) do:

  http://mydomain.org/fuseki3/greenstone/query?query=select+*+where+%7B+%3Fs+%3Fo+%3Fp+%7D+limit+100&output=text&stylesheet=

Factoring in these details, it is possible to setup a transform/page/sparql.xsl page in Greenstone3 that is fully operational,
even in the ReverseProxying situation.


!!!!!!!!!
****
**** From here on, the instructions have not been updated to the newer /fuseki3 embeddedin GS3 Tomcat
****
!!!!!!

One key step in sparql.xsl is to updated the form input argument for 'stylesheet' to specify the proxied prefix URL:

  stylesheet=/greenstone3-lod/xml-to-html-links.xsl
  stylesheet=%2Fgreenstone3-lod%2Fxml-to-html-links.xsl


When asking for the SPARQL XML result to be transformed to html-links, the hyperlinks in the page generated
also need some tweaking.  The Greenstone3 sparql.xsl page helps plumb the static files used back to the
/greenstone3-lod/ url, but inside 'xml-to-html-links.xsl' this sets another 'stylesheet=' argument that
needs to be updated to the ReverseProxy setup


    <a href="?query={$query}&amp;output=xml&amp;stylesheet=%2Fxml-to-html-links.xsl">
=>    
    <a href="?query={$query}&amp;output=xml&amp;stylesheet=%2Fgreenstone3-lod%2Fxml-to-html-links.xsl">

You might need to reload the xml-to-html-links.xsl file in the browser if it has been cached before the change


% fgrep -rl xml-to-html etc/
  etc/pages/sparql.html
  etc/pages/sparql.tpl
  etc/pages/xml-to-html-links.xsl




#----
# Note about Jena code:
#----

  Jena is a pure Java code base, and the relevant compiled jar files
  are bundled with this extension, so no actual compilation is needed.
  The main task CASCADE-MAKE.sh does is to untar the 'binary' files,
  and setup them up in appropriate top-level ' lib' folder (for jar
  files) etc so Greenstone can find them

  In case it is ever needed, the companion source code is in 'src'
  directory (taken from the Apache Jena website, matched to the binary
  version).  For source code, there was only a zip version of the file
  to download.

   To run the command-line client programs, such as 's-put', this
   requires Ruby to be installed.  The source code for this is
   provided in the 'packages' directory, and compiled up and installed
   as part of running ./CASCADE-MAKE.sh