[[ux_xnjs-idb-applications]]
More on the IDB Application definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Simple application definitions and application arguments have already been
covered in the previous section. Here, more details are
presented.

==== Pre and post-commands

Sometimes it is useful to be able to execute one or several commands before or after the
execution of an application. For example, to add directories to the path, or 
perform some pre-processing. The IDB allows to specify these using the 
PreCommand and PostCommand tags.

For example

--------------------------------------
  <idb:IDBApplication>
    <idb:ApplicationName>java</idb:ApplicationName>
    <idb:ApplicationVersion>1.5.0</idb:ApplicationVersion>
    <jsdl:POSIXApplication xmlns:jsdl="http://schemas.ggf.org/jsdl/2005/11/jsdl-posix">
      <jsdl:Executable>/usr/bin/java</jsdl:Executable>
      <jsdl:Argument>-cp$CLASSPATH?</jsdl:Argument>
      <!-- other args omitted for clarity -->
    </jsdl:POSIXApplication>
    <idb:PreCommand>PATH=$PATH:/opt/myapp/bin ; export PATH</idb:PreCommand>
    <idb:PreCommand>/opt/example/aquire_license</idb:PreCommand>
    <idb:PostCommand>/opt/example/release_license</idb:PostCommand>
   </idb:IDBApplication>
-------------------------------------

These commands will be executed as part of the user's job script.

==== Interactive execution when using a batch system

If an application should not be submitted to the batch system, but be run on 
the login node (i.e. interactively), a flag in the IDB can be set:

-------------------------------------
  <idb:IDBApplication>
    <idb:ApplicationName>SomeApp</idb:ApplicationName>
    <idb:ApplicationVersion>1.0</idb:ApplicationVersion>
    
    <!-- instructs TSI to run the application interactively -->
    <idb:PreferInteractive>true</idb:PreferInteractive>
    
    <jsdl:POSIXApplication xmlns:jsdl="http://schemas.ggf.org/jsdl/2005/11/jsdl-posix">
      <!-- other args omitted for clarity -->
    </jsdl:POSIXApplication>
   </idb:IDBApplication>
--------------------------------------

[NOTE]
===============
This should only be used for very short-running tasks, since UNICORE cannot track the
status of such a task. It is simply forked by the TSI, and UNICORE will just assume it is finished after
a short while.
===============

=== Application metadata (simple)

For client components it is very useful to have a description of an application in terms
of its arguments. This allows for example the "Generic" GridBean in the UNICORE Rich client to
automatically build a nice GUI for the application.

You can optionally attach metadata to an applications arguments.
  
-------------
  <jsdl:Argument Description="Verbose Execution"
                 Type="boolean" 
                 ValidValues="true false"
   		 DependsOn="..."
                 Excludes="..."
                 IsEnabled="false"
                 IsMandatory="false">+v$VERBOSE?</jsdl:Argument>
-------------

Some metadata is inferred automatically, such as the argument name (+VERBOSE+ in the 
example above).
  
The meaning of the attributes should be fairly obvious.
  
 - the +Description+ attribute contains a human-readable description of the argument
 
 - the +Type+ attribute can have the values "string", "boolean", "int", "double", 
"filename" or "choice". In the case of "choice", the +ValidValues+ attribute is used 
to specify the list of valid values. The type +filename+ is used to specify that 
this is an input file for the application, allowing clients to enable special actions 
for this.

 - The +MimeType+ attribute allows to specify the mime-types of an input or output 
file as a comma-separated list. This can be used by smart clients, for example to 
check the viability of workflows.

 - The +ValidValues+ attribute is used to limit the range of valid values, depending 
on the +Type+ of the argument. The processing of this attribute is client-dependent. 
The UNICORE Rich Client supports intervals for the numeric types, 
and Java regular expressions for the string types.

 - +DependsOn+ and +Excludes+ are space-separated lists of argument names to control dependencies. 
For example, a "VERBOSE and a "QUIET" attribute should exclude each other.

 - +IsMandatory+ (values: true or false) specifies if a parameter MUST be provided.
 
 - +IsEnabled+  (values: true or false) is intended to tell clients that the parameter 
should initially be enabled in the GUI.

==== Application metadata (complex)

You can also add metadata as XML to the IDB entry, which allows you to add your custom metadata:

The XML schema can be found online at http://unicore.svn.sourceforge.net/viewvc/unicore/jsdl-xmlbeans/trunk/src/main/schema/jsdl-unicore.xsd
   
Currently the XML metadata only encompass argument metadata, similar to the "simple" metadata 
described above. However, custom metadata can be added in case an application requires it.

Here is a simple example.
  
--------------------------------------
  <idb:IDBApplication>
    <idb:ApplicationName>SomeApp</idb:ApplicationName>
    <idb:ApplicationVersion>1.0</idb:ApplicationVersion>
    
    <!-- metadata -->
    <u6:Metadata xmlns:u6="http://www.unicore.eu/unicore/jsdl-extensions">
      <!-- example argument-->
      <u6:Argument>
        <u6:Name>PRECISION</u6:Name>
        <u6:ArgumentMetadata>
          <u6:Type>choice</u6:Type>
          <u6:Description>Precision of the computation</u6:Description>
          <u6:ValidValue>Lax</u6:ValidValue>
          <u6:ValidValue>Reasonable</u6:ValidValue>
          <u6:ValidValue>Precise</u6:ValidValue>
          <u6:ValidValue>Pedantic</u6:ValidValue>
          <u6:IsMandatory>true</u6:IsMandatory>
        </u6:ArgumentMetadata>
      </u6:Argument>
      <!-- any custom XML can be added as well -->
      <!-- ... -->
    </u6:Metadata>
   </idb:IDBApplication>
-------------------------------------
   
The XML supports the Type, Description, MimeType, IsMandatory, DependsOn, Excludes and ValidValue 
elements, with the same semantics as described above.
 
==== Per-application node requirements

When an application requires a special hardware or software which is available only on a subset of cluster
nodes, node filtering must be applied. It is typically solved by marking the nodes with a special label,
named node property. In application description, the required node properties might be added as follows:

--------------------------------------
  <idb:IDBApplication>
    <idb:ApplicationName>SOME_MPI_APP</idb:ApplicationName>
    <idb:ApplicationVersion>1.0</idb:ApplicationVersion>
    <jsdl:POSIXApplication xmlns:jsdl="http://schemas.ggf.org/jsdl/2005/11/jsdl-posix">
      <jsdl:Executable>/opt/some_mpi_app/binary</jsdl:Executable>
    </jsdl:POSIXApplication>
    <!-- other elements as pre/post commands -->
    <idb:BSSNodesFilter>infiniband</idb:BSSNodesFilter>
    <idb:BSSNodesFilter>gpu</idb:BSSNodesFilter>
   </idb:IDBApplication>
-------------------------------------
 
With such configuration the SOME_MPI_APP application will be executed only on nodes having both the
+infiniband+ and +gpu+ properties.

[NOTE]
===============
Nodes properties will not work with the Java TSI, and need not to be supported for all kinds of batch systems
when using the legacy TSI. Please refer to the TSI documentation for details. 
===============
