Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.franz.agbase
Class AllegroGraphConnection

    java.lang.Object
      AGConnInternals
          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:
  - 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 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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD