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 a 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
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.
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.
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.
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).
Method (t)
Query the version.
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.
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.
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).
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 other keyword arguments initialize slots in the instance.
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.
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.
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.
Method ()
Terminate the AllegroGraph server.
Data Structures and Classes
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 implementeddefault-debug- not implementeddefault-host- default host name for all connectionsdefault-poll-count- default poll count for all connectionsdefault-poll-interval- default poll interval for all connectionsdefault-port- default port number for all connectionsdefault-server-keep- not implementeddebug- not implementedhost- host name for this connectionspoll-count- poll count for this connectionspoll-interval- poll interval for this connectionsport- port number for this connectionsserver-keep- not implementedverbose- not implemented
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.
