agraph-java-client

agraph-java-client copied to clipboard

// This header text is used by Github to form an anchor on the project page. // We link to this anchor from the AllegroGraph client download page // (https://franz.com/agraph/downloads/clients) so if you change this header // text, you must update the link on the client download page. = Java client for Franz AllegroGraph

:version: 4.0.1-SNAPSHOT

This is the Java client for the http://franz.com/agraph/[Franz AllegroGraph] triple store. It contains http://rdf4j.org/[Sesame/RDF4J-] and https://jena.apache.org/[Jena]-compatible APIs.

== Client prerequisites

Java version 8 or higher, and any operating system should work with these jars.

=== Usage

==== Maven

The recommended way of using the client API is to create a dependency on its Maven artifact. To do this in a Maven project, add the following to your dependencies:

[source,xml,subs="verbatim,attributes"]

For Gradle, use this

[source,groovy,subs="verbatim,attributes"] compile group: 'com.franz', name: 'agraph-java-client', version: '{version}'

Apache Ivy syntax:

[source,xml,subs="verbatim,attributes"]

SBT (Scala):

[source,scala,subs="verbatim,attributes"] libraryDependencies += "com.franz" % "agraph-java-client" % "{version}"

Leiningen (Clojure):

[source,clojure,subs="verbatim,attributes"]

[com.franz/agraph-java-client "{version}"]

==== Distribution archive

Tar distributions of the AllegroGraph Java client are available from ftp://ftp.franz.com/pub/agraph/java-client/. A tar distribution includes jar files for agraph-java-client and jars on which it depends.

Programs that use the API should include all JAR files from the lib/ directory of the distribution on their classpath.

To use that local JAR file through Maven install it into your local repository:

[source,sh,subs="verbatim,attributes"] mvn install:install-file -Dfile=lib/agraph-java-client-{version}.jar -DpomFile=pom.xml

Note that when using the API through Maven all dependencies are downloaded from the central repository - JARs included in the distribution are not used.

== Development

=== Testing

Use this command to run the default testsuite. This assumes that AllegroGraph is listening on the local machine on the default port (10035).

mvn test

To include long running tests, do

mvn test -Dtests.include=test.TestSuites\$Prepush,test.TestSuites\$Stress

=== Distribution

To build a distribution archive, do

mvn package

== Tutorials

There are three tutorials located in tutorials/ that can be compiled and run. They are:

sesame/:: Example usage of the AG Sesame/RDF4J interface jena/:: Example usage of the AG Jena interface attributes/:: Example usage of AG Triple Attributes

=== Prerequisites

An AllegroGraph server must be up and running in order to run the tutorials.

The class for each tutorial declares a number of variables near the top of its respective class definition, which provide the information necessary to communicate with AllegroGraph. If necessary, modify these variables to match the settings for your server before compiling each tutorial.

By default, each tutorial looks for AllegroGraph on localhost at port 10035. Each will create a repository named after the respective tutorial in the "java-catalog" catalog.

In order for the tutorial to run successfully, you must ensure that the "java-catalog" catalog has been defined in your agraph.cfg prior to starting AG, or change the value of CATALOG_ID to name a catalog that exists on your server. Use the empty string ("") or null to indicate the root catalog. All other variables must be updated to correspond to your server configuration as well.

=== Compiling Tutorials

Each tutorial is a separate Maven project. To compile the tutorials first install the AllegroGraph Java client into your local repository. This process is described in the 'Usage' section. Then run the following command in the directory containing the tutorial:

 mvn compile

Running Tutorials

To run one of the tutorials, use the following command line:

mvn exec:java

in the directory containing the tutorial you wish to run.

Sesame and Jena tutorials contain multiple, numbered examples. It is possible to run just the specified examples by passing their numbers as arguments in the following way:

mvn exec:java -Dexec.args="1 2 3 5 8 13 21"

The argument 'all' indicates that all examples should be run.

== License

Copyright (c) 2008-2017 Franz Inc. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html[http://www.eclipse.org/legal/epl-v10.html]