API Dev Guide

Make every decision count™www.fico.com

FICO Blaze Advisor API Developer’s Guide

API Developer’s Guide

For Java FICO™ Blaze Advisor®business rules management system

Version 6.9

This document is the confidential, unpublished property of Fair Isaac Corporation. Receipt or possession of it does not convey rights to divulge, reproduce, use, or allow others to use it except as expressly provided in the license agreement between user and Fair Isaac Corporation.

The information in this document is subject to change without notice. If you find any problems in this documentation, please report them to us in writing. Fair Isaac Corporation does not warrant that this documentation is error-free, nor are there any other warranties with respect to the documentation except as may be provided in the license agreement.

© 2000–2010 Fair Isaac Corporation. All rights reserved.

FICO is a registered trademark of Fair Isaac Corporation in the United States and may be a trademark or registered trademark of Fair Isaac Corporation in other countries. Other product and company names herein may be trademarks of their respective owners.

FICO™ Blaze Advisor® business rules management system is covered by Fair Isaac U.S. Patents: 6865566, 6965889, 66968328, 6944604, and others listed in Fair Isaac documentation.

FICO Blaze Advisor 6.9 for Java - Service Pack 1

Last Revised May 14, 2010

Version 6.9

Template LG 6.0

Contents

Contents

CHAPTER 1 ROM and PROM APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7The Repository Object Model (ROM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Connecting to a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Exploring the ROM Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Repository Item Typing Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Project Repository Object Model (PROM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9The PROM Project (NdPromProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Exploring the PROM Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

PROM Item Content (NdPromItemContent) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11NdPromEntity (and its sub-interfaces). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11NdPromTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12NdPromInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12NdPromProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Entity Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Accessing Entity Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12SRL Entity Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Ruleflow Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Question Set Object Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Common ROM API and PROM API Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Specifying a Location (NdLocation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Creating Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Creating a PROM Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Loading a PROM Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Creating an SRL Ruleset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Creating an SRL Function (NdPromSrlFunction). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Creating a Ruleflow (NdPromFlowRuleflow) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Creating a Question Set (NdPromAaiQuestionSet) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Creating an SRL Class (NdPromSrlClassContent) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Creating an SRL Enumeration (NdPromSrlEnumerationContent) . . . . . . . . . . . . . . . . . . . . . . . 24

CHAPTER 2 BOM Admin APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Manipulating Imported External Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

NdPromBomAdmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27NdClassMappingInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27NdClassNameCustomizingInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Creating a New XML BOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Saving a New or Existing BOM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Saving a New BOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Saving an Existing BOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Fair Isaac Corporation Confidential and Proprietary Information 3

Contents

Add or Remove Items to or from Existing BOM(unexposed API) . . . . . . . . . . . . . . . . . . . . . . . 29Customizing a BOM(unexposed API). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

CHAPTER 3 Metaphor APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Loading a Metaphor Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Creating a Metaphor Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Decision Table Editing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Example: Display an Overview of a Decision Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Decision Tree Editing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Example: Create a Subtree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Score Model Editing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Example: List Contents of a Score Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

CHAPTER 4 Custom Provider API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Responsibilities of Provider Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Overview of the Custom Provider API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

NdTemplateValueProvider Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44NdDefaultTemplateValueProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45NdConstrainedListProvider Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45NdDefaultConstrainedListProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46NdDesignProvider Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46NdProvidesDefaultValue Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Creating Custom Provider Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Simple Value List Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Simple SRL and Display List Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Customizing Provider Behavior Using Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Defining Argument Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Processing Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

The Example Base Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Custom Provider Implementation Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

CHAPTER 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RMA Service and Session APIs . . . . . . . . . . . . . . . . . . . . . . 59The RMA Service API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

The RMA Repository (NdRmaRepository) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59RMA Project (NdRmaProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60RMA Entry (NdRmaEntry). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63RMA Directory (NdRmaDirectory). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64RMA Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

File (NdRmaFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Project (NdRmaProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Subproject (NdRmaSubProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Template File (NdRmaTemplateFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Instance File (NdRmaInstanceFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67Editable File (NdRmaEditableFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67

File Content (NdRmaFileContent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68RMA Template (NdRmaTemplate) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68RMA Instance (NdRmaInstance) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Instance Element Node (NdInstanceElementNode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

4 Fair Isaac Corporation Confidential and Proprietary Information

FICO Blaze AdvisorAPI Developer’s Guide

Versioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Versioning Operations (NdRmaEntryVersioningOperations) . . . . . . . . . . . . . . . . . . . . . . . 75Versioning Information (NdRmaEntryVersioningInfo) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

RMA Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Query Instance (NdRmaQueryInstance) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Query Results (NdRmaQueryResultItem) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Filtering Entries in an RMA Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78RMA Entry Filter Manager (NdRmaEntryFilterManager) . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Entry Exclusion Filter (NdRmaEntryExclusionFilter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

RMA Session API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81RMA Session (NdRmaSession) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82RMA Session Properties (NdRmaSessionProperties) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84RMA View (NdRmaView) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84RMA View Properties (NdRmaViewProperties) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

CHAPTER 6 Base Repository and Version Management APIs . . . . . . . . . 89Storage Layer Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89About the Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Version Management Client Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Version Management System Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Administration Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Repository Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Repository Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Repository Entry Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92


Contents


C H A P T E R 1

ROM and PROM APIs

The FICO™ Blaze Advisor® business rules management system ROM and PROM APIs allow you to programmatically read, modify and create entries in the repository. You can use the APIs to navigate a repository, modify or create a project, create directories and add them to a project, inspect and modify the contents of a repository item, create fixed entities, and perform various versioning operations.

The PROM API provides the ability to load templates and providers and to load, create, and modify instances. The PROM API also supports the ability to programmatically create and modify entities with fixed content. The term fixed content, as used in this chapter, signifies that an entity’s content does not contain dynamic elements like placeholders.

The “Entity Creation” example contains Java code which demonstrates how to use the ROM and PROM APIs to create a named object and add it to an existing project; as well as how to create a new project with several entities. The example is located in <ADVISOR_HOME>/examples/repositories/ExamplesRepository/API Examples/PROM API/Entity Creation.

The Repository Object Model (ROM)The Repository Object Model (ROM), is a layer that is used to access the repository's raw data. ROM models the repository with its hierarchy of directories and items within the directories. It defines typing for repository items. ROM provides methods for connecting to the repository, navigating and finding items in the repository, as well as for reading and writing items. ROM accesses items only as raw data, which are represented as strings. All read and write operations access the repository directly, rather than being cached.

Connecting to a RepositoryThe NdRomConnectionManager interface provides methods to connect and disconnect from a repository. Pass an NdWorkspaceConnection object to the newRepositoryConnectionManager() method of NdRomFactory to obtain an NdRomConnectionManager instance. The connection context (NdRomConnectionContext) is used to access ROM once you are connected.

The example code below shows how to obtain a connection to a file-based repository.

//NdFileRepositoryConnection extends NdWorkspaceConnectionNdFileRepositoryConnection connection = new NdFileRepositoryConnection();


CHAPTER 1: ROM and PROM APIs

// Change the path to the repository as appropriate. The repository should exist.connection.setRepositoryFolder("C:/repository");// Connect to repositoryNdRomConnectionManager connectionMgr =

NdRomFactory.newRepositoryConnectionManager(connection);connectionMgr.connect();NdRomConnectionContext conContext = connectionMgr.getConnectionContext();NdRomDirectory romRoot = conContext.getRoot();

To disconnect from the repository, call the disconnect() method of NdRomConnectionManager. To shut down the connection manager, call its shutdown() method.

Exploring the ROM ModelThe organization of the repository is similar to that of a file system. It contains a hierarchy of directories with a single root directory. Directories contain items and other directories. A repository item, like a file in a file system, has content but does not contain other items or directories. Directories and items are both repository entries. This relationship is represented in the ROM API with the classes NdRomDirectory and NdRomItem, which both extend NdRomEntry.

A client can explore the ROM starting from the root directory, which can be obtained by calling the getRoot() method on NdRomConnectionContext. From the root, or any other directory, you can call getEntries() to get all directories and items contained in the directory.

// connContext is an NdRomConnectionContext// romRoot is the root directory of the repository.NdRomDirectory romRoot = connContext.getRoot(); NdRomEntry[] allEntriesInRepository = romRoot.getEntries();

If you know the location of a repository item, you can look up the entry by calling lookupEntry(NdLocation) on the directory. The location is specified from the root directory. NdLocation is discussed in “Specifying a Location (NdLocation)” on page 15.

NdLocation itemLocation = NdLocationFactory.createLocation("/Prom API Example/Cross-sell Rules/crossSell");

NdRomItem rulesetItem = (NdRomItem) romRoot.lookupEntry(itemLocation);

Repository Item Typing AttributesA repository schema element describes a particular type of repository item. The typing information consists of four attributes: the schema element type, its subtype, content type, and target. The type signifies the nature of the item; an SRL ruleset, for example. A subtype is a subcategory of the type. For example, a decision table is a subtype of an SRL ruleset. The content type specifies whether the item contains fixed content, or is a template, or a provider, or is an instance of the indicated type and subtype. The target indicates the purpose of the item. An item used in a rules project has an 'SRL' target. An item used for repository operations has a 'Repository' target.

Here is a list of repository items and their typing information by type, subtype, content type, and target.



Decision Tree Template: SRL ruleset, Decision tree, Template, SRLDecision Tree Instance: SRL ruleset, Decision tree, Instance, SRLRuleset Template Instance: SRL Ruleset, No subtype, Instance, SRLSRL Class: SRL Class, No subtype, Fixed, SRLSRL Function with Fixed Content: Function, No subtype, Fixed, SRLCustom Date Provider: Date, No subtype, Provider, SRLProject: Project, No subtype, Fixed, Repository

In the ROM, the four typing attributes are aggregated into NdRomSchemaElementInfo, which is accessed from NdRomSchemaElement. The schema elements are managed by NdRomSchemaManager. It contains a list of all schema elements known to the connected repository and can lookup the schema element for any repository item. NdRomSchemaManager is obtained from NdRomConnectionContext.

This code retrieves the type and subtype attributes of a repository item.

// connContext is an NdPromConnectionContext & rulesetItem is an NdRomItemNdRomSchemaManager schemaManager = connContext.getSchemaManager();NdRomSchemaElement schemaElement = schemaManager.lookupSchemaElement(rulesetItem);NdRomSchemaElementInfo info = schemaElement.getSchemaElementInfo();int type = info.getType();int subtype = info.getSubType();

NdRomSchemaManager is also used to obtain an NdRomSchemaElement of a particular type. You can obtain an instance of NdPromItemFactory from the schema element which is the factory associated with that particular type of repository item. The factory can be used to create an NdPromItem in a project from entity content.

/ project is an NdPromProjectNdPromSrlEnumerationContent enumeration =

NdPromBomConstructContentFactory.newSrlEnumerationContent(project);NdRomSchemaElement schemaElement = schemaManager.lookupSchemaElement(

TYPE_SRL_ENUMERATION, SUB_TYPE_NONE, CONTENT_TYPE_FIXED, TARGET_SRL);NdPromItemFactory factory = schemaElement.getItemFactory();NdPromItem enumItem = factory.newItem((NdPromEntity)enumeration, project);

...

The integer constants for the repository schema typing attributes, including those in the code above, are declared in the NdRomSchemaConstants interface.

Project Repository Object Model (PROM)The Project Repository Object Model (PROM), is a layer on top of the ROM that is used to access the objects in a repository with a project in context. The content of a repository item is represented as an object. The content is also cached in memory, which means explicit load and save operations are necessary to sync up the content in memory and that in storage.

The PROM Project (NdPromProject)A project, represented by NdPromProject, by definition includes a collection of references to repository directories and other projects which are subprojects of the



project. Such a definition effectively defines a scope, which includes all the directories included by this project, and all the directories included by its subprojects. An instance of NdPromProject gives access to all the repository entries in the scope. These repository directories and repository items and their contents form the PROM.

To create an instance of NdPromProject for an existing project repository item, first obtain an instance of NdRomProject by passing the location of the project repository item to the lookupEntry() method of the NdRomDirectory interface. Use NdPromProjectFactory, which is obtained from NdRomConnectionContext, to create the NdPromProject instance. The code below loads a PROM project from the workspace.

// connContext is an NdRomConnectionContext// “/directory” represents a directory directly under the repository rootNdRomDirectory root = connContext.getRoot();NdLocation location = NdLocationFactory.createLocation(“/directory/projectItem”);NdRomProject romProject = (NdRomProject)root.lookupEntry(location);NdPromProjectFactory factory = context.getProjectFactory();NdPromProject project = factory.createProject(romProject);

To create a new project at a location, the client should use the same project factory. The following is an example of creating a new project. The new project repository item is created in the directory.

NdLocation location = NdLocationFactory.createLocation(“/directory”);NdPromProjectFactory factory = context.getProjectFactory();NdPromProject project = factory.createProject(location);project.save();

The topics of loading and creating a project are discussed in greater detail in “Loading a PROM Project” on page 18 and “Creating a PROM Project” on page 17.

NdPromProject only defines a scope. It is not specific to any domain. It has a subinterface NdPromRulesProject, which can provide additional information and services specific to the rules domain.

Exploring the PROM ModelUsing the getDirectories(), getSubProjects(), and lookupEntry() methods defined in NdPromProject, the client can explore the PROM. The repository directory and repository item in the PROM are defined as NdPromDirectory and NdPromItem, which extend from NdRomDirectory and NdRomItem, respectively.

The PROM API builds on the raw access to the repository which is defined in ROM API by providing access to the repository with typing and caching. The getItemContent() method in NdPromItem returns a typed object. This is different from NdRomItem which has content that is always a String.

The content of a repository item is only loaded after the getItemContent() method is called. The content is loaded to cache. Once loaded, any change to the content is not persisted to the storage until the save() method of NdPromItem is called. Any change in the storage is not reflected in the loaded content until revert() is called and getItemContent() is called again to load the content from storage.



The addItem() method and removeItem() method in NdPromDirectory only affect the in memory object model until the save() method is called on the NdPromItem.

The following is an example of loading a repository item:

// project is an NdPromProjectNdLocation location = NdLocationFactory.createLocation(“item/location”);NdPromItem item = (NdPromItem)project.lookupEntry(location);NdPromItemContent content = item.getItemContent();

Here is an example of creating a repository item and adding it to a project directory.

// project is an NdPromProjectNdLocation location = NdLocationFactory.createLocation(“directory”);NdPromDirectory directory = (NdPromDirectory)project.lookupEntry(location);NdPromItem item = factory.newItem(content, project);directory.addItem(item);item.save();

Note that content is a specific type of NdPromItemContent, such as the NdPromEnumerationContent discussed in “Repository Item Typing Attributes” on page 8. factory is the specific NdPromItemFactory associated with that particular type of repository item, which is discussed in the same section. Refer to “Common ROM API and PROM API Tasks” on page 15 for several more examples of creating repository items. directory is an NdPromDirectory that has been previously added to the project, as described in “Creating Directories” on page 16.

The following is an example of deleting an existing repository item. Note that the item is removed in PROM and then saved in order to persist the change to storage.

// project is an NdPromProjectNdLocation parentLoc = NdLocationFactory.createLocation(“directory/item”);NdPromDirectory directory = (NdPromDirectory)project.lookupEntry(parentLoc);NdLocation itemLoc = NdLocationFactory.createLocation(“item/location”);NdPromItem item = (NdPromItem)project.lookupEntry(itemLoc);directory.removeItem(item);item.save();

PROM Item Content (NdPromItemContent)“NdPromItemContent is the content of a repository item. An instance of this interface represents what the content really is disregarding its persistent format. For example, if the content is an SRL ruleset, the content object is an instance of NdPromSrlRuleset although it may actually be persisted as a template.” (From the API Reference entry for the NdPromItemContent interface. The API Reference is available by selecting API Reference from the Builder Help menu.)

NdPromEntity (and its sub-interfaces)If the content of the repository item is an entity, the content object must be a specific instance of NdPromEntity. For example, if the content of the repository item is an SRL function, the content object is an instance of NdPromSrlFunction, which extends NdPromEntity.



More details of the entity API can be found in “Entity Object Model” on page 12.

NdPromTemplateIf the content of the repository item is an Innovator template of an entity, the content object must be an NdPromTemplate object. NdPromTemplate gives the client access to the templatized entity through getEntityContent() method, which returns a specific instance of NdPromEntityContent. For example, if the content of the repository item is an Innovator template of an SRL ruleset, getEntityContent() method returns an instance of NdPromSrlRulesetContent, which extends NdPromEntityContent.

NdPromInstanceIf the content of the repository item is an instance of template, the content object must be an NdPromInstance object. NdPromInstance gives the client access to the instantiation object model, i.e., a tree of instance nodes. It allows access to the entity resolved from this instance and its linked template. The resolved entity can be obtained through getResolvedEntity() method, which returns a specific instance of NdPromEntity. For example, if the content of the repository item is an Innovator instance of an SRL ruleset, getResolvedEntity() returns an instance of NdPromSrlRuleset, which extends NdPromEntity.

NdPromProviderIf the content of the repository item is a provider, the content object must be an NdPromProvider object. NdPromProvider gives client access to the provider's definition, including the provider class name.

Entity Object ModelThe entity object model is used to access entities and their fields. As described in “PROM Item Content (NdPromItemContent)” on page 11, an entity can be obtained as the content of an entity repository item loaded as an object in PROM. An entity can also be obtained as the templatized content of an Innovator template and as the resolved content of an Innovator instance.

Accessing Entity Content The entity object model contains two complementary sets of interfaces for accessing the content of entities. The API Reference refers to these sets of classes as the entity object model's "string-based" and "content-based" APIs.

The interfaces of the string-based API represent any field that is text in nature as a String. This set of interfaces is used to access entities that are not templatized, but are resolved entities. It provides read-only access. It is primarily used for inspecting the object model.

The interfaces of the content-based API represent any field that is text in nature by NdPromTextContent, which is a data structure that may contain dynamic elements like



placeholders. The subinterfaces of NdPromTextContent represent specialized text content. For example, the body of an SRL function is represented by NdPromSrlBodyTextContent. The content-based API is used to access templatized entities. It provides methods to read and write the content of both templatized and fixed-content entities.

These two sets of APIs are almost parallel to each other. The naming convention is that the interface names and method names in the content-based API have the word Content appended to their counterparts in the string-based API. For example, the content-based counterpart to the string-based interface NdPromSRLRuleset is NdPromSRLRulesetContent. NdPromSrlRule is the string-based correlary to NdPromSrlRuleContent, and so on.

The following code demonstrates how to access a ruleset using string-based interfaces. A ruleset is represented by the string-based NdPromSrlRuleset interface. The method getName() returns the ruleset name as a String.

// item is an NdPromItemNdPromSrlRuleset ruleset = (NdPromSrlRuleset) item.getItemContent();String name = ruleset.getName();

The getSrlRulesetItems() method returns the ruleset items as an array of NdPromSrlRulesetItem.

NdPromSrlRulesetItem[] items = ruleset.getSrlRulesetItems();

An SRL rule (NdPromSrlRule) is obtained from the array of ruleset items. NdPromSrlRule and the other types of ruleset items, such as NdPromSrlPattern, subclass NdPromSrlRulesetItem.

// assumes the ruleset item is a ruleNdPromSrlRule rule = (NdPromSrlRule) items[0];

The rule body (NdPromSrlRuleBody) is obtained from a rule in a ruleset that is not templatized using the getSrlRuleBody() method.

NdPromSrlRuleBody ruleBody = rule.getSrlRuleBody();

Here is code which performs similar work using the corresponding content-based interfaces. The ruleset name is obtained as an NdPromTextContent object. NdPromSrlRuleContent extends NdPromSrlRuleContent and represents an SRL rule which could be either templatized or contain fixed content. Similarly, the NdPromSrlRuleBodyTextContent ruleBody can contain templatized content or fixed content.

// item is an NdPromItemNdPromSrlRulesetContent ruleset = (NdPromSrlRulesetContent) item.getItemContent();NdPromTextContent name = ruleset.getNameContent();NdPromSrlRulesetItemContent[] items = ruleset.getSrlRulesetItemContents();// assumes the ruleset item content is a ruleNdPromSrlRuleContent rule = NdPromSrlRulesetItemContent[0];NdPromSrlRuleBodyTextContent ruleBody = rule.getRuleBodyContent();

As already mentioned, the content-based API contains methods for creating and modifying the entity content. Use the static newTextContent() method of the



NdPromTextContentFactory class to create NdPromTextContent for text-based entity properties such as name and comment.

ruleset.setNameContent (NdPromTextContentFactory.newTextContent("Ruleset name");rule.setNameContent (NdPromTextContentFactory.newTextContent("Rule name");rule.setCommentContent (NdPromTextContentFactory.newTextContent("// Sample rule");

This example uses the string-based API to find a particular rule in a ruleset, then it casts the rule to an NdPromSrlRuleContent object, which is content-based, in order to change the rule body content.

// project is an NdPromProjectNdLocation rulesetLocation = NdLocationFactory.createLocation("Cross-sell Rules/crossSell");NdPromItem rulesetPromItem = (NdPromItem)project.lookupEntry(rulesetLocation);NdPromSrlRuleset ruleset = (NdPromSrlRuleset) rulesetPromItem.getItemContent();NdPromSrlRulesetItem[] rulesetItems = ruleset.getSrlRulesetItems(); for (int i=0; i<rulesetItems.length; i++) {

if (rulesetItems[i] instanceof NdPromSrlRule) {String ruleName = ((NdPromSrlRule)rulesetItems[i]).getName();if (ruleName.equals("rule1")) {

// The string-based NdPromSrlRulesetItem ruleset item is cast to // content-based interfaces are used exclusively.NdPromSrlRuleContent rule = (NdPromSrlRuleContent) rulesetItems[i];// replace rule textNdPromSrlRuleBodyTextContent ruleBody =

NdPromSrlConstructContentFactory.newSrlRuleBodyContent("rule body replacement text");rule.setSrlRuleBodyContent(ruleBody);// print new rule textNdPromSrlRuleBodyTextContent ruleBodyTextContent = rule.getSrlRuleBodyContent();System.out.println("The replacement rule body text is” +

ruleBodyTextContent.generate());}

}}

SRL Entity Object ModelThe object model for SRL entities is in the com.blazesoft.template.repository.objects.rules package. It contains the interfaces for the SRL entities as well as various constructs like the expressions and statements.

The SRL entities include:

SRL ruleset (NdPromSrlRuleset)

The ruleset items within a ruleset (NdPromSrlRulesetItem), which are:

SRL rule (NdPromSrlRule)

SRL event rule (NdPromSrlEventRule)

SRL named object (NdPromSrlNamedObject)

SRL pattern (NdPromSrlPattern)

SRL variable (NdPromSrlVariable)

SRL function (NdPromSrlFunction)



SRL reason code list (NdPromSrlReasonCodeList)

For examples on how to create SRL entities, see “Creating an SRL Ruleset” on page 18, “Creating an SRL Enumeration (NdPromSrlEnumerationContent)” on page 24 and “Creating an SRL Function (NdPromSrlFunction)” on page 21.

Ruleflow Object ModelThe object model for ruleflow is in the com.blazesoft.template.repository.objects.flow package. It contains the interfaces for various ruleflow constructs including the ruleflow entity itself.

For an example of how to create a ruleflow, see “Creating a Ruleflow (NdPromFlowRuleflow)” on page 22.

Question Set Object ModelThe object model for question set is in the com.blazesoft.template.repository.objects.aai package. It contains the interfaces for various question set constructs including the question set itself. Both string-based API and content-based API exist for these constructs.

For an example of how to create a question set, see “Creating a Question Set (NdPromAaiQuestionSet)” on page 22.

Common ROM API and PROM API TasksThis section describes how to perform selected tasks using the ROM and PROM APIs. All the examples of creating entities are confined to entities that are not templatized; that is, they do not contain dynamic content.

Specifying a Location (NdLocation)The NdLocation interface describes the location of entities within a repository. The interface can describe the location of a repository item, which is referred to as an external location. The interface can also describe the location of an entity defined within a repository item. That type of location is called a compound location. It is composed of an external location describing the location of the repository item and an internal location which describes the location of the entity within the repository item. Internal locations are intended for use with templates, as they define the path from the root of the template document to an inner template or template parameter. The discussion of the NdLocation interface in this chapter is confined to external locations.

NdLocationFactory contains these static methods, as well as others, which are used to create an NdLocation.

static NdLocation createLocation(String[] components, boolean absolute) static NdLocation createLocation(String location)



In the first method, if the location is absolute (in which case the value of the boolean absolute is true), each element in the String array represents the name of one of the repository folders in a path from the root of the repository to the item in question, with the last element of the array being the storage name of the item. When the location is relative (the value of the boolean absolute is false), the elements in the String array represent a directory path that is processed in the context of another location.

The following two method calls are equivalent. They create an NdLocation that is a relative location.

NdLocation topDirectoryLocation = NdLocationFactory.createLocation(String[] {"Prom API Example"}, false);NdLocation topDirectoryLocation = NdLocationFactory.createLocation("Prom API Example");

These method calls are also equivalent. They create an NdLocation that is an absolute location.

// projectFactory is an NdPromProjectFactoryNdPromProject project = projectFactory.createProject(NdLocationFactory.createLocation(

new String[]{"PROM API Example", "Entity Creation"}, true));NdPromProject project = projectFactory.createProject(NdLocationFactory.createLocation(

"/PROM API Example/Entity Creation"));

In the first method call the components are elements in a String array. The latter method call represents the components in a String. The leading ‘/’ character indicates that the location is absolute.

Whether you should specify the location as absolute or relative will depend on the task at hand. As mentioned, relative locations are processed in the context of another location. When a directory is created the location is processed in the context of a parent directory or the root of the repository. For this reason, you must use a relative location when created a directory. When looking up a repository item or directory in a project using the lookupEntry() method of the NdPromProject interface, the location is relative since the project provides the context. The lookupEntry() method of the NdRomDirectory interface, however, looks up the entry from the root of the respository when the supplied location is absolute. If the location is relative the lookup is performed from the directory. The NdPromProject interface addDirectory() method, which is used to add a directory to the project, requires an absolute location. The Blaze Advisor API Reference entry for each method that takes an NdLocation parameter specifies whether to use an absolute or a relative location.

Creating DirectoriesYou can create directories with the createDirectory() method of the NdRomMutableDirectory class. NdRomMutableDirectory is a repository directory that is mutable. NdRomMutableDirectory extends NdRomDirectory. A mutable directory allows entries to be added or deleted. Recall that a directory contains entries, which are either other directories or repository items. NdRomMutableDirectory has methods for creating both. The deleteEntry() method physically deletes the given repository entry from the directory.

NdRomDirectory createDirectory(NdLocation location) NdRomItem createItem(NdLocation location)



void deleteEntry(String name)

To create a directory under the repository root directory, obtain the root NdRomDirectory by calling getRoot() on the repository context object (NdRomConnectionContext). Call createDirectory() on the root directory with the NdLocation parameter that specfies the location of the new directory. Whenever you create a directory, the location must be relative and contain only one element in the String array. The absolute parameter to createLocation() is false when the location is relative. A new directory is always created with the NdRomMutableDirectory object of the parent directory and therefore the location is relative to the parent directory. See “Specifying a Location (NdLocation)” on page 15 for discussion of relative and absolute locations.

// conContext is an NdRomConnectionContextNdRomDirectory romRoot = conContext.getRoot(); NdLocation topDirectoryLocation = NdLocationFactory.createLocation(

new String[]{"Prom API Example"}, false);NdRomDirectory topDirectory = ((NdRomMutableDirectory) romRoot).createDirectory(topDirectoryLocation);((NdRomMutableDirectory) topDirectory).setDisplayName("PROM API Example");

The directory is created in storage immediately. Note that romRoot must be cast to NdRomMutableDirectory. NdRomDirectory does not contain methods for creating repository entries. Set the directory's display name in the GUI with setDisplayName().

The steps are similar for creating a directory in another directory. First, create an NdLocation that is a relative location with one component. Pass the NdLocation object to the NdRomMutableDirectory createDirectory() method of the NdRomMutableDirectory object obtained for the parent directory.

// topDirectory is an NdRomDirectoryNdLocation projectLocation = NdLocationFactory.createLocation(new String[]{"Entity Creation"}, false);NdRomDirectory entityCreationDirectory =

((NdRomMutableDirectory) topDirectory).createDirectory(projectLocation);

Add the directory to a PROM project and obtain an NdPromDirectory.

// project is an NdPromProjectNdPromDirectory projectDirectory = project.addDirectory(entityCreationDirectory.getLocation());

The next section, “Creating a PROM Project” on page 17, completes the discussion of creating a directory structure for your project.

Creating a PROM ProjectTo create a PROM project (NdPromProject), first obtain an NdPromProjectFactory instance by calling the getProjectFactory() method of the connection context object (NdRomConnectionContext). Create an NdPromProject by passing an NdLocation to the factory's createProject() method. The NdLocation must be an absolute location. Specify each directory component in the String array, including the top level directory contained in the repository's root directory.

This code creates a PROM project in the Entity Creation directory and adds the directory to the project.



// Create a PROM project in the "Entity Creation" directory// conContext is an NdRomConnectionContext// entityCreationDirectory is an NdRomDirectoryNdPromProjectFactory projectFactory = conContext.getProjectFactory();NdPromProject project = projectFactory.createProject(NdLocationFactory.createLocation(

new String[]{"Prom API Example", "Entity Creation"}, true));project.setDisplayName("Entity Creation");// Add directory to projectNdPromDirectory projectDirectory = project.addDirectory(entityCreationDirectory.getLocation());

When the project is saved, a repository item of type Project is created in the Entity Creation directory (entityCreationDirectory). Note that the directory must still be added to the project by passing the directory location to the NdPromProject addDirectory() method. As you create more directories for your project, each directory must be added to the project in this manner.

In like fashion, you can add any directory within the repository to a project. The NdLocation must be an absolute location. All repository directories that are traversed from the repository root must be named in component parameter's String array.

NdLocation salariesLocation = NdLocationFactory.createLocation(new String[]{"Business Object Models","Java","Imported Java BOMs","Salaries"}, true);

NdPromDirectory salariesDirectory = project.addDirectory(salariesLocation);

Loading a PROM ProjectTo load an existing PROM project (NdPromProject), obtain an NdPromProjectFactory instance by calling the getProjectFactory() method on the connection context (NdRomConnectionContext). Create a location (NdLocation) which includes the directory components from the repository root as well as the PROM project repository item. The NdLocation must be an absolute location. Obtain an NdRomProject by calling lookupEntry() on the ROM root directory. Create the PROM project by passing the NdRomProject object to the factory’s createProject() method.

// conContext is an NdRomConnectionContextNdPromProjectFactory projectFactory = conContext.getProjectFactory();NdLocation projectLocation = NdLocationFactory.createLocation(

new String[]{"PROM API Example", "Entity Creation", "Entity Creation"}, true));NdRomProject romProject = (NdRomProject)romRoot.lookupEntry(projectLocation);NdPromProject project = projectFactory.createProject(romProject);

Note When you use the PROM API to work with multiple projects, you can release the resources that a project holds on to by calling the dispose() method of the NdPromProject interface. To access the project after calling dispose() you must load the project again.

Creating an SRL RulesetThe interfaces for creating a ruleset and ruleset items are defined by the object model for SRL entities in the blazesoft.template.repository.objects.rules package. The object model is introduced in “Entity Object Model” on page 12. The package contains a factory class named NdPromSrlConstructContentFactory which is used to create content-based objects for various SRL constructs.



The example in this section creates a fixed-content SRL ruleset. The public PROM APIs in the current release of the FICO Blaze Advisor do not support creating templatized content.

The NdPromSrlConstructContentFactory method newSrlRulesetContent() is used to create a ruleset, which is an NdPromSrlRulesetContent object. Among the methods available in NdPromSrlRulesetContent are setNameContent(), setCommentContent(), and insertSrlRulesetItemContentAt(). The later method is used to add the ruleset items to the ruleset.

Ruleset items (NdPromSrlRulesetItem) are contained within a ruleset. A ruleset is a repository item, but ruleset items are not repository items. The two senses of the term item should not confused. The content of ruleset items are represented by the NdPromSrlRulesetItemContent interface and include SRL rule (NdPromSrlRuleContent), SRL named object (NdPromSrlNamedObjectContent), SRL pattern (NdPromSrlPatternContent), SRL event rule (NdPromSrlEventRuleContent), and SRL variable (NdPromSrlVariableContent).

Creating a ruleset and ruleset items follows the general pattern of creating the ruleset with the rewSrlRulesetContent() of NdPromSrlConstructContentFactory interface; creating each ruleset item with the appropriate NdPromSrlConstructContentFactory method; creating the content for the ruleset item, usually with methods of NdPromSrlConstructContentFactory and NdPromTextContentFactory; setting the content on the ruleset item; and then inserting the ruleset item into the ruleset and saving the ruleset.

A rule is created with the newSrlRuleContent() method of the NdPromSrlConstructContentFactory interface. The newTextContent() and newSrlRuleBodyContent() methods of the NdPromTextContentFactory interface are used to create content for the rule name and rule body, respectively. After setting the content on the rule, the rule is added to the ruleset with the ruleset's insertSrlRulesetItemContentAt() method.

Both NdPromPattern (a pattern) and NdPromParameter (a parameter) extend the NdPromSrlTypedContent interface and contain typed content. Typed content can be a simple type reference to a primitive type, a class, or an enumeration. Typed content is obtained with the NdPromSrlConstructContentFactory interface newSrlGenericTypeContent() method. The typed content is set on the pattern with setSrlGenericTypeContent() method which is inherited from NdPromSrlTypedContent. The example code shows how to set a collection and a constraint on a pattern.

// project is an NdPromProject// Create 'Cross-sell' ruleset, with rule and two patterns, in 'Cross-sell Rules' directoryNdPromSrlRulesetContent ruleset = NdPromSrlConstructContentFactory.newSrlRulesetContent(project);ruleset.setNameContent(NdPromTextContentFactory.newTextContent("crossSell"));

// Create 'rule1' ruleNdPromSrlRuleContent rule = NdPromSrlConstructContentFactory.newSrlRuleContent(project);// set rule namerule.setNameContent(NdPromTextContentFactory.newTextContent("rule1"));// set rule body



String ruleBodyString = "if boughtProducts.primaryDemographic = promoProducts.primaryDemographic \n" +"then { \n" + "print(\"Shopper: \"shopper.name\", bought: \"boughtProducts.name\", rec: \"promoProducts.name).\n" + "shopper.recommendedProducts.append(promoProducts),\n ignore(boughtProducts).\n}";

NdPromSrlRuleBodyTextContent ruleBody = NdPromSrlConstructContentFactory.newSrlRuleBodyContent(ruleBodyString);

rule.setSrlRuleBodyContent(ruleBody);// A rule is a ruleset item (NdPromSrlRuleContent extends NdPromSrlRulesetItemContent)ruleset.insertSrlRulesetItemContentAt(rule, 0);

// Add 'shopper' parameter to rulesetNdPromSrlParameterContent parameter = NdPromSrlConstructContentFactory.newSrlParameterContent();parameter.setNameContent(NdPromTextContentFactory.newTextContent("shopper"));NdPromSrlGenericTypeContent parameterType =

NdPromSrlConstructContentFactory.newSrlGenericTypeContent("Shopper");parameter.setSrlGenericTypeContent(parameterType);ruleset.insertSrlParameterContentAt(parameter,0);

// Create 'boughtProducts' patternNdPromSrlPatternContent boughtPattern =

NdPromSrlConstructContentFactory.newSrlPatternContent(project);boughtPattern.setNameContent(NdPromTextContentFactory.newTextContent("boughtProducts"));NdPromSrlGenericTypeContent patternType =

NdPromSrlConstructContentFactory.newSrlGenericTypeContent("Product");boughtPattern.setSrlGenericTypeContent(patternType);// set collectionNdPromSrlCollectionTextContent collection =

NdPromSrlConstructContentFactory.newSrlCollectionContent("shopper.purchasedProducts");boughtPattern.setSrlCollectionContent(collection);// A pattern is a ruleset item (NdPromSrlPatternContent extends NdPromSrlRulesetItemContent)ruleset.insertSrlRulesetItemContentAt(boughtPattern, 0);

// Create 'promoProducts' patternNdPromSrlPatternContent promoPattern =

NdPromSrlConstructContentFactory.newSrlPatternContent(project);promoPattern.setNameContent(NdPromTextContentFactory.newTextContent("promoProducts"));//set the typeNdPromSrlGenericTypeContent patternType1 =

NdPromSrlConstructContentFactory.newSrlGenericTypeContent("Product");promoPattern.setSrlGenericTypeContent(patternType1);//set the constraintNdPromSrlConstraintTextContent constraint =

NdPromSrlConstructContentFactory.newSrlConstraintContent("promotion = true");promoPattern.setSrlConstraintContent(constraint);ruleset.insertSrlRulesetItemContentAt(promoPattern, 1);

// Create NdPromItem for the ruleset, add to a PROM directory and save.// schemaManager is an NdRomSchemaManagerNdRomSchemaElement schemaElement = schemaManager.lookupSchemaElement(TYPE_SRL_RULESET,

SUB_TYPE_NONE, CONTENT_TYPE_FIXED, TARGET_SRL);NdPromItemFactory rulesetFactory = schemaElement.getItemFactory();NdPromItem rulesetItem = rulesetFactory.newItem((NdPromItemContent)ruleset, project);// crossSellDiretory is an NdPromDirectorycrossSellDirectory.addItem(rulesetItem);rulesetItem.save();// project is an NdPromProjectproject.save();



Creating an SRL Function (NdPromSrlFunction)An SRL function (NdPromSrlFunction) is defined in the object model for SRL entities in the blazesoft.template.repository.objects.rules package. The package contains a factory class named NdPromSrlConstructContentFactory. To create a fixed-content SRL function, use the factory to create a function object (NdPromSrlFunctionContent) and set the function name. Define a String that contains the body of the function. Use the NdPromSrlConstructContentFactory factory again to create the function body as content-based NdPromSrlBodyTextContent from the String. Set the function body on the function object. Finally, create an NdPromItem for the function and add it to a project directory.

// Create 'main' function in 'Test' directoryNdPromSrlFunctionContent function =

NdPromSrlConstructContentFactory.newSrlFunctionContent(project);function.setNameContent(NdPromTextContentFactory.newTextContent("main"));String functionBodyString = "s1 is a Shopper initially { \n" +

" name = \"Chris Camper\", \n" +" purchasedProducts = an array of Product, \n" +" purchasedProducts.append(tent),\n" +" recommendedProducts = an array of Product.\n" +"}.\n" +"s2 is a Shopper initially { \n" +" name = \"Grace Gardener\", \n" +" purchasedProducts = an array of Product, \n" +" purchasedProducts.append(weeder),\n" +" recommendedProducts = an array of Product.\n" +"}.\n" +"s3 is a Shopper initially { \n" +" name = \"Harry Homeowner\", \n" +" purchasedProducts = an array of Product, \n" +" purchasedProducts.append(bigscreen),\n" +" recommendedProducts = an array of Product.\n" +"}.\n" +"s4 is a Shopper initially { \n" +" name = \"Samantha Socialite\", \n" +" purchasedProducts = an array of Product, \n" +" purchasedProducts.append(tiara),\n" +" recommendedProducts = an array of Product.\n" +"}.\n" +"for each Shopper do { \n" +" apply crossSell(it). \n" +" printRecommendations(it). \n" +"}.";

NdPromSrlBodyTextContent functionBody = NdPromSrlConstructContentFactory.newSrlBodyContent(functionBodyString);function.setSrlBodyContent(functionBody);// Create NdPromItem for function and add to "Test" directoryschemaManager = project.getRomConnectionContext().getSchemaManager();schemaElement = schemaManager.lookupSchemaElement(TYPE_SRL_FUNCTION, SUB_TYPE_NONE,

CONTENT_TYPE_FIXED, TARGET_SRL);NdPromItemFactory functionItemFactory = schemaElement.getItemFactory();NdPromItem functionItem = functionItemFactory.newItem((NdPromItemContent)function, project);testDirectory.addItem(functionItem);functionItem.save();



Creating a Ruleflow (NdPromFlowRuleflow)The factory class for creating various ruleflow constructs is NdPromFlowConstructContentFactory. To create a ruleflow with a flow and task, use the factory to create the ruleflow (NdPromFlowRuleflowContent), then set the name of the ruleflow, as NdTextContent, on the ruleflow object. Use the same factory to create a flow (NdPromFlowFlowContent) and set the flow on the ruleflow. Use NdPromFlowConstructContentFactory again to create a task (NdPromFlowTaskContent). Set name and implementation name on the task, then insert a parameter and flow input on the task. Insert the task into the flow. Finally, create an NdPromItem for the ruleflow and save it with the project.

// project is an NdPromProject// testDirectory is an NdPromDirectory that has been added to the projectNdPromFlowRuleflowContent ruleflow =

NdPromFlowConstructContentFactory.newFlowRuleflowContent(project);ruleflow.setNameContent(

NdPromTextContentFactory.newTextContent("newRuleflow"));

// Create a flow.NdPromFlowFlowContent flow =

NdPromFlowConstructContentFactory.newFlowFlowContent();ruleflow.setFlowFlowContent(flow);

// Create a task.NdPromFlowTaskContent task =

NdPromFlowConstructContentFactory.newFlowTaskContent();task.setNameContent(

NdPromTextContentFactory.newTextContent("newTask"));task.setImplementationNameContent(

NdPromTextContentFactory.newTextContent("newRuleset"));task.insertFlowParameterContentAt(

NdPromFlowConstructContentFactory.newFlowParameterContent("param1"), 0);task.insertFlowInputContentAt(

NdPromFlowConstructContentFactory.newFlowInputContent("foo"), 0);flow.insertFlowFlowItemContentAt(task, 0);

schemaManager = project.getRomConnectionContext().getSchemaManager();schemaElement = schemaManager.lookupSchemaElement(TYPE_RULEFLOW, SUB_TYPE_NONE,

CONTENT_TYPE_FIXED, TARGET_SRL);NdPromItemFactory factory = schemaElement.getItemFactory();NdPromItem item = factory.newItem((NdPromFlowRuleflow) ruleflow, project);testDirectory.addItem(item);item.save();

Note The getType() method in the NdPromFlowTask interface has been renamed getImplementationType().

Creating a Question Set (NdPromAaiQuestionSet)The factory class for creating content-based objects for various question set constructs is NdPromAaiConstructContentFactory. To create a question set with a question, use the factory to create the question set (NdPromAaiQuestionSetContent), then set the name and comment as NdTextContent on the question set. Create a question (NdPromAaiQuestionContent) with the same factory and set NdTextContent prompt



content on question, as well as NdPromAaiClassPropertyContent. Insert the question into the question set. Finally, create an NdPromItem for the question set.

// project is an NdPromProject// testDirectory is an NdPromDirectory that has been added to the projectNdPromAaiQuestionSetContent questionSet =

NdPromAaiConstructContentFactory.newAaiQuestionSetContent(project);questionSet.setNameContent(

NdPromTextContentFactory.newTextContent("newQuestion"));questionSet.setCommentContent(

NdPromTextContentFactory.newTextContent("Sample question set"));

// Add a question.NdPromAaiQuestionContent question =

NdPromAaiConstructContentFactory.newAaiQuestionContent();question.setPromptContent(

NdPromTextContentFactory.newTextContent("What is the driver's age?"));NdPromAaiClassPropertyContent classProperty =

question.getAaiClassPropertyContent();classProperty.setClassNameContent(

NdPromTextContentFactory.newTextContent("Driver"));classProperty.setPropertyNameContent(

NdPromTextContentFactory.newTextContent("age"));questionSet.insertAaiQuestionContentAt(question, 0);

schemaManager = project.getRomConnectionContext().getSchemaManager();schemaElement = schemaManager.lookupSchemaElement(TYPE_QUESTION_SET, SUB_TYPE_NONE,

CONTENT_TYPE_FIXED, TARGET_SRL);NdPromItemFactory factory = schemaElement.getItemFactory();NdPromItem item = factory.newItem((NdPromAaiQuestionSet) questionSet, project);testDirectory.addItem(item);item.save();

Creating an SRL Class (NdPromSrlClassContent)The com.blazesoft.template.repository.objects.bom package contains interfaces for the business object model, which includes the SRL class. The NdPromSrlClassContent interface provides content section-based read/write access to the properties of an SRL class definition. NdPromSrlClassContent class content is created with the newSrlClassContent() method of the NdPromBomConstructContentFactory class, which is included in the package. The insertSrlPropertyContentAt() method (inherited from NdPromSrlPropertiesContainerContent) is used to insert property content (NdPromSrlPropertyContent) into the class content (NdPromSrlClassContent). The newSrlPropertyContent() method of the NdPromBomConstructContentFactory class is used to create NdPromSrlPropertyContent. The name and type of the property content, which correspond to a field name and type, is set with the NdPromSrlPropertyContent interface setNameContent() and setSrlGenericType() methods.

This code creates class content for the SRL class, inserts a field definition into the content, and saves the class as a PROM item in the appropriate directory which has been previously added to the project.

NdPromSrlClassContent classContent = NdPromBomConstructContentFactory.newSrlClassContent(project);

NdPromTextContent className = NdPromTextContentFactory.newTextContent("SimpleSRLClass");



classContent.setNameContent(className);

NdPromSrlPropertyContent prop = NdPromBomConstructContentFactory.newSrlPropertyContent();

NdPromTextContent propName = NdPromTextContentFactory.newTextContent("customerName");prop.setNameContent(propName);NdPromSrlGenericTypeContent propType =

NdPromSrlConstructContentFactory.newSrlGenericTypeContent("string");prop.setSrlGenericTypeContent(propType);classContent.insertSrlPropertyContentAt(prop, 0);

// Save the new class.// project is an NdPromProject & targetDirectory is an NdPromDirectoryschemaElement = schemaManager.lookupSchemaElement(TYPE_SRL_CLASS, SUB_TYPE_NONE,

CONTENT_TYPE_FIXED, TARGET_SRL);factory = schemaElement.getItemFactory();NdPromItem classItem = factory.newItem((NdPromEntity)classContent, project);targetDirectory.addItem(classItem);classItem.save();

Creating an SRL Enumeration (NdPromSrlEnumerationContent)As noted in the previous section, the factory class for creating various content-based constructs in the business object model is NdPromBomConstructContentFactory, which is part of the com.blazesoft.template.repository.objects.bom package. To create an SRL enumeration and enumeration items, use the factory to create the enumeration object (NdPromSrlEnumerationContent), then set the name on the enumeration object. Use NdPromBomConstructContentFactory to create SRL enumeration items (NdPromSrlEnumerationItemContent) and insert each item into the enumeration. Create the NdPromItem for the enumeration and add the NdPromItem to an existing project directory and save.

// Create 'DemographicSegments' enumeration with four enumeration items.NdPromSrlEnumerationContent enumeration =

NdPromBomConstructContentFactory.newSrlEnumerationContent(project);// Create content-based NdPromTextContent text and set the enumeration name.NdPromTextContent enumName = NdPromTextContentFactory.newTextContent("DemographicSegments");enumeration.setNameContent(enumName);// Create SRL enumeration itemsNdPromSrlEnumerationItemContent enumItem1 =

NdPromBomConstructContentFactory.newSrlEnumerationItemContent("outdoorsman");NdPromSrlEnumerationItemContent enumItem2 =

NdPromBomConstructContentFactory.newSrlEnumerationItemContent("homeowner");NdPromSrlEnumerationItemContent enumItem3 =

NdPromBomConstructContentFactory.newSrlEnumerationItemContent("gardener");NdPromSrlEnumerationItemContent enumItem4 =

NdPromBomConstructContentFactory.newSrlEnumerationItemContent("socialite");// Insert the SRL enumeration items on the SRL enumerationenumeration.insertSrlEnumerationItemContentAt(enumItem1, 0);enumeration.insertSrlEnumerationItemContentAt(enumItem2, 1);enumeration.insertSrlEnumerationItemContentAt(enumItem3, 2);enumeration.insertSrlEnumerationItemContentAt(enumItem4, 3);

// Create the NdPromItem for the enumeration// project is an NdPromProjectNdRomSchemaManager schemaManager = project.getRomConnectionContext().getSchemaManager();NdRomSchemaElement schemaElement = schemaManager.lookupSchemaElement(TYPE_SRL_ENUMERATION,

SUB_TYPE_NONE, CONTENT_TYPE_FIXED, TARGET_SRL);NdPromItemFactory enumItemFactory = schemaElement.getItemFactory();



NdPromItem enumItem = enumItemFactory.newItem((NdPromEntity)enumeration, project);// Add the SRL enumeration to an existing project directory// projectDirectory is a NdPromDirectoryprojectDirectory.addItem(enumItem);// Save the SRL enumerationenumItem.save();


C H A P T E R 2

BOM Admin APIs

The FICO™ Blaze Advisor® business rules management system BOM Admin APIs allow you to o programmatically update imported external classes represented as BOM project-level item contents in a repository. The APIs enable you to obtain mapping information, customize a class name, or create and save a new XML BOM. This chapter provides an introduction to some of those capabilities. Consult the Blaze Advisor API Reference for more detailed information. The API Reference is available by selecting API Reference from the Builder Help menu.

Manipulating Imported External ClassesThere are two layers of admin APIs for imported external class management. The PROM layer BOM Admin APIs and the engine layer class admin APIs.

The BOM Admin APIs are used to programmatically access and manipulate the imported external classes represented in a Blaze Advisor repository as BOM PROM item contents. The engine layer APIs are used to manage the imported classes within an engine layer class provider resource.

You can use these APIs to add imported classes from an external object model resource, remove classes from the BOM and its associated class provider resource, customize the imported classes by renaming them in the BOM, and retrieve imported class mapping information.

Note The code snippets provided show how to use the APIs and are not necessarily complete working examples.

NdPromBomAdminThe main entry point for BOM manipulation is the NdPromBomAdmin class.

Package name: com.blazesoft.template.repository.admin

NdClassMappingInfoMapping information is used to provide the names of the raw input to the underlying BOM. This means that mapping information is different for each BOM supported by Blaze Advisor. For example, you would need to use the API differently to obtain mapping information for a Java BOM than to obtain mapping information for an XML BOM.

Package names:


CHAPTER 2: BOM Admin APIs

com.blazesoft.engine.rulescom.blazesoft.engine.rules.java (for NdJavaClassMappingInfo)com.blazesoft.engine.rule.xml (for NdXmlClassMappingInfo)

Example:

NdJavaClassMappingInfo ji = new NdJavaClassMappingInfo();

orNdXmlClassMappingInfo xi = new NdXmlClassMappingInfo();xi.setXmlSchema(“mySchema.xsd”);

NdClassNameCustomizingInfoIf you want to customize a class name during BOM manipulation, you use the NdClassNameCustomizingInfo class. The NdClassNameCustomizingInfo class has a name pair holder for the native class name and the customized Blaze Advisor class name.

Package name: com.blazesoft.engines.rules

Example:

NdClassNameCustomizingInfo ci = new NdClassNameCustomizingInfo();ci.setNativeClassName(“ACCT”);ci.setCustomizedAdvisorClassName(“ACCT_TYPE”);xi.setXmlSchema(“mySchema.xsd”);

You can provide an array of customization information to the mapping information.

Creating a New XML BOMUse the following APIs to create a new XML BOM.

Package names:com.blazesoft.template.repository.objects.bom.NdPromBomConstructContentFactorycom.blazesoft.template.repository.objects.NdPromTextContent

Example:..._bomType = 24; //XML BOM TypeNdPromExternalBomContent bomContent = NdPromBomConstructContentFactory.newExternalBomContent((NdPromRulesProject) _project, _bomType);NdPromTextContent pc = NdPromTextContentFactory.newTextContent(_bomItemName);bomContent.setNameContent(pc);...

Saving a New or Existing BOMUse the following APIs to save a new BOM or an existing BOM.

“Saving a New BOM”

“Saving an Existing BOM” on page 29.

Saving a New BOMYou can save a new BOM using the following API:



Package names:com.blazesoft.template.repository.PromItemContentcom.blazesoft.template.repository.PromItem

Example:

...//Save the BOM item-- needs to changeNdPromItemContent itemContent = (NdPromItemContent) bomContent;//Create a NdPromItem for the BOM and add it to a directoryschemaManager = project.getRomConnectionContext().getSchemaManager();schemaElement = schemaManager.lookupSchemaElement(TYPE_BUSINESS_OBJECT_MODEL, SUB_TYPE_XML_BOM, CONTENT_TYPE_FIXED, TARGET_SRL);NdPromItemFactory itemFactory = schemaElement.getItemFactory();NdPromItem promItem = itemFactory.newItem(itemContent, _project);

_projectDirectory.addItem(promItem);promItem.save();...

Saving an Existing BOMSave an existing BOM using the following API:

Package names:com.blazesoft.template.repository.PromItemContentcom.blazesoft.template.repository.PromItem

Example:

...//Save the BOM itemNdPromItemContent itemContent = (NdPromItemContent) bomContent;NdPromItem promItem = itemFactory,getItem();promItem.save();...

Add or Remove Items to or from Existing BOM(unexposed API)Add items to or remove items from an existing BOM using the following API....NdPromBomAdmin _bomAdmin = new NdPromBomAdmin();NdPromItem bomItem = (NdPromItem) _projectDirectory.lookupEntry(NdLocationFactory.createLocation(_bomItemName));NdPromExternalBomContent bomContent = (NdPromExternalBomContent) bomItem.getItemContent();NdClassMappingInfo mappingInfo = some mapping info..._bomAdmin.addImportedClasses(bomContent, mappingInfo);_bomAdmin.removeImportedClasses(bomContent, mappingInfo);...

Customizing a BOM(unexposed API)Customize a BOM using the following API....NdPromItem bomItem = (NdPromItem) _projectDirectory.lookupEntry(NdLocationFactory.createLocation(_bomItemName));NdPromExternalBomContent bomContent = (NdPromExternalBomContent) bomItem.getItemContent();


CHAPTER 2: BOM Admin APIs

NdClassMappingInfo mappingInfo = some mapping info with customizations... _bomAdmin.customizeImportedClasses(bomContent, mappingInfo);...


C H A P T E R 3

Metaphor APIs

The FICO™ Blaze Advisor® business rules management system Metaphor APIs provide programatic access to the Blaze Advisor metaphors: decision table, decision tree, and score model. The APIs enable you to examine and edit the contents of metaphor instances as well as create new instances. This chapter provides an introduction to some of those capabilities. Consult the Blaze Advisor API Reference for more detailed information. The API Reference is available by selecting API Reference from the Builder Help menu.

Loading a Metaphor InstanceThe initial steps for loading an instance is the same for each type of Blaze Advisor metaphor. The procedure for connecting to your repository and opening the project that contains your metaphor instance is detailed in Chapter 1, “ROM and PROM APIs.”

Once a project has been opened, you can load the metaphor instance in this fashion:

NdLocation location = NdLocationFactory.createLocation("directory/instanceFileName");NdPromItem promItem = (NdPromItem)(project.lookupEntry(location));NdPromItemContent content = promItem.getItemContent();NdInstantiationElement instantiationElt = null;if (content instanceof NdInstantiation) {

instantiationElt = (NdInstantiationElement)content;}

In the example code throughout this chapter instantiationElt will refer to the instance. If the instance is global (i.e. the metaphor instance is a direct child of a repository directory), then this is sufficient. The metaphor instance will be what instantiationElt refers to. Otherwise, you need to navigate the instance to find the instantiation element that corresponds to the metaphor instance, as shown here:

instanceElt = instantiationElt.safeLookup(metaphorInstanceName);

The NdMetaphorSupport class contains methods to determine which type of metaphor the instance is: isDecisionTableInstance(), isDecisionTreeInstance(), and isScoreModelInstance().

if (NdMetaphorSupport.isDecisionTableInstance(instanceElt)) {// execute code to deal with decision tables

}

Creating a Metaphor ModelEach metaphor model has a factory class for creating instances of its metaphor model.


CHAPTER 3: Metaphor APIs

NdDecTableModelFactory.createDecTableModel()Creates a new instance of a decision table model, returned as an NdDecTableModel.

NdDecTreeModelFactory.createDecTreeModel()Creates a new instance of a decision tree model, returned as an NdDecTreeModel.

NdScoreModelModelFactory.createScoreModelModel()Creates a new instance of a score model, returned as an NdScoreModelModel.

Each factory class has a method to set the instantiation element on the model.

For a decision table, call the NdDecTableModelFactory.setDecTableInstance() method.

For a decision tree, call the NdDecTreeModelFactory.setDecTreeInstance() method.

For a score model, call the NdScoreModelModelFactory.setScoreModelInstance() method.

The methods above may throw an NdMetaphorModelException in the event something is wrong with the instance and cannot be corrected. This is a terminal error, and will prevent the metaphor model from using the metaphor instance. These methods may also throw an NdMetaphorWarningException in case an erroneous situation was found, but could be corrected. A NdMetaphorModifiedException is thrown when the metaphor instance was modified by the metaphor model to fix possible problems. This would happen, for example, if the metaphor template was changed.

The decision table model instance decTableModel in the code below is used to edit the decision table, as described in the following section, “Decision Table Editing API” on page 32. Similar code is used to create decision tree and score model instances. These models are discussed in “Decision Tree Editing API” on page 34 and “Score Model Editing API” on page 37.

if (NdMetaphorSupport.isDecisionTableInstance(instanceElt)) {NdDecTableModel decTableModel = NdDecTableModelFactory.createDecTableModel();NdDecTableModelFactory.setDecTableInstance(decTableModel, instanceElt);

}

Decision Table Editing APITh NdDecTableModel interface provides methods for editing a decision table instance. NdDecTableModel includes methods for inserting and deleting columns and rows in the decision table instance, for obtaining the number of columns and rows, for moving columns and rows within the table, and for copy-and-paste of a range of cells.

The “Decision Table Import” example demonstrates how to use the Decision Table Editing APIs to create an instance of a single-axis (columns) decision table template and populate it with data obtained from a CSV file that was generated in Microsoft Excel. The example is located in <ADVISOR_HOME>/examples/ExamplesRepository/API Examples/Metaphor APIs/Decision Table Import.

The getTableInfo() method of NdDecTableModel returns an NdDecTableInfo object, which contains information about the layout of the decision table, including the number



of condition and action rows or columns in a decision table. The getTableLayout() method of NdDecTableInfo returns a constant that indicates the layout, such as NdDecisionMetaphorConstants.DECTABLE_LAYOUT_SINGLE_AXIS_COLS.

NdDecTableInfo tableInfo = decTableModel.getTableInfo();int layout = tableInfo.getTableLayout()

The setCellFieldValue() method sets the field value of the cell. A NdMetaphorModelException is thrown if the value is not of the appropriate type. For example, the exception is thrown if a value that is not a number is used in a cell that has a cell template display name that specifies a number, such as = 'integer'.

Several of the methods in NdDecTableModel access cells in a decision table by row and column coordinates. NdDecTableCellCoordinates represents the coordinates of a cell. This statement sets the field value of the cell at row 2, col 3 in a decision table. The cell template for this cell is = ‘string’, which has only one placeholder. The index of the placeholder, or field, within the cell is 0.

decTableModel.setCellFieldValue(new NdDecTableCellCoordinates(2, 3), 0, "Medical");

When you specify a numeric range, set the first number at placeholder index 0 and the second number at placeholder index 1 of the cell. The cell template display name for this cell is 'real1' < .. <= 'real2', which has two placeholders. These statements set the range 1.0 < .. <= 3.5 on the cell.

decTableModel.setCellFieldValue(new NdDecTableCellCoordinates(2, 3), 0, 1.0);decTableModel.setCellFieldValue(new NdDecTableCellCoordinates(2, 3), 1, 3.5);

The getCellInfo() method returns an NdDecTableCellInfo object that supplies all information necessary to render and edit a cell. The getTemplatesInfo() method of NdDecTableCellInfo returns an NdRangeTableCellTemplatesInfo object.

NdRangeTableCellTemplatesInfo has the getAllowedCellTemplateDisplayNames() method, which obtains the list of allowed cell template display names for the cell. The getCurrentCellTemplateDisplayName() method of NdRangeTableCellTemplatesInfo returns the cell template display name that is selected for the cell.

// getCellInfo(int row, int column)NdDecTableCellInfo cellInfo = decTableModel.getCellInfo(2, 3);String cellTemplateDisplay Name =

cellInfo.getTemplatesInfo().getCurrentCellTemplateDisplayName();

The NdDecTableCellInfo method getRenderingInfo() returns an NdRangeTableCellRenderingInfo object. The isEmpty() method returns true if the cell has no content. The isLabel() methods indicates whether the cell contains a label. The getRole() method of the NdRangeTableCellRenderingInfo returns a constant that indicates the role of the cell.

The selectCellTemplate() method selects the cell template display name on the cell at the specified coordinates. This process is called binding. The cell template display name selected must be one of the allowed cell templates specified for the cell, just as a user in the GUI selects a cell template from a drop-down list of allowed cell templates. The allowed cell templates have been defined in the decision table wizard or manually in



the decision table template designer. A NdMetaphorModelException is thrown if the cell template is not allowed or if the same cell template is already defined for that cell.

decTableModel.selectCellTemplate(new NdDecTableCellCoordinates(row, col), "= 'real'");

Example: Display an Overview of a Decision TableThis example code loops though the rows and columns of a decision table and lists the label or role for each cell.

for (int row = 0; row < decTableModel.getRowCount(); row++) {for (int col = 0; col < decTableModel.getColumnCount(); col++) {

NdDecTableCellInfo info = decTableModel.getCellInfo(row, col);NdRangeTableCellRenderingInfo renderingInfo = info.getRenderingInfo();if (renderingInfo.isEmpty()) {

System.out.print(" ");}else if (renderingInfo.isLabel()) {

System.out.print("H");}else {

switch (renderingInfo.getRole()) {case NdDecisionMetaphorConstants.METAPHOR_ACTION:

System.out.print("A");break;

case NdDecisionMetaphorConstants.METAPHOR_CONDITION:System.out.print("C");break;

}}

}}

Decision Tree Editing APIThe NdDecTreeModel interface provides methods for editing a decision tree instance in the customary tree format as a network of nodes and links. The operations you perform when editing a decision tree in the GUI have correlary methods in the API which are used in a fashion that should be familiar to you.

To begin editing a decision tree, obtain an NdDecTreeModel instance as described in “Loading a Metaphor Instance” on page 31. The code for obtaining the instance is part of the decision tree example in “Example: Create a Subtree” on page 36

The root node of a decision tree is obtained by creating an instance of NdDecTreePath. This class represents a path. The location of a node in a tree is represented by an NdDecTreePath path to the node. You can begin traversing the nodes of a tree by using the getNodeOutgoingNodeAt() method of NdDecTreeModel to obtain the path of one of the node's child nodes; and then continue traversing the tree via one of its child nodes, and so on. The second parameter to the getNodeOutgoingNodeAt() method is the index (base-0) of the child.

// decTreeModel is an NdDecTreeModelNdDecTreePath root = new NdDecTreePath();NdDecTreePath path1 = decTreeModel.getNodeOutgoingNodeAt(root, 0);NdDecTreePath path2 = decTreeModel.getNodeOutgoingNodeAt(path1, 0);



path2 is the first child of the first child of the root node. For the decision tree diagramed below, that is the path to the "Model Year" node for "Charger".

The image below depicts a portion of the decision tree in the “Decision Tree with Patterns” example in <ADVISOR_HOME>/examples/repositories/ExamplesRepository/Metaphors and Templates/Decision Trees/Decision Tree with Patterns.

You can obtain the incoming link condition value ("Charger") and the node label ("Model Year") with these methods:

// returns "Charger"String condition = decTreeModel.getIncomingLinkConditionValue(path2,0));// returns "Model Year"String label = decTreeModel.getNodeLabel(path2));

The “incoming link selected condition format label” is the name of template that is used with the incoming link condition value. Use the getIncomingLinkSelectedConditionFormatLabel() method to obtain it.

//returns "Model = 'string'"String format = decTreeModel.getIncomingLinkSelectedConditionFormatLabel(path2));

You can examine a template to determine the number of placeholders. There is one placeholder for a string value in Model = 'string'. You can use the setIncomingLinkConditionValue() method to change the value of the incoming link condition from "Charger" to "Corvette". The middle parameter is the placeholder index.

decTreeModel.setIncomingLinkConditionValue(path2, 0, "Corvette");

The set of allowed condition group labels for outgoing links for this node is obtained with the getAllowedConditionGroupLabelsForOutgoingLinks() method.

// returns "Make", "Model", "Model Year"String[] allowedLabels =

decTreeModel.getAllowedConditionGroupLabelsForOutgoingLinks(path2);

You can change the condition group to any of the allowed values using the selectConditionGroupForOutgoingLinks() method.

decTreeModel.selectConditionGroupForOutgoingLinks(path2, "Model Year");

Call the getNodeOutgoingLinksCount() method to obtain the number of outgoing links.

// returns: 2int count = decTreeModel.getNodeOutgoingLinksCount(path2));

This example code uses the getNodeOutgoingNodeAt() method to obtain the first outgoing child node (path3) of the node at path2.

NdDecTreePath path3 = decTreeModel.getNodeOutgoingNodeAt(path2, 0);



NdDecTreeNodeRenderingInfo contains a variety information about a node. We learn that path3, is an action node.

NdDecTreeNodeRenderingInfo renderInfo = decTreeModel.getNodeRenderingInformation(path3);// Prints: "Is Rating: 4 an action node? true"System.out.println("Is " + renderInfo.getLabel() + " an action node? " +

renderInfo.isActionNode());

The getIncomingLinkAllowedConditionFormatLabels() method of NdDecTableModel returns an array of the allowed incoming link condition format labels for path3.

// returns:// "Model Year = 'integer'", "Model Year > 'integer'", "Model Year < 'integer'",// "Model Year >= 'integer'", "Model Year <= 'integer',// "Model Year 'integer1' <= .. <= 'integer2', "otherwise"String[] allowedFormats = decTreeModel.getIncomingLinkAllowedConditionFormatLabels(path3);

To change the condition to 1962 - 1964, select the appropriate condition format label from the allowed list. Then, set the value on each placeholder separately.

decTreeModel.selectIncomingLinkConditionFormat(path3,"Model Year 'integer1' <= .. <= 'integer2'");

decTreeModel.setIncomingLinkConditionValue(path3,0, "1962");decTreeModel.setIncomingLinkConditionValue(path3,1, "1964");

To obtain the current action value (the rating), use the getActionValue() method.

// returns: 4int actionValue = decTreeModel.getActionValue(path3, 0, 0));

To change the rating from 4 to 3 and set the node label appropriately, use this code.

decTreeModel.setActionValue(path3, 0, 0, "3.0");decTreeModel.setNodeLabel(path3, "Rating: 3");

Example: Create a SubtreeThis example removes a subtree of nodes from the example decision tree discussed in the previous section. It then re-constructs the entire subtree. The example also demonstrates how to connect to the repository, find the decision tree instance repository item, and how to use NdDecTreeModelFactory to obtain an instance of NdDecTreeModel.

public class ReconstructSubtree implements NdRomSchemaConstants{

public static void main(String[] argv) throws Exception, NdMetaphorModelException

{

NdFileRepositoryConnection connection = new NdFileRepositoryConnection();// change the path to your repository as appropriateconnection.setRepositoryFolder("C:/repositories/ExamplesRepository");NdRomConnectionManager connectionMgr =

NdRomFactory.newRepositoryConnectionManager(connection);connectionMgr.connect();NdRomConnectionContext conContext = connectionMgr.getConnectionContext();NdRomDirectory romRoot = conContext.getRoot();NdRomProject romProject = (NdRomProject)romRoot.lookupEntry( NdLocationFactory.createLocation(

"/Metaphors and Templates/Decision Trees/Decision Tree with Patterns/Decision Tree with Patterns_java"));



NdPromProjectFactory projectFactory = conContext.getProjectFactory();NdPromProject project = projectFactory.createProject(romProject);NdPromItem decisionTreeInstanceItem = (NdPromItem)project.lookupEntry(

NdLocationFactory.createLocation("Decision Tree with Patterns/oldCarsDecisionTree Instance"));NdPromItemContent content = (NdPromItemContent) decisionTreeInstanceItem.getItemContent();NdDecTreeModel decTreeModel = null;if (NdMetaphorSupport.isDecisionTreeInstance((NdInstantiationElement)content)) {

decTreeModel = NdDecTreeModelFactory.createDecTreeModel();}else {

System.exit(1);}NdDecTreeModelFactory.setDecTreeInstance(decTreeModel, (NdInstantiationElement)content);NdDecTreePath root = new NdDecTreePath();NdDecTreePath path1 = decTreeModel.getNodeOutgoingNodeAt(root, 0);NdDecTreePath path2 = decTreeModel.getNodeOutgoingNodeAt(path1, 0);NdDecTreeNodeRenderingInfo renderInfo = decTreeModel.getNodeRenderingInformation(path2);

// TASK: Delete the subtree at this node; then re-create it.decTreeModel.deleteSubtree(path2);NdDecTreePath newPath = decTreeModel.insertNewNode(path1, 0, "Model");decTreeModel.selectConditionGroupForOutgoingLinks(newPath, "Model Year");decTreeModel.selectIncomingLinkConditionFormat(newPath,"Model = 'string'");decTreeModel.setIncomingLinkConditionValue(newPath,0, "Charger");// first conditionNdDecTreePath cond1 = decTreeModel.insertNewNode(newPath, 0, "Model Year");decTreeModel.selectIncomingLinkConditionFormat(cond1,"Model Year = 'integer'");decTreeModel.setIncomingLinkConditionValue(cond1,0, "1968");decTreeModel.insertAction(cond1, 0);decTreeModel.selectActionFormat(cond1, 0, "adjustRating(arg0, ...) ");decTreeModel.setActionValue(cond1, 0, 0, "4.0");decTreeModel.setNodeLabel(cond1, "Rating: 4");// second conditionNdDecTreePath cond2 = decTreeModel.insertNewNode(newPath, 1, "Model Year");decTreeModel.selectIncomingLinkConditionFormat(cond2,"Model Year < 'integer'");decTreeModel.setIncomingLinkConditionValue(cond2,0, "1968");decTreeModel.insertAction(cond2, 0);decTreeModel.selectActionFormat(cond2, 0, "adjustRating(arg0, ...) ");decTreeModel.setActionValue(cond2, 0, 0, "0.0");decTreeModel.setNodeLabel(cond2, "Rating: 0");decisionTreeInstanceItem.save();project.save();

}}

Score Model Editing APIThe NdScoreModelModel interface provides the methods for editing a score model instance. Most of the methods get and set string and integer values on an instance using indices to characteristics, to the bins within characteristics, and to the ranges within bins. For example, to obtain the label of the first characteristic in the “Academic Score” score model, supply the index value 0 (base-0) as the parameter to getCharacteristicLabel().

// returns: "GPA_Score"int chr = 0;String characteristicLabel = scoreModel.getCharacteristicLabel(chr));



Similarily, to obtain the label of the same characteristic’s first bin, supply the index of characteristic and the index of the first bin (0) as parameters to the getBinLabel() method.

// returns: "Between 3.6 and 4.0"int bin = 0;String binLabel = scoreModel.getBinLabel(chr, bin));

To obtain the number of characteristics in the score model and number of bins defined for a particular characteristic, use the getCharacteristicCount() and getBinCount() methods.

// returns: 4int characteristicCount = scoreModel.getCharacteristicCount();// returns: 5 int binCount = scoreModel.getBinCount(chr);

The Academic Score Instance file is part of the “Basic Score Model” example in <ADVISOR_HOME>/examples/repositories/ExamplesRepository/Metaphors and Templates/Score Models/Basic Score Model.

The NdScoreModelModel interface includes methods to add and delete characteristics and bins. Other methods get and set values for: characteristic labels and descriptions, the characteristic baseline score, the bin label, and the score weight and reason code for a bin. Those methods are: addNewCharacteristic(), insertNewCharacteristic(), deleteCharacteristic(), addNewBin(), insertNewBin(), deleteBin(),



getCharacteristicLabel(), setCharacteristicLabel(), getCharacteristicDescription(), setCharacteristicDescription(), getCharacteristicBaselineScore(), setCharacteristicBaselineScore(), getBinLabel(), setBinLabel(), getBinScoreWeight(), setBinScoreWeight(), getBinReasonCodeName(), and setBinReasonCodeName().

Each bin in a score model contains one or more ranges. The NdRangeTableCellTemplatesInfo class is used to supply information about the current cell template used by a range table cell, as well as the allowed cell templates for the cell. To obtain a cell’s range format template, first call getRangeFormatTemplatesInfo() to obtain an NdRangeTableCellTemplatesInfo instance, then call getCurrentCellTemplateDisplayName() on the instance. This example code obtains the range cell template used in the “Between 3.6 and 4.0” bin. The template defines placeholders for two real values.

int range = 0;NdRangeTableCellTemplatesInfo templatesInfo =

scoreModel.getRangeFormatTemplatesInfo(chr, bin, range);// returns: "GPA_Score 'real1' <= .. <= 'real2'"String cellTemplate = templatesInfo.getCurrentCellTemplateDisplayName());

The NdRangeTableCellRenderingInfo class is used to supply the information necessary to render a table range cell. To get the values for the placeholders in a range, obtain an NdRangeTableCellRenderingInfo instance by calling getRangeRenderingInfo(). The getValue() of NdRangeTableCellRenderingInfo returns the placeholder values in a String array.

NdRangeTableCellRenderingInfo renderingInfo =scoreModel.getRangeRenderingInfo(chr, bin, range);

// returns: “3.6” and “4”String[] cellPHValues = renderingInfo.getValues();

In the example score model, the GPA range is between 3.6 and 4.0, inclusive. Suppose you want to change the bin to accomodate some advanced placement students whose GPA can exceed 4.0. You will change the bin label of the “Between 3.6 and 4.0” bin to “Greater than 3.6”, as well as replace the cell range template and placeholder value.

You may want to begin by obtaining the list of allowed cell template display names by calling getAllowedCellTemplateDisplayNames() on the NdRangeTableCellTemplatesInfo object.

String allowedTemplates[] = templatesInfo.getAllowedCellTemplateDisplayNames();for (int template = 0; template < allowedTemplates.length; template++) { System.out.println(allowedTemplates[template]);}

For the example, the print output of this code is:

GPA_Score 'real1' <= .. < 'real2'GPA_Score > 'real'GPA_Score < 'real'GPA_Score >= 'real'GPA_Score <= 'real'GPA_Score 'real1' < .. <= 'real2'GPA_Score 'real1' < .. < 'real2'



The appropriate cell template is GPA_Score >= 'real': GPA is greater than the placeholder value, inclusive. For the example, the value of the placeholder will be “3.6”. The following code sets the new bin label, selects the appropriate template for range cell, and sets the value of the single placeholder defined in the template.

scoreModel.setBinLabel(chr, bin, "Greater than 3.6");scoreModel.selectRangeFormat(chr, bin, range, "GPA_Score >= 'real'");scoreModel.setRangeFieldValue(chr, bin, range, 0, "3.6");

After running the completed API application and reopening the project in the GUI, you can confirm that the bin is redefined.

The NdScoreModelModel interface has a several other methods that pertain to ranges which have not been discussed, including: getRangeCount(), getRangeDescription(), deleteRange(), and insertNewRange().

The NdScoreModelModel interface has methods which are used to move characteristics, bins, and ranges in a score model. Those methods are: moveBinUp(), moveBinDown(), moveCharacteristicsUp(), moveCharacteristicsDown(), moveRangeUp(), moveRangeDown().

Example: List Contents of a Score ModelThe example code below can be used with any score model to list all of the model’s characteristics and bins; as well the range cell template names defined for each bin and the corresponding placeholder values.

NdRangeTableCellTemplatesInfo templatesInfo;NdRangeTableCellRenderingInfo renderingInfo;String[] cellPHValues;

int characteristicCount = scoreModel.getCharacteristicCount();for (int chr = 0 ; chr < characteristicCount; chr++) { System.out.println("\n" + "Characteristic: " + scoreModel.getCharacteristicLabel(chr)); int binCount = scoreModel.getBinCount(chr); for (int bin = 0; bin < binCount; bin++) { System.out.print(" Bin #" + bin + " '" + scoreModel.getBinLabel(chr, bin)); System.out.print("' Weight: " + scoreModel.getBinScoreWeight(chr, bin));



System.out.println(" Reason Code: " + scoreModel.getBinReasonCodeName(chr, bin)); int rangeCount = scoreModel.getRangeCount(chr, bin); for (int range = 0; range < rangeCount; range++) { templatesInfo = scoreModel.getRangeFormatTemplatesInfo(chr, bin, range); System.out.print(" "); System.out.println(templatesInfo.getCurrentCellTemplateDisplayName() + " ("); renderingInfo = scoreModel.getRangeRenderingInfo(chr, bin, range); cellPHValues = renderingInfo.getValues(); for (int ph = 0; ph < cellPHValues.length; ph++) { System.out.print(cellPHValues[ph]); if (ph < cellPHValues.length - 1) { System.out.print(" - "); } } System.out.println(")"); } }}

This is the output of the code when run against the “Academic Score” score model:

Characteristic: GPA_ScoreBin #0 'Between 3.6 and 4.0' Weight: 50 Reason Code: ACAD01

GPA_Score 'real1' <= .. <= 'real2' (3.6 - 4)Bin #1 'Between 2.9 and 3.6' Weight: 30 Reason Code: ACAD02

GPA_Score 'real1' <= .. < 'real2' (2.9 - 3.6)Bin #2 'Between 2.1 and 2.9' Weight: 20 Reason Code: ACAD03

GPA_Score 'real1' <= .. < 'real2' (2.1 - 2.9)Bin #3 'Less than 2.1 ' Weight: 5 Reason Code: ACAD05

GPA_Score 'real1' <= .. < 'real2' (0 - 2.1)Bin #4 'All Other' Weight: 0 Reason Code: UEXP

Characteristic: SAT_ScoreBin #0 'Greater than 1400' Weight: 50 Reason Code: ACAD01

SAT_Score >= 'real' (1,400)Bin #1 'Between 1200 and 1400' Weight: 30 Reason Code: ACAD02

SAT_Score 'real1' <= .. < 'real2' (1,200 - 1,400)Bin #2 'Between 1000 and 1200' Weight: 20 Reason Code: ACAD03

SAT_Score 'real1' <= .. < 'real2' (1,000 - 1,200)Bin #3 'Between 800 and 1000' Weight: 10 Reason Code: ACAD04

SAT_Score 'real1' <= .. < 'real2' (800 - 1,000)Bin #4 'Less than 800' Weight: 5 Reason Code: ACAD05

SAT_Score 'real1' <= .. < 'real2' (0 - 800)Bin #5 'All Other' Weight: 0 Reason Code: UEXP

<..portion removed..>Characteristic: Academic HonorsBin #0 'National Honors' Weight: 50 Reason Code: ACAD01

Academic Honors = 'string' (AP_Scholar)Academic Honors = 'string' (National_Merit_Scholar)Academic Honors = 'string' (National_Honors_Scholar)

Bin #1 'Local Honors' Weight: 40 Reason Code: ACAD01Academic Honors = 'string' (Honor_Roll)Academic Honors = 'string' (Deans_Award)Academic Honors = 'string' (Citizenship_Award)

Bin #2 'Service Awards' Weight: 20 Reason Code: ACAD02Academic Honors = 'string' (Merit_Award)

Bin #3 'No Awards' Weight: 0 Reason Code: ACAD06Academic Honors = 'string' (none)

Bin #4 'All Other' Weight: 0 Reason Code: UEXP


C H A P T E R 4

Custom Provider API

This chapter is an introduction to understanding and developing FICO™ Blaze Advisor® business rules management system custom providers. The topics in this chapter include:

“Responsibilities of Provider Classes”

“Overview of the Custom Provider API” on page 44

“Creating Custom Provider Classes” on page 47

“The Example Base Class” on page 55

“Custom Provider Implementation Guidelines” on page 56

Responsibilities of Provider ClassesBlaze Advisor provider classes are invoked by the Innovator engine as part of the process of generating SRL and other content from a template and an instantiation file. In the case of a rule template, the template file is responsible for defining the logical structure of the rules, and for defining the placeholders within that structure which allow the rules to be modified. The instantiation file provides the values that will be supplied for the placeholders when content is generated from a template's content section. Providers are responsible for providing the Innovator engine with the values necessary to instantiate a template that contains value holders. When a template contains only fixed content and no values holders, then the data the Innovator engine processes comes from the fixed content section and providers are not involved. Providers must implement the following functions:

They are responsible for any transformation of values that should occur when a template is resolved against an instantiation. Provider beans are invoked by the Innovator engine during the resolving process and are passed a value retrieved from the instantiation object model.

They are responsible for verifying that the value to be passed back to the Innovator engine is of the correct type.

Certain templates might require that the values supplied to the template be constrained to being one value out of a set of enumerated values. This is the case with the custom providers that are discussed in this chapter. If a provider is supplying values for such a template, they must implement an additional interface, the NdConstrainedListProvider interface, which allows the Innovator engine to determine what the constraints are. The provider should return a list of the values that are acceptable.


CHAPTER 4: Custom Provider API

Certain templates might require that the behavior of a provider is customizable. This is the case with value holders in templates (defined in the parameters element of the XML template document) which optionally override the arguments passed to providers by the Innovator engine. The example custom providers discussed in this chapter, as well as the example custom providers in the <ADVISOR_HOME>/examples/customProviders/java/stateProvince directory, demonstrate the use of arguments to customize how the provider processes values.

Overview of the Custom Provider APIThis section provides an overview of the most important classes and interfaces of the Custom Provider API for building custom providers. This overview does not describe all methods in the classes and interfaces. Refer to the API Reference for information on these methods. The API Reference for the Innovator Custom Provider API is available by selecting API Reference from the Builder Help menu.

NdTemplateValueProvider InterfaceAll providers implement the NdTemplateValueProvider interface. The interface defines the basic features of a provider. The interface includes conversion methods which every provider must support. The methods allow the values passed in from the Innovator engine to be transformed in a manner determined by the provider. The convertToDisplayValue() method returns the value that should be used for display purposes in an RMA for a given instantiation value. Conversely, convertFromDisplayValue() returns the value that should be stored in the instantiation object for a given display value. (The instantiation object is the binary representation of the instantiation file.) The convertToContentValue() method is used to convert an instantiation value to the content value. However, when the instantiation value and SRL value are the same, which is usually the case with custom providers, no translation occurs and the method simply returns the instance value that is passed to it.

An NdProviderContext object is an argument in all of the methods of this interface. The context argument allows the provider to obtain information about the context in which the provider is being invoked. The NdProviderContext class includes the getContentLocale() method which returns locale information as a java.util.Locale object. The convert methods can use the locale information to perform locale-based conversion.

The setArgs() method sets the values of control variables that customize the behavior of the provider. For a discussion on designing custom providers with arguments see “Creating Custom Provider Classes” on page 47.

The validateInstantiationValue() method returns true if the supplied value from the instantiation object satisfies all of the constraints that the provider has placed on the value. Your supplied instantiation value must be valid. Therefore this method should return true.

Other methods return descriptive information about the provider to the Innovator engine. getProviderType() returns the type of the provider class as a String.



getValueType() returns a constant which indicates the type of value provided by the provider.com.blazesoft.template.engine public interface NdTemplateValueProvider{

public void checkInstantiationValue(NdProviderContext context, String instantiationValue);public String convertFromDisplayValue(NdProviderContext context, Object displayValue);public String convertFromJavaObject(NdProviderContext context, Object javaObject);public String convertToContentValue(NdProviderContext context, String instantiationValue);public Object convertToDisplayValue(NdProviderContext context, String instantiationValue);public Object convertToJavaObject(NdProviderContext context, String instantiationValue);public Class getDisplayValueClass(NdProviderContext context);public String getProviderType(NdProviderContext context);public Class getValueClass(NdProviderContext context);public int getValueType(NdProviderContext context);public void reset(NdProviderContext context);public void setArgs(NdProviderContext context, NdProviderStaticArg[] args);

}

NdDefaultTemplateValueProviderNdDefaultTemplateValueProvider is an abstract class that provides default implementations of the methods in the NdTemplateValueProvider interface. The convert methods (convertToDisplayValue(), etc.) pass values without change. validateInstantiationValue() does not apply any constraints on the instantiation value. It returns true for any instantiation value passed to it. setArgs() does not process any arguments.

As a convenience, providers can subclass this class and override only those methods needed to define their specific functionality.

NdConstrainedListProvider InterfaceNdConstrainedListProvider is a subinterface to the NdTemplateValueProvider interface. This interface is implemented by a provider when the value it provides must be constrained to one of a discrete set of values.

The getAllowedInstantiationValues() method returns an array of all the values that can be legally stored in the nodes of the instantiation object for which the provider is providing values. The getAllowedDisplayValues() method returns an array of all the values that can be legally displayed for the nodes of the instantiation object for which the provider is providing values. The getAllowedJavaValues() method returns an array of all values that can be legally supplied to a Java client for the nodes of the instantiation object. Each method should return null if the provider does not implement the constraint that the value be a member of a set of discrete values.com.blazesoft.template.engine public interface NdConstrainedListProvider extends NdTemplateValueProvider{

public String[] getAllowedInstantiationValues(NdProviderContext context);



public Object[] getAllowedDisplayValues(NdProviderContext context);public Object[] getAllowedJavaValues(NdProviderContext context);

}

NdDefaultConstrainedListProviderNdDefaultConstrainedListProvider is an abstract class that extends NdDefaultTemplateValueProvider and implements the NdConstrainedListProvider interface. It provides default implementations for two of the methods in the NdConstrainedListProvider interface, getAllowedDisplayValues() and getAllowedJavaValues(). Providers that extend NdDefaultContrainedListProvider must implement getAllowedInstantiationValues(). The getAllowedDisplayedValues() method first invokes the getAllowedInstantiationValues() method (on the subclass which implements it) to obtain an array of the allowed instantiation values, and then invokes convertToDisplayValue() on each element of the array to generate the array of allowed display values. The default implementation of getAllowedJavaValue() is identical to getAllowedDisplayValues(). Both methods return an array of allowed display values.

The validateInstantiationValue() method overrides the default implementation inherited from NdDefaultTemplateValueProvider. validateInstantiationValue() invokes the getAllowedInstantiationValues method and checks that the supplied value matches one of the items in the array of allowed values.com.blazesoft.template.enginepublic abstract class NdDefaultContrainedListProvider extends NdDefaultTemplateValueProvider

implements NdConstrainedListProvider{

public Object[] getAllowedDisplayValues(NdProviderContext ctxt); public Object[] getAllowedJavaValues(NdProviderContext ctxt);public boolean validateInstantiationValue(NdProviderContext ctxt, String value);

}

NdDesignProvider InterfaceThe NdDesignProvider interface defines the methods that supply meta information about the provider. This interface is implemented by every standard Blaze Advisor provider, as well as the example custom providers in the <ADVISOR_HOME>/examples/customProviders/java/stateProvince directory. The Custom Provider API does not include a class that provides default implementation of these methods. Your provider must implement each of these methods.

The NdDesignProvider interface defines the methods that supply meta information about the provider. This interface is implemented by every standard Blaze Advisor provider, as well as the example custom providers in the <ADVISOR_HOME>/examples/customProviders/java/stateProvince directory. The Custom Provider API does not include a class that provides default implementation of these methods. Your provider must implement each of these methods.

The getDisplayName() method returns the display name of the provider. The display name of the provider appears in the provider editor. The getDisplayKey() method



returns a key value which identifies the provider’s icon bitmap and its label. getDescription() returns the description of the provider. The description is displayed In New Provider dialog box when the provider’s icon is selected. This method is not used with custom providers, since custom provider icons do not appear in the New Provider dialog box.

The getArgumentDescriptors() method returns the description for the provider's arguments. If no arguments are supported this method must return an array of zero length (i.e., return NdDesignProviderArg[0];). com.blazesoft.template.engine.providerpublic interface NdDesignProvider{

public String getDisplayName(NdProviderContext context);public String getDescription(NdProviderContext context);public String getDisplayKey(NdProviderContext context);public NdDesignProviderArg[] getArgumentDescriptors(NdProviderContext context);

}

NdProvidesDefaultValue InterfaceThe NdProvidesDefaultValue interface defines the way for value providers to provide the default values. Providers implement this interface if they are capable of providing a meaningful default value for the type of value that they represent.

The provideDefaultValue() method returns a default value for the type of value represented by this value provider. provideUniqueDefaultValues() returns a sequence of unique default values for the type of value represented by this value provider. If the provider cannot generate the number of values specified in the numValues parameter, then it should return an array of smaller size that contains all of the values that it was able to generate. com.blazesoft.template.enginepublic interface NdProvidesDefaultValue{

public String provideDefaultValue(NdProviderContext context); public String[] provideUniqueDefaultValues(NdProviderContext context, int numValues);

}

Creating Custom Provider ClassesThe custom providers in the custom providers example (see the example in <ADVISOR_HOME>/examples/customProviders/java) demonstrate how to use the Custom Provider API to create your own constrained value list custom provider. This section focuses on the key elements of creating custom providers, with reference to the example code. You may want to open the source code in an editor and change the values or attempt to add capability by implementing an appropriate interface. The source code for the example custom providers is available in a subdirectory of the example directory noted above.

Two very simple custom providers are presented first. These custom providers demonstrate some of the essential features of the Custom Provider API with minimal



code. The source code for the simple custom providers is not included in the custom providers example folder.

Simple Value List ProviderThe SimpleValueListProvider custom provider provides a String value that is constrained to one of a discrete set of values. This custom provider is functionally similar to a value list provider that has been configured to supply a value from a list of String values.

The getAllowedInstantiationValues method returns the set of discrete values that is defined for the provider. SimpleValueListProvider requires very little code because it is derived from classes that supply default implementations of the interface methods that are required for constrained list providers.

// SimpleValueListProvider.javapublic class SimpleValueListProvider extends NdDefaultConstrainedListProvider {

public final static String PROVINCES_ABBREV[] ={"AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT"};

public SimpleValueListProvider(){}public String[] getAllowedInstantiationValues(NdProviderContext context)

throws com.blazesoft.template.engine.NdTemplateException{

return PROVINCES_ABBREV;}

}

The list of allowed display values appears in the provider editor, as shown below.



Recall that the NdContrainedListProvider interface is implemented by a provider when the value it provides must be constrained to one of a discrete set of values (see “NdConstrainedListProvider Interface” on page 45). The three methods of this interface return the allowed sets of instantiation, display, and Java values. All constrained list providers must implement the getInstantiationValues() method of the interface, which returns a String array of all values that can be legally stored in the instantiation object for which the provider is providing values. The Custom Provider API does not supply a default implementation of this method since the array would always be unique to the provider.

The Innovator engine determines the list of display values which appear in a drop-down list in an RMA by calling convertToDisplayValue() for every value in the array returned by getInstantiationValues(). The default implementation of convertToDisplayValue() in NdDefaultTemplateValueProvider returns the value that is passed to it, so no conversion occurs. The display value is the same as the instantiation value.

Simple SRL and Display List ProviderThe SimpleSRLAndDisplayListProvider custom provider is a constrained list provider just as is SimpleValueListCustomProvider. Both providers provide a String value that is constrained to one of a discrete set of values. The key difference between the two is that SimpleSRLAndDisplayListCustomProvider also provides a unique RMA display value for each instantiation value.

DisplayValuesProvider is the base class for the custom providers examples, which are described in “Custom Providers Example” on page 33 of Examples.pdf. DisplayValuesProvider is discussed in “The Example Base Class” on page 55.

Providers that extend DisplayValuesProvider must implement getInstantiationValues() and getDisplayedValues(). getInstantiationValues() returns the array of allowed instantiation values. The getDisplayedValues() method returns the array of valid display values that correspond to the array of allowed instantiation values. The two arrays correspond in the sense that for a given array index, a valid instantiation value and the corresponding valid RMA display value for that instantiation value may be obtained.

public class SimpleSRLAndDisplayListProvider extends DisplayValuesProvider implements NdDesignProvider

{public final static String PROVINCES_ABBREV[] =

{ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" };public final static String PROVINCES[] =

{ "Alberta", "British Columbia", "Manitoba", "New Brunswick","Newfoundland and Labrador", "Northwest Territories", "Nova Scotia","Nunavut", "Ontario", "Prince Edward Island", "Quebec", "Saskatchewan","Yukon" };

private String[] instantiationValues;private String[] displayValues;

public SimpleSRLAndDisplayListProvider(){}protected String[] getInstantiationValues() throws NdTemplateException



{instantiationValues = PROVINCES_ABBREV;return instantiationValues;

}protected String[] getDisplayedValues() throws NdTemplateException{

displayValues = PROVINCES;return displayValues;

}public NdDesignProviderArg[] getArgumentDescriptors(NdProviderContext parm1)


return new NdDesignProviderArg[0];}public String getDisplayName(NdProviderContext parm1)


return "";}public String getDescription(NdProviderContext parm1)


return "SRL and display value provider for list of Canadian provinces and territories.";

}public String getDisplayKey(NdProviderContext parm1)


return "Custom Provider";}

}

The DisplayValuesProvider class overrides the default implementation of the NdTemplateValueProvider interface convert methods. Each of these methods use the value lists returned by getDisplayValues() and getInstantiationValues() to perform the necessary value conversion.

As applied to the SimpleSRLAndDisplayListProvider provider, the convertToDisplayValue() method returns the display value in the PROVINCES array returned by getDisplayValues() that corresponds to a given instantiation value which is present in the PROVINCES_ABBREV array returned by getInstantiationValues().

// from DisplayValuesProvider.javapublic Object convertToDisplayValue(NdProviderContext context, String value)

throws NdTemplateException{

String displayValue = "";String[] displayedValues = getDisplayedValues();String[] storedValues = getInstantiationValues();if (displayedValues != null && storedValues != null) {

for (int index = 0; index < storedValues.length; index++) {if (storedValues[index].equals(value)) {

displayValue = displayedValues[index];break;

}}

}return displayValue;

}



Customizing Provider Behavior Using ArgumentsThe SimpleSRLAndDisplayListProvider provider discussed in the previous section (“Simple SRL and Display List Provider” on page 49) is functionally identical to the default behavior of the ConstantDisplayValuesProvider example provider, as determined by the provider’s default argument settings. The ConstantDisplayValuesProvider provider supports U.S. states as well as Canadian provinces and territories.

The ConstantDisplayValuesProvider provider’s default setting for the Display Value argument configures the provider to display the full names, rather than the abbreviated names, of either states or provinces in the RMA. The default List Contents setting restricts the provider to providing values for Canadian provinces and territories only. The List Contents drop-down list allows users to select between State, Province/territory and Both. The ability to customize the behavior of the provider sets ConstantDisplayValuesProvider apart from the SimpleValueListProvider which does not support provider arguments.

Provider argument descriptors are defined in the provider’s getArgumentDescriptors() method. You can change the default values of the arguments in the provider editor. You can override the default values in a provider value holder by using the value holder’s Set Arguments dialog box. When argument values change, the Innovator engine calls the provider’s setArgs() method. setArgs() is also called whenever a value must be provided to a value holder. setArgs() is passed an array of provider arguments. In the course of processing the arguments, setArgs() will typically set the values of variables which are used elsewhere in the provider code to control the required behavior.



Defining Argument DescriptorsThe getArgumentDescriptors() method of ConstantDisplayValuesProvider defines two NdDesignProviderSelectableArg argument descriptors, displayType and listType. The NdDesignProviderSelectableArg class defines a single-valued argument that can take its value from a list of choices presented to the user in a drop-down box. displayType describes an argument that is named “DisplayType” in the constructor, as you can observe in the code below for the getArgumentDescriptors() method. The setArgs() method identifies the argument by this name, as described in the next section. setDisplayName() sets the label for the argument in the provider editor, which is “Display Value.” setDescription() sets the description of the argument. setChoices() sets the actual choice values that setArgs() obtains using the argument’s getValue method. The argument is defined with two choice values: “Full name” and “Abbreviated name.” (Note that String constants are used in place of String literals in the code.) The same values are used in setDisplayChoices(), which sets the displayed choice labels as they appear in the provider editor. The setDefaultValue() method is called to set the default value of the argument to “Full name”. setMandatory() sets whether or not the argument is mandatory.

The listType NdDesignProviderSelectableArg is set up in the same fashion. The name of the argument being defined is “ListType.” The label for the argument in the provider editor is “List Contents.” The list of choices which will appear in a drop-down box in the editor is “State,” “Province/territory.” and “Both.” The default choice is “State”.

Compare the code below with the image of the ConstantDisplayValuesProvider editor in the previous section (“Customizing Provider Behavior Using Arguments” on page 51).

// from ConstantDisplayValuesProvider.javapublic NdDesignProviderArg[] getArgumentDescriptors(NdProviderContext parm1)


NdDesignProviderSelectableArg displayType = new NdDesignProviderSelectableArg("DisplayType");displayType.setDisplayName("Display Value");displayType.setDescription("Display the full name or abbreviation");// displayType.setChoices(new String[] {"Full name", "Abbreviated name");displayType.setChoices(new String[] {DISPLAY_TYPE_FULL, DISPLAY_TYPE_ABBREV});displayType.setDisplayChoices(new String[] {DISPLAY_TYPE_FULL, DISPLAY_TYPE_ABBREV});// displayType.setDefaultValue("Full name");displayType.setDefaultValue(DISPLAY_TYPE_FULL);displayType.setMandatory(true);

NdDesignProviderSelectableArg listType = new NdDesignProviderSelectableArg("ListType");listType.setDisplayName("List Contents");listType.setDescription("Display the states, provinces, or both");// listType.setChoices(new String[] {"State", "Province/territory", "Both"});listType.setChoices(new String[] {LIST_TYPE_STATE, LIST_TYPE_PROVINCE, LIST_TYPE_BOTH});listType.setDisplayChoices(new String[] {LIST_TYPE_STATE, LIST_TYPE_PROVINCE, LIST_TYPE_BOTH});// listType.setDefaultValue("State");listType.setDefaultValue(LIST_TYPE_STATE);listType.setMandatory(true);

return new NdDesignProviderArg[] { listType, displayType } ;}



As described above, the ConstantDisplayValuesProvider provider uses single-valued NdDesignProviderSelectableArg() argument descriptors that define arguments that can take their value from a list of choices. The UserDefinedDisplayValuesProvider provider in the custom providers example uses single-value NdDesignProviderTypeArg arguments descriptors. This class defines a single-valued argument that is not restricted to selection from a pre-determined set of choices. Values are entered in a text box.

The example UserDefinedDisplayValuesProvider provider uses a multi-valued argument descriptor (NdDesignProviderMultiArg), labeled Element, that is composed of two single arguments of type NdDesignProviderTypedArg, which are labeled “Stored Value” and “Displayed Value.” The user who is configuring the provider can create any number of Element arguments in the provider editor. Each Element specifies a state or provence abbreviation with the displayed name, such as AB and Alberta.

In the code below for the getArgumentDescriptors() method of the UserDefinedDisplayValuesProvider, the names of the two NdDesignProviderTypedArg single arguments are specified in the calls to the constructor. The names, “StoredValue” and “DisplayedValue”, identify the arguments when they are processed in the setArgs method. The setDisplayName() method is called to set the display names of the arguments, which are “Content Value” and “Display Value”. These values are used as labels for the single arguments in the Element shown in the image above. setDescription() is called to set the description of each argument, but the description does not appear in the provider editor. setType() is called to set the argument type to String. setDefaultValue() sets the default value of the argument to an empty string.

As mentioned above, the NdDesignProviderMultiArg class describes a provider's multi-valued argument. The stored name of the argument is set to “Element” in the constructor. This is the name the setArgs() method uses to identify the argument. The setDisplayName() method is called to set the display name of the elements, which is “Element”, as shown in the image above. The setNewCmdName() method is called to set the value of the tooltip, which is “New Element”. The setMultiple() method is called to set whether the argument can be multiple, which is true in the case of this multiple argument. The setArgumentDescriptors() method is passed an array of



NdDesignProviderArg which includes the two single NdDesignProviderTypeArg arguments. Finally, the getArgumentDescriptors() method returns the NdDesignProviderArg element argument descriptor that has been defined.

// from UserDefinedDisplayValuesProvider.javapublic NdDesignProviderArg[] getArgumentDescriptors(NdProviderContext context)

throws NdTemplateException{NdDesignProviderTypedArg storedValue = new NdDesignProviderTypedArg("StoredValue");

storedValue.setDisplayName("Content Value");storedValue.setDescription("SRL value generated during runtime");storedValue.setType(NdTemplateManager.BUILTIN_STRING_PROVIDER);storedValue.setDefaultValue("");

NdDesignProviderTypedArg displayedValue = new NdDesignProviderTypedArg("DisplayedValue");displayedValue.setDisplayName("Display Value");displayedValue.setDescription("Value displayed to the user");displayedValue.setType(NdTemplateManager.BUILTIN_STRING_PROVIDER);displayedValue.setDefaultValue("");

NdDesignProviderMultiArg element = new NdDesignProviderMultiArg("Element");element.setDisplayName("Element");element.setDescription("List Element");element.setDisplayKey("Value");element.setGroup("Element");element.setNewCmdName("New Element");element.setMultiple(true);element.setArgumentDescriptors(new NdDesignProviderArg[]{storedValue, displayedValue});

return new NdDesignProviderArg[]{element};}

Processing ArgumentsAs mentioned above, the setArgs() method of a provider is called by the Innovator engine. The setArgs() method is passed NdProviderStaticArg arguments which are processed in the method.

The ConstantDisplayValuesProvider provider defines two String variables, displayType and listType. The variables are used to customize the behavior of the provider. The provider’s setArgs() method assigns the value in the argument named “DisplayType” to displayType and the value of the argument named “ListType” to listType.

// from ConstantDisplayValuesProvider.javapublic void setArgs(NdProviderContext context, NdProviderStaticArg[] args)


if (args != null & args.length > 0) {for (int index = 0; index < args.length; index++) {

if (args[index].getName().equals("DisplayType")) {displayType = args[index].getValue();

}else if (args[index].getName().equals("ListType")) {

listType = args[index].getValue();}

}}

}



The provider’s getInstantiationValues and getDisplayValues methods use displayType and listType to determine the appropropriate array to return. For example, the getInstantiationValues method returns the STATE_ABBREV array if listType equals “States”. It returns the PROVINCE_ABBREV array if listType equals “Province/territories” and it concatenation of both arrays if listType equals “Both”.

// from ConstantDisplayValuesProvider.javaprotected String[] getInstantiationValues()


if(listType.equals(LIST_TYPE_STATE)) {initializationValues = STATES_ABBREV;

}else if(listType.equals(LIST_TYPE_PROVINCE)) {

initializationValues = PROVINCES_ABBREV;}else {

String[] allowedValues = new String[STATES_ABBREV.length + PROVINCES_ABBREV.length];System.arraycopy(STATES_ABBREV, 0, allowedValues, 0, STATES_ABBREV.length);System.arraycopy(PROVINCES_ABBREV, 0, allowedValues, STATES_ABBREV.length,

PROVINCES_ABBREV.length);initializationValues = allowedValues;

}return initializationValues;

}

The Example Base ClassThe DisplayValuesProvider class is useful for creating many custom providers. The class is not part of the Custom Provider API. It is included with the custom providers example. The source code and class files for all example custom providers are available in the <ADVISOR_HOME>/examples/customProviders/java/stateProvince folder. The class extends NdDefaultContrainedListProvider. The example custom providers in the example extend DisplayValuesProvider, which is an abstract class.

Providers that extend DisplayValuesProvider class must implement the two abstract methods that are declared in the class, getInstantiationValues() and getDisplayValues(). getInstantiationValues() returns a String array that contains the allowed instantiation values. The provider’s content values are the same as the instantiation values unless the provider overrides the default implementation of the convertToContent() method, which ensures they are the same value. The getDisplayValues() method returns a String array that contains the allowed display values. The String arrays returned by getInstantiationValues() and getDisplayValues() are constructed in parallel, such that for a given array index, a valid instantiation value (again, this is also the content or SRL value) and the corresponding valid RMA display value may be obtained.

Recall that it is the responsibility of a constrained list provider to define the valid values. Each provider is free to obtain the values it provides in any fashion. The example providers demonstrate different methods for obtaining value lists.The StaticClassMethodProvider obtains values by calling static accessor methods on a class that defines the appropriate String arrays as constants. The name of the class that holds the values and the names of the appropriate accessor methods are specified when



the provider is configured in the provider editor. The UserDefinedDisplayValuesProvider is passed values that a user defines in elements in the provider editor. The values are passed as arguments to the provider’s setArgs() method. Finally, the ConstantDisplayValuesProvider obtains values from String arrays defined in the class.

The implementations of getAllowedDisplayValues() and getAllowedJavaValues() methods in the DisplayValuesProvider class both return a String array obtained by calling getDisplayedValues(). Compare this implementation to the default implementation described in “NdDefaultConstrainedListProvider” on page 46, which obtains display values by invoking convertToDisplay() on each element of the String array returned by getAllowedInstantiationValues().

The getAllowedInstantiationValues() method of the DisplayValuesProvider class returns an array of all the values that can be legally stored in the nodes of the instantiation object, as described in “NdConstrainedListProvider Interface” on page 45. The getAllowedInstantiationValues() method calls getInstantiationValues() to obtain the allowed instantiation values. getAllowedInstantiationValues() is called by the provider’s validateInstantiationValue() method, which returns true if its parameter value is contained in the array of valid instantiation values returned by this method.

The DisplayValuesProvider class overrides the default implementation (in NdDefaultConstrainedListProver) of all the NdConstrainedListProver interface convert methods. For description of these methods see “NdTemplateValueProvider Interface” on page 44. The DisplayValuesProvider implementation of these methods each make use of the allowed instantiation values returned by getInstantiationValues(), as well as the allowed display values returned by getDisplayedValues().

Custom Provider Implementation GuidelinesWhen creating custom provider classes consider the following general implementation guidelines:

Custom Provider classes get instantiated once per project and per user. So for instance, if you have 10 concurrent users of an RMA, this will result into 10 instances of that Custom Provider class being created.

When providers are called by our code, they're typically always used in this sequence:

First, the reset() method is called.

Then, the setArgs() method is called.

Finally the operation of choice is called (such as getAllowedDisplayValues(), or convertToContentValue(), or validateValue(). for instance).

The bottom line is that the reset() and setArgs() methods are called very often. Sometimes just to get the type of provider or the type of value returned by the provider. So care must be taken to avoid doing costly operations in the reset() and



setArgs() methods. Also those methods should not throw any runtime exception. Any operation that is costly to compute or may fail should be done only as the result of calling one of the other methods.

If some operation done by a custom provider class is very costly (for instance, reading information from a database, or returning a list of SRL entities of a particular type in the current project), then care must be taken to avoid doing the same operation too many times. Caching information in a local, private, non-static Hashtable field for instance is a common way to keep and re-use previous results if those results do not change between invocations of the provider.

Even if results may change between invocations, you may still use caching techniques, but you must also worry about invalidating the cache if part of it becomes invalid. For instance, if you've read information from files that reside on your file system and kept that information in some local cache, indexed by the file location, you should invalidate the information associated with that file if you detect that file has been modified (using the Last Modified attribute of the file for instance to detect whether a file has changed).

For implementing caches, it's important to note that it is the same Custom Provider class that is shared between all RMA sessions, so care must be taken if the information is stored in a static field. It might be OK to use a static field for such cached data, but only if the cached data is constant and can indeed be shared across all sessions. Also the code that reads from or writes to that cache must be synchronized to prevent multiple threads/sessions to access that data at the same time in an uncoordinated fashion (thrashing).

If the cached data could grow to a large amount over time, you could add additional techniques to partially release the memory kept by the oldest parts of your cache, such as using weak references or weak hashmaps to keep references to cached data.

In the particular case where the data being retrieved is stored in a database, you should consider not only caching the data retrieved from that database but also sharing or pooling of connections (to avoid having each session result into a new database connection).

In the particular case where the data being retrieved comes from the current project content, you should use the new NdPromProviderUtil.getPromProject() method to retrieve the current NdPromProject, and from that get the list of directories, items, and entities that are relevant to the provider (instead of using methods such as NdTemplateManager.loadInstantiation()). The main benefits of using the new PROM APIs are that they give a fully objectified view of what's in the current project, as well as cache all necessary information.


C H A P T E R 5

RMA Service and Session APIs

The FICO™ Blaze Advisor® business rules management system RMA API is a high-level API for developers building rule maintenance applications (RMAs). The API is independent of the execution environment, so it is not limited to web-based applications, but can be used to build RMAs in other environments including Java Swing.

The RMA API is composed of the RMA Service API and the RMA Session API. The RMA Service API includes interfaces which offer a means of connecting to a repository, opening a project, finding relevant instances, editing instances, and saving those instances in the repository. The purpose of the RMA Session API is to supplement the RMA Service API by providing a state-holding interface while still not being tied to any one client technology or execution environment.

The RMA Service APIThe RMA Service API offers a simple set of interfaces geared towards editing instances of templates. As with the PROM API, the RMA API operations are always performed in the context of a project. The API provides a simple means of connecting to either a versioned or non-versioned repository, opening a project, navigating the contents of the project in order to find relevant instances, and then making it possible to edit and save those instances. The API also allows the creation of new instances from templates found in the project, as well the execution of queries to find entries of interest within the project. Proper collaboration with the versioning system is provided by the API as well.

The RMA Repository (NdRmaRepository)An RMA application which uses the RMA API begins by obtaining an instance of NdRmaRepository by passing a repository connection object to the connectToRepository() method of NdRmaRepositoryFactory. The NdRmaRepository instance is used to open an RMA project (see “RMA Project (NdRmaProject)” on page 60). NdRmaRepository supplies two methods for opening a project.

NdRmaProject openProject(String projectFullDisplayPath)NdRmaProject openProject(NdLocation projectAbsoluteLocation)

Both methods accept a parameter which specifies the location of the project as an absolute location from the root directory of the repository. The difference between the two is that the parameter to the openProject(String projectFullDisplayPath) method is a String path which is built with display names, as they appear in the


CHAPTER 5: RMA Service and Session APIs

Builder IDE. In contrast, the openProject(NdLocation projectAbsoluteLocation) method opens the project at the location specified by an absolute NdLocation. File system names are used when creating an NdLocation, rather than display names. The later method is used when file system names are preferred over display names and in those cases where the location of the project was obtained by using the ROM and PROM APIs, but it was deemed preferable to deal with that project as an NdRmaProject. See “Specifying a Location (NdLocation)” on page 15 for discussion on creating an absolute NdLocation.

The NdRmaRepository interface consists primarily of methods which supply information about the repository connection and the repository.

boolean isVersionControlled()boolean isPrivateWorkspaceUsed()boolean isConnected()void disconnect()Date getConnectionDate()NdRepositoryConnection getRepositoryConnection()

The isVersionControlled() method returns true if the repository supports versioning operations. isPrivateWorkspaceUsed() returns true if the repository uses a private workspace. isConnected() returns true if the repository is connected. disconnect() disconnects from the repository. getConnectionDate() returns the connection date. The getRepositoryConnection() method returns the NdRepositoryConnection object that was used to connect to the repository. You can obtain information about the repository connection with this object, such as the name of the repository or the user name.

NdRmaRepository also contains these utility methods for displaying dates and obtaining the display Calendar.

String formatDateForDisplay(Date date)String formatDateForDisplay(Date date, Locale locale, TimeZone timeZone)NdCalendar getDisplayCalendar()

The formatDateForDisplay(Date date) method returns the supplied Date as a localized String representation of the connection date. formatDateForDisplay(Date date, Locale locale, TimeZone timeZone) returns the supplied Date as a display-friendly String, localized according to the supplied locale and time zone. The getDisplayCalendar() method returns the displayCalendar using the default, server-side locale.

RMA Project (NdRmaProject)An RMA project is represented by NdRmaProject, which is obtained by calling openProject() method of the NdRmaRepository interface.

NdFileRepositoryConnection connection = new NdFileRepositoryConnection();connection.setUser("Template Developer");connection.setRepositoryFolder("../../workspaces/MerchWksp");NdRmaRepository rmaRepository = NdRmaRepositoryFactory.connectToRepository(connection);NdRmaProject rmaProject = rmaRepository.openProject("/Business Library/MerchandisingRMA");



The following methods are provided to support subproject navigation and multi-project detection:

NdRmaSubProject[] getSubProjects()boolean isMultiProject()void refresh()

The getSubProjects() method returns the subprojects belonging to this project as an array of NdRmaSubProject. A project may include one or more subprojects, as well as imported directories and directories of its own. A “multi-project” is a project that is composed of two or more subprojects and does not have directories of its own, although it may have imported directories.The isMultiProject() method returns true if this project is a multi-project. The list of subprojects returned by getSubProjects() is cached by the project object, so the same list is assured every time getSubProjects() is invoked. To obtain an accurate subdirectory list in the event the project subdirectories in the repository change, call refresh() to reset the cached lists. The refresh() method simultaneously refreshes the cached directory lists returned by the getDirectories() and getAllDirectories(), which are decribed below.

The NdRmaProject interface provides a number of methods to navigate the directories referenced by the project, as well as their contents.

NdRmaDirectory[] getDirectories(boolean includeSystemDirectories) NdRmaDirectory[] getAllDirectories(boolean includeSystemDirectories)NdRmaDirectory addDirectory(String directoryDisplayName) void deleteDirectory(NdRmaDirectory directory)

The getDirectories() method returns the directories which are imported by the project and the project’s subprojects. getAllDirectories() returns the directories imported by the project and the project’s subprojects, as well as all the subdirectories of the project and its subprojects. Set the boolean includeSystemDirectories parameter of the methods to true to include directories that are located in system directories and their subdirectories. (Any Entry Exclusion or Entry Inclusion Filters which are defined for the current project will restrict which directories are returned by these methods.) As noted above, the list of directories is cached, so every time these methods are invoked the same results are assured. To obtain accurate lists in the event the project directories and subprojects in the repository change, call refresh() to reset the cached lists.

Invoke the addDirectory() and deleteDirectory() methods to add a directory or remove a directory from the project, respectively. The directory is created at the root of the repository. A new directory is typically used for saving query instances from the RMA. A directory must be empty before deleting it.

For convenience, specific methods are provided to obtain all the entries representing templates, instances, query templates and query instances in the project. Set the boolean includeSystemDirectories parameter of the methods to true to include templates that are part of system directories and their subdirectories.

NdRmaTemplate[] getAllTemplates(boolean includeSystemDirectories)NdRmaTemplate[] getFilterTemplates(boolean includeSystemDirectories)NdRmaQueryTemplate[] getAllQueryTemplates(boolean includeSystemDirectories)NdRmaQueryTemplate[] getSearchQueryTemplates(boolean includeSystemDirectories)



NdRmaQueryTemplate[] getComparisonQueryTemplates(boolean includeSystemDirectories)NdRmaQueryTemplate[] getVerificationQueryTemplates(boolean includeSystemDirectories)NdRmaInstance[] getAllInstances(boolean includeSystemDirectories)NdRmaInstance[] getFilterInstances()boolean includeSystemDirectoriesNdRmaQueryInstance[] getAllQueryInstances(boolean includeSystemDirectories)NdRmaQueryInstance[] getSearchQueryInstances(boolean includeSystemDirectories)NdRmaQueryInstance[] getComparisonQueryInstances(boolean includeSystemDirectories)NdRmaQueryInstance[] getVerificationQueryInstances(boolean includeSystemDirectories)dispose()

The getAllTemplates() method returns all the templates in the project, including Filter and Query templates. getFilterTemplates() returns all the Filter templates in the project. The output of this method is unaffected by any current inclusion filter. getAllQueryTemplates() returns all the Query templates in the project. getSearchQueryTemplates() returns all the Search Query templates in the project. getComparisonQueryTemplates() returns all the Comparison Query templates in the project. getVerificationQueryTemplates() returns all the Verification Query templates in the project. getAllInstances() returns all the instances in the project. getFilterInstances() returns all the Filter instances in the project. The output of this method is unaffected by any current inclusion filter. getAllQueryInstances() returns all the Query instances in the project. getSearchQueryInstances() returns all the Search Query instances in the project. getComparisonQueryInstances() returns all the Comparison Query instances in the project. getVerificationQueryInstances() returns all the Verification Query instances in the project. The dispose() method releases the project resources. Any subsequent attempt to use the disposed project will result in an assert Exception

The methods described above return by default all the entries that are found when traversing the directories imported by the project (aside from directories that are explicitly excluded with an Exclusion Filter). However, a method of the project’s Filter Manager, NdRmaEntryFilterManager.setEntryExclusionFilter(), allows client code to provide an NdRmaEntryExclusionFilter to automatically filter out unwanted results when these entry-collecting methods are used. Passing null to setEntryExclusionFilter() will remove the filter and thus reset the behavior of those methods to the default. See “RMA Entry Filter Manager (NdRmaEntryFilterManager)” on page 79.

NdRmaProject includes a method for obtaining the project’s Filter Manager:

NdRmaEntryFilterManager getEntryFilterManager()

Invoke the project’s getEntryFilterManager() method to obtain the Filter Manager.

NdRmaProject provides a method for obtaining an entry by its location.

NdRmaEntry lookupEntryByLocation(NdLocation absoluteLocation)

The lookupEntryByLocation() method obtains the NdRmaEntry at the supplied absolute location (NdLocation) from the repository root. The method is convenient for switching to the RMA API after having navigated the repository using the ROM and PROM APIs. Note that an NdRmaEntry may be either a file or a directory. This method will return null when an entry cannot be found at the provided absolute location. The method will



throw an exception if the absolute location belongs to a storage folder for sub-instances stored-separately, or if it is not an absolute location, or if the project has been previously disposed of. NdRmaEntry has a complementary method, getLocation(), which returns the NdLocation corresponding to the entry. For a discussion on the distinction between an absolute and relative NdLocation, see “Specifying a Location (NdLocation)” on page 15.

Errors that may occur when dealing with the project may be handled with the following methods:

boolean hasErrors()NdRMAException[] getErrors()void clearErrors()

The hasErrors() method returns true if errors were found while performing any operation on the project. getErrors() returns the errors that were found while performing any operation on the project. clearErrors() clears the list of errors that were kept since the last call to this method. Consider clearing the cached list of errors prior to performing a discrete set of operations on the project, so that the successive calls to hasErrors() and getErrors() reflect only the errors in the immediate set.

NdRmaProject supports versioning by virtue of extending NdRmaEntry, which has methods for obtaining versioning information and versioning operations.

A project in a versioned repository provides versioning information and supports versioning operations, but not the getVersion(), promote(), and restore() methods. (See “Versioning” on page 75.)

RMA Entry (NdRmaEntry)An NdRmaEntry is either a project directory or a file in a project. This is similar to an NdPromEntry in the PROM API, that is either a directory or an item, which is the ROM API and PROM API term for a file.

The NdRmaEntry interface includes the following methods:

String getDisplayName()String[] getDisplayPath()NdLocation getLocation()NdRmaDirectory getParentDirectory()NdRmaProject getProject()

The getDisplayName() method returns the display name of the file as it appears in the Builder IDE. getDisplayPath() returns the display path of the file, as an array of String. Each element represents a node in the hierarchy. The hierarchy starts at the project node. The last element in the array is the display name of the file. getLocation() returns an NdLocation object that is the absolute location of the entry from the root of the repository. getParentDirectory() returns the directory that contains the entry. null is returned if the entry has no parent; which would be the case if, for example, the entry were a project or one of the top-level project directories. Note that the getDisplayPath(), getLocation(), and getParentDirectory() methods cannot be used if the entry is a transient Query instance (one whose isTransient() method returns



true). An exception will be thrown in this case. getProject() returns the project the entry belongs to.

The following methods are used to obtain the entry’s repository schema typing attribute values, which are defined by the com.blazesoft.templates.repository.NdRomSchemaConstants interface. See “Repository Item Typing Attributes” on page 8.

int getType()int getSubType()int getContentType()int getTarget()

The getType() method returns the NdRomSchemaConstants “type” value for this entry, such as TYPE_SRL_ENUMERATION. getSubType() returns the “subType” value for this entry, such as SUB_TYPE_NONE. getContentType() returns the “contentType” value for this entry, such as CONTENT_TYPE_FIXED. The getTarget() method returns the “target” value for this entry, such as TARGET_SRL.

An entry also supplies methods to deal with versioning and authorization:

NdRmaEntryVersioningInfo getVersioningInfo()NdRmaEntryVersioningOperations getVersioningOperations()

The getVersioningInfo() method returns the versioning information (NdRmaEntryVersioningInfo) for the entry. If the repository does not support versioning, or there is no versioning information for the entry, this method returns null. getVersioningOperations() returns the versioning operations (NdRmaEntryVersioningOperations) that may be performed on the entry. If the repository does not support versioning, or the entry does not support any versioning operation, this method returns null. For the current release of the RMA Service API, versioning operations are supported for only two kinds of entries: instances (NdRmaInstance) and projects (NdRmaProject). For projects, only the update() operation is presently supported.

RMA Directory (NdRmaDirectory)NdRmaDirectory provides the following methods in addition to those inherited from NdRmaEntry:

boolean hasEntries()NdRmaEntry[] getEntries()void resetEntries()NdRmaDirectory createDirectory(String directoryDisplayName)void deleteEntry(NdRmaEntry entry)rename(String name)NdRmaGloballyDeletedFile[] getGloballyDeletedFiles() void resetGloballyDeletedFiles() boolean hasGloballyDeletedFiles()

The hasEntries() method returns true if the directory has any content. getEntries() returns all the entries in the directory. The list of entries is cached. If any entry exclusion filter was defined at the project level, then the result provided by these methods will



depend on the filter. Projects and subprojects will never be in the list of entries returned by getEntries(). The reason is that directories are fetched in the context of some project, and other projects that may be contained in those directories are invisible to the root project. The resetEntries() method clears the cache of entries. This is useful so that the next call to getEntries() returns an up-to-date list of entries. The createDirectory() method creates a subdirectory of the specified name. The deleteEntry() method deletes the supplied entry. rename(String name) renames the directory. The new name must not contain any illegal characters and cannot be a duplicate of another directory within the same parent directory. getGloballyDeletedFiles() returns all the files in this directory that have been deleted and then checked into the versioning system. resetGloballyDeletedFiles() clears the cache of files that have been deleted then checked into the versioning system. The hasGloballyDeletedFiles() method returns true if the directory has any file that has been deleted then checked into the versioning system.

Versioning operations are not provided for a directory in the current release, even though NdRmaDirectory extends NdRmaEntry, which supports versioning. However, NdRmaDirectory does provide the following method for obtaining versioning information for all the entries in a directory:

public NdRmaDirectoryVersioningInfos getVersioningInfos()

The getVersioningInfos() method returns an instance of NdRmaDirectoryVersioningInfos which may be used to obtain the versioning status and lock information for all the entries in the directory. This method is provided so that a more efficient retrieval of versioning information can be performed when such information is needed for more than one entry. The NdRmaDirectoryVersioningInfos interface is discussed in “Versioning Information (NdRmaEntryVersioningInfo)” on page 76.

RMA FilesAs described in “RMA Entry (NdRmaEntry)” on page 63, an entry in a repository is either a project directory or a file in a project. Files are always contained by a directory, with the exception of projects. The four types of files supported by the RMA API are listed below. Each interface extends NdRmaFile.

project (NdRmaProject)

subproject (NdRmaSubProject)

template file (NdRmaTemplateFile)

instance file (NdRmaInstanceFile)

File (NdRmaFile)The NdRmaFile interface provides the following methods.

Date getLastModifiedDate() boolean isLogicallyDeleted() boolean isNew() void reloadContent()



NdRmaEntry getOriginalTipEntry()NdRmaInstanceFile getRootInstanceFile()String getSubInstancePath()String getSubInstanceSectionName()

The getLastModifiedDate() method returns the date the file was last modified. To obtain a display-friendly, localized String for that Date, call NdRmaRepository.formatDateForDisplay(). The isLogicallyDeleted() method returns true if the file has been logically deleted. A logically deleted file is one that is either deleted locally in the workspace or deleted globally in the versioning system. isNew() returns true if the file was just created and never saved. The reloadContent() method reloads the content of the file and discards changes which have not been saved. getOriginalTipEntry() returns the working copy, or “tip” entry file if the file is a version of an entry, otherwise null is returned. getRootInstanceFile() returns the root instance (parent) file if this entry represents the entry for a sub-instance stored-separately. This method returns null if this entry does not represent an instance stored-separately. The getSubInstancePath() method returns the path to the sub-instance stored-separately within the instance contained by this file. getSubInstanceSectionName() returns the section name of the sub-instance stored-separately within the instance contained by this file. Both getSubInstancePath() and getSubInstanceSectionName() are used by entries representing instances stored-separately, so that with the root instance file, the sub-instance path, and sub-instance section name it is possible to find the sub-instance linking to the instance stored-separately.

Project (NdRmaProject)Projects (NdRmaProject) and subprojects (NdRmaSubProject) are not included in the list of entries returned by the getEntries() method of NdRmaDirectory (see “RMA Directory (NdRmaDirectory)” on page 64). The reason is that directories are fetched in the context of some project, and other projects that may be contained in those directories are invisible to the root project which provides the context.

NdRmaProject and NdRmaSubProject extend NdRmaFile so that it can supply versioning information, and so that versioning operations can be performed. For the current release, however, only instances support all versioning operations. Projects support some versioning operations, as described in “Versioning” on page 75.

The methods available in NdRmaProject are discussed in “RMA Project (NdRmaProject)” on page 60.

Subproject (NdRmaSubProject)A subproject is simply a project contained by another project. NdRmaProject and NdRmaSubProject extend NdRmaFile so that it can supply versioning information. This extension also allows versioning operations to be performed on an NdRmaProject, like any other entry. However, NdRmaSubProject objects are read-only; no operations are allowed that can change its state. Versioning is not supported. To operate on a subproject, open the subproject as a project using the NdRmaRepository.openProject() method described in “RMA Project (NdRmaProject)” on page 60. Alternatively, obtain



the NdRmaProject instance by calling getRmaProject() (inherited from NdRmaEntry) on the subproject instance.

To limit the ability to modify the subproject, the following methods inherited from NdRmaFile are overridden:

NdRmaEntryVersioningOperations getVersioningOperations()void reloadContent()

The getVersioningOperations() method returns null. Calling reloadContent() on a subproject will result in an NdRMAException being thrown.

Template File (NdRmaTemplateFile)The NdRmaTemplateFile interface represents a file which contains a template. NdRmaTemplateFile supplies these methods.

NdRmaTemplate getTemplate()NdRmaFile saveAs(NdRmaDirectory targetDirectory, String name)

The getTemplate() method returns the template that this file contains. saveAs() saves a copy of the file in the specified target directory. The copy that was created is returned. The new name must not contain any illegal characters and cannot be a duplicate of another file within the same directory.

Instance File (NdRmaInstanceFile)The NdRmaInstanceFile interface represents a file that contains an instance. NdRmaInstanceFile provides this method:

NdRmaInstance getInstance()

The getInstance() method returns the instance that this file contains.

NdRmaInstanceFile extends NdRmaEditableFile which provides the editing capability for the instance. See “Editable File (NdRmaEditableFile)” below.

Editable File (NdRmaEditableFile)NdRmaEditableFile is implemented by files that allow editing. For the current release, only instances instances are editable. NdRmaEditableFile extends NdRmaFile.

void save()NdRmaFile saveAs(NdRmaDirectory targetDirectory, String name)boolean isModified()rename(String displayName)boolean isStoredSeparately()

The save() method saves the file. If the file is read-only or is a transient Query instance, this method will fail. The saveAs() method saves a copy of the file, with a new name, in the specified target directory. The copy that is created is returned as an NdRmaFile. The isModified() method returns true if the file has been modified. After the file is saved, isModified() will return false. Saving a modified file with a new name using



saveAs() will result in isModified() returning true, since a copy will have been saved and not the original file. The rename() method is used to rename the file. The file will be marked as modified, and will not be saved.isStoredSeparately() returns the true if this file is an instance that is currently stored separately.

File Content (NdRmaFileContent)The file content interfaces are NdRmaTemplate and NdRmaInstance, as well as NdRmaQueryTemplate and NdRmaQueryInstance. These interfaces extend NdRmaFileContent, which contains the following method:

NdRmaFile getFile()

The NdRmaFile getFile() method returns the file that contains the content.

The NdRmaTemplate and NdRmaInstance interfaces are discussed in the following sections.

RMA Template (NdRmaTemplate)NdRmaTemplate provides the following methods in addition to the getFile() method inherited from NdRmaFileContent:

NdRmaInstance generateInstance(NdRmaDirectory targetDirectory, String instanceDisplayName)String getDisplayName()boolean isComparisonQueryTemplate()boolean isFilterTemplate()boolean isQueryTemplate()boolean isSearchQueryTemplate()boolean isVerificationQueryTemplate()boolean isTransient()

The generateInstance() method generates a new instance of the template in the specified target directory and saves it. If the instance is created in a versioned repository it must be checked in. The new instance may be edited, as described in “Editing the Contents of an Instance” on page 71. The getDisplayName() method returns the display name of this template entry. isComparisonQueryTemplate() returns true if this template is a Comparison Query template. isFilterTemplate() returns true if this template is a Filter template. isQueryTemplate() returns true if this template is a Query template. isSearchQueryTemplate() returns true if this template is a Search Query template. The isVerificationQueryTemplate() method returns true if this template is a Verification Query template.

The isTransient() method returns true if this template is in a transient state. When NdRmaInstance.getTemplate() returns an NdRmaTemplate, it may need to return a template in a “transient” state - meaning the template can only be used to test its properties and to obtain the display name of the template. This is necessary when the template has been excluded from the project and yet we still want to supply an NdRmaTemplate from the instance's getTemplate() method. For example, the Standard Business Query template has been excluded when generating the RMA, and yet we want to still be able to group instances of that template under the template's display



name, even though a new instantiation of the template can not be made. (Excerpted from the API Reference entry for the NdRmaTemplate interface.)

Versioning information regarding the template file may obtained through the NdRmaFile object which is returned by calling getFile(). For the current release, however, version operations are not supported for templates. Subprojects do not implement versioning operations. See “Versioning” on page 75.

RMA Instance (NdRmaInstance)NdRmaInstance extends NdRmaFileContent, and as such, it inherits the getFile() method which ultimately gives access to the versioning information and versioning operations for that file.

NdRmaInstance provides a method for obtaining the template for this instance:

NdRmaTemplate getTemplate()

The getTemplate() method returns the NdRmaTemplate entry that the instance was generated from. If the project directory containing the template has been excluded or filtered out, the NdRmaTemplate object returned will be in a transient state. That is, the template’s isTransient() method will return true, and its getFile() and generateInstance() methods will throw an exception. getTemplate() returns null if the template could not be obtained due to a linking error.

An instance can be obtained by calling the getInstance() method of the NdRmaInstanceFile interface. The NdRmaInstanceFile object you use can be obtained by calling the lookupEntryByLocation(NdLocation location) method of NdRmaProject, as shown in the code below. You can obtain all instances in a project by calling the getAllInstances() method of the NdRmaProject.

This code shows how to obtain an instance by two methods. The first obtains the instance specified by its absolute location from the repository root. The second obtains the instance by iterating through all instances in the project to find its display name.

// Obtain an instance by location// rmaProject is an NdRmaProjectString instanceLocation = "/Business Library/Region_3/Merchandising Region_3";NdRmaInstance rmaInstance = null;NdLocation location = NdLocationFactory.createLocation(instanceLocation);NdRmaEntry rmaEntry = rmaProject.lookupEntryByLocation(location);if (rmaEntry instanceof NdRmaInstanceFile) {

rmaInstance = ((NdRmaInstanceFile)rmaEntry).getInstance();}

// Obtain an instance by display nameString instanceName = "Merchandising Region_3";NdRmaInstance[] rmaInstances = rmaProject.getAllInstances(true);for (int i = 0; i < rmaInstances.length; i++) {

rmaFile = ((NdRmaFileContent)rmaInstances[i]).getFile();if (rmaFile.getDisplayName().equals(instanceName)) {

rmaInstance = rmaInstances[i];break;

}}



These methods help identify if the instance is one of a special type of instance:

boolean isFilterInstance()boolean isQueryInstance()

The isFilterInstance() method returns true if this instance is an instance of a Filter template. isQueryInstance() returns true if this instance is an instance of a Query template.

When instances are loaded from the repository some linking errors may occur. This can happen when the template of the instance might have changed, or might not exist anymore. These errors are dealt with using the following NdRmaInstance methods:

boolean hasLinkingErrors()NdRMAException[] getLinkingErrors()void clearLinkingErrors()boolean hasLinkingFixes()NdInstantiationFix[] getLinkingFixes()void fixLinkingErrors()

The hasLinkingErrors() method returns true if linking errors occurred while loading the instance. getLinkingErrors() returns a list of the linking errors that may have occurred while loading the instance. If no error occurred, an empty array is returned. clearLinkingErrors() clears the list of linking errors. This is useful if fixLinkingErrors() is not called and you wish to ignore the errors. hasLinkingFixes() returns true if there are linking fixes available for the instance. getLinkingFixes() returns an array of NdInstantiationFix objects which can provide information about the linking fixes that exist on the instance and which can be fixed by calling fixLinkingErrors(). If no fixes are needed an empty array is returned. Call the fixLinkingErrors() method to automatically fix the linking issues if there are any. The list of linking fixes is then cleared. Note that this method does not fix validation errors, which are errors that may occur during the editing of the instance.

Displaying the Contents of an Instance

The following NdRmaInstance methods are used to get the contents of an instance:

NdInstanceElementNode[] getInstanceElementNodes()NdInstanceElementNode[] getInstanceElementNodes(NdInstanceElementNode node)NdInstanceElementNode[] getInstanceElementNodesForTOC()NdInstanceElementNode[] getInstanceElementNodesForTOC(NdInstanceElementNode node)NdInstanceElementNode lookupInstanceElementNode(String instanceSectionName,

String nodePath, boolean resultForTOC)

The getInstanceElementNodes() method returns the top-level nodes of the instance as an array of NdInstanceElementNode. To get the sub-nodes, call getInstanceElementNodes(NdInstanceElementNode node) on each node.

The getInstanceElementNodesForTOC() method returns the instance element nodes that are used to display the table of contents of the instance. (An example of a “table of contents” is the table of contents in a generated RMA.) A variant of this method takes an NdInstanceElementNode as a parameter and will supply the instance nodes for the passed node. lookupInstanceElementNode() returns the instance node at the supplied



path in the instance section of the supplied name. To lookup this node in the context of a table of contents, set resultForTOC to true. See “Instance Element Node (NdInstanceElementNode)” on page 74.

Editing the Contents of an Instance

This section describes the NdRmaInstance methods which are available for editing an instance. Editing errors may occur during the execution of these methods (see “Editing Errors” on page 73).

void setNodeValue(NdInstanceElementNode node, String displayValue)NdInstanceElementNode[] getAffectedInstanceElementNodes()void setNodeInstance(NdInstanceElementNode node, String templateDisplayName)void addListValue(NdInstanceElementNode list, String displayValue)void addListValueBefore(NdInstanceElementNode list, String displayValue,

NdInstanceElementNode targetNode)void addListValueAfter(NdInstanceElementNode list, String displayValue,

NdInstanceElementNode targetNode)

The setNodeValue(NdInstanceElementNode node, String displayValue) method sets the value of the supplied node to the passed display value. If the displayValue is not different than the current displayValue then the value will not be applied. getAffectedInstanceElementNodes() returns the nodes that have been secondarily and consequentially changed due to the most-recent use of the setNodeValue() method. This list will not include the instanceElement node directly modified by the most-recent use of the setNodeValue() method. This method will return an empty array if no nodes have been affected by the most-recent setNodeValue() usage.setNodeInstance() replaces the instance in the specified node with a new instance of the specified template name. This method can only used for nodes configured by a template list provider. The template name must be the display name of one of the templates listed in that template list provider.

The addListValue() method adds the supplied display value to the supplied list node. addListValueBefore() adds the supplied display value to the supplied list immediately before the existing element targetNode. Editing errors may occur during the execution of this method. addListValueAfter() adds the supplied display value to the supplied list immediately after the existing element targetNode. Editing errors may occur during the execution of this method.

The addListValueXXX() methods described above add only String values. In contrast, the following addListInstanceXXX() methods are used to add instances of templates to the supplied list.

void addListInstance(NdInstanceElementNode list)void addListInstance(NdInstanceElementNode list, String templateDisplayName)void addListInstanceBefore(NdInstanceElementNode list, NdInstanceElementNode targetNode)void addListInstanceBefore(NdInstanceElementNode list, String templateDisplayName,

NdInstanceElementNode targetNode)void addListInstanceAfter(NdInstanceElementNode list, NdInstanceElementNode targetNode)void addListInstanceAfter(NdInstanceElementNode list, String templateDisplayName,

NdInstanceElementNode targetNode)



The addListInstance(NdInstanceElementNode list) method is used when the list may only contain instances of the same template. The addListInstance(NdInstanceElementNode list, String displayValue) method is used when the list may only contain instances of different templates. (Examples of both usages are found in AddSegmentExample.java, which is part of the RMA API example.)

The addListInstanceBefore(NdInstanceElementNode list, NdInstanceElementNode targetNode) method adds an instance element to the supplied list immediately before the existing element targetNode. The addListInstanceBefore(NdInstanceElementNode list, String templateDisplayName, NdInstanceElementNode targetNode) method adds an instance element of the template type identified by the given templateDisplayName to the supplied list immediately before the existing element targetNode. A corresponding set of addListInstanceAfter() methods work in the identical fashion as the addListInstanceBefore() methods, except the instance element is added after the existing element, rather than before.

The position of existing nodes within their containing lists may be changed using the following methods:

void moveListNodeUp(NdInstanceElementNode node)void moveListNodeDown(NdInstanceElementNode node)void moveListNodesUp(NdInstanceElementNode[] nodes)void moveListNodesDown(NdInstanceElementNode[] nodes)

The moveListNodeUp(NdInstanceElementNode node) method moves the node up within its containing list (i.e., its index in the list is decremented by 1). moveListNodeDown(NdInstanceElementNode node) moves the node down within its containing list (i.e., its index in the list is incremented by 1). The moveListNodesUp(NdInstanceElementNode[] nodes) method moves the nodes up within their containing list. The nodes retain their relative position within the list and the node in the nodes with the highest index will be located just before the node above the node with the lowest index in the list. If the node with the lowest index is at the top of the list no action will occur. moveListNodeDown(NdInstanceElementNode[] nodes) moves the nodes down within their containing list. The nodes retain their relative position within the list and node in the nodes with the lowest index will be located just after the node below the node with the highest index in the list. If the node with the highest index is at the bottom of the list no action will occur.

void moveListNodesBefore(NdInstanceElementNode[] nodes, NdInstanceElementNode targetNode)void moveListNodesAfter(NdInstanceElementNode[] nodes, NdInstanceElementNode targetNode)

The moveListNodesBefore() method moves the nodes before the targetNode in their containing list (i.e. each of the nodes’ index in the list will be less than the targetNodes' index with the final node from nodes having an index that is 1 less than the targetNodes' index. The relative position of each node in nodes will be maintained. The moveListNodesAfter() method moves the nodes after the targetNode in their containing list (i.e. each of the nodes’ index in the list will be greater than the targetNodes' index with the first node from nodes having an index that is 1 greater than the targetNodes' index. The relative position of each node in nodes will be maintained.

Nodes are deleted with these methods:



void deleteListNode(NdInstanceElementNode node)void deleteListNodes(NdInstanceElementNode[] nodes)

deleteListNode() deletes the supplied node from its containing list. deleteListNodes(NdInstanceElementNode[] nodes) deletes the supplied nodes from their containing list.

Editing Errors

Editing errors may occur during the execution of any of the methods described in the previous section (“Editing the Contents of an Instance” on page 71). An editing error will occur, for example, when an incorrect template display name is supplied to the addListInstance(NdInstanceElementNode list, String templateDisplayName) method. The errors may be obtained with the following NdRmaInstance methods.

boolean hasEditingErrors()boolean hasEditingError(NdInstanceElementNode node)NdRmaException getEditingError(NdInstanceElementNode node)NdRmaException getEditingError(String nodePath)String[] getPathsOfNodesWithEditingErrors()void clearEditingErrors()

The hasEditingErrors() method returns true if the editing of this instance generated errors. hasEditingError(NdInstanceElementNode node) returns true if the editing of this instance generated an error caused by the provided node. getEditingError(NdInstanceElementNode node) returns the editing error that may have occurred by calling one of the editing methods on the supplied node. If no error occurred, null is returned. getEditingError(String nodePath) returns the editing error that may have occurred by calling an editing method for the node located by the supplied node path. If no error occurred, null is returned. getPathsOfNodesWithEditingErrors() returns an array of nodePaths for the nodes that currently have editing errors. If no nodes have an error then an empty array is returned. clearEditingErrors() clears all the editing errors that may have occurred.

Validation Errors

When changes are made to an instance, those changes need to be validated in order to verify that the instance conforms to the constraints put in place by the template. The following NdRmaInstance methods are related to validation.

void validate()void validate(NdInstanceElementNode)boolean hasValidationErrors()boolean hasValidationError(NdInstanceElementNode node)NdRMAException getValidationError(NdInstanceElementNode node)NdRMAException getValidationError(String nodePath)NdRMAException[] getNodeValidationErrors()String[] getPathsOfNodesWithValidationErrors()NdRMAException[] getOtherValidationErrors()void clearValidationErrors()



Begin validation by calling one of the validate() methods. This will generate a list of validation errors in cache. You may want to call the clearValidationErrors() method before calling validate() in order to clear any existing list.

The validate() method tries to validate this instance. A variant of validate() takes an NdInstanceElementNode as a parameter to only validate that node, and its sub-nodes, and not the whole instance. hasValidationErrors() returns true if the validation of this instance generated validation errors. hasValidationError(NdInstanceElementNode node) returns true if the validation of this instance generated an error caused by the provided node. getValidationError(NdInstanceElementNode node) and getValidationError(String nodePath) return the validation error that occurred on the supplied node. If no error occurred on that node, either method returns null. getNodeValidationErrors() returns the node-specific validation errors that occurred on the instance. If no node-specific errors occurred on the instance, this method returns an empty array. getPathsOfNodesWithValidationErrors() returns an array of nodePaths for the nodes that currently have validation errors that occurred on the instance. If no node-specific errors occurred on the instance, this method returns an empty array. getOtherValidationErrors() returns the validation errors for which there is no associated node. If no such error occurred, this method returns an empty array. The clearValidationErrors() method clears the list of editing errors.

Instance Element Node (NdInstanceElementNode)NdInstanceElementNode is the base interface for all nodes returned by the getInstanceElementNodes() and getInstanceElementNodesForTOC() methods of the NdRmaInstance interface. The NdInstanceElementNode interface provides only one method:

NdRmaInstance getInstance()

The getInstance() method returns the root instance this node belongs to.

Several interfaces which represent nodes extend NdInstanceElementNode. These interfaces include:

NdWhitespaceNode

NdStringNode

NdErrorNode

NdMetaphorNode

NdAbstractInstanceNode

The NdWhitespaceNode interface represents a whitespace node and provides the getWhitespace() method which returns the whitespace character of the node. The NdStringNode interface represents a string node and provides the getString() method which returns the String value of the node. The NdErrorNode interface represents an error node and provides the getError() method which returns the NdError for the node. The NdMetaphorNode interface wraps the information needed to display one of the metaphors (decision table, decision tree, or score model). The NdAbstractInstanceNode interface represents a generic instance node which could be a single instance node or a list node.



The NdAbstractInstanceNode interface represents a generic instance node which could be a single instance node or a list node. Several interfaces which represent nodes extend NdAbstractInstanceNode. These interfaces are:

NdInstantiationNode

NdInstanceNode

NdTableRowNode

NdAbstractInstanceListNode

NdInstanceListNode

NdTableNode

The NdInstantiationNode interface represents an instantiation node. NdInstanceNode represents a generic instance node which could be a single instance node or a list node. NdTableRowNode represents a row in the table. NdAbstractInstanceListNode represents an instance list node, as opposed to a single instance node. The NdInstanceListNode and NdTableNode interfaces extend NdAbstractInstanceListNode. NdInstanceListNode defines the instance list node interface and NdTableNode represents an instance list node that would be displayed in a table. For details on these interfaces refer to the Blaze Advisor API Reference.

VersioningThe RMA Service API supports versioning of repository entries through two interfaces, NdRmaEntryVersioningOperations and NdRmaEntryVersioningInfo.

The NdRmaEntry interface provides the getVersioningOperations() method for obtaining NdRmaEntryVersioningOperations for the entry. The method returns null if the repository does not support versioning or if the entry cannot be versioned. In the current release, only instances (NdRmaInstance) support all versioning operations. Projects (NdRmaProject) support some versioning operations, but not the getVersion(), promote(), and restore() methods. Versioning is not supported by subprojects.

The getVersioningInfo() method of NdRmaEntry obtains versioning information (NdRmaEntryVersioningInfo) which is provided for all entries in a versioned repository. The method returns null if the repository does not support versioning.

Versioning Operations (NdRmaEntryVersioningOperations)The NdRmaEntryVersioningOperations interface declares the following methods:

void update()void checkOut()void cancelCheckOut()void checkIn(String comment)NdRmaEntry getVersion(String versionId)void promote()void restore()

The update() method updates the entry by fetching the latest version from the versioning system. checkOut() checks out the entry from the versioning system.



cancelCheckOut() cancels a previous check out from the versioning system. checkIn() checks the entry into the versioning system with the supplied comment. getVersion() returns a version of the entry that corresponds to the supplied version ID. promote() promotes the entry in the versioning system so that it becomes the top version. restore() restores the entry that was previously deleted.

Versioning Information (NdRmaEntryVersioningInfo)The NdRmaEntryVersioningInfo interface provides methods which return instances of classes and interfaces in the com.blazesoft.repository.base package that provide versioning information.

NdRepositoryVersionHistory[] getVersioningHistory() NdRepositoryEntryLockInfo getVersioningLockInfo() NdRepositoryVersionResultSet getVersioningStatusInfo()

The getVersionHistory() method returns an array of NdRepositoryVersionHistory which represents each element in the repository entry’s versioning history. This class contains methods for obtaining the version ID, user ID, timestamp, comment, location and deletion status.

The getVersioningLockInfo() method returns NdRepositoryEntryLockInfo which provides current lock information on the versioned entry. This interface has methods for obtaining and setting the status of the lock (not locked, locked by user, locked by user in another workspace, locked by another user), the user ID of the owner of the lock, the date of the lock, and the location of the entry.

The getVersioningStatusInfo() returns an NdRepositoryVersionResultSet which defines the result set returned by the invocation of methods in the repository version manager interface. For further information, consult the Blaze Advisor API Reference entry for NdRepositoryVersionResultSet.

The versioning status and lock information for all entries in a directory can be obtained quite efficiently using the getVersioningInfos() method of the NdRmaDirectory interface which returns an instance of NdRmaDirectoryVersioningInfos. Versioning operations are not available for the directory itself in the current release. A list of directories in a project can be obtained by calling NdRmaProject.getDirectories(). See “RMA Project (NdRmaProject)” on page 60.

The NdRmaDirectoryVersioningInfos interface contains these methods:

NdRepositoryEntryLockInfo[] getVersioningLockInfos() NdRepositoryVersionResultSet[] getVersioningStatusInfos()

The getVersioningLockInfos() method returns the versioning lock information for all the entries in this directory. getVersioningStatusInfos() returns an array of NdRepositoryVersionResultSet which defines the result set returned by the invocation of methods in the repository version manager interface.



RMA QueriesThe RMA Service API supports the execution of existing queries at the project level. Query results are returned as an array of NdRmaQueryResultItem. Query results can be instances as well as the contents of instances.

Query instances are obtained through the getAllQueryInstances() method of NdRmaProject (“RMA Project (NdRmaProject)” on page 60). The method returns all the Query instances that can be found in the project.

NdRmaQueryInstance[] getAllQueryInstances(boolean includeSystemDirectories)

Query Instance (NdRmaQueryInstance)The NdRmaQueryInstance interface extends NdRmaInstance, so that it can be displayed, edited, and versioned just like any other instance. The interface supplies methods used to run the query and gets its results:

void executeQuery()void executeQueryAsynchronously()void executeQueryForTOC()void executeQueryAsynchronouslyForTOC()int getQueryExecutionStatus()boolean hasQueryResults()NdRmaQueryResultItem[] getQueryResults()void stopQueryExecution()

The executeQuery() and executeQueryForTOC() methods execute the query. The later method accumulates only the results that are relevant for a table of contents. Both methods execute the query synchronously. This means that the thread in which the method is invoked waits until execution is complete. The corresponding executeQueryAsynchronously() and executeQueryAsynchronouslyForTOC() methods execute the query asynchonously. This means that the thread in which this method is invoked will not wait until its execution is completed, but the query status will be updated as the execution progresses. An entry exclusion filter can be set on the project to filter query results. The getQueryExecutionStatus() method returns the status of the query execution. The status can be one of: EXEC_STATUS_NOT_STARTED, EXEC_STATUS_COMPLETE, EXEC_STATUS_EXECUTING, EXEC_STATUS_CANCELLED, or EXEC_STATUS_ABORTED. The hasQueryResults() method returns true if the execution of the query delivered results. getQueryResults() returns the results of the query execution as an array of NdRmaQueryResultItem. The stopQueryExecution() method stops the execution of this query. This is only applicable to asynchronously executed queries.

Errors that may occur when executing queries may be obtained with the following methods:

boolean hasQueryExecutionErrors()NdRMAException[] getQueryExecutionErrors()void clearQueryExecutionErrors()



The hasQueryExecutionErrors() method returns true if any error occurred while trying to execute the query. getQueryExecutionErrors() returns the errors that occurred during the execution of the query. If no error occurred, an empty array will be returned. The clearQueryExecutionErrors() method clears the errors that may have occurred during the execution of the query.

These methods identify which special subtype of Query instance this Query instance is:

boolean isComparisonQueryInstance() boolean isSearchQueryInstance()boolean isVerificationQueryInstance()

The isComparisonQueryInstance() method returns true if this instance is an instance of Comparison Query. isSearchQueryInstance() returns true if this instance is an instance of Search Query. The isVerificationQueryInstance() method returns true if this instance is an instance of Verification Query.

This method indicates if the Query instance is a “transient” Query instance:

boolean isTransient()

A Transient Query instance is created using NdRmaQueryTemplate.generateTransientQueryInstance(). It serves as a lightweight, on-the-fly, use-and-lose query tool. A Transient Query instance cannot be saved. Attempting to use the NdRmaEntry methods save(), getLocation(), getDisplayPath(), or getParentDirectory() will result in an Exception. Transient Query instances are excluded from results returned by NdRmaDirectory.getEntries(), but are included with the results returned by the NdRmaProject getXXX() query-related methods.

This method allows the transient Query instance to be deleted. It cannot be deleted in the way a regular instance can be because that requires knowing the parent directory:

void deleteTransientQueryInstance()

The deleteTransientQueryInstance() method deletes a “transient” Query instance. Internally it obtains the parent directory and deletes it from there in the usual fashion. Of course, once this method has been used, this transient Query instance becomes invalid and can no longer be used.

Query Results (NdRmaQueryResultItem)The NdRmaQueryResultItem interface, used for returning query results, is a tag interface that is extended by NdRmaInstance. This means that query results will consist of instances, including query instances, as well as instance contents.

Filtering Entries in an RMA ProjectThe RMA Entry Filter Manager provides the ability to apply filtering to the current RMA Project. The NdRmaEntryFilterManager interface includes methods for working with both exclusion filters and inclusion filters. As the names imply, an exclusion filter will leave the item in question unfiltered if it does not match the condition for exclusion.



An inclusion filter will leave the item in question unfiltered if it does match the condition for inclusion.

A second type of inclusion filter exists for RMA projects. From the Blaze Advisor IDE, a filter can be applied to the PROM Project. That filter exists as a PROM project property. When an RMA project object is created, the RMA Entry Filter Manager is created and automatically applies the existing PROM project inclusion filter (if any). This filter cannot be set or removed by using the RMA Service APIs. When filtering has been applied, items that have been created new or have been modified will not be excluded due to the filtering.

RMA Entry Filter Manager (NdRmaEntryFilterManager)An instance of NdRmaEntryFilterManager is obtained for the project by calling getEntryFitlerManager() method of NdRmaProject.

The RMA Filter Manager declares the following methods:

void setEntryExclusionFilter(NdRmaEntryExclusionFilter rmaEntryExclusionFilter)NdRmaEntryExclusionFilter getEntryExclusionFilter()void setSecondaryEntryExclusionFilter(NdRmaEntryExclusionFilter secondaryRmaEntryExclusionFilter)void setEntryInclusionFilter(String filterAbsoluteLocationAsString)NdRmaEntry getEntryInclusionFilter()boolean isAnyFilterApplied()boolean isAnyInclusionFilterApplied()

The setEntryExclusionFilter() sets the given NdRmaEntryExclusionFilter as the current RMA Project exclusion filter. Passing null to setEntryExclusionFilter() will remove the filter. Use the getEntryExclusionFilter() method to obtain the current RMA Project exclusion filter. The return value is null if none currently set.

Use setSecondaryEntryExclusionFilter() to apply a second, additional RMA entry exclusion filter to the RMA project. This is intended to be used for temporary additional filtering. If no filter was previously applied using the setEntryExclusionFilter() method then this will be the only filter. Passing null to setSecondaryEntryExclusionFilter() will remove the secondary filter, leaving the exclusion filter previously set using setEntryExclusionFilter(), if any, untouched.

The setEntryInclusionFilter(String filterAbsoluteLocationAsString) method sets an RMA entry inclusion filter on the RMA project. The parameter is the absolute location (full pathname) of the entry inclusion filter. An inclusion filter is implemented as a type of Query instance that must have already been instantiated in Builder or the RMA. The getEntryInclusionFilter() method returns the current RMA Project’s inclusion filter as an NdRmaEntry or null if none has been set. The NdRmaEntry object allows information about the inclusion filter, such as its location or display name or display path, to be easily obtained.

The isAnyFilterApplied() method returns true if any inclusion or exclusion filter is currently applied to the RMA Project. isAnyInclusionFilterApplied() returns true if any inclusion filter is currently applied to the RMA Project. The method will return



true even when there is only an automatically applied, IDE-set, PROM project inclusion filter.

Entry Exclusion Filter (NdRmaEntryExclusionFilter)The NdRmaEntryExclusionFilter interface is used in filtering the set of items that are returned by a number of methods in the RMA API. The filtering is performed by your own custom exclusion filter class, which must implement NdRmaEntryExclusionFilter. You can use an exclusion filter to filter the results obtained from the getAllTemplates(), getAllInstances(), getAllQueryTemplates(), getAllQueryInstances(), getAllDirectories(), and getDirectories() methods in the NdRmaProject interface; as well as the getEntries() method in the NdRmaDirectory interface; and the executeQuery() and executeQueryForTOC() methods in the NdRmaQueryInstance interface.

The NdRmaEntryExclusionFilter interface contains two methods.

boolean isEntryToBeExcluded(NdRmaEntry entry)boolean isExcludedDirectoryToBeBrowsed(NdRmaDirectory directory)

The isEntryToBeExcluded() method returns true if the supplied entry is to be excluded from the results of methods navigating the project. isExcludedDirectoryToBeBrowsed() returns true if the supplied directory, which is to be excluded from the results of methods navigating the project, should itself be browsed in case its entries are not to be excluded.

Here is an example of a simple implementation of NdRmaEntryExclusionFilter that filters out entries whose path is in a list of paths to exclude:

public class RmaEntryExcludedPathsFilter implements NdRmaEntryExclusionFilter{

private Vector _excludedPaths;

public RmaEntryExcludedPathsFilter(Vector excludedPaths){

_excludedPaths = excludedPaths;}public boolean isEntryToBeExcluded(NdRmaEntry rmaEntry){

NdLocation entryLocation = rmaEntry.getLocation();entryLocation = rmaEntry.getLocation();if (entryLocation == null) {

return false;}String path = entryLocation.toString();for (int i = 0; i < _excludedPaths.size(); i++) {

String excludedPath = (String) _excludedPaths.elementAt(i);// If the path equals an excludedPath or starts with an exludedPath + "/"// then it is either exactly an excluded path, or it is a subdirectory of // one and thus it should be excluded.if (path.equals(excludedPath) || (path.startsWith(excludedPath + "/"))) {

return true;}

}return false;

}



public boolean isExcludedDirectoryToBeBrowsed(NdRmaDirectory directory){

// If a directory is to be excluded then so should its contents.return false;

}}

Only one custom exclusion filter may be set on a project at a time. Use the setEntryExclusionFilter(RmaEntryExcludedPathsFilter filter) method of NdRmaEntryFilterManager to set the filter. One may, of course, switch to another filter by calling the method again. Pass null to the method to indicate that no filtering should be performed. Obtain an instance of NdRmaEntryFilterManager with the getEntryFilterManager() method of NdRmaProject. Use the getEntryExclusionFilter() method of NdRmaEntryFilterManager to obtain the current NdRmaEntryExclusionFilter. See “RMA Entry Filter Manager (NdRmaEntryFilterManager)” on page 79.

The sample client code below passes a Vector of excluded paths to the constructor of the filter class. It sets the project filter by passing the filter to setEntryExclusionFilter(). The call to getAllQueryInstances() returns all query instances available to the project, except those in the /Business Library/Asia and/Business Library/Europe directories and their subdirectories.

// rmaProject is an NdRmaProjectVector excludedPaths = new Vector();excludedPaths.addElement("/Business Library/Asia");excludedPaths.addElement("/Business Library/Europe");RmaEntryExcludedPathsFilter myFilter = new RmaEntryExcludedPathsFilter(excludedPaths);NdRmaEntryFilterManager filterManager = rmaProject.getEntryFilterManager();filterManager.setEntryExclusionFilter(myFilter);NdRmaQueryInstance[] queries = rmaProject.getAllQueryInstances(true);

RMA Session APIA Rule Maintenance Application is designed to enable a user to create and modify instance files. The RMA Service API is designed to accommodate those RMA needs by providing functionality which interacts with the ROM and PROM APIs and results in changes to the project which are persisted in the repository. The purpose of the RMA Session API is to supplement the RMA Service API by providing a state-holding interface while still not being tied to any one client technology or execution environment. Note that the term “session” used in the name of this API refers to a “user session” implying “this application as used by one user”, as opposed to a web session.

During a user's application session, there are two types of information which are needed and/or modified by both the application layer (the RMA Service API), and the presentation medium (the application's user interface). Some of that information is static for the duration of the session, such as the current project; and some of it changes frequently with each change to the user interface view. The RMA Session API supports both types of information and is an interface between the application and presentation levels.



The RMA Session API defines the methods for keeping necessary state information in a Java class. The Java class can then be kept in a web session variable for web clients, or used directly by a fat client. Having all the state information gathered, organized, and supported by this API enables all the items required to maintain state to be held in a single NdRmaSession session object (see “RMA Session (NdRmaSession)” on page 82).

When a state-inducing action is performed on behalf of an RMA user, the RMA Session API can enable the retention and use of that state information for the life of the user's session. Additionally, the API provides a facility for client RMA applications to supply a set of properties, defined by the RMA developer, which can be saved as part of the session state information (see “RMA Session Properties (NdRmaSessionProperties)” on page 84). Also, to enable recovery from application errors, there are commands for capturing a backup of the state information so that, if needed, another provided command can restore the session state to its last-cached configuration.

An application commonly has a consistent framework for maintaining application presentation, composed of one or parts that are the main “working“ area. A typical framework could consist of a title or banner area at the top, followed by a toolbar of global commands common to the application at any time such as “Help,“ “Sign In,“ “Sign Out, “ and a main area that is sensitive to and displays the application's current context. We call this dynamic area a “View.“ An RMA View is represented by the NdRmaView interface (see “RMA View (NdRmaView)” on page 84).

Often, there is a need to display only one View area, such as when a list of the project’s files and directories is being displayed. At other times the user may choose to have more than one View open simultaneously, such as when editing an instance in one View and comparing it to a version of that instance in a second View.

Different Views have different requirements. Sometimes a View will be a single pane such as when a sign-in or login page is displayed. Other times a View is more complex, such as the View of an Instance editor. That View can even have other sub-areas that are dependent upon the state of the main area such as a “Table of Contents,” a context-sensitive command bar, or a navigation mechanism that reflects the item in the View’s location. The actual design and needs of an application’s Views will vary from one RMA design implementation to the next.

RMA Session (NdRmaSession)The RMA Session (NdRmaSession) contains only methods that support the state maintenance needs which are common to every RMA application, while recognizing that not all RMA applications will have the same needs. To accomplish these disparate goals, the RMA Session provides methods that set or access objects of known and expected types.

Where the state information may be specific to a custom RMA, the design may be organized into a class where the class name is pre-defined (NdRmaSessionProperties), but the definition of the class is decided by the developer of the RMA. See “RMA Session Properties (NdRmaSessionProperties)” on page 84.



The NdRmaSession interface defines methods for accessing the session properties object defined by the RMA developer. Other methods are provided to open a View or an array of views, close a single View or close all open Views, and to retrieve a particular open View or an array of all open Views, etc.

“Opening a View” is simply the act of handing the View object, which was independently created in other server-side code, to the RMA Session API so that it can keep it as state information.

To assist in error recovery, the RMA Session API provides the captureRecoveryState() method to take a snapshot of the NdRmaSession object, and the restoreRecoveryState() method to replace the current state with the most recently captured state.

The NdRmaSession interface defines these methods:

void setRepository(NdRmaRepository rmaRepository)void setProject(NdRmaProject rmaProject)NdRmaSessionProperties getSessionProperties()void openView(NdRmaView view)void openViews(NdRmaView[] views)boolean hasAnyView()NdRmaView getView(String viewId)NdRmaView[] getAllViews()void closeView(String viewId)void closeAllViews(String viewId)void closeAllViews()void captureRecoveryState()void restoreRecoveryState()NdRmaSession cloneSession()

The setRepository() method saves the provided RMA repository entry as the repository for the session. setProject() saves the provided RMA project entry as the project for the session. getSessionProperties() retrieves the client-defined NdRmaSessionProperties object. openView() saves the provided, client-obtained view (NdRmaView) object, thus establishing an open view in this session state object. If an open view with the same viewId value as this view exists, it is replaced with this view object. The relative order of the open views is maintained. openViews() saves the supplied array of client-obtained view (NdRmaView) objects thus establishing them as open views in this session state object. If an existing open view with the same viewId value as one of these views in the provided array already exists, it is replaced with the new view object. Note that the relative order of open views is maintained. hasAnyView() returns true if any view is currently open for this session. The getView() method retrieves the view object identified by the given viewId.

getAllViews() retrieves an array of all currently opened view objects within this session. The relative order of open views is maintained. That is, if View ʺaʺ is opened, and then View ʺbʺ and View ʺcʺ are opened, then the array returned is: views[0] == View ʺaʺ, views[1] == View ʺbʺ, and views[2] == View ʺcʺ. If View ʺbʺ is closed, then the array returned is: views[0] == View ʺaʺ and views[1] == View ʺcʺ.



The closeView() method closes the view identified by the given viewId. If the view is a child view then the child is closed and the child's parent will, once again, be open and own the same viewId. closeAllViews() closes all currently opened view objects identified by the given viewId. That is, a family of views will be closed if the viewId points to either a parent or a child. closeAllViews() closes all currently opened view objects within this session. captureRecoveryState() saves the current state of this session. This method is called by clients of the RMA Session API in order to preserve the current state. A client might use this method prior to handling any new requested action caused by an RMA user so that if the action caused an error, then the error page could offer a recovery (“back”) link to a state that did not cause an exception. restoreRecoveryState() replaces all current state with the state that was most-recently saved. The cloneSession() method returns a new NdRmaSession with all session-level objects and properties copied from this session to the new session object. No view-level information is copied to the new session.

RMA Session Properties (NdRmaSessionProperties)Different RMAs will have different needs depending on varied factors, such as what platform the RMA is targeting, or what features the user interface will support, etc. The RMA Session APIs can not anticipate those needs, and will not directly support any feature targeted to a particular deployment. However, the need does exist for those properties to become part of the session state so that they can be accessed on both the server and client sides.

To accommodate this need, an instance of the NdRmaSessionProperties object is created and cached by NdRmaSession’s constructor. A method to access the session properties object is provided in the NdRMASession (see “RMA Session (NdRmaSession)” on page 82). These methods simply allow the properties to be saved along with the other current stateful information and will never be accessed by the RMA Session API.

RMA View (NdRmaView)An RMA application typically has a framework that remains relatively unchanged throughout the session. In addition to that framework there are commonly one or more areas of the application which are the main presentation panes. These main areas are termed Views.

The RMA Service API defines the NdRmaEntry interface, which represents the main “visual” component, if you will, of an RMA such as a project, a directory, or an instance. An RMA View (NdRmaView) presents one of those NdRmaEntry objects as a View in the RMA. There can be more than one representation of NdRmaEntry object in the same RMA. For example, one View of an instance could be represented as the instance being edited. Another View of that same object might be represented as the instance being saved as a new instance in the “Save As" pane, or as the object whose version history is being displayed in the “History" pane.

A View may not be representing object at all, such as when the “Sign In” dialog, which gathers user information prior to establishing a repository connection, is being displayed. That is still a View.



A View can represent just a single pane, or page, such as a web page; and it can represent an NdRmaEntry object where that object is being presented in a particular context such as in its editor or in its History viewer. The RMA Session API’s NdRmaView interface names these parts of the View. String viewerName is the name of the viewer for this View. It names the means by which the View is rendered. In web enviroment that is the web page name. NdRmaEntry viewEntry is the NdRmaEntry object that is the subject of the View (it may be null).

Note that an NdRmaEntry object can access both the project and the repository objects. That is useful because at any time, while a View is open, those objects are available to display information about themselves. When a View does not have a viewEntry there is also no project or repository available such as when the View is of the “Sign In” page.

To accommodate customizations and design-specific state information, the RMA View has a properties object associated with it. The definition of that object is up to the RMA developer. See “RMA View Properties (NdRmaViewProperties)” on page 87.

The NdRmaView interface provides set and access methods for the NdRmaEntry object in the view, as well for the name of the viewer/renderer. A refresh method is provided to refresh the underlying ROM/PROM object that is the represented by the viewEntry. The refresh applies only to Views holding NdRmaEntry objects (not null). It will update that object from the repository and additionally, it will refresh any other open View.

Because a user may wish to have multiple Views open simultaneously, the NdRmaView constructor creates, and caches as part of the View, a string ID that is guaranteed to be unique throughout the lifetime of the current session. An accessor method provides the viewId. The value of the viewId is not important to the RMA, it is just a differentiator and a means to refer to and access a particular View.

There are times when an RMA design may call for creating a View that is a copy of an existing View, such as the RMA “Split View” command. To support this need, NdRmaView provides the cloneView() method which returns a new NdRmaEntry object with identical data except it has its own, unique viewId.

There are times when one may wish to create a View that spawns from, and replaces, the current View without losing the original View; such as when an instance is being edited and the user wants to navigate to a sub-instance (rule) where that rule is stored (versioned) separately from the parent instance. One may wish to close the child View and be able to view the parent at a later time, in the same state it had been when the child was first open. To support this, the cloneChildView() method which creates a clone of the current View, as does the cloneView method with a few exceptions. The cloned child View uses the same viewId as its parent, it caches the parent view, and the child does not inherit the parent’s errors. Its Exceptions array is always initially empty. When a View is created in this manner, the boolean method isChildView() returns true, otherwise it returns false. The getParentView() method returns the parent View, or null if isChildView() returns false.

The NdRmaView interface provides state-related methods pertaining to Views of NdRmaEntry objects. The createView() method of the NdRmaViewFactory class is used to



create an NdRmaView instance and the NdRmaView constructor takes an NdRmaSession object.

The NdRmaView interface defines these methods:

NdRmaSession getSession()NdRmaViewProperties getViewProperties()String getViewId()void setViewEntry(NdRmaEntry viewEntry)NdRmaEntry getViewEntry()void setViewNodePath(String viewNodePath)String getViewNodePath()void setViewInstanceSectionName(String viewInstanceSectionName)String getViewInstanceSectionName()void setViewerName(String viewerName)String getViewerName()NdRmaView cloneView()NdRmaView cloneChildView()NdRmaView getParentView()boolean isChildView()void resetProperties()void refresh()void addException(NdRMAException exception)void addExceptions(NdRMAException[] exception)boolean hasException()NdRMAException[] getExceptions()void clearExceptions()

The getSession() method returns the session object that this View belongs to. getViewProperties() retrieves the client-defined NdRmaViewProperties object. getViewId() returns the auto-generated, session-unique identifier assigned to this NdRmaView object when it was created. setViewEntry() sets the NdRmaEntry object which this View will be representing (may be null). getViewEntry() returns the NdRmaEntry object which this View is currently representing. The method returns null if no viewEntry has been set.

setViewNodePath() sets the path to the current sub-instance node belonging to the current viewEntry where the sub-instance is not one that is stored-separately. This value should be set to null when the View is not for a sub-instance. getViewNodePath() returns the nodePath to the current sub-instance which is not stored-separately. The nodePath value should be null when the View is not currently of a sub-instance.

setViewNodePath() sets the path to the current sub-instance node belonging to the current viewEntry where the sub-instance is not one that is stored-separately. This value should be set to null when the View is not for a sub-instance. getViewNodePath() returns the nodePath to the current sub-instance which is not stored-separately. The nodePath value should be null when the View is not currently of a sub-instance.

setViewInstanceSectionName() sets the instance section name for the current sub-instance node belonging to the current viewEntry where the sub-instance is not one that is stored-separately. This value must be one of the NdAbstractInstanceNode.INSTANCE_SECTION_XXX values; or null when the View is not for a sub-instance. getViewInstanceSectionName() returns the instanceSectionName



value that was most-recently set using setViewInstanceSectionName(). The instanceSectionName value should be null when the View is not currently of a sub-instance. setViewerName() sets the name of the viewer (page name) that will be used to present this View. getViewerName() returns the name of the viewer (page name) that will be used to present this View, or its default value, an empty String, if none has been set. cloneView() returns a clone of the current View, however the viewId of the clone will be unique. cloneChildView() returns a child clone of the current View. The viewId of the child clone will be the same as this View’s viewId. The Exceptions array will be empty. This View will be cached as the parent View of the new child View. getParentView() returns the NdRmaView object which is the parent View of this View, or null if this View is not a child View. isChildView() returns true if this View has a parent View. resetView() resets the values of all the View properties, including the NdRmaViewProperties properties, to their original, default values. refresh() refreshes the current project and all open Views from the repository. addException(NdRMAException exception) adds the given NdRMAException object to the array of previously saved exception objects (if any). addExceptions(NdRMAException[] exception) adds the given array of NdRMAException objects to the array of previously saved exception objects (if any). hasException() returns true if any NdRMAException objects have been saved (and not cleared) for this session. getExceptions() returns an array of previously saved NdRMAException objects. If there is only one Exception, then the array will have only one item. If there are no Exceptions, then the array will be empty. clearExceptions() clears all previously saved exception objects.

RMA View Properties (NdRmaViewProperties)Different Views will have different needs depending on varied factors, such as whether a particular viewer has any dependent sub-areas or panes, or if a View should be readonly or not. The RMA View API can not anticipate those needs, and will not directly support any feature targeted to a particular View’s needs. However, the need does exist for those properties to become part of the View state so that they can be accessed on both the server and client sides.

To accommodate this need, an instance of the NdRmaViewProperties object is created and cached by NdRmaView’s constructor. A method to access the view properties object is provided in the RMA View API. See “RMA View (NdRmaView)” on page 84.

These methods simply allow the properties to be saved along with the other current stateful information and will never be accessed by the RMA View API.


C H A P T E R 6

Base Repository and Version Management APIs

The FICO™ Blaze Advisor® business rules management system base repository and version management interfaces and APIs support:

Implementing a custom repository storage layer that Blaze Advisor can make use. These interfaces are referred to as the base repository interfaces.

Implementing an interface to a third party content management system that Blaze Advisor can make use of. These interfaces are referred to as the version management interfaces.

These APIs are used to implement the repository, and are separate from the APIs used by clients of the repository. They clearly define the semantics of repository and version management operations so that all implementations behave in the same way.

Storage Layer InterfacesThe base repository package is com.blazesoft.repository.base. The JavaDoc is in the Innovator section. You can find the JavaDoc by going to Help > API Reference in Builder. These base repository interfaces are responsible for the storage and retrieval of information stored in the repository:

NdRepositoryEntry

This interface is the base interface from which all other interfaces in the storage layer are derived.

NdRepositoryItem

This interface is used to represent entries in the storage layer that have content (i.e. are not directories).

NdRepositoryDirectory

This interface is used to represent directories within the storage layer.

NdRepository

This interface represents the entire repository as it is represented in the storage layer.


CHAPTER 6: Base Repository and Version Management APIs

About the WorkspaceThe workspace represents the view of and interaction with the physical storage layer and the version manager, authorization manager and lock managers that have been configured on the repository.

You should not need to implement the workspace interfaces for a custom repository. Blaze Advisor includes complete implementations that it uses for these operations.

The workspace layer is responsible for:

All interactions with the version manager. This removes the need for implementations of the storage layer to be aware of the version manager, therefore simplifying the implementations.

All interactions with the authorization and lock managers. This removes the need for the version manager implementations to be aware of these concepts, therefore simplifying the implementations.

The workspace interfaces are extensions of the storage layer interfaces that include versioning operations. They delegate to whatever version manager has been configured on the repository.

Version Management Client InterfacesThe interface for version management is NdWorkspaceVersionManager, named to emphasize the fact that this version manager is responsible for interactions between items that exist physically in the workspace and the versioning system. Most of the methods return either a boolean value or are declared to be void methods. If an operation cannot complete successfully, the methods are expected to throw an NdRepositoryVersionException that can contain an array of NdRepositoryVersionResultSet objects that summarize the status of the operation for repository entries that were involved in the operation. Only the location, success status and command output attributes of these result sets will be inspected by upper layers of the Advisor code.

It should be noted that the workspace version manager is responsible for the versioning of repository entries and their associated repository entry attributes, which implies that the versioning system needs to know how repository entry attributes are represented in the storage layer. For example, in the file repository that is supplied with Advisor an entry's attributes are stored in a file that is in the same directory and that has the file extension .innovator_attbs.

NdWorkspaceVersionManager

NdWorkspaceVersionManagerListener

Whenever a workspace version manager causes a modification to be made to the workspace, it is responsible for sending an event to any listeners that have registered interest in such changes. Typically, the only such listener would be the workspace itself. This allows implementations of the workspace version manager to



inform the workspace that it needs to synchronize itself with the current state of the repository as reflected in the storage layer.

NdWorkspaceVersionManagerEvent

This event is sent whenever the workspace version manager causes a change to be made to the representation of a repository entry in the storage layer. The event object contains two items of information:

The location of the repository entry that was affected.

An integer code indicating if the repository entry was modified, added to or removed from the storage layer.

Version Management System InterfacesThese interfaces are used for access to the versioning system outside the context of a workspace. The primary use is to provide a mechanism, via the NdVersioningSystemVersionManager interface, for browsing through the contents of the versioning system. The implementation of this interface is free to determine how much of the versioning system should be revealed to the client of the interface. The main use that will be made of this interface in Advisor will be to allow the browsing of items that have been deleted in the versioning system such that they no longer appear in the workspace whenever a repository is checked out.

NdVersioningSystemVersionManager

The implementation class for this interface will be a configurable item within the version manager configuration, which specifies both the workspace and system version managers. The interface contains the following methods:

NdRepositoryEntryFactory

This interface is used to create repository entries that are returned from the repository system version manager. This interface is implemented by the workspace layer and passed to the repository system version manager. The workspace implementation will create workspace entries which, since they do not correspond to entries in the physical storage layer, will all be virtual entries, i.e. their isVirtual method will return a true value.

Administration InterfacesThere are two administration interfaces, one associated with the storage layer and the other associated with the versioning system. They are separated out from the other interfaces so as not to confuse the roles of software that accesses the storage layer or versioning system from the workspace layer versus software that needs to perform administrative functions on a workspace.

NdRepositoryAdmin

NdRepositoryVersionSystemAdmin


CHAPTER 6: Base Repository and Version Management APIs

Repository ConnectionsConnections are made to a repository via an NdRepositoryConnection instance. During the process of establishing a connection to a repository, the repository configuration will be loaded from persistent storage in the repository, and will be used to configure the repository and any versioning system.

Repository ConfigurationsRepository configurations are serialized into an XML document that is stored at a well-known location within the repository. Instances of the repository configuration class are created from the contents of this XML document via the Blaze dynamic object model. For example, the portion of the repository configuration that specifies the repository connection will appear as follows:

<RepositoryConfig>…<RepositoryConnection><Factory>com.blazesoft.repository.file.NdFileRepositoryConnection</Factory><RepositoryName>MyRep</RepositoryName><RepositoryFolder>c:\xyz\MyRep</RepositoryFolder>…</RepositoryConnection>…</RepositoryConfig>

Repository Entry FiltersRepository entry filters are instances of NdRepositoryEntryFilter. They filter the entries within a directory to remove any administrative files that the versioning system may have placed there, and which are not logically part of the repository content. The workspace uses these filters to remove entries from the storage layer before presenting the entries to the ROM layer.


Index

BBOM 27BOM Admin APIs

manipulating imported external classes 27

BOM manipulation APIs 27

Cconnecting to repository 7ConstantDisplayValuesProvider 51,

56content-based API 12create

custom provider 47decision table 32decision tree 34enumeration 24Metaphor Model 31NdLocation 8NdPromItem 9NdRomDirectory 16PROM project 17question set 22ruleflow 22score model 37SRL class 23SRL function 21SRL ruleset 18

custom providercaching 57creating 47implementation guidelines 56

Ddecision tables

editing 32decision trees

editing 36DisplayValuesProvider 49, 55

Eedit

decision table 32decision tree 34

score model 37Entity Object Model 12entry exclusion filter 80

Iimported external classes

manipulating programmatically 27

Lloading a PROM project 18

MMetaphor APIs

creating a model 31loading an instance 31

NNdConstrainedListProvider 45NdContrainedListProvider 49NdDecTableModelFactory 32NdDecTreeModelFactory 32NdDecTreeNodeRenderingInfo 36NdDecTreePath 34NdDefaultConstrainedListProvider

46NdDefaultTemplateValueProvider

45NdDesignProvider 46NdDesignProviderMultiArg 53NdDesignProviderSelectableArg 52NdDesignProviderTypedArg 53NdLocation 8NdMetaphorModelException 32NdPromEntity 11NdPromInstance 12NdPromItemContent 11NdPromProject 9, 57NdPromProvider 12NdPromSrlRuleContent 13NdPromSrlRuleset 13NdPromTemplate 12NdPromTextContent 12NdProviderStaticArg 54


Index

NdProvidesDefaultValue 47NdRmaEntryExclusionFilter 80NdRmaQueryInstance 77NdRmaQueryResultItem 78NdRomConnectionContext 8NdRomConnectionManager 7NdRomSchemaManager 9NdScoreModelModelFactory 32NdTemplateValueProvider 44

Pperformance

custom providers 56Project Repository Object Model

(PROM) 9PROM item content 11PROM task

create enumeration 24create question set 22create ruleflow 22create SRL class 23create SRL function 21create SRL ruleset 18creating a PROM Project 17loading a PROM project 18release project resources 18

QQuestion Set Object Model 15

Rrelease PROM project resources 18repository item

find location 8typing attributes 8

Repository Object Model (ROM) 7RMA query 77Ruleflow Object Model 15

Sscore models

editing with API 37SRL Entity Object Model 14string-based API 12

Ttyping attributes of repository item 8

UUserDefinedDisplayValuesProvider 53


API Dev Guide

Documents

Transcript of API Dev Guide