Configurator Extensions

This chapter covers the following topics:

• Introduction to Configurator Extensions
• Configurator Extension Rules
• Configurator Extension Archives
• Events
• Argument Binding
• Legacy Functional Companions

Introduction to Configurator Extensions

Important: There is new functionality related to Configurator Extensions when using the Fusion Configurator Engine (FCE). The FCE is an alternative to the configuration engine described in this document. For all information about the FCE, see the Oracle Configurator Fusion Configurator Engine Guide.

Configurator Extensions extend your runtime Oracle Configurator with custom code through established interfaces.

The term Configurator Extension includes the following:

• A Configurator Extension class, which is the compiled Java code that implements the desired behavior, and which is contained in a Configurator Extension Archive.

• A Configurator Extension instance, which is the event-driven execution of the Java binary class at runtime.

• A Configurator Extension Rule, which is the set of arrangements you make in Oracle Configurator Developer to associate the Configurator Extension class with a Model. This includes bindings between method parameters in the Java class and elements of the Model.

The behavior of a Configurator Extension is defined by the methods of a Java class. The Java class is developed outside Configurator Developer, then inserted into the CZ schema in the form of a Configurator Extension Archive.

To enable your Configurator Extension to work with your configuration model, you must associate it with a node in your Model. You create this association in Oracle Configurator Developer as a type of rule called a Configurator Extension Rule.

Configurator Extensions work in any runtime Oracle Configurator. They are triggered either by events during a configuration session or by user-defined commands attached to controls in the user interface.

The Generic Configurator UI, cannot contain visible buttons for triggering Configurator Extensions. For more information about the Generic Configurator UI, see the Oracle Configurator Implementation Guide.

For examples of how Configurator Extensions are employed, see the Oracle Configurator Extensions and Interface Object Developer’s Guide.

Configurator Extension Rules

See Creating a Configurator Extension Rule for the detailed procedure define a Configurator Extension Rule.

A Configurator Extension Rule consists of:

• A specified Model node (called the base node).

• An instantiation scope for the Configurator Extension (with every base node instance or with the set of instances).

• A specified Java class from a Configurator Extension Archive in the Archive Path for that Model (or from the class path for the host application). See Configurator Extension Archives and The Archive Path.

• One or more event bindings, made between a predefined event and a method in the Java class. See Events.

• One or more argument bindings for each event binding, between a parameter of the Java method and an argument. See Argument Binding.

During a configuration session, the bound Configurator Extension methods run in reaction to certain configuration session events that are related to specified nodes of the Model. The Configurator Extension can modify the configuration. The relationship of a Configurator Extension to the runtime Oracle Configurator is shown in Relationship of a Configurator Extension to Runtime Oracle Configurator.

Relationship of a Configurator Extension to Runtime Oracle Configurator

At runtime, the Java class that implements your Configurator Extension runs in the same JVM as the runtime Oracle Configurator.

Configurator Extension Archives

See Creating a Configurator Extension Archive for the detailed procedure for defining a Configurator Extension Archive.

A Configurator Extension Archive is an object in the Main area of the Repository that stores one or more compiled Java classes so that they are available both during configuration model development and at runtime. The purpose of an Archive is to incorporate the Java classes that implement Configurator Extensions into the same Oracle Applications environment that is used for developing and running Oracle Configurator. This removes the need to install external class files, configure the Web server to recognize them, and restart the Web server to load them.

The Archive Path

See Configurator Extension Archive Path for the detailed procedure for defining an Archive Path for a Configurator Extension.

The Archive Path is:

• Like a Java class path for the Configurator Extension Rules defined in a Model

• A setting for a Model that lists the Configurator Extension Archives to be used for Configurator Extensions defined in that Model

• A list whose order determines the order in which the Archives are searched at runtime for the Java classes that implements Configurator Extensions

When you associate a Java class with a Model node (as described in Choosing the Java Class), Configurator Developer presents you with a list of all of the classes that are available for use in that association. This list of classes consolidates all of the classes in all of the Configurator Extension Archives that are in the Archive Path of the current Model.

An Archive can be in the Archive Path of any number of Models. A Model can have any number of Archives in its Archive Path.

Archive Path Precedence

The Archive Path determines the precedence among versions of a class. If a class occurs in more than one Configurator Extension Archive, then the list of available classes displays the class stored in the Configurator Extension Archive that is nearest to the beginning of the Archive Path. This resolution of overlapping class names allows you to manage different versions of the same class. To ensure that a certain version of a class is loaded, edit the Archive Path so that the Configurator Extension Archive containing the desired version is ahead of the Archives containing other versions of the class.

At runtime, a parent Model's Archive Path is prepended to every referenced child Model's Archive Path. This means that every Model's Archive Path can be overridden by the parent Model's Archive Path if the parent Model's Archive Path contains a different version of the same class or classes.

At runtime, the Archive Paths of all Models are blended into a single sequence of archives, which is used throughout the entire configuration session. In cases of sibling references to different child Models that contain Archives with different versions of the same class, the class that is defined in the Archive associated with the first child takes precedence, and is used for both Models, even though the second child Model has its own Archive.

In addition to the classes available to a host application through the Archive Paths of its Models, there is almost certainly a set of Java classes that is available through the class path of the host application itself. Since these classes are already in the JVM’s class path, they take precedence over the Archive Path.

Using Archives During Development

During development, define your Configurator Extension Archives to reference your Java archive files through a URL so that changes to them are reflected without having to upload them. Later, when your Java classes and your Model are ready to deploy, define your Archive to upload your Java archive files into the database, so that they can be published with the Model.

If you change the signature of a Java method used in a Configurator Extension Rule, then you must create a new binding that reflects those changes. If you have already uploaded the Java class containing the changed method, then you must upload it again.

Your Archives can include the Java source code for your custom classes, as well as the compiled classes themselves. However, while you can upload new classes to Archives, you cannot download Archives to your own computer. Consequently, you must ensure the preservation of your source code, since you cannot use the Repository for source control.

Using Archives During Deployment

When a configuration model is published, any Configurator Extension Archives that are in its Archive Path are included in the publication, so that the correct version of the uploaded Java class for every Configurator Extension is kept with the Model, and is loaded at runtime when the publication is used to initialize Oracle Configurator. This allows different versions of the same Java class to be running simultaneously in the same JVM. This design also allows you to modify the behavior of a Configurator Extension without restarting the Web server. The ability to change classes without restarting the Web server is sometimes called hot swapping.

Events

An event is something that occurs during a runtime configuration session, such a change in the value of a node. Events have names, such as postValueChange.

The runtime Oracle Configurator uses the Oracle Configuration Interface Object (CIO) to detect and react to events, using objects called listeners, which are registered to listen for the occurrence of specified events. You do not have to explicitly specify listeners when you use Configurator Extensions. When you create an event binding for a Configurator Extension Rule, Oracle Configurator Developer registers the appropriate listener for the specified event.

Event Binding

If an event occurs during a runtime configuration session, and there are bindings for that event with that scope in any Configurator Extension Rules in the Model, then the runtime Oracle Configurator runs all the bound methods for that event.

The events that you can bind to a Configurator Extension are predefined in the CZ schema. Predefined Events for Binding describes these events. When you define a Configurator Extension Rule, you choose one of these events as part of the binding of your Java class to your Model.

You can define custom events called command events. Listeners registered for command events listen for a specified command (defined as a string). You specify the string in a Configurator Extension Rule as part of an event binding for the event onCommand. You can use this functionality to extend the set of events beyond those that are predefined in the CZ schema.

Note: Oracle Configurator does not support any user-defined events other than the custom command event.

Event Binding Scopes

In Configurator Developer, you bind events within a certain scope. This event binding scope tells listeners that are registered for the event where in the runtime Model tree to listen for an occurrence of that event. Event Binding Scopes and Event Binding Scopes describe the scopes for event binding.

Event Binding Scopes

Event Binding Scope	Listens for Events ...
Global	Anywhere in the runtime tree of the current configuration instance.
Base Node	Only on the node bound to the Configurator Extension Rule.
Base Node Subtree	On the node bound to the Configurator Extension Rule and all its descendants.

Event Binding Scopes

At runtime, in a configuration session, an event occurs within an event execution scope, which is either Global or Node.

• Events that occur in the Global scope are propagated to all listeners whose event scope is Global. These events are the ones in Predefined Events for Binding that are related to the configuration object, such as postConfigInit.

• Events that occur in the Node scope are propagated in the following sequence, which ascends the tree structure of the configuration model:

  1. By listeners that are registered on the node of execution scope and that have an event binding scope of Base Node or Base Node Subtree

  2. By listeners that are registered on ancestors of the node of the execution scope and that have an event binding scope of Base Node Subtree (which means that the node of execution scope is part of their Base Node Subtree binding)

  3. By global listeners, which are registered on all nodes.

Predefined Events for Binding

The table Predefined Events for Binding describes the predefined events that you can bind to a Configurator Extension. Some events have event-specific parameters that you use as arguments when binding the method parameters of a Java class in a Configurator Extension Rule. These parameters are included in the table Predefined Events for Binding.

See Creating Event Bindings for the detailed procedure for defining the event bindings for a Configurator Extension Rule.

Predefined Events for Binding

Event Name	Related To	Description	Event Parameter Name and Type	Event Binding Scope
postCXInit	Configurator Extension	Event dispatched after initialization of the Configurator Extension. This can occur on initialization of a configuration session, or runtime addition of a component.	None	Base Node only
preCXTerminate	Configurator Extension	Event dispatched immediately before termination of the Configurator Extension. This can occur on termination of a configuration session, or runtime deletion of a component.	None	Base Node only
postInstanceAdd	Component Instance	Event dispatched immediately after adding a component instance.	compSet (ComponentSet) instance (Component)	All scopes
postInstanceDelete	Component Instance	Event dispatched immediately after deleting a component instance.	compSet (ComponentSet) instance (Component)	All scopes
postInstanceEditable	Component Instance	Event dispatched immediately after making a component instance editable.	instance (Component)	All scopes
postInstanceNonEditable	Component Instance	Event dispatched immediately after making a component instance non-editable.	instance (Component)	All scopes
postInstanceNameChange	Component Instance	Event dispatched immediately after a component’s instance name is changed.	instance (Component)	All scopes
onInstanceLoad	Runtime Node	Event dispatched when a component instance or other associated node is created, or brought into the configuration.	newNode (IRuntimeNode)	All scopes
postInstanceLoad	Runtime Node	Event dispatched immediately after a component instance or other associated node is created, or brought into the configuration.	newNode (IRuntimeNode)	All scopes
onValidateEligibleTarget	Connection	Event dispatched during the validation of eligible Connector target instances. A method bound to this event should return a Boolean value. Oracle Configurator uses this value to decide whether the Event Parameter target is eligible. If the bound method does not return any Boolean value, then it assumes that target is eligible.	connector (Connector) target (Component)	Base Node only
postConnect	Connection	Event dispatched immediately after a Connector is connected to a target component instance.	connector (Connector) target (Component)	All scopes
postDisconnect	Connection	Event dispatched immediately after a Connector is disconnected from a target component instance.	connector (Connector) target (Component)	All scopes
onCommand	Custom Command	Event dispatched when Oracle Configurator runs a custom-defined command. This event must be used when generating custom output.	HttpServletResponse (HttpServletResponse)	All scopes
postConfigInit	Session	Event dispatched immediately after initializing a new or restored configuration session.	None	Global only
postConfigNew	Session	Event dispatched immediately after a new configuration session has been initialized.	None	Global only
postConfigRestore	Session	Event dispatched immediately after a restored configuration session has been initialized.	None	Global only
preConfigTerminate	Session	Event dispatched immediately before terminating a configuration session. In the UI, this occurs after the end user clicks either the "Done" or "Cancel" button and then clicks an "OK" button to dismiss any notifications or warnings that might be displayed by Oracle Configurator.	None	Global only
preConfigDone	Session	Event dispatched immediately before completing a configuration session. In the UI, this occurs after the end user clicks the "done" button and then clicks an "OK" button to dismiss any notifications or warnings that might be displayed by Oracle Configurator.	None	Global only
preConfigSave	Session	Event dispatched immediately before saving a configuration.	None	Global only
postConfigSave	Session	Event dispatched immediately after saving a configuration.	None	Global only
preConfigCancel	Session	Event dispatched immediately before canceling a configuration session. In the UI, this occurs after the end user clicks the "cancel" button and then clicks an "OK" button to dismiss any notifications or warnings that might be displayed by Oracle Configurator.	None	Global only
preConfigSummary	Session	Event dispatched immediately before displaying the Summary of a configuration session.	None	Global only
onConfigLineType	Session	Event dispatched during the calculation of a line type, which occurs when saving a configuration or displaying its summary.	None	Global only
onConfigValidate	Values	Event dispatched during the validation performed after every CIO transaction.	None	Global only
postValueChange	Values	Event dispatched immediately after the value of a node is changed.	changedNode (IRuntimeNode)	All scopes

Note: You cannot specify an argument whose type is ComponentSet by selecting a node in your Model. You must specify the argument by selecting the event parameter compSet. See Predefined Events for Binding.

Argument Binding

To complete an event binding in a Configurator Extension Rule, you must bind each parameter of the Java method that implements the desired behavior to an argument. The argument specifies some object or value that is available during the configuration session.

Parameter Types for Argument Specification describes the types of arguments that you can bind to method parameters.

Parameter Types for Argument Specification

Parameter Type	Meaning
System Parameter	An object obtained from Configurator Developer or the runtime Oracle Configurator, containing information about the runtime environment of the Configurator Extension. System Parameters for Argument Specification describes these objects.
Event Parameter	A parameter of the event that is bound to the method. Event parameters are specific to particular events. Some events have no parameters, if the nature of the event does not require them. Predefined Events for Binding describes event parameters for the events that are predefined in the CZ schema.
Model Node or Property	A node of the Model to which the Configurator Extension is bound, or a Property of one of the nodes.
Literal	An unquoted character string. The string is automatically converted to an integer or decimal if the method parameter requires that type.

System Parameters for Argument Specification describes the parameters that you can choose when you select to bind a System Parameter to an argument.

System Parameters for Argument Specification

Parameter	Meaning
BaseNodeOfRule	The Model node that is bound to the Configurator Extension Rule.
CXEvent	An instance of the CXEvent class in the CIO, which contains accessor methods for obtaining information about the event that triggered the Configurator Extension Rule.
CXRule	An instance of the CXRule class in the CIO, which contains accessor methods for obtaining details about the Configurator Extension Rule itself.
Configuration	The configuration object created by the CIO during the runtime session in which the Configurator Extension runs. This is an instance of the Configuration class in the CIO, which contains accessor methods for obtaining details about the configuration.
Rule Description	The text of the Description of the current Configurator Extension Rule. You create this Description when you create the Rule. You can also obtain this data through the CXRule parameter.
Rule ID	The internal Rule ID of the current Configurator Extension Rule. This ID is generated automatically by Oracle Configurator Developer when you create a Rule. You do not need to know its value when using this System Parameter. You can also obtain this data through the CXRule parameter.
Rule Name	The Name text of the current Configurator Extension Rule. You create this Name when you create the Rule. You can also obtain this data through the CXRule parameter.

See Binding Arguments to Parameters for the detailed procedure for defining the argument bindings for a Configurator Extension Rule.

Legacy Functional Companions

By default, you cannot create or maintain Functional Companions in Configurator Developer, as they have been replaced by Configurator Extensions. However, if you still need to create or maintain Functional Companions, your system administrator can provide this functionality by changing the value of a profile option. Oracle strongly recommends that you migrate all Functional Companions to Configurator Extensions.

For more information, see the current release or patch information for Oracle Configurator on MetaLink, Oracle's technical support Web site.