HOWTO use the API

The definition API is located in the package client.data and can be used without the client GUI.
In order to define some studies perform the following steps:


1. Define your code packages. Create package objects with 

public Package(Connection definitions, String name, String version, String architecture, String url) 

and call performDbInsert() on them. You can try to upload a local file to the specified URL with
upload(String localFile), but Java doesn't provide good support for uploading files.


2. Create a study. The most convenient constructor is the one defining all the parameters:

public Study(Connection db, String name, String version, String command)

You can then add some of your previously defined packages to the study:

StudyPackages pkgs = study.getPackages();
pkgs.put(pkgs.new Package("name", "version", "path on simulating host");

"put" will prevent you from adding multiple versions of the same package or putting the same package
at multiple paths. If you really want to do that you can use "add" instead.
When you're done with the study you can call performDbIsert to write it into the database. You
can also do that later, as it is a recursive operation and will also insert your groups and simulations
Be careful though; if you call performDbInsert multiple times, multiple entries will be created. If you
want to avoid that, use performDbUpdate.

3. Create groups. If you don't want to generate simulation from parameter ranges you're free to group
the simulations by any criteria. If you want to generate them automatically it's highly advised not
to mix manually created and generated simulations.
For adding Groups you can use "add" on the Study and the Group constructors, for example

public Group(Connection db, String name, int studyId)

Use performDbInsert and performDbUpdate to write your changes to the database.
For each group parameter ranges, input and output files can be defined. The procedure
is similar as wit StudyPackages. For example for an output file that shall be fetched:

GroupResultsFiles files = group.getResultsFiles();
files.put(files.new File("/tmp/result"));

For configuration files you need to provide the path the file shall be copied to on the simulating
host and a local path from where the file shall be fetched when inserting or updating the database
record. The file is loaded into the database (simulation.in_files) as soon as you insert or update 
the group. After that, if you don't touch the File object's contents the new record is used. You can
clone File objects with their copy-constructor in order to use the same configuration file with multiple groups but without 
keeping multiple copies in the database.
String and Numeric Parameters aren't evaluated yet. Only manual adding of Simulations is supported

4. Create simulations and add them to groups

In order to create empty simulations use the following constructor:

public Simulation(Connection definitions) 

Inside of groups simulations can be managed with get/add/remove as usual. Creating new Parameters is done in 
the following way:

simulation.put(simulation.new Parameter(name, value));

With this method, remove(String name) and get(String name) the parameters can be managed inside simulations.
As soon as you commit a simulation to the database it will be visible to the wrappers associated with the database.
So be sure to have all parameters, files and packages configured correctly before writing a simulation to the 
database. Otherwise the simulation might start before the definition is finished. Committing to the database is secured
by a transaction so you don't need to insert the simulations as last items, but still this might be a good idea if you want
to be really sure that no corruption occurs.





