Changes between Version 15 and Version 16 of Java API

Timestamp:

11/01/12 17:27:37 (12 years ago)

Author:

jorisborgdorff

Comment:

--

Java API

@@ -18 +18 @@
 The conduit is the mechanism in the MUSCLE runtime environment to send data. In the API, the {{{ConduitEntrance}}} and {{{ConduitExit}}} are accessible. The {{{ConduitEntrance}}} is used to send data, while the {{{ConduitExit}}} receives data. These entrances and exits, as we call them, can be accessed in two ways. Either they are created in the {{{addPortals()}}} method, or they are called on the fly in the code using the {{{out()}}} and {{{in()}}} methods.
 
-The [[doxygen:addPortals|addPortals()]] method is called before the submodel starts, so the exits and entrances are stored as fields of your class. The conduit exit and entrance uses Java Generics to define what kind of data will be received or sent, both in the field declaration and in the addExit or addEntrance method. This allows for compile-time and run-time checking of data that is sent over the conduit.
+The [[doxygen:muscle/core/kernel/RawInstance#addPortals|addPortals()]] method is called before the submodel starts, so the exits and entrances are stored as fields of your class. The conduit exit and entrance uses Java Generics to define what kind of data will be received or sent, both in the field declaration and in the addExit or addEntrance method. This allows for compile-time and run-time checking of data that is sent over the conduit.
 {{{
 ConduitExit<double[]> exitA;
@@ -92 +92 @@
 
 To get other types of parameters than strings, use {{{getPathProperty()}}} for a {{{File}}}, {{{getIntProperty()}}} for an {{{int}}}, {{{getDoubleProperty()}}} for a {{{double}}} and {{{getBoolProperty()}}} for a {{{boolean}}}.
+
+=== Input/output ===
+
+The philosophy of MUSCLE is that I/O should be done by the runtime system, and not directly coded, unless done with Terminals. Therefor, rather than writing to a file or reading from a file directly, we advise to use a {{{FileSource}}} or {{{FileSink}}} and attach that to a conduit from which you read. In this way, if you decide that the input should not come from a file but from another submodel, the code in the submodel does not have to change.
+
+Each submodel and terminal has its own temporary directory, which can be accessed with
+{{{
+File tmpPath = getTmpPath();
+}}}
+after which the path can be used to write files, for instance, {{{fileOut.dat}}}.
+{{{
+FileWriter fw = new FileWriter(new File(tmpPath, "fileOut.dat"));
+}}}
+
+In this path it is safe to write output in this directory, since this will only be associated to the current submodel in the current run. The path is always printed at the beginning and ending of the execution, and can be specified on the command line with the {{{--tmp-path}}} flag. Additional to the given temporary path, it will create the directory {{{hostname_date_time_pid}}} in which the results of the current run are stored. This way, a script can always contain the same temporary path but MUSCLE will use a new unique directory for each run.
+
+Reading files depends on what type of execution method is chosen for. Middleware such as QCG can usually stage in and out files for a single job. If files are staged in this fashion ({{{fileIn.dat}}} for example), and the {{{--tmp-path}}} points to the directory which contains the staged files, you can use
+{{{
+FileReader fr = new FileReader(new File(getTmpPath(), "../../fileIn.dat"));
+}}}
+as this will point to the {{{--tmp-path}}}.
+
+=== Printing and logging ===
+
+To keep track of what the different submodels are doing a logging facility is available. Simply call
+{{{
+log("some message");
+}}}
+and the message will be printed with timestamp and kernel name, and written to a log file {{{"kernelName.log"}}}, in the temporary path of the kernel. For more control over the log levels, a [[http://docs.oracle.com/javase/7/docs/api/java/util/logging/Level.html|Java log Level]] can be used:
+{{{
+log("some message", Level.SEVERE);
+}}}
+Finally, for full control over the logger and for error handling the logger can also be accessed directly.
+{{{
+try {
+        doSomethingDangerous();
+}
+catch (Exception ex) {
+        getLogger().log(Level.SEVERE, "error message", ex);
+}
+}}}
 
 == MUSCLE MML API ==