Class SocketConnector

  • All Implemented Interfaces:
    java.lang.Runnable, IConnector

    public class SocketConnector
    extends java.lang.Object
    implements IConnector, java.lang.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