Background

The HEC-WAT (Watershed Analysis Tool) is a plugin framework that links applications together to conduct evaluations of watersheds as a system. The WAT plugin technology facilitates the integration of these models. 

What is a "Plugin"?

The plugin is a software component that adds a specific feature to an existing computer program (Wikipedia).  It exists to provide customization to the software that supports a plugin framework. There are many ways that plugins can be implemented in software designs, but in essence they all seek to facilitate consistent communication between different programs based on a specified set of expected calls and call sequences. In the case of HEC-WAT, in general, the plugin operates as an adapter, enveloping a complicated model and producing a consistent set of externally facing API calls shared across all applications that are being "plugged in". This API facilitates passing data, execution computations, editing alternatives, and viewing results. By implementing the plugin API any application can be integrated into the HEC-WAT framework.

How does HEC-WAT leverage plugins?

HEC-WAT leverages plugins to operate in a compute sequence or as a simple utility feature. The plugin framework in HEC-WAT relies on a set of Interfaces that define behaviors. Internally to HEC-WAT the framework calls on the methods defined by the interfaces and manages each plugin abstractly through the interface definition. HEC-WAT has no awareness of the function of the application aside from the plugin interfaces it has implemented. Through the use of a program plugin, the WAT incorporates a program seamlessly into the user interface and/or computational logic. There are many different levels of integration available depending on the type of plugin interfaces that are implemented on the instance of the plugin. For programs that already exist and are fully functional outside of HEC-WAT, a client-server architecture with the WAT acting as the client and the model program as the server provides a way to integrate complex programs while keeping the program separated from the WAT. The client-server connection can be implemented in any fashion that works for the program. Traditionally, Java RMI has been used as the transport layer between the client and server sides, though the plugin developer is free to use the communication mechanism they want between their client and server sides. While all plugins must be written in Java, the model or program that the plugin is wrapping can be written in any language. plugins have been written for Java programs, C++ programs, Fortran programs, VB/VB.net programs, as desktop applications or as command line programs.

Implementing Interfaces

Implementing the plugin interfaces within the plugin jar allows a programmer to fulfill the HEC-WAT plugin API by creating an adapter for the API of the model. Within HEC-WAT, all plugins are referred to through these interfaces and HEC-WAT does not know which process each plugin represents in the watershed.

plugins containing all of their computational logic

The simplest design for plugins occurs when the plugin is the entire model — many plugins use this design within HEC-WAT. These plugins are "self-contained" because they contain all of their own computational logic. The logic is completely in the plugin and doesn't need the client-server design of the other plugins.
To support this some new classes were added to the plugin framework extending the interfaces described above. The new classes make it easier for other plugins to be written, factoring common code into a few classes.
1.1.1.1Base Self-Contained Classes
The class hec2.wat.plugin.AbstractSelfContainedPlugin is the base class for plugins that handle everything themselves (they are not wrapping an existing model). The class signature looks like:
public abstract class AbstractSelfContainedPlugin<E extends SelfContainedPluginAlt> extends AbstractComputablePlugin implements DisplayableWatPlugin, SelfContainedPlugin
A plugin that extends AbstractSelfContainedPlugin will have a constructor similar to this:
public class FragilityCurvePlugin extends AbstractSelfContainedPlugin<FragilityCurveAlt> implements CreatableWatPlugin

Figure 4 plugin Interfaces

plugins for programs that run outside of the WAT process

For other models that want to run the modeling application in a separate process, there are base classes in the WAT that can be extended which provide the basic functionality of proxying the plugin API calls from the client portion of the plugin (client portion of the plugin resides in the same JVM as the WAT) to the server portion of the plugin.

Java Program plugin

The Java-based programs share a common client-side plugin and RMI interface for the server side. The server side is unique to each program so the client needs to only implement a couple of methods. Since the server-side component of the plugins is implemented using the same RMI interface, the client side can be based on the same base class, with the only difference being the server that they launch.
There are two categories of designs used to incorporate the HEC modeling programs. The first one is used for the Java® based programs. This design is shown below:

Figure 5 Design for Java-based programs

Non Java Program plugin

The second design is for programs that are not written in Java such as C# or Visual Basic programs.

Figure 6 Non-Java Plugin
The final plugin design is for plugins that handle most of the plugin details but launch an external program for the computation. This process works well for programs that are written as command line accessible programs.

Figure 7 Non Java Plugin
It is not intended that any of the standalone model programs contain WAT-specific code when they are running outside of the WAT environment.
When designing a plugin, there are a few critical questions that must be asked prior to beginning:

1. Will the plugin operate as a part of the WAT compute sequence?
2. Will the plugin generate events or consume event data?
3. Does the computational logic for the program exist already?
4. Is the computational logic written in Java?
5. Can the computational engine operate within the WAT JVM?

plugin API

plugin Interfaces & Class

Interfaces Overview

Figure 32 Basic WAT plugin Interfaces

SimplePlugin

The base interface for all plugins for both WAT and CWMS CAVI/RTS.

ComputablePlugin

Interface for plugins that participate in the simulation process.

WatPlugin

plugins to be inserted into a WAT Simulation compute must implement the hec2.wat.plugin.WatPlugin, which extends hec2.wat.plugin.SimpleWatPlugin and defines methods used by the Simulation process.

DisplayableWatPlugin

plugins that also need to be able to display information on the map schematic should implement the interface, hec2.wat.client.DisplayableWatPlugin. The DisplayableWatPlugin interface defines additional functionality that a plugin must support to be displayed on a map schematic. These are things like returning a list of elements to display, displaying an editor for an item, displaying output for one or more elements, etc…
The hec2.wat.client.DisplayableWatPlugin interface extends hec2.wat.client.WatPlugin.
The four HEC programs will all be DisplayableWatplugins, since they all have graphics elements.

Java Program plugin

Two of the Java based programs (i.e. ResSim, and FIA) share a common client-side plugin and RMI interface for the server side. On the other hand, the server side is unique to each program, which means that the client needs to only implement a couple of methods. Since the server-side component of the plugins will all be implemented using the same RMI interface, the client side can be based on the same base class, with the only difference being the server that they launch.

Self-Contained plugins

Two of the plugins are written completely in the plugin, the Hydrologic Sampling and Fragility Curve plugin, and don't need the client-server design of the other plugins. To support this some new classes were added to the plugin framework, though to the WAT they are still accessed through the existing interfaces. The new classes were written to make it easier for other plugins to be written, factoring common code into a few classes.

Base Classes

The class hec2.wat.plugin.AbstractSelfContainedPlugin is the base class for plugins that handle everything themselves (no existing model that they are wrapping). The class signature looks like:
public abstract class AbstractSelfContainedPlugin<E extends
SelfContainedPluginAlt> extends
AbstractComputablePlugin implements DisplayableWatPlugin, SelfContainedPlugin
A plugin that extends AbstractSelfContainedPlugin will have a constructor similar to this:
public class FragilityCurvePlugin extends AbstractSelfContainedPlugin<FragilityCurveAlt> implements CreatableWatPlugin


Figure 33 Plugin classes

Dynamic Linking

Dynamic Linking allows for the replacement of the <Model Alternative> portion of the DSS F-Part. For a plugin to participate in Dynamic Linking it has to implement the hec2.plugin.DynamicLinkagePlugin interface.

Example of F-Part Replacement

Using the example for standard F-Part Replacement, if the ResSim DSS F-Parts are linked to WithoutPro:50Years:HMS-Base during the compute ResSim's DSS output F-Part comes in as UpdatedCon:Jan_2006:ResSim-FloodOps, then it would change the first part of its linked DSS pathnames to UpdatedCon:Jan_2006:HMS-Base. Then finding that the ComputeOptions contained Dynamic Linkages that said to replace HMS Base with HMS Jan06 the input DSS F-Parts would change to UpdatedCon:Jan_2006:HMS-Jan06.