Client Operations Processor API

This chapter discusses the PeopleSoft Configurator Client Operations Processor (COP) Java API and its application classes.

Click to jump to parent topicUnderstanding the COP Java API

The COP Client Operations Processor provides, through its Java API, the public interface to the Configurator. Your User Interface (UI), or other application, calls the COP Java API to communicate with the Configurator Engine and its associated modules.

In many cases, developers designing a UI to use with the PeopleSoft Configurator will not have to make COP Java API calls (or write any code) themselves. Instead, they can use the Configurator Control Templates, which allow them to use standard Configurator controls to present their interface. The Control Templates are used within JavaServer Pages. The Control Templates themselves make COP Java API calls to implement the behavior of the standard controls.

However, in some cases, you may want to have controls whose behavior or appearance is different from any of the existing Configurator controls. In these cases you will have to modify the code in the JavaServer Pages (JSP), or write your own from scratch. Alternatively, you may need to create a UI that uses something other than JSP or standard Web technologies in general.

In that case, these chapters are the reference you need. They describe how to understand, modify, and write Java code that communicates with the Configurator by making COP API calls.

You can use the COP API to:

Click to jump to top of pageClick to jump to parent topicChoices

Choices are inputs to the model that specify values. Usually they are user inputs (set through a UI), but they can also be programatically generated. The Configurator has two kinds of choices: extern variables and domain members.

Extern variables (also called simply “externs”) are named variables whose values are of types int, double, string, boolean, and date. The UI may restrict what a user can enter so that, for example, the extern variable only contains a single floating-point number. Extern variables are frequently used in expressions.

Domain members are individual, discrete choices. They are arranged into groups, each group associated with a decision point (or selection point). A domain member usually has a number of attribute values—such as its description, size, or color—that the Advanced Configurator can access and use in various ways.

Click to jump to top of pageClick to jump to parent topicDecision Points and Domain Members

Two modeling concepts—decision points and domain members—are very important in understanding how to use the COP Java API. This section describes these concepts and how they relate to the UI.

The UI is a visual representation of your model (or, at least, a portion of the model). The model contains decision points and domain members, some of which will be displayed in the UI.

The figure shows a sample UI for a “Sandwich Model," in which the user can order a sandwich by choosing the filling, bread, condiments, extras, and temperature.

A decision point is a collection of associated options that the user (or, through software, the application) can choose from. The options in a decision point are usually alternatives, although they need not be mutually exclusive. The individual options themselves are called domain members of that decision point. For example, in the Sandwich Model, the area labeled “Filling” represents a decision point—the user can select a sandwich meat from this collection. Each of the possible choices—Roast Beef, Turkey, Chicken, Tuna—represents a domain member of this decision point.

The COP Java API does not directly define or use decision point objects or domain member objects. Instead it encapsulates them in objects of type ControlData (for decision points) and ControlItem (for domain members). Frequently, in discussing the COP Java API, these distinctions will be blurred when there’s no chance of ambiguity.

A decision point has certain properties—such as a name or a “multiselect" property—that can be obtained (through Java COP API calls) from the corresponding ControlData object. Likewise, a domain member has properties that can be obtained from the corresponding ControlItem object. But ControlData and ControlItem objects can also contain additional information, often representing current or developer-determined conditions. (For example, the ControlItem objects belonging to a ControlData object may have a sort-ordering established by the software when it created the ControlData object. This ordering is not a part of the corresponding decision point and its domain members.)

See Also

ControlData

ControlItem

Click to jump to parent topicApplication Classes

This section lists the COP Java API classes and the primary uses of each.

Click to jump to top of pageClick to jump to parent topicClientOperations

ClientOperations is the principal class you will be using. Its methods include:

getControlData is arguably the most important method in the ClientOperations class. It creates a ControlData object representing a decision point, which in turn contains an array of ControlItem objects representing the decision point’s domain members. The UI obtains most of the information it needs from these objects.

Click to jump to top of pageClick to jump to parent topicConfiguration

The Configuration class represents a configuration of choices (which may be user, computer, default choices, and extern variables), together with the configuration attributes and the model’s name, version, and compileID. The ClientOperations class has methods to create a Configuration object that represents the current configuration, and to restore a configuration represented by a Configuration object.

The Configuration class includes methods for:

Click to jump to top of pageClick to jump to parent topicControlData

The ControlData class represents a decision point, and contains display information for the decision point and its domain members (ControlItem objects). ControlData objects are created by the ClientOperations method getControlData. The ControlData class includes methods for:

Click to jump to top of pageClick to jump to parent topicControlItem

The ControlItem class represents a domain member, and contains display information on the domain member and its attributes. ControlItem objects are obtained from a ControlData object that represents the domain member’s decision point. The ControlItem class includes methods for:

Click to jump to top of pageClick to jump to parent topicChoice

Choice is the superclass for DMChoice (for domain member choices) and EVChoice (for extern variable choices). You pass a vector of Choice objects (possibly including both DMChoice objects and EVChoice objects), one for each user choice, to the Configurator in the ClientOperations method processChoices, which then processes the choices to create a solution state.

In previous versions of the Configurator, objects of type Choice were used to represent domain member choices. For compatibility, the current Choice class still retains a number of methods that only make sense for domain member choices, but these methods are deprecated, and identical methods have been included in the DMChoice class. Use the methods in the DMChoice class instead of the deprecated methods in the Choice class.

The Choice class also contains non-deprecated methods for a few actions that are meaningful for both DMChoice and EVChoice, including:

Click to jump to top of pageClick to jump to parent topicDMChoice

DMChoice is a subclass of Choice.

The DMChoice class is used to represent domain member choices (selections and eliminations). You create a DMChoice object by calling the ClientOperations method makeSelectedChoice (when the user wishes to include a domain member) or makeEliminatedChoice (when the user wishes to exclude a domain member).

The DMChoice objects generated by makeSelectedChoice and makedEliminatedChoice represent user choices. However, by using the DMChoice method setState, you can change them to represent computer or default choices (or various combinations).

Click to jump to top of pageClick to jump to parent topicEVChoice

EVChoice is a subclass of Choice.

The EVChoice class is used to represent extern variable choices. You create an EVChoice object by calling the ClientOperations method makeExternVarChoice.

Click to jump to top of pageClick to jump to parent topicItemFilter

The ItemFilter class specifies a filter for a decision point’s domain members. You can use it to filter out all eliminated domain members, or all eliminated domain members whose elimination values fall outside some given range.

The ClientOperations method getControlData has an ItemFilter parameter, which you can use to filter out domain members that, in some models, the UI designer does not wish the user to see (such as all eliminated items). The filter parameter is optional. If you supply null instead, no filtering will be done. The exception is discarded domain members, which are always filtered out.

See Handling Deleted Domain Members.

Click to jump to top of pageClick to jump to parent topicItemIterator

The ItemIterator class is used to iterate through the domain members of a decision point—more specifically, through the ControlItem array of a ControlData object. An iterator (object of type ItemIterator) returns the ControlItem objects both sorted and filtered, as specified by your software. (The ControlItem array itself is neither sorted nor filtered by the COP.)

The sorting done by an iterator can either be a standard sort order implemented by the COP or a custom sort order determined by a comparator you provide. You can also have more than one iterator for a single ControlData object.

See Also

Sorting and Filtering

Click to jump to top of pageClick to jump to parent topicExternVar

The ExternVar class represents an extern variable, and gives access to its name, type, and value.

Click to jump to top of pageClick to jump to parent topicNumericData

The NumericData class is used to get the type and value of numeric variables. Some models contain variables that you may wish to display in the UI, such as “total grams of saturated fat" or “number of video card slots remaining." These values are generated by the Configurator Engine, based on formulas specified in the model. From the point of view of the COP, they are read-only.

Numeric data are distinct from: configuration attributes; extern variables; and domain member attributes, prices, and quantities.

Click to jump to top of pageClick to jump to parent topicViolation

The Violation class is used to report on violations associated with the configuration, decision points, and domain members. It returns a user-readable explanation for the violation.