<= Previous | Next => | Table of Contents DataVision User's Manual

4 Incorporating DataVision Into a Java Application

It isn't difficult to incorporate DataVision into a Java application. Instantiate a Report object and have it read the XML file and possibly a parameter value XML file, then give the report object a layout engine object (such as LaTeXLE).

Here's how you would do it:

Report report = new Report();
report.setDatabasePassword("mypassword");
report.readFile(xml_file_name); // Must be after password
if (there_are_params_in_report) {
    // This must come after reading the report file
    report.setParameterXMLFile(param_xml_file_name);
}
report.setLayoutEngine(new LaTeXLE(a_writer));
// ...or HTMLLE, or SwingLE, or any other layout engine

// Finally, run the report either in a separate thread or in
// the current thread. Pick one of the following two.
report.run();      // Run the report in a separate thread.
                   // Doesn't wait for this thread to finish
                   // (code left as an exercise for the reader).
// or
report.runReport();   // Run the report in this thread

Finally, you must include in your classpath three JAR files that come with DataVision: DataVision.jar, MinML.jar, and jcalendar.jar. MinML is the XML parser written by John Wilson and JCalendar is the calendar Swing widget by Kai Toedter.

4.1 Asking for Parameter Values

There are two ways a report gets parameter values: either by asking the user or by reading a parameter XML file. If you want the user to be prompted for input, you should not give the report a parameter file name. Instead, you should tell the system that you want to use a Swing window to prompt the user for parameter values by using the following code some time before running the report:

ErrorHandler.useGUI(true);

When a report runs, it asks itself, "Do I have any parameters that need values?" If the answer is yes, it then asks itself, "Am I using a GUI?" If the answer to that question is "yes", it opens a Swing window to ask the user for parameter values. If the answer is "no", it reads the parameter XML file you gave it.

To specify a parameter file on the command line, use the -r command line option. See Running DataVision from the Command Line for details.

To specify a parameter's value within your code, you need to ask the report object to find it and then set its value.

// Ask the report to find the parameter for you
Parameter p = report.findParameter(new Long(myParamID));
// or p = report.findParameterByName("My Parameter Name");

// Set the parameter's value. This sets a single value.
p.setValue(0, "The New Value");
// To set more values (if it is a range or a list of values), keep
// calling setValue().
// p.setValue(1, "Another Value");

Now, the tricky part: telling the report that it does not have to read a parameter XML file or ask the user for values. My untested suggestion: create a subclass of Report and override askForParameters. In that new method, set the parameter values and then tell the report that you are done.

protected void askForParameters() {
    // Ask the report to find the parameter for you
    Parameter p = findParameter(new Long(myParamID));

    // Set the parameter's value. This sets a single value.
    p.setValue(0, "The New Value");

    // The next two lines are necessary.
    askedForParameters = true;
    parametersHaveValues = true;
}

<= Previous | Next => | Table of Contents Valid XHTML 1.0! DataVision User's Manual