Component API and Resource Specification

Component Level Metadata

Component meta data is attached to components at the Java source level. A special style (called javadoc style) for comments is being used to embed meta data sections which are preceding the component class and the component attributes.

/**
 * <meta data for components or attributes>
 */
<component or attribute declaration>

The meta data is embedded into /** */, which is a comment to the Java Programming Language but can be recognized by other tools. It is important to note, that the to asterisks at the beginning are required to make the meta data show up for these tools.

Specific meta data starts with a special key @oms. concatenated with the meta data name. It is followed by the meta data value separated by space. The prefix @oms is used to introduce a name space for OMS related meta data. The <key> selects categories for different kinds of meta data. The key is followed by the meta data value.

@oms.<key>  <value>

In general meta data for components and attributes has the following structure.

/** 
 * <English Name>.
 * <English description>
 *
 * @oms.<key_1> <value_1>
 * ...
 * @oms.<key_n> <value_n>
 */
<component or attribute declaration>

The first sentence is usually the component name in English; followed by a description also in English. Other OMS related keys and values are following. After the meta data section the component or attribute definition follows.

The meta data section for the PET example is shown in the Example below “Component meta data for the PET example”. Note that meta data entries may span over multiple lines, but get recognized as one entry.

/** Soil moisture accounting Component.
 *
 * This module does soil moisture accounting, including addition of 
 * infiltration, computation of actual evapotranspiration, and seepage 
 * to subsurface and groundwater reservoirs.
 *
 * @oms.category        hydrology
 * @oms.version         1.3
 * @oms.created         July 1992
 * @oms.url             http://oms.ars.usda.gov/svn/mod/trunk/smbal.java
 * @oms.doc             http://wwwbrr.cr.usgs.gov/projects/SW_precip_runoff/mms/html/smbal_prms.html
 * @oms.author          G. H. Leavesley, george@usgs.gov
 * @oms.reference       Zahner, R., 1967, Refinement in empirical functions for 
 *                      realistic soil-moisture regimes  under forest cover, 
 *                      in Sopper, W. E., and Lull, H. W., eds., 
 *                      International Symposium of Forest Hydrology: New York, Pergamon Press, 
 *                      p. 261-274 
 */
class SoilMoistureBalance {
   ...
}

Example: Component meta data for the PET example

Localization

If the name or the description should be localized, the following notation should be used:

@oms.name_<language>_<country>_<variant>   <loc_name>

The language argument is a valid ISO Language Code. These codes are the lower-case, two-letter codes as defined by ISO-639. You can find a full list of these codes at a number of sites (http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt). The country argument is a valid ISO Country Code. These codes are the upper-case, two-letter codes as defined by ISO-3166 (http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html). The variant code is vendor specific. Usually such a variant is oriented towards architectures, browsers, or operating systems. Examples are (WIN, MAC, or POSIX).

As an example for a localized component name is

@oms.name_de_DE  Interzeption

Component Meta data Reference

Each component class level or attribute level meta data. Class level meta data contains information about the component as a whole. In general class level meta data helps categorizing the component. The table below shows component meta data.

Multiplicity refers to the minimum and maximum number of occurrences of an entry. For example 0..n means that an entry is not required to be present and or may be there in an arbitrary number.

Attributes

Attributes are qualified by (i) name, (ii) type, and (iii) meta data. Meta data is optional, name and type are required. The name of an attribute is an alphanumerical identifier, the type is defined in the OMS API. Technically an Attribute consists of four parts as shown in Example “Attribute Definition Example (potet)”.

    /** Potential ET.                                               (1)
     *  @oms.access write
     *  @oms.unit   mm
     */
    public void setPotET(Attribute.Double potET) {      (2)
        this.potET = potET;
    }
    
    public Attribute.Double getPotET() {            
        return potET;
    }
   private Attribute.Double potET;                         (3)

(1) Attribute meta data.

The Attribute meta data proceedes the attribute declaration. It uses meta data declarations as specified in Table 4.4, “Attribute Meta Data”. In the given example the meta data annotates the potET attribute to be written to by this component and having the unit mm.

(2) Attribute setter/getter.

There are always two methods required for each attribute, a getter and a setter. The getter returns the attribute, the setter assigns an external attribute to the component. The code is very simple and usually follows the pattern shown in this example. Both methods have to be public as required by the java beans standard.

(3) Attribute declaration.

The attribute is declared as a private field in a component. It does not have to be public since there are getter and setter methods to provide external access to the attribute. The attribute type is one out of several types provided from the OMS core API. These types are introduced in Section 1.2.1, “Attribute Types”

Attribute Types

Attribute types are specify a numerical or nonnumerical type of an attribute for a component. The Attribute interface is part of the OMS Core API.

The Notation Attribute.Double refers to the Interface 'Attribute' which has a so called inner interface 'Double'. All Types supported in OMS are all interfaces within 'Attribute'.

Component Interfaces

The main purpose of a (scientific) component is to perform some one or a set of equations. In the potential evapotranspiration is computed. The implementation logic was realized in a Component method called execute(). The component was required to offer this method because it is implementing the Executable interface.

The code below shows the usage if interfaces in OMS components. It uses the OMS API Interface Executable.

public interface Executable {   
    public void execute() throws Exception;
}

public class PET implements Executable {  

   public void execute() throws Exception { 
      // execute implementation to perform
      // PET computation.
   }
}

• The Executable Interface is declared here. In such a declaration, the class keyword is replaced with the interface keyword. Also, the methods specified in the interface do not have an implementation body. The Interface declares the execute() as the only method in this interface
• The PET class declaration list the Interface Executable after the keyword implements. This means that PET has to provide an implementation for the execute() method being specified in Executable. Not implementing a method required by an interface would lead to a compile error. If there are multiple interfaces implemented, they have to be separated by comma. The Interface name must be either fully qualified (package name + class name) or the class just imports the interface by using the import statement before.
• The method signature ( name, return type, argument list) of the execute method specified in the interface Executable and implemented in PET have to match.

What is the purpose having an interface such as Executable, when a component is providing the implementation anyway ?

Interfaces are specifying behavioral access points to components. In general an interface is a collection of operations that are used to specify a service of a component. If a component is 'tagged' by implementing a certain interface, OMS can use such information to make some decisions how to handle this component. For example if it is implementing the Viewable interface, OMS will show it in a user interface and allow for user interaction.

The Component behavior is defined by interfaces offered by the OMS Core API package org.oms.model.components. In order to cover different aspects, components can implement different interfaces to fit their needs. For example if a component is handling its internal state and it implemented partly in a native language, it will implement the Runnable, Stateful and Native interface. The benefit of such an approach is

• Component can be customized regarding their behavior. The overall component behavior is the sum of all implemented interfaces.
• Any class, even in an existing hierarchy can become an OMS component just by OMS interface adaptation. There is no need to subclass from an existing OMS classes.

OMS handles a certain set of interfaces in order to service different semantical aspects of the component behavior. All the Interfaces are defined in the package org.oms.model.

Executable

Interface for defining the components processing logic

Stateful

Interface that offers internal state management for the component

Native

Interface to support native code.

Visualizable

Interface which makes the component visualizable

Component Interface 'Executable'

The Executable Interface provides the ability to execute a component. Probably almost all OMS components have this interface implemented. As the execute() method's signature indicates, that the execute method may throw an Exception.

package org.oms.model.components;
/** Executable is the base interface for all OMS components. At the minimum, the
 * component must provide some executable functionality.
 *
 * @author  Olaf David
 */
public interface Executable {
    
    /** Execute this component.
     * @throws Any type of Exception which may arise.
     */
    void execute() throws Exception
}

Whenever a component gets executed, this method will be called. If an Exception occurs, OMS will catch it and propagate it to the OMS runtime user interface. The example given below shows the implementation of execute() to find the maximum of a values in a DoubleArray Attribute.

Example:

import org.oms.model.components.Executable;

public class AComponent implements Executable

    Attribute.DoubleArray values;
    Attribute.Double max;

    public void execute() throws Exception  {
       if (values.getLength()==0)
         throw new IllegalArgumentException("No values");
       double m = values.getValue(0);
       for(int i=1; i< values.length(); i++) {
           if (values.getValue(i) > m) m = values.getValue(i);
       }
       max.setValue(m);
    }
}