com.franz.agbase
Class AllegroGraphConnection

java.lang.Object
  extended by AGConnInternals
      extended by com.franz.agbase.AllegroGraphConnection

public class AllegroGraphConnection
extends AGConnInternals

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.
 void addPrologFile(java.lang.String nameOfFile)
          Add some Prolog rules to the server from a file visible to the server.
 void addPrologRule(java.lang.String ruleInString)
          Add one Prolog rule to the server.
 void addPrologRules(java.lang.String[] arrayOfRules)
          Add some Prolog rules to the server from an array of rules.
 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.
 java.lang.Object[] evalInServer(java.lang.String expression)
          Evaluate a Lisp expression 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 getChunkCountWarningLimit()
          Query the indexing chunk count warning limit in the AllegroGraph server.
 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.
 long getDefaultSPOGICacheSize()
          Query the default size of the SPOGI cache in the current server.
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.
 java.lang.String[] getPrologFunctors()
          Return a list of all the known Prolog functors.
 java.lang.String[] getPrologFunctors(java.lang.String regExp)
          Return a list of all the known Prolog functors that match a pattern.
 java.lang.String[] getPrologRules()
          Return a listing of all the known Prolog rules.
 java.lang.String getPrologRules(java.lang.String functorName)
          Return a listing of the rules pertaining to one Prolog functor.
 java.lang.String[] getPrologRules(java.lang.String[] functorNames)
          Return a listing of the rules pertaining to a set of Prolog functors.
 boolean getServerKeep()
          Retrieve the value of the Server Keep flag.
 java.lang.String getServerVersion()
          Query version information from the AllegroGraph server
 int getTimeout()
          Retrieve the current timeout value for this connection.
 long[] getTimers()
          Get the cumulative timers from the server and reset them.
 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.
 java.lang.String reportMemoryUsage(java.lang.String to, java.lang.String tempDir)
          Return a string containing memory usage information from the server.
 boolean serverLevel(int level)
          Query the implementation level of the AllegroGraph server.
 void serverTimers(boolean onOff, boolean perStore)
          Manage cumulative timers for all clients.
 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 setChunkCountWarningLimit(long s)
          Set the indexing chunk count warning limit 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.
 void setDefaultSPOGICacheSize(long size)
          Modify the default size of the SPOGI cache in the current server.
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 initial 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:

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 acknowledgment 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()
Disable the interface. All remote references to AllegroGraph data are invalidated by this call. Any open triple stores are closed.


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

getChunkCountWarningLimit

public long getChunkCountWarningLimit()
                               throws AllegroGraphException
Query the indexing chunk count warning limit in the AllegroGraph server.

Returns:
the indexing chunk count warning limit.
Throws:
AllegroGraphException

setChunkCountWarningLimit

public void setChunkCountWarningLimit(long s)
                               throws AllegroGraphException
Set the indexing chunk count warning limit 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 500.

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 expression 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 programming 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 called code must not touch any triple stores that may be accessed by this or by other client applications. If the code needs to access a triple store, the AllegroGraph.evalInServer method must be called on a suitable instance.

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

getServerVersion

public java.lang.String getServerVersion()
                                  throws AllegroGraphException
Query version information from the AllegroGraph server

Returns:
a string containing version information
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.

serverTimers

public void serverTimers(boolean onOff,
                         boolean perStore)
                  throws AllegroGraphException
Manage cumulative timers for all clients.

Parameters:
onOff -
perStore - if true, collect per-store times for each active store instance in addition to cumulative times.
Throws:
AllegroGraphException

getTimers

public long[] getTimers()
                 throws AllegroGraphException
Get the cumulative timers from the server and reset them.

Returns:
An array of 5 numbers.
Throws:
AllegroGraphException

getNamespaces

public java.lang.String[] getNamespaces()
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 persistent.

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

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
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

stopServer

public int stopServer(boolean killNotStarted)
               throws java.io.IOException
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

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.


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 persistent 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.

getDefaultSPOGICacheSize

public long getDefaultSPOGICacheSize()
                              throws AllegroGraphException
Query the default size of the SPOGI cache in the current server.

Returns:
the default size of the SPOGI cache.
Throws:
AllegroGraphException

setDefaultSPOGICacheSize

public void setDefaultSPOGICacheSize(long size)
                              throws AllegroGraphException
Modify the default size of the SPOGI cache in the current server.

Parameters:
size - must be positive.

Note: The default size affects all triple stores created on this server by any application, and any user connected to this server. This method may be removed in future versions with more strict access controls.

Throws:
AllegroGraphException

getPrologFunctors

public java.lang.String[] getPrologFunctors()
                                     throws AllegroGraphException
Return a list of all the known Prolog functors.

Returns:
Each array element contains the name of one Prolog functor. Each name is displayed relative to the :db.agraph.user package.
Throws:
AllegroGraphException

getPrologFunctors

public java.lang.String[] getPrologFunctors(java.lang.String regExp)
                                     throws AllegroGraphException
Return a list of all the known Prolog functors that match a pattern.

Parameters:
regExp - a regular expression
Returns:
Each array element contains the name of one Prolog functor whose name matches the regExp. Each name is displayed relative to the :db.agraph.user package.
Throws:
AllegroGraphException

getPrologRules

public java.lang.String[] getPrologRules()
                                  throws AllegroGraphException
Return a listing of all the known Prolog rules. This list may contain many obscure rules known only to the AllegroGrapg internals.

Returns:
Each array element contains the rules pertaining to one functor.
Throws:
AllegroGraphException

getPrologRules

public java.lang.String getPrologRules(java.lang.String functorName)
                                throws AllegroGraphException
Return a listing of the rules pertaining to one Prolog functor.

Parameters:
functorName -
Returns:
a listing of the rules pertaining to this functor
Throws:
AllegroGraphException

getPrologRules

public java.lang.String[] getPrologRules(java.lang.String[] functorNames)
                                  throws AllegroGraphException
Return a listing of the rules pertaining to a set of Prolog functors.

Parameters:
functorNames -
Returns:
each array element is a listing of the rules pertaining to the corresponding functor. If there are no rules, the array element will be null.
Throws:
AllegroGraphException

addPrologRule

public void addPrologRule(java.lang.String ruleInString)
                   throws AllegroGraphException
Add one Prolog rule to the server.

Parameters:
ruleInString - the text of one rule.
Throws:
AllegroGraphException - Note that Prolog rules are global to the AllegroGraph server and therefore affect all users simultaneously.

addPrologFile

public void addPrologFile(java.lang.String nameOfFile)
                   throws AllegroGraphException
Add some Prolog rules to the server from a file visible to the server. The file can only contain Prolog rules, in-package forms and defpackage forms.

Parameters:
nameOfFile - the name of a file
Throws:
AllegroGraphException - Note that Prolog rules are global to the AllegroGraph server and therefore affect all users simultaneously.

addPrologRules

public void addPrologRules(java.lang.String[] arrayOfRules)
                    throws AllegroGraphException
Add some Prolog rules to the server from an array of rules. The array can only contain Prolog rules, in-package forms and defpackage forms.

Parameters:
arrayOfRules -
Throws:
AllegroGraphException - Note that Prolog rules are global to the AllegroGraph server and therefore affect all users simultaneously.

reportMemoryUsage

public java.lang.String reportMemoryUsage(java.lang.String to,
                                          java.lang.String tempDir)
                                   throws AllegroGraphException
Return a string containing memory usage information from the server.

Parameters:
to - if null, return a string containing the information; if the empty string, print the information to the server log file; any other string should contain the pathname of a file where the information will be written.
tempDir - if null, use the server default temporary directory; a string specifies a directory where the server can write a temporary file, or the full name of the file.
Returns:
a string, the contents may be useful to Franz customer support, or null if a file was specified.
Throws:
AllegroGraphException