API Dev Guide

Fair Isaac Blaze Advisor6.5

API DEVELOPER’SGUIDE

Best Practices

API Developer’s Guide

:

2 Fair Isaac Confidential and Proprietary Information

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.© 2005-2008 Fair Isaac Corporation. All rights reserved. Fair Isaac 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.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.

Product Name: Blaze Advisor 6.5 for Java - Service Pack 5Last Revised 12/20/2007Version 6.5Template LG5.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). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Creating a Ruleflow (NdPromFlowRuleflow) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Creating a Question Set (NdPromAaiQuestionSet) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Creating an SRL Class (NdPromSrlClassContent) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Creating an SRL Enumeration (NdPromSrlEnumerationContent) . . . . . . . . . . . . . . . . . . . . . . . 24

CHAPTER 2 Metaphor APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Loading a Metaphor Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Creating a Metaphor Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Decision Table Editing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

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

Example: Create a Subtree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Score Model Editing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

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

Fair Isaac Confidential and Proprietary Information 3

Contents

CHAPTER 3 Custom Provider API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Responsibilities of Provider Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Overview of the Custom Provider API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

NdTemplateValueProvider Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38NdDefaultTemplateValueProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39NdConstrainedListProvider Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39NdDefaultConstrainedListProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40NdDesignProvider Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40NdProvidesDefaultValue Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Creating Custom Provider Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Simple Value List Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Simple SRL and Display List Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Customizing Provider Behavior Using Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Defining Argument Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Processing Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

The Example Base Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Custom Provider Implementation Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

CHAPTER 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RMA API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53The RMA Repository (NdRmaRepository) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

RMA Project (NdRmaProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54RMA Entry (NdRmaEntry) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56RMA Directory (NdRmaDirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57RMA Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

File (NdRmaFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Project File (NdRmaProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Template File (NdRmaTemplateFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Instance File (NdRmaInstanceFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Editable File (NdRmaEditableFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

File Content (NdRmaFileContent) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59RMA Template (NdRmaTemplate) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59RMA Instance (NdRmaInstance) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Displaying the Contents of an Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Editing the Contents of an Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Instance Element Node (NdInstanceElementNode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Versioning Operations (NdRmaEntryVersioningOperations) . . . . . . . . . . . . . . . . . . . . . . . . . . 64Versioning Information (NdRmaEntryVersioningInfo). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

RMA Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Query Instance (NdRmaQueryInstance) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Query Results (NdRmaQueryResultItem) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Entry Exclusion Filter (NdRmaEntryExclusionFilter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

CHAPTER 5 Base Repository and Version Management APIs . . . . . . . . 69Storage Layer Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69About the Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Version Management Client Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Version Management System Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71


Fair Isaac Blaze AdvisorAPI Developer’s Guide

Administration Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Repository Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Repository Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Repository Entry Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72


Contents


C H A P T E R 1

ROM and PROM APIs

The 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/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();// Change the path to the repository as appropriate. The repository should exist.


CHAPTER 1: ROM and PROM APIs

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 NdRomConnetcionContext// 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.lookup(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) NdPromSrlRulesetItem[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 20.

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 21.

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 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 bodyString 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();

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

Metaphor APIs

The 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 2: 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 26. Similar code is used to create decision tree and score model instances. These models are discussed in “Decision Tree Editing API” on page 28 and “Score Model Editing API” on page 31.

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 getCellFieldValue() method returns a cellʹs field value and setCellFieldValue() 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 NdDecTableCellValue(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 NdDecTableCellValue(2, 3), 0, 1.0);decTableModel.setCellFieldValue(new NdDecTableCellValue(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 25. The code for obtaining the instance is part of the decision tree example in “Example: Create a Subtree” on page 30

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 3

Custom Provider API

Responsibilities of Provider ClassesProvider 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.

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.


CHAPTER 3: Custom Provider API

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 41.

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 39). 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 50.



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)

hrows com.blazesoft.template.engine.NdTemplateException{

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 43) 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 45).

// 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 40, 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 39. 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 38. 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 4

RMA API

The 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 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 54). 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 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.


CHAPTER 4: RMA API

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. formatDateForDisplay() returns the supplied Date as a localized representation of the connection date. getRepositoryConnection() 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 two utility methods for displaying dates.

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

The formatDateForDisplay(Date date) method returns the supplied Date as a localized String. The formatDateForDisplay(Date date, Locale locale, TimeZone timeZone) method includes parameters to specify the Locale and TimeZone used to format the date.

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("../../repositories/MerchandisingExampleRepository");NdRmaRepository rmaRepository = NdRmaRepositoryFactory.connectToRepository(connection);NdRmaProject rmaProject = rmaRepository.openProject("/Business Library/MerchandisingRMA");

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()void resetDirectories()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.



The list of directories is cached by the project object, so every time these methods are invoked the same results are assured. To obtain accurate lists in the event the project directories in the repository change, call resetDirectories() 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.

For convenience, specific methods are also provided to obtain all the entries representing templates, instances, query templates and query instances in the project.

NdRmaTemplate[] getAllTemplates()NdRmaInstance[] getAllInstances()NdRmaQueryInstance[] getAllQueryInstances()NdRmaTemplate[] getAllQueryTemplates()void setEntryExclusionFilter(NdRmaEntryExclusionFilter exclusionFilter)

The getAllTemplates() method returns all the templates in the project. getAllInstances() returns all the instances in the project. getAllQueryInstances() returns all the query instances in the project. getAllQueryTemplates() returns all the query templates in the project. These methods by default return all the entries that are found when traversing the directories imported by the project. However, a special method, 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.

A method is provided 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. 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.


CHAPTER 4: RMA API

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 63.)

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. getProject() returns the project the entry belongs to.

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

NdRmaEntryVersioningInfo getVersioningInfo()NdRmaEntryVersioningOperations getVersioningOperations()boolean isOperationAllowed(int operationCode)

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, versioning operations are supported for only two kinds of entries: instances (NdRmaInstance) and projects (NdRmaProject). For projects, the getVersion(), promote(), and restore() methods of NdRmaEntryVersioningOperations are not supported. isOperationAllowed() returns true if the repository operation whose code is supplied is allowed. Refer to the API Reference entry for NdRomOperation to view the set of operation codes. The Blaze Advisor API Reference is available by selecting API Reference from the Builder Help menu.



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)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. resetEntries() 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. 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 64.

RMA FilesAs described in “RMA Entry (NdRmaEntry)” on page 56, 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 three types of files supported by the RMA API are listed below. Each interface extends NdRmaFile.

Project (NdRmaProject)

Template file (NdRmaTemplateFile)


CHAPTER 4: RMA API

Instance file (NdRmaInstanceFile)

Editable file (NdRmaEditableFile)

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

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

The getLastModifiedDate() method returns the date the file was last modified. isLogicallyDeleted() 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.

Project File (NdRmaProject)Projects (NdRmaProject) are not included in the list of entries returned by the getEntries() method of NdRmaDirectory (see “RMA Directory (NdRmaDirectory)” on page 57). 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 extends 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 63.

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

Template File (NdRmaTemplateFile)The NdRmaTemplateFile interface represents a file which contains a template. NdRmaTemplateFile only supplies one method.

NdRmaTemplate getTemplate()

The getTemplate() method returns the template that this file contains.

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

NdRmaInstance getInstance()



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

NdRmaInstanceFile extends NdRmaEditableFile which provides the editing capability for the instance. NdRmaEditableFile is discussed in the following section.

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

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

The save() method saves the file. If the file is read‐only, 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. isModified() 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.

File Content (NdRmaFileContent)The file content interfaces are NdRmaTemplate and NdRmaInstance, as well as NdRmaQueryTemplate and NdRmaQueryTemplateInstance. 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 method in addition to the getFile() method inherited from NdRmaFileContent:

NdRmaInstance generateInstance(NdRmaDirectory targetDirectory, String instanceDisplayName)

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 61.

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. (See “Versioning” on page 63.)


CHAPTER 4: RMA API

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

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/USA/Merchandising USA";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 USA";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;

}}

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()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. Call the fixLinkingErrors() method to automatically fix the linking errors if there are any. The list of linking errors 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 InstanceThe following NdRmaInstance methods are used to get the contents of an instance:

NdInstanceElementNode[] getInstanceElementNodes()NdInstanceElementNode[] getInstanceElementNodes(NdInstanceElementNode node)NdInstanceElementNode[] getInstanceElementNodesForTOC()NdInstanceElementNode[] getInstanceElementNodesForTOC(NdInstanceElementNode node)

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. See “Instance Element Node (NdInstanceElementNode)” on page 62.

Editing the Contents of an InstanceThe following NdRmaInstance methods are available for editing an instance.

setNodeValue(NdInstanceElementNode node, String displayValue)setNodeInstance(NdInstanceElementNode node, String templateDisplayName)addListValue(NdInstanceElementNode list, String displayValue)addListInstance(NdInstanceElementNode list)addListInstance(NdInstanceElementNode list, String templateDisplayName)deleteListNode(NdInstanceElementNode node)moveListNodeUp(NdInstanceElementNode node)moveListNodeDown(NdInstanceElementNode node)

The setNodeValue() method sets the value of the supplied node to the passed display value. setNodeInstance() sets the instance of the supplied node using the supplied template display name for that instance. The addListValue() method adds the supplied display value to the supplied list node. This sort of list contains only String values. In contrast, both addListInstance() methods are used to add instances of templates to the supplied list. 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.) deleteListNode() deletes the supplied node from its containing list. moveListNodeUp() moves the node up in its containing list (i.e., its index in the list is decremented by 1). moveListNodeDown() moves the node down in its containing list (i.e., its index in the list is incremented by 1).

Editing errors may occur during the execution of any of the above mentioned methods. 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.


CHAPTER 4: RMA API

boolean hasEditingErrors()NdRmaException getEditingError(NdInstanceElementNode node)void clearEditingErrors()

The hasEditingErrors() method returns true if the editing of this instance generated errors. getEditingError() 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. clearEditingErrors() clears all the editing errors that may have occurred.

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()NdRMAException getValidationError(NdInstanceElementNode node)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. getValidationError() returns the validation error that occurred on the supplied node. If no error occurred on that node, this method returns null. getOtherValidationErrors() returns the validation errors for which there is no associated node. If no such error occurred, this method returns an empty array. clearValidationErrors() 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 API Reference.

VersioningThe RMA 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.

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.


CHAPTER 4: RMA API

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 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.

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 QueryThe RMA 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 54). The method returns all the Query instances that can be found in the project.

NdRmaQueryInstance[] getAllQueryInstances(boolean includeSystemDirectories)

Query Instance (NdRmaQueryInstance)The NdRmaQueryInstance 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 executeQueryForTOC()int getQueryExecutionStatus()boolean hasQueryResults()NdRmaQueryResultItem[] getQueryResults()

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. 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. hasQueryResults() returns true if the execution of the query delivered results. getQueryResults() returns the results of the query execution as an array of NdRmaQueryResultItem.

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

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


CHAPTER 4: RMA API

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.

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

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 NdRmaProject to set the filter. You 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. Use the getEntryExclusionFilter() of NdRmaProject to obtain the current NdRmaEntryExclusionFilter.

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);rmaProject.setEntryExclusionFilter(myFilter);NdRmaQueryInstance[] queries = rmaProject.getAllQueryInstances(true);


CHAPTER 4: RMA API


C H A P T E R 5

Base Repository and Version Management APIs

The 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. 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.

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.


../../../doc/api/innovator/com/blazesoft/repository/base/NdRepositoryEntry.html

../../../doc/api/innovator/com/blazesoft/repository/base/NdRepositoryItem.html

../../../doc/api/innovator/com/blazesoft/repository/base/NdRepositoryDirectory.html

../../../doc/api/innovator/com/blazesoft/repository/base/NdRepository.html

CHAPTER 5: Base Repository and Version Management APIs

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:


../../../doc/api/innovator/com/blazesoft/repository/base/NdWorkspaceVersionManager.html

../../../doc/api/innovator/com/blazesoft/repository/base/NdWorkspaceVersionManagerListener.html

../../../doc/api/innovator/com/blazesoft/repository/base/NdWorkspaceVersionManagerEvent.html


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

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.


../../../doc/api/innovator/com/blazesoft/repository/base/NdVersioningSystemVersionManager.html

../../../doc/api/innovator/com/blazesoft/repository/base/NdRepositoryEntryFactory.html

../../../doc/api/innovator/com/blazesoft/repository/base/NdRepositoryAdmin.html

../../../doc/api/innovator/com/blazesoft/repository/base/NdRepositoryVersionSystemAdmin.html

../../../doc/api/innovator/com/blazesoft/repository/base/NdRepositoryConnection.html

CHAPTER 5: Base Repository and Version Management APIs

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.


../../../doc/api/innovator/com/blazesoft/repository/base/NdRepositoryEntryFilter.html

Index

Cconnecting to repository 7ConstantDisplayValuesProvider 45,

50content‐based API 12create

custom providers 41decision table 26decision tree 28enumeration 24Metaphor Model 25NdLocation 8NdPromItem 9NdRomDirectory 16PROM project 17question set 22ruleflow 21score model 31SRL class 23SRL function 20SRL ruleset 18

custom providerimplementation guidelines 51

custom providerscaching 51creating 41

Ddecision tables

editing 26decision tree

editing 30DisplayValuesProvider 43, 50

Eedit

decision table 26decision tree 28score model 31

Entity Object Model 12entry exclusion filter 66

Lloading a PROM project 18

MMetaphor APIs

creating a model 25loading an instance 25

NNdConstrainedListProvider 39NdContrainedListProvider 43NdDecTableModelFactory 26NdDecTreeModelFactory 26NdDecTreeNodeRenderingInfo 30NdDecTreePath 28NdDefaultConstrainedListProvider

40NdDefaultTemplateValueProvider

39NdDesignProvider 40NdDesignProviderMultiArg 47NdDesignProviderSelectableArg 46NdDesignProviderTypedArg 47NdLocation 8NdMetaphorModelException 26NdPromEntity 11NdPromInstance 12NdPromItemContent 11NdPromProject 9, 52NdPromProvider 12NdPromSrlRuleContent 13NdPromSrlRuleset 13NdPromTemplate 12NdPromTextContent 12NdProviderStaticArg 49NdProvidesDefaultValue 41NdRmaEntryExclusionFilter 66NdRmaQueryInstance 65NdRmaQueryResultItem 66NdRomConnectionManager 7NdRomConnetcionContext 8NdRomSchemaManager 9NdScoreModelModelFactory 26NdTemplateValueProvider 38

Pperformance


Index

custom providers 51Project Repository Object Model

(PROM) 9PROM item content 11PROM task

create enumeration 24create question set 22create ruleflow 21create SRL class 23create SRL function 20create 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 65Ruleflow Object Model 15

Sscore model

editing 31SRL Entity Object Model 14string‐based API 12

Ttyping attributes of repository item 8

UUserDefinedDisplayValuesProvider 47


Date post:	02-Dec-2014
Category:	Documents
Upload:	zeller2010
View:	156 times
Download:	0 times

API Dev Guide

Documents