.. _java:
Use from Java
=============
Java prerequisites
------------------
* Java 8 or 11 JDK
* `Maven `_
Dependencies
^^^^^^^^^^^^
See `Maven Central `_ for available artifacts.
The public-facing Java modules are:
* ``twks-agraph``\ : `AllegroGraph `_ implementation of the ``Twks`` API
* ``twks-api``\ : public-facing Java library API, including the store library API ``Twks``
* ``twks-client``\ : public-facing Java client API
* ``twks-nanopub``\ : library for working with nanopublications, independently of TWKS
* ``twks-tdb``: `Jena TDB2 `_ implementation of the ``Twks`` API
* ``twks-uri``\ : tiny type for URIs
* ``twks-vocabulary``\ : RDF vocabulary singletons, similar to ``org.apache.jena.vocabulary``
The above modules are supported by various internal modules, such as the ``twks-abc`` module of abstract base classes for ``Twks`` implementations. API users should not need these.
Releases
~~~~~~~~
Release dependencies can be added directly to your Maven/Gradle/SBT configuration:
.. code-block::
edu.rpi.tw.twks
twks-api
1.0.2
Snapshots
~~~~~~~~~
Snapshots from Maven Central require enabling the OSSRH snapshot repository.
In Maven ``~/.m2/settings.xml``
.. code-block::
allow-snapshots
true
snapshots-repo
https://oss.sonatype.org/content/repositories/snapshots
false
true
Or in ``build.sbt``\ :
.. code-block::
resolvers += Resolver.sonatypeRepo("snapshots")
Then use a dependency as:
.. code-block::
edu.rpi.tw.twks
twks-api
1.0.5-SNAPSHOT
.. _java-examples:
Java examples
-------------
The repository contains a `number of examples of using TWKS from Java `_.
.. _java-client:
Using the Java client
---------------------
The easiest way to access the store is over the network, as a client of the TWKS server. This allows the server implementation to be isolated.
A Java client library is provided, `TwksClient `_. It is available via the following Maven dependency:
.. code-block::
edu.rpi.tw.twks
twks-client
1.0.0
See the :ref:`java-examples` for an example of Java client use.
.. _java-lib:
Using the store as a library from Java
--------------------------------------
Add a ``Twks`` implementation to your Maven/SBT/Gradle/etc. dependencies:
.. code-block::
edu.rpi.tw.twks
twks-tdb
1.0.0
Java nanopublication library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This library is an implementation of the current `Nanopublication Guidelines `_. It can be used independently of TWKS.
The `Nanopublication `_ class is the primary abstraction.
You can parse nanopublications or loose assertion graphs with the `NanopublicationParser `_ class or build them from parts (named graphs) using the `NanopublicationFactory `_ class.
Java library development
^^^^^^^^^^^^^^^^^^^^^^^^
The TWKS public-facing library API is in the class `Twks `_.
Like Jena ``Model`` and ``Dataset``\ , ``Twks`` has multiple implementations. For example, `Tdb2Twks `__.
You can instantiate an implementation directly, or indirectly through `TwksFactory `_), which is what the server and command line interfaces do.
.. _java-cli:
Java command line use
---------------------
A command-line interface provides various sub-commands for manipulating TWKSs. After building, run:
.. code-block::
java -jar java/dist/twks-cli-current.jar --help
To see the available sub-commands and their options.
Note that TDB2 is a single process store, so you will not be able to access it from separate library-using, command line, and/or server processes concurrently.
.. _java-server:
Running the TWKS server directly on the host
--------------------------------------------
You can run the server directly on your host machine in one of two ways:
Using your own servlet container
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After building the project with ``mvn package``\ , copy the ``java/dist/twks-server-current.war`` to your servlet container's ``webapps`` directory e.g., ``/var/lib/jetty/webapps``.
You may want to rename the ``.war`` to ``ROOT.war`` to mount at the root context.
Running the server from Maven
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The server can be started directly using Maven:
.. code-block::
cd java
mvn jetty:run
See the `jetty-maven-plugin documentation `_ for ``-D`` configuration options to control the port.
Various server options that require interaction with the host are disabled by default. You can use ``-D`` with properties to enable them. For example, to enable ``extfs`` against a directory:
.. code-block::
cd java
mvn jetty:run -Dtwks.extfs=$PWD/../py/examples/extfs/
Or persist to disk with the TDB implementation of the store:
.. code-block::
cd java
mvn jetty:run -Dtwks.tdbLocation=$PWD/../data