Class SocketConnector

java.lang.Object
laas.openrobots.ontology.connectors.SocketConnector
All Implemented Interfaces:
Runnable, IConnector

public class SocketConnector extends Object implements IConnector, Runnable
Implements a socket interface to oro-server RPC methods.

The protocol is ASCII-based (ie, you can connect to the server with telnet to test everything).

Requests

The general structure of a request to the server is:
 method_name
 [parameter1]
 [parameter2]
 [...]
 #end#
 
parameters can be either:
  • strings (quotes are not necessary, and are removed if present),
  • integers (strings made only of numbers),
  • floats (strings made of numbers with a dot somewhere),
  • booleans (strings equal to true or false, case insensitive),
  • (ordered) lists or (unordered) sets of strings, with this structure: [val1, val2, ..., valn]. If strings contain commas, they must be (single or doubled) quoted.
  • map of (key, value) pairs of strings, with this structure: {key1:val1, key2:val2, ...}. If strings (be keys or values) contain commas, they must be (single or doubled) quoted.
Please note that collections of collections are not supported.

Responses

The server response has this structure if the request succeeded:
 ok
 [return_value]
 #end#
 

And this structure in case of failure:
 error
 [name of the exception, if available]
 [human-readable error message - that *may* spend over several lines]
 #end#
 

Events

If an event has been registered (cf EventModule#registerEvent(String, String, Set, IEventConsumer)), the server may send the following type of message when the event it triggered.
 event
 [event_id]
 [event_return_value]
 #end#
 
The event_id will match the id returned at event registration. The return values depend on the type of event. Details are provided on the IWatcher.EventType page.

Some examples

You can test this example by directly connecting to the server with a tool like telnet.

Retrieving a human-friendly list of available methods on the server

 > help
 

Retrieving a machine-friendly list of available methods on the server

 > listMethods
 > #end#
 

Adding facts to the knowledge base

 > add
 > [human rdf:type Human, human rdfs:label "Ramses", myself sees Ramses]
 > #end#
 

Retrieving facts

This command should return the list of humans the robot currently sees.
 > find
 > [?humans rdf:type Human, myself sees ?humans]
 > #end#
 

Registering an event

The example below registers an trigger upon new instances of humans.
 > registerEvent
 > new_instance //event type
 > on_true              //triggering type
 > [Human]
 > #end#
 
The server answer ok, with a unique ID bound to this so-called "event watcher"
 > ok
 > 4565-4587995-112355-21446
 > #end#
 
If a new human appears in the ontology, the server send this kind of notification
 > event
 > 4565-4587995-112355-21446
 > [ramses]
 > #end#
 
Please refer to IWatcher.EventType page for the list of event types and IWatcher.TriggeringType for the list of ways the trigger an event.
Since:
0.6.0