1

Here you configure the connection to a CouchDB server. After entering a host address and a port (default values are 'localhost' and '5984') you can enter an existing database name or choose one from the drop down menu. The listener automatically tries to obtain a list of databases whenever the host field is modified. Username and password are optional. The 'heartbeat' field sets the time interval for the changes feed in ms (default is 5000). That means, after the connection has been established the listener receives a newline character from CouchDB every <heartbeat> milliseconds to keep the connection alive. Practically this value should have no influence on the behavior of the CouchDBListener, although a very small value will put more stress on the CPU and a too high value might lead to a timeout of the underlying C-sockets. For safety you might choose a value in the range of some seconds (1000 - 10000).

2

The big button 'Listen!' in the upper right corner tells the CouchDBListener to start a session, which means:

- the button's title is set to 'Stop!'

- all other controls on the user interface are disabled

- the selected control structures (see 2.) are uploaded

- a message document is uploaded

- a changes feed is started

- CouchDBListener will react to every change happening to the uploaded documents he only database in existence at the time of this writing is at UNC on the ORCA development machine. You will probably want to set up your own local database. Here’s how:

3

Here you can create a list of commands a client will be able to execute from CouchDB. The commands are displayed in the green table, which is initially empty. One command consists of a 'Label', an 'Object', a 'Selector', a default 'Value' and an 'Info' string. In order to create a command, you fill the form below the table and then click the 'Add' button.

'Label' serves as a unique key to the command and a client will use that key later to execute it. One label may not be used twice. If you try, the command is not added and an error message is logged to the status log below.

'Object' refers to the ORCA object you want to perform one of its methods. What you enter here is the objectID string (same as you pass to the 'find' function in ORCA script). For convenience all objects in the experiment and its subviews are listed in the dropdown menu. This list can be updated by clicking the 'update' button.

After selecting an object its methods are automatically listed in the dropdown menu of the 'Selector' field. You can either select one from the list or use the autocomplete feature to search for a method.

Note that if a selector requires arguments, you either have to enter them directly after the colon or you can enter '$1' for one argument per selector (like in the command label object). This means that the client can define this argument on CouchDB or, if not, the default value will be used.

In the 'Info' field you can provide information on the command for the client.

Having added at least one commmand, you might want to check if it executes properly. To do this, select the command in the table and click the 'Execute (test)' button. It runs the command once and logs a success message to the status log.

'Remove' removes the command from the table. 'Edit' also removes the command but displays its contents in the form, so you can make changes and add it again.

4

This is just a TextView that can be cleared by clicking the 'clear' button. Firstly it serves as a feedback for the ORCA user, so he is informed whenever a command is executed from CouchDB. Secondly it is useful for debugging in the development process. Thirdly it can be used for error messages, e.g. if a user wants to add command with an already existing label.

Future Features

The tabbed section lists “commands”, “scripts”, and “Parameters”. These sections are still under development.

Scripts

This section is not implemented yet. It will provide a client with the ability to run a set of scripts, that can be modified in CouchDB. This is much less restrictive than the commands section and should be used carefully.

Parameters

Also not implemented. This will contain a set of parameters for indirectly controlling processes in ORCA.

Some notes on the CouchDB interface

When you start a session, the table will be converted to a CouchDB document and uploaded. The document is named 'Commands' and contains a field 'keys' where all commands are listed. To execute a command, a client has to enter the label of the command into the field 'execute'. If the command includes a '$1' sign, he can also enter an argument into the field 'Value (optional)'. After the new 'Commands' document has been uploaded, the CouchDBListener is notified and queries the changed document from CouchDB. The content is checked and if 'execute' contains a valid command it is executed. After that a success message is uploaded back on CouchDB into the "Messages" document and the "Commands" document is reset to its initial state.

The "Messages" document contains a history of messages from the Listener. The fields are named after the date and time of the message (as obtained by [NSDate date]) and contain the messages as values.