Appendix - Writing Plug-Ins
The purpose of this appendix is to explain how to write your own HEC-DssVue plugin.
A "plug-in" is an executable ".jar" file that is saved in the "Plugins" directory that can access and perform functions on top of HEC-DSSVue. No modifications are needed to the original program to provide this additional functionality. Access and use of a plug-in should appear seamless to a user; generally their functionality is accessed through a standard menu.
Using the Java programming language, you can write a plug-in for HEC-DSSVue to provide custom capabilities such as data processing. Please refer to the DSS Programmers guide for Java for the key objects that are typically used such as HecTime, DSSPathname, TimeSeriesContainer, PairedDataContainer,
Plugins are Java source code compiled into jar files, such as 'usgsPlugin.jar', and placed the jar\ext directory of HEC-DssVue. When HEC-DssVue starts up it looks at all jar files in the plugin directory (default: jar\ext). For each Jar found it checks the MANIFEST.MF file to see if that Jar should be loaded. If the MANIFEST.MF has an "HecDssVuePlugin" entry the plugin is loaded.
Below is an example Manifest:
jar\ext\HelloPlugin-1.0.jar\META-INF\MANIFEST.MF
Manifest-Version: 1.0
HecDssVuePlugin: HelloPlugin
Implementation-Version: 1.0
Source code for the following Plugin examples are available on Github.
| Example | What does this plugin do? |
|---|---|
| HelloPlugin | simple plugin that adds a "Hello Plugin" item to the Tools Menu. |
| ToTextPlugin | The ToTextPlugin takes selected time series data sets and writes the data out to a text file. You can use this to create an input file in a certain format for other programs. |
To compile and create a Plugin (jar) file for the ToTextPlugin above follow these steps:
- Download the source code: https://github.com/HydrologicEngineeringCenter/DssVue-Example-Plugins/archive/master.zip
- unzip to c:\project (or your favorite working area)
edit C:\project\DssVue-Example-Plugins-master\ToTextPlugin\build.gradle and modify the (fileTree( dir: ... ) line below to match your DssVue or CWMS vue Jar directory.
// DssVue install dir compile fileTree(dir: 'C:/Programs/CWMS-v3.2.1.256/common/jar', include: ['*.jar'])// other example location: C:\Programs\HEC-DSSVue-v3.0.1.42\jarJS- open up a command prompt in the directory C:\project\DssVue-Example-Plugins-master\ToTextPlugin
- type: gradlew jar (see screen below )
- If you don't have errors the file ToTextPlugin-1.0.jar will be in the directory C:\project\DssVue-Example-Plugins-master\ToTextPlugin\build\libs
- copy ToTextPlugin-1.0.jar to the DssVue plugin directory "C:\Programs\HEC-DSSVue-v3.0.1.42\jar\ext" for example. For a CWMS install use: C:\Programs\CWMS-v3.2.1.459b\common\jar\ext
- Run HEC-DssVue and you should see a new ToolButton named "To Text File" as shown below.
compiling a plugin using gradle
C:\project\DssVue-Example-Plugins-master\ToTextPlugin>gradlew jar
> Task :compileJava
> Task :processResources NO-SOURCE
> Task :classes
> Task :jar
Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org/6.4.1/userguide/command_line_interface.html#sec:command_line_warnings
BUILD SUCCESSFUL in 5s
2 actionable tasks: 2 executed
C:\project\DssVue-Example-Plugins-master\ToTextPlugin>
