com.franz.ag
Class AllegroGraphConnection

java.lang.Object
  com.franz.ag.AllegroGraphConnection

public class AllegroGraphConnection

extends java.lang.Object

This class implements access to AllegroGraph triple stores through a server interface.

One instance of this class can support access to several open triple stores, each with its own AllegroGraph instance. A Java application may connect to multiple servers by creating multiple instances of this class.

Constructor Summary

AllegroGraphConnection()
Create an instance of a connection to an AllegroGraph Server.

Method Summary

AllegroGraph	access(AllegroGraph ag) Connect an AllegroGraph instance to a triple store.
AllegroGraph	access(java.lang.String name, java.lang.String directory) Create an instance that accesses an existing AllegroGraph triple store or a freshly created new empty triple store.
AllegroGraph	create(AllegroGraph ag) Connect an AllegroGraph instance to a triple store.
AllegroGraph	create(java.lang.String name, java.lang.String directory) Create an AllegroGraph instance that accesses a new empty AllegroGraph triple store.
void	deleteStore(java.lang.String name) Delete the triple store with the given name.
void	deleteStore(java.lang.String name, java.lang.String directory) Delete the triple store with the given name.
void	disable() Disable the interface.
void	disable(boolean close) Disable the interface.
boolean	enable() Enable the interface by connecting to an AllegroGraph server.
void	enableHasValueReasoning() Enable reasoning with the hasValue predicate.
java.lang.Object[]	evalInServer(java.lang.String expression) Evaluate a Lisp expession in the AllegroGraph server.
boolean	exists(java.lang.String name, java.lang.String directory) Determine if an AllegroGraph triple store exists.
AllegroGraph	federate(java.lang.String name, AllegroGraph[] parts, boolean supersede) Combine several open triple stores into one federated triple store.
AllegroGraph	findStore(java.lang.String name) Find an open triple store with the given name.
AllegroGraph	findStore(java.lang.String name, java.lang.String directory) Find an open triple store with the given name.
long	getChunkSize() Query the indexing chunk size in the AllegroGraph server.
java.lang.String	getCommand() Retrieve the command used to start an AllegroGraph server.
int	getDebug() Retrieve the debug flag.
static java.lang.String	getDefaultCommand() Retrieve the static default command used to start an AllegroGraph server.
static int	getDefaultDebug() Retrieve the static default debug flag.
long	getDefaultExpectedResources() Get the current server default value for the expected number of unique resources in a new triple store.
static java.lang.String	getDefaultHost() Retrieve the static default host name.
static java.lang.String	getDefaultMode() Retrieve the static default connection mode.
static int	getDefaultPollCount() Retrieve the static default value of the poll count parameter.
static int	getDefaultPollInterval() Retrieve the static default value of the poll interval parameter.
static int	getDefaultPort() Retrieve the static default primary port number.
static int	getDefaultPort2() Retrieve the static default secondary port number.
static boolean	getDefaultServerKeep() Retrieve the static default value of the Server Keep flag.
static int	getDefaultTimeout() Retrieve the static default value of the connection timeout.
java.lang.String	getHost() Retrieve the host name.
static NamespaceRegistry	getInitialNamespaceRegistry() Query the current initial namespace registry.
java.lang.String	getMode() Retrieve the connection mode.
NamespaceRegistry	getNamespaceRegistry()
java.lang.String[]	getNamespaces() Query the namespace definitions in the AllegroGraph server.
int	getPollCount() Retrieve the current value of the poll count parameter.
int	getPollInterval() Retrieve the current value of the poll interval parameter.
int	getPort() Retrieve the primary port number.
int	getPort2() Retrieve the secondary port number.
boolean	getServerKeep() Retrieve the value of the Server Keep flag.
int	getTimeout() Retrieve the current timeout value for this connection.
int	interrupt() Attempt to interrupt an operation in the AllegroGraph server.
boolean	isBusy() Query the state of the AllegroGraph/Java connection.
boolean	isEnabled() Query the state of the AllegroGraph/Java connection.
static void	main(java.lang.String[] args) Run this method to set the default AllegroGraph server command once per installation.
AllegroGraph	open(AllegroGraph ag) Connect an AllegroGraph instance to a triple store.
AllegroGraph	open(java.lang.String name, java.lang.String directory) Create an instance that accesses an existing AllegroGraph triple store.
void	registerNamespace(java.lang.String prefix, java.lang.String full) Register one namespace definition.
void	registerNamespaces(java.lang.String[] defs) Register several namespace definitions.
AllegroGraph	renew(AllegroGraph ag) Connect an AllegroGraph instance to a triple store.
AllegroGraph	renew(java.lang.String name, java.lang.String directory) Create an instance that accesses an AllegroGraph triple store.
AllegroGraph	replace(AllegroGraph ag) Connect an AllegroGraph instance to a triple store.
AllegroGraph	replace(java.lang.String name, java.lang.String directory) Create an instance that accesses an AllegroGraph triple store.
boolean	serverLevel(int level) Query the implementation level of the AllegroGraph server.
int	serverTrace(boolean onoff) Change the trace state in the AllegroGraph server.
int	serverTrace(java.lang.String outFile) Start tracing calls from Java in the AllegroGraph server.
void	setChunkSize(long s) Set the indexing chunk size in the AllegroGraph server.
void	setCommand(java.lang.String cmd) Set the command used to start an AllegroGraph server.
void	setDebug(int db) Set the debug flag.
static void	setDefaultCommand(java.lang.String cmd) Set the static default command used to start an AllegroGraph server.
static void	setDefaultDebug(int db) Set the static default debug flag.
void	setDefaultExpectedResources(long s) Set the current server default value for the expected number of unique resources in a new triple store.
static void	setDefaultHost(java.lang.String host) Set the static default host name.
static void	setDefaultPolling(int count, int interval) Set the static default values of the poll count and poll interval parameters.
static void	setDefaultPort(int port) Set the static default primary port number.
static void	setDefaultPort2(int port) Set the static default secondary port number.
void	setDefaultServerKeep(boolean v) Set the static default value of the Server Keep flag.
static void	setDefaultTimeout(int defaultTimeout) Set the default timeout value for connection attempts.
void	setHost(java.lang.String newhost) Set the host name.
static void	setInitialNamespaceRegistry(NamespaceRegistry ns) Set the current initial namespace registry.
void	setNamespaceRegistry(NamespaceRegistry ns) Register several namespace definitions.
void	setPolling(int count, int interval) Set the current values of the poll count and poll interval parameters.
void	setPort(int p) Set the primary port number.
void	setPort2(int p) Set the secondary port number.
void	setServerKeep(boolean v) Set the value of the Server Keep flag.
void	setTimeout(int timeout) Set the timeout value for connection attempts.
void	startServer() Start a system process running an AllegroGraph server.
void	startServer(java.lang.String log) Start a system process running an AllegroGraph server.
int	stopServer() Stop an AllegroGraph server process that was started by this Java application.
int	stopServer(boolean killNotStarted) Stop an AllegroGraph server process.
java.lang.String	toString() Display some details about the server instance.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AllegroGraphConnection

public AllegroGraphConnection()

Create an instance of a connection to an AllegroGraph Server. The instance is a placeholder for parameters until the enable() method is called.

Method Detail

getInitialNamespaceRegistry

public static NamespaceRegistry getInitialNamespaceRegistry()

Query the current initial namespace registry. This namespace registry is copied into every new AllegroGraphConnection instance.

Returns:

the current instance.

setInitialNamespaceRegistry

public static void setInitialNamespaceRegistry(NamespaceRegistry ns)

Set the current initial namespace registry. This namespace registry is copied into every new AllegroGraphConnection instance.

Parameters:

ns - the instance to set. If this is set to null, then there is no default namespace registry.

The initial value is NamespaceRegistry.RDFandOwl.

getDefaultPollCount

public static int getDefaultPollCount()

Retrieve the static default value of the poll count parameter. The built-in initial value is 1.

Returns:

an integer that determines the number of connection attempts

getDefaultPollInterval

public static int getDefaultPollInterval()

Retrieve the static default value of the poll interval parameter. The built-in initial value is 500.

Returns:

an integer number that determines the interval (in milliseconds) between attempts to connect

getPollCount

public int getPollCount()

Retrieve the current value of the poll count parameter.

Returns:

an integer that determines the number of connection attempts

getPollInterval

public int getPollInterval()

Retrieve the current value of the poll interval parameter.

Returns:

an integer that determines the interval between attempts to connect

setDefaultPolling

public static void setDefaultPolling(int count,
                                     int interval)

Set the static default values of the poll count and poll interval parameters.

Parameters:

count - an integer that determines the number of connection attempts

interval - an integer that determines the interval between attempts to connect

A positive value greater than zero is used to set the corresponding parameter. If a zero or negative value is specified, the corresponding parameter is unchanged.

The initial static defaults are 2 for poll count and 500 for poll interval.

setPolling

public void setPolling(int count,
                       int interval)

Set the current values of the poll count and poll interval parameters.

Parameters:

count - an integer that determines the number of connection attempts

interval - an integer that determines the interval between attempts to connect

A positive value greater than zero is used to set the corresponding parameter.

If a zero value is specified, set the current value of the parameter from the static default value.

If a negative value is specified, the corresponding parameter is unchanged.

The inital values are set from the static default values.

If an application encounters timeout exceptions when attempting a connection one or both of these parameters should be given a larger value.

getDefaultMode

public static java.lang.String getDefaultMode()

Retrieve the static default connection mode.

Returns:

The string "direct".

getMode

public java.lang.String getMode()

Retrieve the connection mode.

Returns:

The string "direct" or "jlinker".

getDefaultPort

public static int getDefaultPort()

Retrieve the static default primary port number. The built-in initial value is 4567.

Returns:

The default primary port number.

setDefaultPort

public static void setDefaultPort(int port)

Set the static default primary port number. If the static default primary port number is not set explicitly, the built-in initial value is 4567.

Parameters:

port - A port number.

getPort

public int getPort()

Retrieve the primary port number.

Returns:

The primary port number. The built-in initial value is 4567.

setPort

public void setPort(int p)

Set the primary port number. If the primary port number is not set explicitly, the static default is used.

Parameters:

p - A port number.

getDefaultPort2

public static int getDefaultPort2()

Retrieve the static default secondary port number. The built-in initial value is 4568.

Returns:

The default secondary port number.

setDefaultPort2

public static void setDefaultPort2(int port)

Set the static default secondary port number. If the static default secondary port number is not set explicitly, the built-in initial value is 4568.

Parameters:

port - A port number.

getPort2

public int getPort2()

Retrieve the secondary port number.

Returns:

The default secondary port number. The built-in initial value is 4568.

setPort2

public void setPort2(int p)

Set the secondary port number. If the secondary port number is not set explicitly, the static default is used.

Parameters:

p - A port number.

getDefaultHost

public static java.lang.String getDefaultHost()

Retrieve the static default host name. The built-in initial value is "" which denotes "localhost".

Returns:

The default host name.

setDefaultHost

public static void setDefaultHost(java.lang.String host)

Set the static default host name. If the static default host name is not set explicitly, the built-in initial value is "" which denotes "localhost".

Parameters:

host - A host name string. The empty string denotes the loopback host "localhost".

getHost

public java.lang.String getHost()

Retrieve the host name.

Returns:

The host name used for a connection to the AllegroGraph server. The built-in initial value is "" which denotes "localhost".

setHost

public void setHost(java.lang.String newhost)

Set the host name. If the host name is not set explicitly, the static default host name is used.

Parameters:

newhost - A host name string. The empty string denotes the loopback host "localhost".

getDefaultDebug

public static int getDefaultDebug()

Retrieve the static default debug flag. The built-in default value is zero.

Returns:

The default debug flag.

setDefaultDebug

public static void setDefaultDebug(int db)

Set the static default debug flag. If the static default debug flag is not set explicitly, the built-in initial value is zero.

Parameters:

db - When true, new instances of AllegroGraphConnection are created in debug mode and produce additional progress messages. A zero value suppresses all output. Values 1 to 4 produce increasing amounts of output.

getDebug

public int getDebug()

Retrieve the debug flag.

Returns:

The debug flag. The built-in initial value is zero.

setDebug

public void setDebug(int db)

Set the debug flag. If the debug flag is not set explicitly, the static default debug flag is used.

Parameters:

db - When >0, new instances of AllegroGraphConnection are created in debug mode and produce additional progress messages.

getDefaultCommand

public static java.lang.String getDefaultCommand()

Retrieve the static default command used to start an AllegroGraph server. The built-in default value is the empty string.

Returns:

a command string. An empty string indicates that the command is unknown and hence not usable.

setDefaultCommand

public static void setDefaultCommand(java.lang.String cmd)

Set the static default command used to start an AllegroGraph server.

Parameters:

cmd - A command string that will start the AllegroGraph server process in the local machine.

If the static default command is not set explicitly, it is looked up in the Java System property "com.franz.ag.exec". If it set to " ", the string containing one space. then a value is obtained from

• from a User Preference
• from a system Preference.

The Preference values may be initialized once per installation by calling the main() method of this class. The Preferences values are saved in the registry on Windows machines but are not reliable on some Linux or Unix machines.

getCommand

public java.lang.String getCommand()

Retrieve the command used to start an AllegroGraph server.

Returns:

a command string. An empty string indicates that the command is unknown and hence not usable.

setCommand

public void setCommand(java.lang.String cmd)

Set the command used to start an AllegroGraph server. If the command is not set explicitly, the static default command is used.

Parameters:

cmd - A command string that will start the AllegroGraph server process in the local machine.

getDefaultServerKeep

public static boolean getDefaultServerKeep()

Retrieve the static default value of the Server Keep flag. The built-in initial value is false.

Returns:

true true or false

setDefaultServerKeep

public void setDefaultServerKeep(boolean v)

Set the static default value of the Server Keep flag.

The Server Keep flag determines the behavior when an instance of AllegroGraphConnection is discarded. If the instance called startServer() and the Server Keep flag is false, then the server process is terminated. Otherwise the server process is left running.

Parameters:

v -

getServerKeep

public boolean getServerKeep()

Retrieve the value of the Server Keep flag.

Returns:

true or false

See Also:

getDefaultServerKeep()

setServerKeep

public void setServerKeep(boolean v)

Set the value of the Server Keep flag. If the flag is not set explicitly, the static default value is used.

The Server Keep flag determines the behavior when an instance of AllegroGraphConnection is discarded. If the instance called startServer() and the Server Keep flag is false, then the server process is terminated. Otherwise the server process is left running.

Parameters:

v -

enable

public boolean enable()
               throws java.io.IOException,
                      AllegroGraphException

Enable the interface by connecting to an AllegroGraph server. The connection is determined by the following values:

• The integer port number where the AllegroGraph server is listening is queried with getPort() and modified with setPort().
• The name of the host where the AllegroGraph server is listening is queried with getHost() and modified with setHost(). This can normally be "localhost" or "".
• The connection mode is queried with getMode() and modified with setDirect() or setJLinker().
• The integer port number for the second socket in the AllegroGraph/Java connection. Some implementations of the AllegroGraph server use two sockets. This argument is ignored if the server uses only one socket.

Returns:

true if the connection was not enabled and now is. Return false if the connection was already enabled.

Throws:

java.io.IOException - if the interface cannot be enabled.

Only one instance with mode "jlinker" can be enabled at any one time in each running Java application.

• Direct Mode Exceptions:
  • "Too many connections." -- The AllegroGraph Version 1.2 server allows only one connection at a time.
  • "Connection rejected." -- The AllegrGraph server application filter function rejected the connection.
  • "Connected but timed out." -- The expected server acknowledgement byte did not arrive in the expected time interval.
  • "Unexpected initial reply " -- A byte arrived from the server but it was unexpected.
  • other socket error
• JLinker Mode Exceptions:
  • "Only one enabled JLinker instance allowed."
  • "Connection failed with null explanation."
  • "Connection failed with empty explanation."
  • other jlinker error
  • other socket error
  AllegroGraphException

interrupt

public int interrupt()
              throws AllegroGraphException,
                     java.io.IOException

Attempt to interrupt an operation in the AllegroGraph server.

Returns:

the integer 1 if an operation was actually interrupted; 0 if the connection specified by the argument was idle; or a negative integer if the operation failed in some way because the connection was not in a running or idle state.

Throws:

AllegroGraphException

java.io.IOException

disable

public void disable()
             throws AllegroGraphException

Disable the interface. All remote references to AllegroGraph data are invalidated by this call. Any open triple stores are closed.

Throws:

AllegroGraphException

disable

public void disable(boolean close)

Disable the interface.

Parameters:

close - If true, close any open triple stores before disabling the interface.

All remote references to AllegroGraph data are invalidated by this call.

If called with a false arguments, any open triple stores will remain open for a while, at most until the AllegroGraph server is shut down. This option should be used only if the application is such that any open AllegroGraph instances will never be used again.

isEnabled

public boolean isEnabled()

Query the state of the AllegroGraph/Java connection.

Returns:

true if the interface is enabled.

isBusy

public boolean isBusy()

Query the state of the AllegroGraph/Java connection.

Returns:

true if the interface is enabled and busy.

create

public AllegroGraph create(java.lang.String name,
                           java.lang.String directory)
                    throws AllegroGraphException

Create an AllegroGraph instance that accesses a new empty AllegroGraph triple store.

triple stores are created with the methods access(), create(), open(), renew(), and replace().

Parameters:

name - the name of the triple store or a pathname string that specifies the name and location of the triple store. If the name argument is a pathname string then the directory argument must be null.

directory - the directory where the data base does or will reside. If this argument is a non-null string, then the name argument must be a simple name.

Throws:

AllegroGraphException - if the triple store exists already, or if the new triple store cannot be created for any other reason.

create

public AllegroGraph create(AllegroGraph ag)
                    throws AllegroGraphException

Connect an AllegroGraph instance to a triple store. The triple store is created where one did not exist.

This form is useful when additional attributes must be set with AllegroGraph.setAttribute(String, Object) before connecting to the triple store.

Parameters:

ag - An unconnected AllegroGraph instance.

Returns:

the AllegroGraph instance argument, updated and connected.

Throws:

AllegroGraphException

open

public AllegroGraph open(java.lang.String name,
                         java.lang.String directory)
                  throws AllegroGraphException

Create an instance that accesses an existing AllegroGraph triple store.

triple stores are created with the methods access(), create(), open(), renew(), and replace().

Parameters:

name - the name of the triple store or a pathname string that specifies the name and location of the triple store. If the name argument is a pathname string then the directory argument must be null.

directory - the directory where the data base does or will reside. If this argument is a non-null string, then the name argument must be a simple name.

Throws:

AllegroGraphException - if the triple store does not exist or if it cannot be opened for any other reason.

open

public AllegroGraph open(AllegroGraph ag)
                  throws AllegroGraphException

Connect an AllegroGraph instance to a triple store. The triple store must exists; connect to it.

This form is useful when additional attributes must be set with AllegroGraph.setAttribute(String, Object) before connecting to the triple store.

Parameters:

ag - An unconnected AllegroGraph instance.

Returns:

the AllegroGraph instance argument, updated and connected.

Throws:

AllegroGraphException

exists

public boolean exists(java.lang.String name,
                      java.lang.String directory)
               throws AllegroGraphException

Determine if an AllegroGraph triple store exists.

Parameters:

name - the name of the triple store or a pathname string that specifies the name and location of the triple store. If the name argument is a pathname string then the directory argument must be null.

directory - the directory where the data base does or will reside. If this argument is a non-null string, then the name argument must be a simple name.

Returns:

true if the triple store exist, false otherwise.

Throws:

AllegroGraphException - if the call fails for some reason.

If this method returns true, then creating an AllegroGraph instance with the open() method will succeed.

access

public AllegroGraph access(java.lang.String name,
                           java.lang.String directory)
                    throws AllegroGraphException

Create an instance that accesses an existing AllegroGraph triple store or a freshly created new empty triple store. If the triple store exists, it is opened. If the triple store does not exist, it is created.

Triple stores are created with the methods access(), create(), open(), renew(), and replace().

Parameters:

name - the name of the triple store or a pathname string that specifies the name and location of the triple store. If the name argument is a pathname string then the directory argument must be null.

directory - the directory where the data base does or will reside. If this argument is a non-null string, then the name argument must be a simple name.

Throws:

AllegroGraphException - if the triple store cannot be opened or created.

access

public AllegroGraph access(AllegroGraph ag)
                    throws AllegroGraphException

Connect an AllegroGraph instance to a triple store. If the triple store exists, connect to it; if it does not exist, create it.

This form is useful when additional attributes must be set with AllegroGraph.setAttribute(String, Object) before connecting to the triple store.

Parameters:

ag - An unconnected AllegroGraph instance.

Returns:

the AllegroGraph instance argument, updated and connected.

Throws:

AllegroGraphException

renew

public AllegroGraph renew(java.lang.String name,
                          java.lang.String directory)
                   throws AllegroGraphException

Create an instance that accesses an AllegroGraph triple store. If the triple store exists, it is deleted and replaced with a new empty triple store.

Triple stores are created with the methods access(), create(), open(), renew(), and replace().

Parameters:

name - the name of the triple store or a pathname string that specifies the name and location of the triple store. If the name argument is a pathname string then the directory argument must be null.

directory - the directory where the data base does or will reside. If this argument is a non-null string, then the name argument must be a simple name.

If the operation implies the deletion of a triple store, the entire directory is deleted.

Throws:

AllegroGraphException - if the triple store cannot be accessed or created.

renew

public AllegroGraph renew(AllegroGraph ag)
                   throws AllegroGraphException

Connect an AllegroGraph instance to a triple store. If the triple store exists, delete it and replace it with a new empty one; if it does not exist, create it.

This form is useful when additional attributes must be set with AllegroGraph.setAttribute(String, Object) before connecting to the triple store.

Parameters:

ag - An unconnected AllegroGraph instance.

Returns:

the AllegroGraph instance argument, updated and connected.

Throws:

AllegroGraphException

replace

public AllegroGraph replace(java.lang.String name,
                            java.lang.String directory)
                     throws AllegroGraphException

Create an instance that accesses an AllegroGraph triple store. The triple store must already exist, and it will be replace with a new empty one.

Triple stores are created with the methods access(), create(), open(), renew(), and replace().

Parameters:

name - the name of the triple store or a pathname string that specifies the name and location of the triple store. If the name argument is a pathname string then the directory argument must be null.

directory - the directory where the data base does or will reside. If this argument is a non-null string, then the name argument must be a simple name.

Since the operation implies the deletion of a triple store, the entire directory is deleted.

Throws:

AllegroGraphException - if the triple store does not exist, or if it cannot be replaced for any reason.

replace

public AllegroGraph replace(AllegroGraph ag)
                     throws AllegroGraphException

Connect an AllegroGraph instance to a triple store. The triple store must exist; delete it and replace it with a new empty one.

This form is useful when additional attributes must be set with AllegroGraph.setAttribute(String, Object) before connecting to the triple store.

Parameters:

ag - An unconnected AllegroGraph instance.

Returns:

the AllegroGraph instance argument, updated and connected.

Throws:

AllegroGraphException

getChunkSize

public long getChunkSize()
                  throws AllegroGraphException

Query the indexing chunk size in the AllegroGraph server.

Returns:

the indexing chunk size.

Throws:

AllegroGraphException

setChunkSize

public void setChunkSize(long s)
                  throws AllegroGraphException

Set the indexing chunk size in the AllegroGraph server. See the discussion of chunk size at AllegroGraph.indexTriples().

Parameters:

s - the desired chunk size

The built-in default value is 1,048,576 (2 to the 20th) on 32-bit platforms and 2,097,152 (2 to the 21st) on 64-bit platforms.

Note that this is a global value that affects all the triple stores in a server.

Throws:

AllegroGraphException

getDefaultExpectedResources

public long getDefaultExpectedResources()
                                 throws AllegroGraphException

Get the current server default value for the expected number of unique resources in a new triple store.

Returns:

the current value of this server parameter.

Throws:

AllegroGraphException

setDefaultExpectedResources

public void setDefaultExpectedResources(long s)
                                 throws AllegroGraphException

Set the current server default value for the expected number of unique resources in a new triple store. The new value will affect any triple stores created after this call. This number is the expected number of distinct URIs and literals in the triple store.

If the number is too small, performance may suffer during triple store creation. A rough rule of thumb is to specify a number that is one third of the number of triples. The built-in default is 100000.

Parameters:

s - the new value.

Throws:

AllegroGraphException

evalInServer

public java.lang.Object[] evalInServer(java.lang.String expression)
                                throws AllegroGraphException

Evaluate a Lisp expession in the AllegroGraph server. The expression is evaluated in the default environment associated with this AllegroGraphConnection instance.

Parameters:

expression - A string containing a well-formed Lisp expression.

Returns:

An array of Object instances representing the values computed by the call. The values returned by the call must be coercible to simple Java types: number, string, vector of numbers, vector of strings, UPI instance, vector of UPIs, or null.

Throws:

AllegroGraphException - *

Usage:

This method allows a Java application to run programs in the AllegroGraph server. Using this method can change the state of the server and the content of triple stores. It is provided as a diagnostic aid, and as a tool for advanced users.

By default, this method is disabled in the server. It must be enabled by starting the server with a file of permitted expression patterns. See the server reference for details.

Most uses of this method will require some knowledge of the Lisp programing language, and an understanding of the AllegroGraph implementation.

The evaluation environment contains bindings for *package*, *readtable*. Each AllegroGraphConnection instance defines a distinct default environment.

The initial value of *package* is the db.agraph.user package. It uses :cl, :excl, :db.agraph, and :prolog. If the value of *package* is modified, the change persists for subsequent calls to evalInServer on the same connection.

The initial value of *readtable* is a copy of the standard Common Lisp readtable. If the value of *readtable* is modified, the change persists for subsequent calls to evalInServer on the same connection.

Side-effects on the environment persist as long as the connection is maintained.

If a Java application needs to mention symbols in a fixed application package (maybe mentioned in a source file), it may be advisable to evaluate an in-package form in the environment.

The variable *db* is bound if AllegroGraph.evalInServer is called but if modified, the change will not persist.

serverTrace

public int serverTrace(boolean onoff)

Change the trace state in the AllegroGraph server.

Parameters:

onoff - true to turn on tracing.

When tracing is turned on in the AllegroGraph server, every call from Java to the server causes some output on the server console. This output may be useful in diagnosing some problems. Since tracing may produce large quantities of output it should be used with caution and only around critical sections of code.

The trace state is global for all connections to the server.

Returns:

-1 if the call failed for some reason, 0 otherwise.

serverLevel

public boolean serverLevel(int level)
                    throws AllegroGraphException

Query the implementation level of the AllegroGraph server.

Parameters:

level - A positive integer.

Returns:

True if the server is at or above the specified level.

Throws:

AllegroGraphException

serverTrace

public int serverTrace(java.lang.String outFile)

Start tracing calls from Java in the AllegroGraph server.

Parameters:

outFile - the name and path for a file where the trace output will go.

When tracing is turned on in the AllegroGraph server, every call from Java to the server causes some output on the server console. This output may be useful in diagnosing some problems. Since tracing may produce large quantities of output it should be used with caution and only around critical sections of code.

The trace state is global for all connections to the server.

Returns:

-1 if the call failed for some reason, 0 otherwise.

getNamespaces

public java.lang.String[] getNamespaces()
                                 throws AllegroGraphException

Query the namespace definitions in the AllegroGraph server. There is one set of namespace definitions in the AllegroGraph server. The definitions are copied to each triple store created from this connection instance. Therefore, changes to this table do not affect any triple stores that are already open. The definitions are not persisitent.

Returns:

An array of strings. The even numbered elements are prefixes and the following odd numbered element is the full namespace text.

Throws:

AllegroGraphException

getNamespaceRegistry

public NamespaceRegistry getNamespaceRegistry()

registerNamespace

public void registerNamespace(java.lang.String prefix,
                              java.lang.String full)

Register one namespace definition. The definition is added to the registry used to initialize new AllegroGraph instances. The definition overrides an existing definition.

Parameters:

prefix - the prefix

full - The full namespace text. If the full text is null or "", then the prefix is removed from the table.

Throws:

AllegroGraphException

registerNamespaces

public void registerNamespaces(java.lang.String[] defs)

Register several namespace definitions. The definitions are added to the current table and override any existing definitions.

Parameters:

defs - An array of strings. The even numbered elements are prefixes and the following odd numbered element is the full namespace text. If the full text is null or "", then the prefix is removed from the table.

setNamespaceRegistry

public void setNamespaceRegistry(NamespaceRegistry ns)

Register several namespace definitions. The definitions replace any definitions that were in place.

Parameters:

ns - the source of the definitions.

toString

public java.lang.String toString()

Display some details about the server instance.

startServer

public void startServer()
                 throws java.io.IOException

Start a system process running an AllegroGraph server. Equivalent to startServer(null).

Throws:

java.io.IOException

startServer

public void startServer(java.lang.String log)
                 throws java.io.IOException

Start a system process running an AllegroGraph server.

Parameters:

log - The name of a log file or null. If non-null, the AG server writes a log to this file in the home directory.

Throws:

java.io.IOException - from Runtime.exec().

If the command was specified with setCommand(String) or with setDefaultCommand(String) then the command specified by the program is used.

If the command is specified as "" or " " and the system property "com.franz.ag.exec" is set then the property value is used.

If the command is specified " " then system and user Preferences are examined. The Preferences values may be set by executing the main() method in this class.

stopServer

public int stopServer()
               throws java.io.IOException,
                      AllegroGraphException

Stop an AllegroGraph server process that was started by this Java application.

Returns:

0 if all went smoothly, -1 if there was no process to terminate, or a positive number of error responses.

Throws:

java.io.IOException

AllegroGraphException

stopServer

public int stopServer(boolean killNotStarted)
               throws java.io.IOException,
                      AllegroGraphException

Stop an AllegroGraph server process.

Parameters:

killNotStarted - if false, stop the server if it was started by this application; if true, stop the server even if it was started some other way.

Returns:

0 if all went smoothly, -1 if there was no process to terminate, or a positive number of error responses.

Throws:

java.io.IOException

AllegroGraphException

main

public static void main(java.lang.String[] args)

Run this method to set the default AllegroGraph server command once per installation.

Parameters:

args - The arguments to the JVM invocation.

  java AllegroGraphConnection [-system command] [-user command]
  

If the -system argument is supplied, set the default for all users.

If the -user argument is supplied, set the default for the current user only.

The command argument is the absolute pathname to the AllegroGraphJavaServer executable.

enableHasValueReasoning

public void enableHasValueReasoning()
                             throws AllegroGraphException

Enable reasoning with the hasValue predicate. This is an experimental feature that is not available in all AllegroGraph installations.

Throws:

AllegroGraphException

federate

public AllegroGraph federate(java.lang.String name,
                             AllegroGraph[] parts,
                             boolean supersede)
                      throws AllegroGraphException

Combine several open triple stores into one federated triple store.

Parameters:

name - A name for the federation. It is best to use a unique name.

parts - The triple stores that will be federated. All the compoent triple stores must be open and must be connected through the same connection.

supersede - When false, throw an exception if a triple store with the same name is already open. When true, and an open triple store with the same name is found, then close the triple store before making the federation. If the existing triple store was a federated store, it is destroyed by closing it; If the existing triple store is a persisitent store, then closing it simply makes it unavailable until reopened.

The Default Graph in a Federated Triple Store

The default graph of a federated triple store is distinct from the default graph of the component stores. The default graph of any triple store is distinct from the default graph of any other triple store. As a result, the default graph is not a useful concept in federated stores. If an application needs to view some triples in several different stores of a federation as members of the same graph, then the triples must be created with a common graph marker.

Throws:

AllegroGraphException

findStore

public AllegroGraph findStore(java.lang.String name)
                       throws AllegroGraphException

Find an open triple store with the given name.

Parameters:

name - The name of a triple store. This can be a simple name or a pathname string.

Returns:

A new AllegroGraph instance for the triple store.

Throws:

AllegroGraphException - if the name is not found or ambiguous.

findStore

public AllegroGraph findStore(java.lang.String name,
                              java.lang.String directory)
                       throws AllegroGraphException

Find an open triple store with the given name.

Parameters:

name - The name of a triple store.

directory - The directory where the triple store is filed. This argument can be used to identify one of several triple stores with the same name. If this argument is a non-null string, then the name argument must be a simple name.

Returns:

A new AllegroGraph instance for the triple store.

Throws:

AllegroGraphException - if the name is not found or ambiguous.

deleteStore

public void deleteStore(java.lang.String name)
                 throws AllegroGraphException

Delete the triple store with the given name.

Parameters:

name - The name of a triple store. This can be a simple name or a pathname string.

Throws:

AllegroGraphException - if the name is not found or ambiguous.

deleteStore

public void deleteStore(java.lang.String name,
                        java.lang.String directory)
                 throws AllegroGraphException

Delete the triple store with the given name.

Parameters:

name - The name of a triple store.

directory - The directory where the triple store is filed. This argument can be used to identify one of several triple stores with the same name. If this argument is a non-null string, then the name argument must be a simple name.

Throws:

AllegroGraphException - if the name is not found or ambiguous.

getDefaultTimeout

public static int getDefaultTimeout()

Retrieve the static default value of the connection timeout. The built-in initial value is 5000.

Returns:

the defaultTimeout in milliseconds. See also getTimeout().

setDefaultTimeout

public static void setDefaultTimeout(int defaultTimeout)

Set the default timeout value for connection attempts.

Parameters:

defaultTimeout - the defaultTimeout to set in milliseconds. See also setTimeout(int).

getTimeout

public int getTimeout()

Retrieve the current timeout value for this connection. The default initial value is queried with getDefaultTimeout(). The value is modified with setTimeout(int).

Returns:

the timeout in milliseconds.

setTimeout

public void setTimeout(int timeout)

Set the timeout value for connection attempts. This value is used when connecting to a server. If the server does not connect within this interval, the connection is aborted. The server must also send an identifying byte within 10 times this interval, or the connection is aborted.

Parameters:

timeout - the timeout to set in milliseconds.