Building a Client Library for Construct at Construct

This post contains a guide for building a data port and query service client proxy for Construct in a language of your choice. The purpose of proxy objects is to disguise as much as possible the distributed nature of Construct from the developer — taking care of locating and accessing Construct services over the network.

The following sections describe (at a high level) the steps involved in building proxies for the data port and query service. If you plan to implement a client proxy, take a look at the Java, Python, and Ruby code in the codebase for examples. See the Construct protocols on the tutorial page for protocol details.

Layer 1: Finding and Connecting to Services - Connect to the Construct Bonjour Proxy

The Construct Bonjour Proxy maintains a list of active Construct instances that it can see. Assuming you have set it up on your machine, it will be running on port 3826. Connect to this port to be sent a list of service descriptors.

Layer 2: Connecting to a Service

Assuming that some services are present, pseudocode for this process is a follows:

iterate through each available service instance
- if the service descriptor contains the desired service, attempt to create a connection to it
- if successful, return the connection. If not, continue the iteration

If no suitable services are available, you may wish to throw an exception.

Layer 3: Wrapping the socket in an appropriate client object

The final step is to provide code that can be wrapped round the socket to handle interaction with the services and client. Code is required for each Construct service that the client requires to access (the data port and the query service).

Retain a reference to the socket as it can be reused for multiple interactions. You should only need to obtain a new set of service descriptors when your connection fails.

Below are examples of the sort of functionality you may wish to provide in your proxy:

The Data Port proxy

Methods:

Constructor (boolean scan_localhost_only)
- start the process to scan for Construct instances
add(String rdf)
- Take RDF statement(s) in String format
- Create a connection to a data port (see Layer 2)
- Format the data using the correct protocol (see Construct protocols tutorial) and send it to the data port
- Get the response from the data port (using the correct protocol) and return true/false to indicate successful submission
add(String rdf, long expiryTime)
- As above, but add the expiry time to the end of concatenated N-Triple string
add(LanguageSpecificConstruct model)
- Convert the (Jena, rdflib etc.) model to N-Triples and continue as add(String rdf)
add(Model model, long expiryTime)
- Convert the (Jena, rdflib etc.) model to N-Triples and continue as add(String rdf, long expiryTime)
Destructor
- stop the process scanning for Construct instances

The Query Service proxy

Methods:

Constructor (boolean scan_localhost_only)
- start the process to scan for Construct instances
query(String sparqlQuery)
- Takes in a String containing a SPARQL query
- Create a connection to the query service (see Layer 2), format the query using the correct protocol (see Construct protocols tutorial page) and send the query.
- Get the response from the data port (using the correct protocol)
- If an error occurred, return null
- If successful, transform the RDF into the appropriate language specific construct representing a SPARQL result set (Jena, rdflib etc.)
Destructor
- stop the process scanning for Construct instances