GWBplugin – Getting started with Java

The GWB plug-in feature is implemented as a Dynamic-Link Library (DLL). For Java we provide a GWBplugin wrapper class contained in GWBplugin.java. For ease of use we also provide a jar file GWBplugin.jar which contains the GWBplugin wrapper and the required Java Native Access library. This page answers common queries about how to use the Java version of the plug-in feature.


Using the plug-in

Using the GWB plug-in feature:

  1. Using the GWBplugin.jar file in your Java program.
  2. GWBplugin Java wrapper class overview.
  3. Initializing the GWB application you wish to use.
  4. Configure and execute your calculations.
  5. Retrieving the results.
  6. Cleaning up.

Using the GWBplugin.jar file in your Java program.

To compile your program you will need to have a Java Development Kit (JDK) installed. The JAR file you need to add to your CLASSPATH is installed to your computer in the "src" directory of the GWB directory and named GWBplugin.jar. For step-by-step instructions on setting up your build environment and examples using the command line and Eclipse please see Quickstart tutorials and examples.

GWBplugin Java wrapper class overview.

This is a synopsis of the Java wrapper class provided by GWBplugin.jar in the "src" directory of the GWB installation folder. The source is also available in GWBplugin.java.

// GWBplugin.java

package GWBplugin;

import com.sun.jna.*;
import com.sun.jna.ptr.PointerByReference;

public class GWBplugin {
  static public double ANULL = -999999;
  public GWBplugin();
  public int initialize(String app_name, String file_name = null, String cmds = null);
  public int exec_cmd(String uline);
  public int results(Object data, String value, String units = null, int ix = 0, int jy = 0);
  public void destroy();
}

Initializing the GWB application you wish to use.

Within your code you must first create a "GWBplugin" object. Next, use the "initialize" function to start the GWB application of interest by passing the application name, a optional file name for the GWB application to write output to, and any command-line type arguments.

Syntax

public int initialize(
  String app_name, 
  String file_name = null, 
  String cmds = null
);

Parameters

app_name
A string containing the GWB application name you wish to use. Valid options are rxn, spece8, react, x1t, and x2t.
file_name [optional]
A string containing the name of the file you want the GWB application to write its output to. Can be null or an empty string if you do not want the output to be written to a file.
cmds [optional]
A string containing command-line options you could normally pass to the application when running it from the command-line. Can be null or an empty string.

Command-line options:
-cd
Change the working directory to the directory containing the input script specified with the -i option.
-nocd
Do not change the working directory.
-i <input_script>
Read initial input commands from the specified file.
-gtd <gtdata_dir>
Set directory to search for thermodynamic datasets.
-cond <cond_data>
Set the dataset for calculating electrical conductivity.
-d <thermo_data>
Set the thermodynamic dataset.
-s <surf_data>
Set a dataset of surface sorption reactions.
-iso <isotope_data>
Set a dataset of isotope fractionation factors.

Return value

Non-zero on success and zero on failure.

Remarks

  • For this function to succeed you must have your GWB installation folder added to the PATH environment variable so all the required DLLs can be found.
  • initialize must be done before trying to use any of the other functions.

Examples

import GWBplugin.GWBplugin;
...
GWBplugin myPlugin = new GWBplugin();
...
// plug-in SpecE8 with no output written and no options
int success = myPlugin.initialize("spece8");
...
// plug-in React with output written to output.txt and no options
int success = myPlugin.initialize("react","output.txt");
...
// plug-in X1t with no output written, no working directory change,
//  and read input from pb_contam.x1t
int success = myPlugin.initialize("x1t",null,
     "-nocd -i \"c:/program files/gwb/script/pb_contam.x1t\"");

Configure and execute your calculations.

The "exec_cmd" function can be used to transmit commands to the plug-in. Each application has a chapter in the reference manual of the documentation on what commands are available. You use these commands to configure the application and then send a "go" command to trigger the calculations.

Syntax

public int exec_cmd(
  String uline
);

Parameters

uline
A string containing the command you wish to send to the GWB application.

Return value

Non-zero on success and zero on failure.

Remarks

None.

Examples

myPlugin.exec_cmd("3 mmol H+");
myPlugin.exec_cmd("2 mmol Ca++");
myPlugin.exec_cmd("5 mmolar Cl-");
myPlugin.exec_cmd("go");

Retrieving the results.

Retrieving the results using the GWB plug-in feature can be accomplished using the "results" function. The keywords, default units, and return types are the same as those listed in the Report Command chapter of the reference manual in the documentation. To use the "results" function you provide an array of the proper data type, along with the desired report command and keywords, optional desired units, and the node location of choice (X1t and X2t only).

Syntax

public int results(
  Object data,
  String value,
  String units = null,
  int ix = 0,
  int jy = 0
);

Parameters

data
Array of data to fill. Can be null or of type int[], double[], or String[]
value
String containing the report command keyword and arguments.
units [optional]
String containing the units you would like the results returned in. Can be null or an empty string if you want default units.
ix [optional]
X node position.
jy [optional]
Y node position.

Return value

The number of values written (or to be written) to the array.

Remarks

  • To determine the size of array you will need first call this function with data parameter as null and with the rest of the parameters filled. Please see the "Appendix: Report Command" section in the GWB Reference Manual for details on data types and available keywords. The Reference Manual can be found in the documentation section of the website.
  • If the command fails for any reason, for example if the requested data doesn't exist or the specified unit conversion failed, the data will be filled with GWBplugin.ANULL (-999999.0).
  • ix is only used when running X1t and X2t. Otherwise it is ignored.
  • jy is only used when running X2t. Otherwise it is ignored.

Examples

// get aqueous species names
int ndata = myPlugin.results(null,"species");
String Species[] = new String[ndata];
myPlugin.results(Species,"species");

// get aqueous species concentrations in mg/kg
double Conc[] = new double[ndata];
myPlugin.results(Conc,"concentration aqueous","mg/kg");

// get pH at node 3,5
double pH[] = new double[1];
myPlugin.results(pH,"pH",null,3,5);

Cleaning up.

The "destroy" function can be used to free up the underlying memory associated with the GWBplugin object.

Syntax

public void destroy();

Parameters

None.

Return value

None.

Remarks

None.

Examples

myPlugin.destroy();

Quickstart tutorials and examples

Step-by-step instructions for compiling GWBplugin Example 1 on the command line.

For this tutorial you will need to have a Java development kit installed.

The first thing you need to do is to open the command prompt ...

cmd.exe

Then create a working folder ...

mkdir "%homepath%\GWBplugin"

Change to that folder ...

cd "%homepath%\GWBplugin"

Copy the "src" folder from GWB installation – default install path shown ...

copy /Y "C:\Program Files\GWB\src"

Add the GWB installation folder to your path ...

set path=C:\Program Files\GWB;%path%

Add the JDK bin folder to your path if it is not already there ...

set path=C:\Program Files\Java\jdk1.8.0_65\bin;%path%

Create the build folder ...

mkdir class

Add the build folder and GWBplugin JAR file to your classpath ...

set classpath=class;C:\Program Files\GWB\src\GWBplugin.jar;%classpath%

Compile the example file...

javac GWBplugin_Java_Example1.java -d class

You are now ready to run the example (-Xss10m increases the stack size, default stack is usually too small) ...

java -Xss10m Example1

Which should produce output similar to the following ...

Beginning run.
Finished run.

concentration of Cl- in molal is    0.05000
concentration of Cl- in mg/kg is       1770

There are 4 aqueous species.

Cl-  =       1770 mg/kg
H+   =  1.139e-05 mg/kg
HCl  =  1.234e-11 mg/kg
OH-  =    0.02039 mg/kg

Congratulations on plugging into the GWB!


Java plug-in support

Why does it say it can't find the GWBplugin.dll when I try to run my program?
In order to locate the GWB DLLs the GWBplugin class uses you must add the GWB installation directory to the PATH environment variable. In addition you also need to be using the correct version of the Java virtual machine: 32-bit Java can only load the 32-bit version of GWBplugin.dll and 64-bit Java can only load the 64-bit version of GWBplugin.dll.

I have the correct paths added to my path environment variable for the JDK and GWB, but it still is unable to load GWBplugin.dll?
There is also a java.exe located in Windows\System32 so if that is in the PATH before the JDK that will be used and may be the incorrect 32-bit/64-bit version. Put the JDK before Windows\System32 to be sure to use java.exe from the JDK.

Why do I get a CLassNotFoundException?
Double check that you have the correct path for GWBplugin.jar added to your CLASSPATH environment variable.

Where are the GWBplugin files that I need to use in my program?
The GWBplugin JAR file (GWBplugin.jar) is installed to the "src" folder in the GWB directory.

For answers to additional questions please check the plug-in section of the reference manual in the documentation, our main support FAQ, or contact us.