# 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 first restriction is that none of the classes that are not part of the standard DRM distribution are allowed to be in the classpath of the application which runs the node. To avoid violating this restriction, always start the node with a classpath which contains nothing else than the classes of the node, when developing experiments. This restriction will normally not be violated by average users, only by people who work on developing the DRM itself, and tend to have their experiments nearby...
- The second restriction is that the classes have to be either in one jar file, or under one directory.

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

- Experiments started from a jar are completely mobile, ie agents of that experiment can move to any other node without restriction.
- Experiments started from a directory behave differently. Agents from such experiments can move to another node only if on the filesystem of the computer that runs that node there is a directory with exactly the same name and content than the one used for starting. The possibility of starting from a directory is there to allow quick development and debugging only, and normally used only if all the nodes use the very same filesystem (ie if they were started on the same computer by the same user).

## 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.