Component Development

• A Component Creation Wizard helps creating Java new components.
• A Native Component creation Wizard supports the adaptation of native sources as OMS components.
• An Attribute editor provides GUI based editing of attribute and component meta data.

The next section introduces a conceptual basic of simulation components, then an example of a component which computes potential evapotranspration is developed using several tools.

OMS Components

A component representing a certain conceptual function in a simulation is the foundation for each model. A hydrological model for example usually needs components for handling input/output, has components representing processes of a hydrological system such as precipitation, interception and runoff, and has to realize general data processing functions such as reading climate data or parameter sets. The key for a proper model design based on components is a clean "separation of concerns" in a model. Components for a model hosted in OMS have to provide a certain aspect What qualifies a part of a model to become a component?

1. A component has a certain and mostly one conceptual function in a model. It represents a physical process, a management action, a data gathering part, or the presentation of results to the user interface. Such functions need to be identified and separated from each other. Each of these aspects will result in a component.
   
   
2. An identified component can be fully described regarding to its function, data requirements and data offerings. Therefore, the specification and later implementation of a component will be done with respect to its anticipated simulation context, but a tight dependency to this context is avoided. Later in the process of development, the component will be tested standalone using a test bed environment to prove its correct work.
   
   
3. The component is general enough to be used in other models and applications. So designing and implementing it right from the beginning will eventually require more work at the beginning, but will definitively pay off when it gets reused and re purposed later.

By analyzing simulation models a classification of potential components can be made.

• Scientific components implement methods and equations to estimate some physical phenomenon. Examples would be a component estimating amount of water evaporated from a certain land cover into, a component predicting the soil loss due to wind erosion, etc. Such components usually apply some mathematical function.

• Scientific utility components support the analysis of models by providing statistical analysis methods such as descriptive statistics, frequency analysis, etc. Distribution generator components are used to provide data to scientific components.

• Control components are responsible for managing the execution of a model. A Runge-Kutta Integration component, a Time management, or a Convergence criteria component are examples for this.

• Data Input/Output components are providing data to other components in a simulation model. Such components could handle data transfer from databases or files to the model. Visualization components like graphs or spreadsheets are also falling under this category.

An OMS component can be written in the Java Programming Language or in the FORTRAN programming language. Java is the preferred implementation language for components since you will experience all the benefits and advantages of this platform. The use of FORTRAN components enables the integration of legacy FORTRAN code as components into the system.

Figure: Component Creation Wizard

The creation of a component is performed by the New Wizard. It gets invoked by selecting the menu item File | New. There are different code templates for creating both Java and Native Components. The Figure “Component Creation Wizard” shows available OMS templates. For component development only Java Component and Native Component are relevant.

Creating a Java Component

Open the New Wizard as described above. In several steps you will be asked details about creating a Java component.

1. Choose Template ...
   You need to select the template Java Component, which can be found in the template folder Templates | Object Modeling System | Component API and hit the Next > Button.
2. Target Location ...
   Choose a name for the component and the folder where to create it. All project folder are listed in this view. Provide a name without any extension (the default file extension .java will be added). The name has to be a valid identifier in Java (No spaces, usual alphanumerical conventions) Hit hit the Next > Button.
3. Capabilities ...
   Select the component capabilities. This will affect the interfaces this component will be implementing. If none of the check boxes are selected, the component will implement the Java interface Executable. See the Resource Specifications about the different interfaces and their semantics. Hit the Finish Button.

The new component will opened and appears in the source editor for editing.

Managing Component Attributes

Attributes can be added to both Java and Native Components. However, the Native components wizard already creates attributes for all data being used in as arguments to a native call. Nevertheless attributes can be added to native components to perform additional operation besides the wrapped FORTRAN functionality.

The OMS user interface contains a window for managing component attributes. It can be activated by selecting the menu item Window | Component Attributes. The window appears initially at the right part of the user interface. This window is sensitive to the selection of a component in the projects window and the source editor. It changes its content to show always the attributes of the selected component. Figure Attribute Editor shows the Attributes Editor for a component named Snow with 5 different attributes.

Figure: Attribute Editor

The main attribute editors purpose is the source management for attributes within components. Therefore any editing operation in the attribute editor will directly affect the associated component source. Both, attribute editor and an open component source are always kept in sync.

Attributes can only be added, edited and deleted using the attribute editor. Thus, all the sections in the component source related to attributes are guarded (not editable!), which is indicated by the light blue background of the source. Protecting the component source regarding to attribute sections ensures their correct structure. By using the attribute editor the attribute sections in the component source are always in a syntactically correct status.

The Properties Window is being used to edit the attributes meta data. The meta data content of a selected attribute in the Attribute Editor is shown in the properties window. Any change in here will affect the attribute settings in the source. An overview about the relationships between the component source file, Attribute Editor and the Properties Window while attribute editing is shown in the Figure below.

Figure: Attribute Editing Workflow

The following operations can be performed using the Attribute Editor:

Adding a new attribute

Provide the name and select the type of the attribute to create and hit the green add Button. Note that a valid attribute name is an identifier according to the Java language specification. An valid name is starting with a letter followed by any number of letters or digits or underscores. No spaces are allowed and Java language keywords are prohibited too. The newly created attribute will appear as sub node of the Component Meta Data node.

Deleting an existing attribute

Right click on the attribute node and select Delete, or use the keyboard. All attribute related code will be deleted out of the component.

Getting an attribute from another component

Select another component in the Project window or the source editor, the Attribute Editor will show its attributes. Right click on an attribute node and select Copy (or type Control+C). Select the target component in the project window or the source editor. Right click on the Component Meta Data node in the Attributes Editor and select Paste (or type Control+V). The attribute will be copied.

Changing the name of the attribute

Select the attribute within the Attribute Editor, which name should be changed. In the Properties window set the Name property. The name of the attribute and all other occurrences (references in code) will be changed to the new name.

Setting the attribute access

Select the attribute within the Attribute Editor. In the Properties window operate the Data Access property and select one of the options provided in the combo box. The default setting is read/write.

Setting the default value

Select the attribute within the Attribute Editor. In the Properties window provide a default value for the attribute using the Default Value property If no default value is given, standard rules apply according to the Java programming language specification.

Changing the attribute type

Select the attribute within the Attribute Editor which type should be changed. In the Property window choose a different type by using the combo box in the Type property. Changing an attribute type should be handled with caution, especially if the attribute is already used in the component's code. It could cause the code to break!

Assigning a unit to an attribute

Select the attribute within the Attribute Editor which unit should be set. Provide a unit in the Unit property.

Setting a constraint

Select the attribute within the Attribute Editor. In the Property Window provide a valid constraint.

Providing attribute description

Select the attribute within the Attribute Editor. The Description property in the Properties window allows the input of text to be used as description for the attribute. A description should have a short first sentence and an optional longer text about the attribute.

Assigning the attribute role

Select the attribute within the Attribute Editor. The Property Window allows the selection of an attribute as a Parameter or a Dimension.

Managing Component Meta Data

OMS components have associated meta data which provide additional information about a component such as author, version, literature references, etc. Using the Attribute Editor component meta data can be edited. Like Attributes, component meta data is stored in the component source file. It is guarded to against incorrect modifications.

Figure: Managing Component Meta Data

The component meta data can be edited by selecting the node Component Meta Data in the Attribute Editor for an active component. The Properties window then allows editing of the component meta data by operating individual properties such as Author or Description as shown in Figure Managing Component Meta Data.