Starting Experiments

Introduction

Starting experiments has a number of technical requirements that are detailed in this note. These requirements have to do with security and efficiency. In this document we describe how to start an experiment in a typical case. Typical case means that it is run on multiple nodes (the code of the experiment will migrate from one node to another), the nodes involved use a security manager and it contains user-written classes.

What classes to write?

The experiment has to contain at least two classes: an agent and a launcher class. It may contain any additional classes and resources.

A launcher is by definition any class that has a constructor which accepts exactly one parameter of type drm.core.Node and implements the interface java.lang.Runnable. When a node launches an experiment it in fact runs this class after constructing it with itself as a parameter. A launcher will normally launch agents using the interface provided by the node.

An agent is by definition any class that implements the drm.agentbase.IAgent interface. Normally it will extend a class from package drm.agents or any other class from a library that implements drm.agentbase.IAgent. An agent must be present even if it its empty ie if it does nothing else but calls the constructor of its superclass.

Where to put stuff?

Packaging the experiment has no restrictions. In principle, even if more experiments use the same package (or even class!) names, conflicts are not possible. However, it is a good practice to package the experiment into a uniquely named package.

There are more restrictions however on the physical location of the experiment at launching time:

The mobility of experiments started from a jar and from a directory are different.

The name of the experiment

Users should keep in mind that the resources associated with the experiment are identified by the experiment name (or job name, which means the same). The job name is the name returned by IAgent.getJob(). Launching agents with different job names within the same job (experiment) is technically possible but in fact it is equivalent to starting many experiments. This results in an unnecessary multiplication of the resources (the jar file) used by the experiment.

For the above reason only one experiment name should be used within the experiment, and this name should also be unique to avoid conflicts with other users' experiments. For example, names like "test", "experiment", "myexp" etc should be avoided. Appending a random number and username is a possible solution.

Launching

To launch an experiment on a DRM one has to have access to a node which is part of that DRM. There are two applications that can be used to run a node. The first is called drm.server.NakedNode and the second is drm.server.TestGUINode. When running these application they have to be properly configured to connect to the target DRM we want to launch to.

The actual launching can be scheduled in the configuration settings, or it can be done interactively (only in the case of drm.server.TestGUINode). In the first case the property "runClass" can be used (see configuration guide and configurable properties), in the second case the message dialog "File/run script" can be used. The value to be typed (or configured) has to identify the launcher class of the experiment (see above) and has the same syntax in both cases:

filename[!packagename.classname]
"filename" specifies the location of the experiment. It can be a jar file or a directory as described above. The classname of the launcher class can be optionally given. it has to be a full classname with full package specification. If the classname is not given then "Launch" is used (default package). Note that in the case of launching using the configuration possibilities (for NakedNode this is the only way) launching happens only after a delay to make sure that the node is connected to the DRM already.