The ILM Server is a program for running communication experiments implemented in java. It works by sending messages through sockets to a server. The messages are hash tables with strings for keys and any object as values. These allow clients to interact in an experiment though a series of rounds. Each round consists of several actions (or ‘stages’). The server has the following responsibilities:
Keep track of the connected clients.
Keep track of which experiments are currently running.
Keep track of which clients are part of which experiments.
Keep track of the status of each client.
Recieve messages from clients and send them on to other relevant clients.
Alert clients when all clients in the experiment are ready to proceed.
Maintain a set of globally accessible variables for each experiment.
Write output to files on the server.
The clients interact with the server to complete an experiment. The client side can be a bit confusing, since one class describes both the actions of the speaker and the listener. Both clients then run the same program, and the server assigns their roles. A variable ‘role’ keeps track of the current role of the particular client on the client side.
The client side must usually be initiated with more memory allocated to it than the default setting, in order to load all the stimuli (e.g. images). This is done using the VM argument -Xmx200m (sets for 200 megabytes). When running the program from the command line, use the prefix -J-Xmx200m.
The experiment proceeds as follows:
The host client connects to the server and selects an experiment file for the experiment.
The other clients connect to the server and join the experiment.
When a client presses ‘Start’, their status is set to READY.
When all clients are READY, the server sends a NEXTROUND message to all the clients.
On recieving a NEXTROUND message when the experiment has not begun, the client’s startExperiment() method is invoked.
On recieving a NEXTROUND message when the experiment has begun, the client’s nextRound().
When nextRound() is called, the following things happen:
- The stimulus number is incremented by 1
- The state variable is set to -1
- The round attributes are loaded
- If a break is specified, doBreak() is called.
- Otherwise, nextAction(null) is called
nextAction(Hashtable) diverts the action to the correct action sequence (testing(Hashtable) or training(Hashtable), depending on the round attributes).
Say that this round is a testing round. The nextAction(Hashtable) method is called at each action stage of the test round (and passes on to testing(Hashtable)). A switch construction within testing(Hashtable) activates the right action in the sequence. SPEAKER and LISTENER have the separate sequences. Each stage sets up the possibility of calling nextAction. In pseudo code (‘stage’ and ‘action’ are the same thing, but it’s labelled ‘stage’ in the code):
SPEAKER:
switch(action):
stage 1: display options
stage 2: recieve choice from speaker (me)
send choice to listener
wait
stage 3: recieve choice from listener
send round data to server for saving
do feedback
stage 4: change status to READY
LISTENER:
switch(action):
stage 1: wait
stage 2: recieve choice from speaker
display choice
display options
stage 3: recieve choice from listener (me)
send choice to speaker
do feedback
//(only speaker saves data)
stage 4: change status to READY
Note how the actions match up. When the cliens are in stage 1, the speaker can see the options and the listener is waiting. When the speaker chooses and option, this is sent to nextAction(Hashtable) with stage==2 (stage is a global variable, not passed to nextAction) and sends the option to the listener. When the listener receives the option, this triggers nextAction(Hashtable) with stage==2 and displays the choice and options. When the listener makes a choice, this is sent to nextAction(Hashtable) with stage==3. This sends the listener’s choice to the speaker and does some feedback. The message from the listener triggers nextAction(Hashtable) in the speaker with stage==3. The speaker sends the round results to the server to be saved, and does feedback. The feedback ends by activating nextAction(Hashtable) with stage==4 which changes the status of the client to READY (check the code – this may not be the case for all examples, some call feedback and then change the status in the same stage).
When the server detects that both clients are READY, it sets their statuses to BUSY and sends a NEXTROUND message which activates nextRound(), and the process starts over again.
The training method works in the same way.
The training and test methods are the ones that will usually need to be tweaked for a new experiment. You should do this in a new, extended class and over-ride the training() and testing() methods.
Examples:
There are some example extensions for reference. See the documentation for more details about each.
The ILMExperiment class is a very basic template that should be extended. It incudes methods for adding drawing inputs.
The example class DoubleFeedbackExperiment extends ILMExperiment to include a more flexible display (layered panes) and backgrounds.
The example class KCSExperiment extends DoubleFeedbackExperiment for a different experiment set up. This is the classic Kirby, Cornish & Smith (2007) experiment (1 player or communicative), with an added possibility of displaying the history of interactions.
The example class NamingGameExperiment is provided as an example of an experiment with more than 2 participants. It implements a human version of the Naming Game or Category game where many participants (default of 4) play games in pairs. Pairs rotate according to the experiment attributes.
It should be apparent looking at the different examples that each experiment requires radically different programming. This is why we didn’t attempt to make the structure of the experiments more manipulable outside the code.