source: gs2-extensions/apache-jena/trunk/src/README-FUSEKI3.txt@ 38208

!!!!!!!!!!!!!!
! DEPRECATED !
!!!!!!!!!!!!!!

These notes were written for when Fuseki3 was run as its own
standalone server on a separate port to the Greenstone3 installation.

***********



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

Installation of this extension follows the usual pattern:

    ./CASCADE-MAKE.sh

Test out the triplestore server with:

  source ./setup.bash
  gs-triplestore-server3.DEPRECATED


A successful run will produce output similar to the following:

    [2023-01-13 03:48:52] Server     INFO  Running in read-only mode for /greenstone
    [2023-01-13 03:48:52] Server     INFO  Apache Jena Fuseki 3.17.0
    [2023-01-13 03:48:53] Config     INFO  FUSEKI_HOME=/mnt/disks/atea-scratch-encrypted/davidb/research/code-managed/intermuse/greenstone3-svn/gs2build/ext/apache-jena/packages/apache-jena-fuseki-3.17.0
    [2023-01-13 03:48:53] Config     INFO  FUSEKI_BASE=/mnt/disks/atea-scratch-encrypted/davidb/research/code-managed/intermuse/greenstone3-svn/gs2build/ext/apache-jena/run
    [2023-01-13 03:48:53] Config     INFO  Shiro file: file:///mnt/disks/atea-scratch-encrypted/davidb/research/code-managed/intermuse/greenstone3-svn/gs2build/ext/apache-jena/run/shiro.ini
    [2023-01-13 03:48:53] Config     INFO  Template file: templates/config-tdb-dir
    [2023-01-13 03:48:54] Server     INFO  Database: TDB1 dataset: location=etc/tdb-triple-store3
    [2023-01-13 03:48:54] Server     INFO  Path = /greenstone
    [2023-01-13 03:48:54] Server     INFO  System
    [2023-01-13 03:48:54] Server     INFO    Memory: 4.0 GiB
    [2023-01-13 03:48:54] Server     INFO    Java:   11.0.16.1
    [2023-01-13 03:48:54] Server     INFO    OS:     Linux 5.11.0-1029-gcp amd64
    [2023-01-13 03:48:54] Server     INFO    PID:    1025186
    [2023-01-13 03:48:54] Server     INFO  Started 2023/01/13 03:48:54 UTC on port 4040


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

Note: if you want to stop the triplestore server, just press ^C,

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

Assuming you are running the gs-triplestore-server3 ...

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:4040/

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

Then add to the Apache2 configuration file:

    ProxyPass        /greenstone3-lod3/ http://localhost:4040/
    ProxyPassReverse /greenstone3-lod3/ http://localhost:4040/

You can now visit the interactive interface as:

    http://mydomain.org/greenstone3-lod3/


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

    https://mydomain.org/greenstone3-lod3/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=/greenstone3-lod3/%2Fxml-to-html-links.xsl">


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


    emacs $GSDL3SRCHOME/build.properties

####!!!

For /fuseki3 running within Greenstone3 tomcat server, do the above but:

stylesheet=/fuseki3/%2F ...

And after accessing the /fuseki3 URL to unbundle the WAR file:

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



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

To run a SPARQL query directly, you would do:

  http://localhost:4040/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/greenstone3-lod/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.

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