Package ilog.rules.dvs.excel

Provides the classes and interfaces to use for reading and writing to Excel 2003 scenario files.

Overview

A scenario represents the values of the input parameters of a ruleset, that is, the input data to ruleset execution, plus any expectations on the execution results that you wish to test.

In the API, a scenario suite represents a list of such scenarios. If you are using the proposed Excel 2003 format to store your scenarios, your scenario suite becomes an Excel 2003 scenario file, where each scenario is identified with a unique ID. Scenario files contain a Scenarios worksheet for the values of the input data. If you are testing the results of the execution, the Excel 2003 scenario file also contains one or both of the following worksheets:

  • Expected Results - For tests on output parameters of the ruleset.
  • Expected Execution Details - For technical tests on the engine, for example number of rules fired.

If you are using a custom scenario provider such as a database, the notion of scenario file is no longer pertinent.

Excel Readers

There are two approaches to reading data from an Excel 2003 scenario file:

The reader approach uses IlrExcel2003ScenarioSuiteReaderFactory to handle basic file management, and IlrExcel2003ScenarioSuiteReader to read and interpret the data, as follows:

  1. Create an input stream on the scenario file
  2. Load the ruleset archive to access the BOM
  3. Get an instance of the reader factory
  4. Create and use the new reader

The following code example shows how to implement the reader approach:

// Create an input stream on the scenario file
InputStream scenarioSuite = new FileInputStream("my-scenario.xls");
// Load the ruleset archive
InputStream rulesetArchiveInputStream =  new FileInputStream("my-ruleset.jar");
IlrRulesetArchive rulesetArchive = IlrRulesetArchive.extractArchive(new IlrJarArchiveLoader(new JarInputStream(rulesetArchiveInputStream)));
// Get an instance of the reader factory
IlrExcel2003ScenarioSuiteReaderFactory factory = IlrExcel2003ScenarioSuiteReaderFactory.getInstance();
// Create a new reader
IlrExcel2003ScenarioSuiteReader reader = factory.getNewReader(scenarioSuite, rulesetArchive);
// Use the reader
reader.getScenarioCount();
...
// Close the reader
reader.close();

Excel Writers

To write data to an Excel scenario file using the API, you need:

  • A scenario file that has the correct column headings.
  • A ruleset archive.
  • The model type.
  • A property map to describe how to interpret the BOM.

Population of the scenario file is performed by an IlrExcel2003ScenarioSuiteWriter, which is created from an IlrExcel2003ScenarioSuiteWriterFactory to handle basic file management.

The following code example shows how to write to an Excel scenario file:

// Create an input stream on the scenario file
InputStream scenarioSuite = new FileInputStream("my-scenario.xls");
// Load the ruleset archive
InputStream rulesetArchiveInputStream = new FileInputStream("my-ruleset.jar");
IlrRulesetArchive rulesetArchive = IlrRulesetArchive.extractArchive(new IlrJarArchiveLoader(new JarInputStream(rulesetArchiveInputStream)));
// Get an instance of the writer factory
IlrExcel2003ScenarioSuiteWriterFactory factory = IlrExcel2003ScenarioSuiteWriterFactory.getInstance();
// Create a new writer with mapping properties that explains how to interpret the BOM
Properties mappingProperties = new Properties();
mappingProperties.put("converter_my.Class", "my.Class");
IlrExcel2003ScenarioSuiteWriter writer = factory.getNewWriter(scenarioSuite, rulesetArchive, IlrExcel2003ScenarioSuiteWriterFactory.ModelType.XOM, mappingProperties);
// Use the writer
...