Previous topic  Top  Next topic  Print this Topic
 

Socket Client API

 

OntoBroker provides a API for accessing a OntoBroker inference server. The new API replaces the classes:

EmbeddedQueryClient
EmbeddedCommandClient
QueryClient
CommandClient

The new API is more user-friendly and easier to understand. The new API is based on a new (binary) client/server socket protocol which allows faster streaming of result data.

Getting Started

The socket client API was designed so that you only need one OntoBroker library to add to your CLASSPATH. Just take the:

com.ontoprise.ontobroker.socketclient_6.0.0.jar

from the "plugins" directory of your installation and add it to your program.

Short Tutorial

The basic idea behind the API is that you need a connection object for all actions (queries and commands). Connection objects can be created via

OntoBrokerConnection conn = OntoBrokerConnectionManager.getConnection();

The connection manager automatically opens the connection and tries to connect to an inference server. If the user name and password are provided, the manager will authenticate with the server. Note that the various "getConnection()" methods allow arguments for specifying host, port, user name, password and socket timeout.

The most important API interfaces are

OntoBrokerConnectionManager (creates connections to an inference server)
OntoBrokerConnection (represents a connection to an inference server and allows you to execute queries and commands)
ServerException (is thrown when an error occurs on the server)
ClientQueryConsumer (allows the query results to be received as a stream)

When you have a connection you can execute:

queries and
commands

on the connection. Besides the simple forms of retrieving results (get results as String arrays) it is also possible to get the results via a callback handler:

OntoBrokerConnection conn = OntoBrokerConnectionManager.getConnection();

conn.executeQuery("?- ?X::?Y.", new PrintingConsumer());

 

The "PrintingConsumer" is a simple implementation of the callback interface:

private class PrintingConsumer implements ClientQueryConsumer {

 

     private int _resultArity;

 

     @Override

     public void receivedQueryFinished() {

         System.out.println("Done.");

     }

 

       @Override

       public void receivedQueryStarted(long queryKey, String[] variableNames) {

           System.out.println("Query started: " + queryKey);

           _resultArity = variableNames.length;

           for (int i=0; i<_resultArity; i++) {

               if (i != 0) {

                   System.out.print(", ");

               }

               System.out.print(variableNames[i]);

           }

           System.out.println();

       }

 

       @Override

       public void receivedTraceMessage(String msg) {

           System.out.println(msg);

       }

 

       @Override

       public void receivedTuple(ClientTerm[] tupleBuffer) {

           for (int i=0; i<_resultArity; i++) {

               if (i != 0) {

                   System.out.print(", ");

               }

               System.out.print(tupleBuffer[i]);

           }

           System.out.println();

       }

 

   }

The "ClientTerm" looks similar to the "Term" interface, but behaves differently:

It is not internalized. This means that two equal terms may not be identical.
The "toString()" method only supports ObjectLogic

Besides this, handling is similar to the KAON2 API. For example, you can call a "getType()" method which will return a "ClientDatatype" which allows you to check if the term is a IRI constant, a string constant, a list, ...