# Lisp Client API to Remote AllegroGraph, version 3.3

# Table of Contents

## Introduction

## Starting the Server

## Connecting to the Server

## Using a Remote Triple Store

## Reference

### Managing a Connection

### Data Structures and Classes

## Indices

### Class index

### Function index

## Introduction

The AllegroGraph client API is yet another view of the triple store for a Lisp application. The triple store in this case is accessed through a server that runs in another process and may be located on a separate host located far from the client. The same server is used by Lisp and Java clients.

## Starting the Server

The server is started in Lisp with a call to start-ag-server. We also distribute a stand-alone server executable described in Java Tutorial.

    > (start-ag-server :port 4567)
    #<db.agraph.dlink::server-data-port *:4567 -1 @ #x12abe14a>
    4567

## Connecting to the Server

Before any client interaction with a triple store, the client application must make a connection to the server. Note that all of the functions in the client API are exported from the `db.agraph.client` package:

    > (setq agc (db.agraph.client:make-allegrograph-connection
                  :port 4567))
    #<db.agraph.client:allegrograph-connection
        nil:4567 not connected @#x12eb6fc2>

    > (db.agraph.client:enable-connection agc)
    #<db.agraph.client:allegrograph-connection
        nil:4567 enabled @#x12eb6fc2>

The first expression creates a connection instance but the instance is still disabled, but initialized with default values. If necessary, the client-slot method may be used to modify any settings that must differ from the defaults. The third expression actually makes the connection and signals an error if the connection attempt fails.

The application must save the connection instance since it is a required argument to subsequent operations.

Once you have a connection to the server established, you can connect to existing triple stores and create new ones using the regular Lisp API (see the reference guide). The only difference is the addition of some new keyword arguments:

    > (setq ts (create-triple-store
                   "/tmp/oldstore"
                   :connection agc
                   :triple-store-class 'remote-triple-store))

## Using a Remote Triple Store

Once a remote triple store is created, it is used like any other triple store. For example:

    > (load-ntriples
        "/data/agraph/sample-inputs/wilburwine.ntriples")
    2012
    #(0 0 0 0 248 75 113 71 0 0 0 31)

    > (triple-count)

    > user> (setf cursor (get-triples :p !rdf:type))
    #<db.agraph::remote-cursor
      #<remote-triple-store
        nil:4567//tmp/oldstore, #<allegrograph-client>,
        open @ #x12d07a22>
      @ #x130d9652>
    t

    > (count-cursor cursor)
    658

Note that the call to `get-triples` returns a `remote-cursor` instead of a regular cursor. Like a remote-triple-store, a `remote-cursor` uses the same API as regular cursors.

## Reference

### Managing a Connection

X client-chunk-size agc &optional value
function

Method (allegrograph-connection)

Query or set the chunk size used during indexing.

Note that this is a global value that affects all triple stores accessed on a given server.

X client-expected-resources agc &optional value
function

Method (allegrograph-connection)

Query or set the default number of unique resources in each triple store.

- value - If this argument is omitted or nil, return the current value in the server. If this argument is a positive integer, it specifies a new value.

This default value is used when a new triple store is created. It determines the initial size of some internal tables.

X client-namespaces agc &rest args &key clear register
function

Method (allegrograph-connection): agc &key register

Without the keyword arguments, return a list of current default namespace definitions associated with this connection. This is an alternating list of prefix string and namespace onnect-string.

If the clear keyword argument is non-nil, the current definitions are erased.

If the register keyword argument is specified, the default namespace definitions are updated. The argument must be an alternating list of prefix strings and namespace string. If the namespace string is nil or the empty string, that entry is deleted.

This method has no effect on the existing triple stores or on the server.

COMPATIBILITY NOTE: In earlier versions of AllegroGraph, this method modifed the global namespace table in the AllegroGraph server.

X client-store-exists agc name &key directory
function

Method (allegrograph-connection t)

Return t if the specifed triple store is found.

- name - the name of the triple store
- directory - a string that specifies the pathname of the directory where the remote triple store is or will be located. The pathname is used in the server process environment (not the client's).

X client-version ag &key all
function

Method (t)

Query the version.

X disable-connection agc &key (close-all t)
function

Method ((eql :all))

Disable all connections.

Method (allegrograph-connection)

Disable a connection. All allegrograph-client instances opened from this connection are invalidated by this call. The close-all argument should be specified as nil only when the application is such that any allegrograph-client instances opened from this connection will never be used again.

X enable-connection agc
function

Method (allegrograph-connection)

Enable a connection instance by connecting to the server. If the connection is already enabled return nil. If the connection is established during the call, return the allegrograph-connection instance.

The parameters of the connection are pre-set in the slots of the allegrograph-connection instance.

X eval-in-server agc expression
function

Method (allegrograph-client t)

Like the method specialized on allegrograph-connection, but adds a binding of `*db*` to the environment. The variable is bound to the triple store identified by the first argument.

Method (allegrograph-connection t)

Evaluate an expression in the AllegroGraph server and return the values. The values must be suitable for restricted serialization: numbers, strings, UPIs, or sequences of these.

- expression - this argument should be a string containing an expression to be evaluated.

The server environment has a separate binding of `*package*` and `*readtable*`. The initial binding of `*package*` is the `db.agraph.user` package. The initial binding of `*readtable*` is the value of `(copy-readtable)`.

X make-allegrograph-connection &rest args &key port host poll-count poll-interval enable debug command server-keep default-command default-debug default-host default-poll-count default-poll-interval default-port default-server-keep
function

Create and return an instance of allegrograph-connection. This instance must be used when accessing the server.

The enable argument, when non-nil, causes the connection to be enabled. Otherwise the enable-connection method must be called before the connection can be used.

The port argument specifies the port number where the AllegroGraph server is listening.

The host argument specifies the name or IP-address of the host where the AllegroGraph server is listening.

The poll-count and poll-interval arguments specify how persistently an enable call should try to connect. The poll-interval argument specifies the number of seconds to wait between connection attempts.

The other keyword arguments initialize slots in the instance. The default- arguments modify the default values for subsequent calls to make-allegrograph-connection.

X query-connection agc
function

Method (allegrograph-connection)

Query the state of a connection. Return one or two value:

- `:idle` - the connection is ready. A new client call will be serviced immediately.

- `:busy` - the connection is ready but actively servicing a client call. A new client call will be queued adn serviced in turn.

- `nil` - the connection is not enabled. A second value provides more detail:

  - `:not-connected` - the connection has never been enabled.
  - `:closed` - the connection was enabled and then was disabled.

X server-level agc test-level
function

Method (allegrograph-connection)

Query the implementation level of the server. At times, we may publish integers that identify the availability of certain features. Return non-nil if the server level is at or above the specified integer.

X server-trace agc &optional onoff
function

Method (allegrograph-client)

Turn trace messages in the server on and off. With no keyword argument, query the state of tracing in the server. Tracing applies only to calls that involve this triple store.

Method (allegrograph-connection)

Turn trace messages in the server on and off. With no keyword argument, query the state of tracing in the server. Tracing applies to all calls to the server through this or any other connection.

X stop-server agc
function

Method ()

Terminate the AllegroGraph server.

### Data Structures and Classes

X allegrograph-connection
class

This class implements a connection to the AllegroGraph server. Class and instance slots specify how the connection is made and how it should behave. All the slots are accessed with the `client-slot` method.

One connection can access any number of triple stores.

The `client-slot` function can be used to query and update the following slots:

- `default-command` - not implemented
- `default-debug` - not implemented
- `default-host` - default host name for all connections
- `default-poll-count` - default poll count for all connections
- `default-poll-interval` - default poll interval for all connections
- `default-port` - default port number for all connections
- `default-server-keep` - not implemented
- `debug` - not implemented
- `host` - host name for this connections
- `poll-count` - poll count for this connections
- `poll-interval` - poll interval for this connections
- `port` - port number for this connections
- `server-keep` - not implemented
- `verbose` - not implemented

X client-slot x name
function

Methods of this generic function allow query or update of certain slots of the object x. The name argument may be a string or a symbol in any package. If the named slot is not accessible, an error is signalled.

Some slots are maintained lazily and may not have a value when queried. In that case the result is `nil`. The function `get-slots` may be called to force an update of a lazy slot. Most updates require a round-trip to the AllegroGraph server.

X get-slot x name
function
Methods of this generic function allow query of certain slots and make sure that the slot contains a valid value. The name argument may be a string or a symbol in any package. If the named slot is not accessible, an error is signalled.

## Indices

### Class index

- allegrograph-connection

### Function index

- client-chunk-size
- client-expected-resources
- client-namespaces
- client-slot
- client-store-exists
- client-version
- disable-connection
- enable-connection
- eval-in-server
- get-slot
- make-allegrograph-connection
- query-connection
- server-level
- server-trace
- stop-server