Rappture Java API

Currently in development are the Java bindings to the Rappture Development Toolkit.

The following classes are defined in the rappture package. To use them, either prefix the class names with rappture (for example: rappture.Library), or place the following code at the beginning of your file.

import rappture.*;

Note that the rappture package must be in the classpath when compiling your source code.

javac -cp /path/to/rappture/lib/java Source.java

Library Class Summary

This class provides a Java interface to Rappture I/O (RpLibrary) class.

Constructor Summary

Library( String path )

Method Summary

String get( String path )

byte[] getData( String path )

double getDouble( String path )

int getInt( String path )

String getString( String path )

void put( String path, Object value, boolean append )

void put( String path, Object value )

void putData( String path, byte[] value, boolean append )

void putData( String path, byte[] value )

void putFile( String path, String filename, boolean compress, boolean append )

void putFile( String path, String filename, boolean compress )

void putFile( String path, String filename )

void result( int exitStatus )

void result()

String xml()

Units Class Summary

This class provides a Java interface to Rappture Units (RpUnits) class.

Method Summary

double convertDouble( String fromVal, String to )

String convertString( String fromVal, String to, boolean units )

String convertString( String fromVal, String to )

Utils Class Summary

This class provides a Java interface to Rappture Utils (RpUtils) class.

Method Summary

void progress( int percent, String text )

void progress( int percent )

---

Library Class Detail

Constructor Detail

public Library( String path )

Purpose:

Create a Rappture I/O object using the xml file located at path as the object reference.

Input Arguments:

1) path - path of xml file to be opened with Rappture.

# Contents of driver.xml
# <run>
#     <input>
#         <number id="Ef">
#             <units>eV</units>
#             <min>-10eV</min>
#             <max>10eV</max>
#             <default>0eV</default>
#             <current>3eV</current>
#         </number>
#     </input>
# </run>

class Example{
  public static void main(String args[]){
    rappture.Library driver = new rappture.Library("driver.xml");
    System.exit(0);
  }
}

Method Detail

public String get( String path )

Purpose:

Retrieve the data held at the xml location path. Equivalent to getString( path ).

Input Arguments:

1) path - xml path (location) of the element to be retrieved.

Return Value:

Returns a String object containing the data held at the specified xml location.

# Contents of driver.xml
# <run>
#     <input>
#         <number id="Ef">
#             <units>eV</units>
#             <min>-10eV</min>
#             <max>10eV</max>
#             <default>0eV</default>
#             <current>3eV</current>
#         </number>
#     </input>
# </run>

class Example{
  public static void main(String args[]){
    rappture.Library driver = new rappture.Library("driver.xml");
    String Ef = driver.get("input.number(Ef).current");
    System.out.println("Ef = " + Ef);
    System.exit(0);
  }
}

# Result:
# Ef = 3eV

public byte[] getData( String path )

Purpose:

Retrieve the data held at the xml location path.

Input Arguments:

1) path - xml path (location) of the element to be retrieved.

Return Value:

Returns a byte array containing the data held at the specified xml location.

public double getDouble( String path )

Purpose:

Retrieve the data held at the xml location path.

Input Arguments:

1) path - xml path (location) of the element to be retrieved.

Return Value:

Returns a double precision floating point number containing the data held at the specified xml location.

# Contents of driver.xml
# <run>
#     <input>
#         <number id="Ef">
#             <units>eV</units>
#             <min>-10eV</min>
#             <max>10eV</max>
#             <default>0eV</default>
#             <current>3eV</current>
#         </number>
#     </input>
# </run>

class Example{
  public static void main(String args[]){
    rappture.Library driver = new rappture.Library("driver.xml");
    double Ef = driver.get("input.number(Ef).current");
    System.out.println("Ef = " + Ef);
    System.exit(0);
  }
}

# Result:
# Ef = 3.0

public int getInt( String path )

Purpose:

Retrieve the data held at the xml location path.

Input Arguments:

1) path - xml path (location) of the element to be retrieved.

Return Value:

Returns an integer value containing the data held at the specified xml location.

public String getString( String path )

Purpose:

Retrieve the data held at the xml location path. Equivalent to get( path ).

Input Arguments:

1) path - xml path (location) of the element to be retrieved.

Return Value:

Returns a String object containing the data held at the specified xml location.

public void put( String path, Object value, boolean append )

Purpose:

Place the string representation of the value Object into the library at the xml location path. If the append flag is set to 1, then value will be appended to data that already exists at path. If the append flag is set to false, then value will overwrite data that may have existed at path.

Input Arguments:

1) path - xml path (location) to store value.

2) value - Data to store in the library. The string representation of the object is written by using Object.toString().

3) append - Append flag. If set to false, data at path will be overwritten. If set to true, new data will be appended to the existing data.

# Contents of driver.xml
# <run>
#     <input>
#         <number id="Ef">
#             <units>eV</units>
#             <min>-10eV</min>
#             <max>10eV</max>
#             <default>0eV</default>
#             <current>3eV</current>
#         </number>
#     </input>
# </run>

class Example{
  public static void main(String args[]){
    String Ef;
    rappture.Library driver = new rappture.Library("driver.xml");

    System.out.println("Overwrite:");
    driver.put("input.number(Ef).current", 6, false);
    Ef = driver.get("input.number(Ef).current");
    System.out.println("Ef = " + Ef);

    System.out.println("Append:");
    driver.put("input.number(Ef).current", "eV", true);
    Ef = driver.get("input.number(Ef).current");
    System.out.println("Ef = " + Ef);

    System.exit(0);
  }
}

# Result:
#
# Overwrite:
# Ef = 6
# Append:
# Ef = 6eV

public void put( String path, Object value )

Purpose:

Place the string representation of the value Object into the library at the xml location path. Overwrites any data that previously existed at path. Equivalent to put(path, value, false).

Input Arguments:

1) path - xml path (location) to store value.

2) value - Data to store in the library. The string representation of the object is written by using Object.toString().

public void putData( String path, byte[] value, boolean append )

Purpose:

Places value into the library at the xml location path. If the append flag is set to 1, then value will be appended to data that already exists at path. If the append flag is set to false, then value will overwrite data that may have existed at path.

Input Arguments:

1) path - xml path (location) to store value.

2) value - Data to store in the library object.

3) append - Append flag. If set to false, data at path will be overwritten. If set to true, new data will be appended to the existing data.

public void putData( String path, byte[] value )

Purpose:

Places value into the library at the xml location path. Overwrites any data that previously existed at path. Equivalent to putData(path, value, false).

Input Arguments:

1) path - xml path (location) to store value.

2) value - Data to store in the library object.

public void putFile( String path, String filename, boolean compress, boolean append )

Purpose:

Places the contents of the file filename into the library at the xml location path. If the append flag is set to 1, then value will be appended to data that already exists at path. If the append flag is set to false, then value will overwrite data that may have existed at path.

Input Arguments:

1) path - xml path (location) to store value.

2) filename - Name of the file to be stored.

3) compress - Set to true to indicate that the binary data should be compressed.

4) append - Append flag. If set to false, data at path will be overwritten. If set to true, new data will be appended to the existing data.

public void putFile( String path, String filename, boolean compress )

Purpose:

Places the contents of the file filename into the library at the xml location path. Overwrites any data that previously existed at path. Equivalent to putFile(path, value, compress, false).

Input Arguments:

1) path - xml path (location) to store value.

2) filename - Name of the file to be stored.

3) compress - Set to true to indicate that the binary data should be compressed.

public void putFile( String path, String filename )

Purpose:

Places the contents of the file filename into the library at the xml location path. Binary data is automatically compressed. Overwrites any data that previously existed at path. Equivalent to putFile(path, value, true, false).

Input Arguments:

1) path - xml path (location) to store value.

2) filename - Name of the file to be stored.

public void result( int exitStatus )

Purpose:

Write the data from Library object instance to file and signal the end of processing to the graphical user interface.

Input Arguments:

1) exitStatus - Integer representing the success or failure of the application. 0 for success, any other number is failure.

# Contents of driver.xml
# <run>
#     <input>
#         <number id="Ef">
#             <units>eV</units>
#             <min>-10eV</min>
#             <max>10eV</max>
#             <default>0eV</default>
#             <current>3eV</current>
#         </number>
#     </input>
# </run>

class Example{
  public static void main(String args[]){
    String Ef;
    rappture.Library driver = new rappture.Library("driver.xml");
    driver.put("input.number(Ef).current", "6eV");
    Ef = driver.get("input.number(Ef).current");
    System.out.println("Ef = " + Ef);
    driver.result(0);
    System.exit(0);
  }
}

# Result:
#
# A run.xml file is created and the Rappture graphical user Interface is signaled that processing has ended.

public void result()

Purpose:

Write the data from Library object instance to file and signal the end of processing to the graphical user interface. Equivalent to result(0).

public String xml()

Purpose:

Provides the entire xml of the Library.

Return Value:

Returns a String object containing the entire xml of the Library.

Units Class Detail

Method Detail

public double convertDouble( String fromVal, String to )

Purpose:

Returns the decimal value of the String fromVal in units given by the String to. Equivalent to Double.valueOf(convertString(fromVal, to, false)).

Input Arguments:

1) fromVal - String with numeric portion as well as optional units (for example: "3m" or "3").

2) to - String name of the units to convert to.

Return Value:

Decimal value of fromVal in units specified by to.

public String convertString( String fromVal, String to, boolean units )

Purpose:

Returns a String containing the value of the String fromVal in units given by the String to. Units are appended to the result if the units flag is true.

Input Arguments:

1) fromVal - String with the numeric portion as well as optional units (for example: "3m" or "3").

2) to - String name of the units to convert to.

3) units - Flag to indicate whether or not units should be included in the output String.

Return Value:

String containing the converted value of fromVal in units specified by to with optional units.

# Contents of driver.xml
# <run>
#     <input>
#         <number id="Ef">
#             <units>eV</units>
#             <min>-10eV</min>
#             <max>10eV</max>
#             <default>0eV</default>
#             <current>3eV</current>
#         </number>
#     </input>
# </run>

class Example{
  public static void main(String args[]){
    String result;
    double resultD;

    rappture.Library driver = new rappture.Library("driver.xml");
    String Efstr = driver.getString("input.number(Ef).current");
    double Ef = rappture.Units.convertString(Efstr, "J");
    System.out.println("Ef in Joules = " + Ef);

    result = rappture.Units.convertString("3cm", "m", true);
    System.out.println("result = " + result);

    resultD = rappture.Units.convertDouble("300K", "F");
    System.out.println("result = " + resultD);

    result = rappture.Units.convertString("3cm", "A");
    System.out.println("result = " + result);

    result = rappture.Units.convertString("3", "m");
    System.out.println("result = " + result);

    result = rappture.Units.convertString("3", "m", false);
    System.out.println("result = " + result);

    System.exit(0);
  }
}

# Result:
# Ef in Joules = 4.80653e-19J
# result = 0.03m
# result = 80.33
# result = 3e+08A
# result = 3m
# result = 3

public String convertString( String fromVal, String to )

Purpose:

Returns a String containing the value of the String fromVal in units given by the String to. Units are included in the output. Equivalent to convertString(fromVal, to, true).

Input Arguments:

1) fromVal - String with the numeric portion as well as optional units (for example: "3m" or "3").

2) to - String name of the units to convert to.

Return Value:

String containing the converted value of fromVall in units specified by to.

Utils Class Detail

Method Detail

void progress( int percent, String text )

Purpose:

Updates Rappture's progress bar percentage and message.

Input Arguments:

1) percent - Current progress bar percentage.

2) text - Message to be displayed on progress bar.

void progress( int percent )

Purpose:

Updates Rappture's progress bar percentage. Equivalent to progress( percent, "")

Input Arguments:

1) percent - Current progress bar percentage.