This chapter collects instructions on how to use Configurator Extensions for specific tasks, such as generating custom output and filtering for connectivity
This chapter covers the following topics:
Every Configurator Extension must be bound to some configuration event. Therefore, you should review the available events to help determine the situations in which you can employ a Configurator Extension.
While there are no formal types for Configurator Extensions themselves, it is possible to categorize the configuration events to which you can bind Configurator Extensions. The table Types of Configuration Events lists the available types of configuration events and an example event for each type. For a list of events that you can use for processing configurations, see Events for Processing Configurations. For more details, and a full list of the available events, see the chapter on Configurator Extensions in the Oracle Configurator Developer User’s Guide.
| Event Type | Possible Use | Example Event |
|---|---|---|
| Configurator Extension | Triggering actions that are required when the base node for a Configurator Extension Rule is instantiated. | postCXInit |
| Connection | Filtering valid targets for a Connector. | onValidateEligibleTarget |
| Custom Command | Processing custom command strings that you define. Required when generating custom output. | onCommand |
| Session | Triggering actions that are required at some specified point in a configuration session. | postConfigInit |
| Value-Related | Validating selections or values. | onConfigValidate |
You can generate custom output that is displayed when the end user clicks a button in the UI of the runtime Oracle Configurator.
The Configurator Extension for this task must be bound to the onCommand event with a custom command string that you define. This custom command is handled by the UI layer for the runtime Oracle Configurator. The other requirement is that your Java method must take an argument of type HttpServletResponse.
For the detailed procedure for creating a Configurator Extension Rule, see Building Configurator Extensions and the related sections of the Oracle Configurator Developer User’s Guide. A summary of the required tasks is provided here, with additional explanation where necessary.
The Java method for your Configurator Extension class must take an argument of the type javax.servlet.http.HttpServletResponse. You must use this data type because it is the location where your Configurator Extension generates custom output.
An example of a very simple custom output class is shown in Generating Custom Output (HelloWorldCX.java). The example prints a simple message in an HTML page.
Compile the Java class for your Configurator Extension and place it in a Java class archive file.
Create a Configurator Extension Archive for the class, and add it to the Archive Path for your Model.
Define a Configurator Extension Rule with the options listed in the following table:
| Option | Choose ... |
|---|---|
| Model Node | The node of your Model on which you want the button for the command event to be placed by Oracle Configurator. This node is independent of the node to which you might bind an argument whose Argument Specification is Model Node or Property. |
| Java Class | HelloWorldCX, selected from your Configurator Extension Archive. |
| Java Class Instantiation | With Model Node Instance |
Create an event binding for the Configurator Extension Rule with the options listed in the following table:
Create an argument binding for the event binding with the options listed in the following table:
| Option | Choose ... |
|---|---|
| Argument Type | javax.servlet.http.HttpServletResponse |
| Argument Specification | Event Parameter |
| Binding | HttpServletResponse |
Generate logic for your Model, to reflect the addition of the Configurator Extension Rule.
Create or refresh a User Interface for your Model. This creates a button in the User Interface that by default is captioned with the Command Name that you specified in the binding for the onCommand event. The button is placed on the page for the Model Node that you associated with the Configurator Extension (the base node).
To change the default caption of the button, edit the Text Expression field in the Caption Source for the button.
The Button Action for the button is automatically set by Oracle Configurator Developer to use an Action Type of Raise Command Event in which the Command is the Command Name string in your event binding. The fact that these command strings are the same is what causes the button to invoke the Java class for your Configurator Extension. If you change the Command Name string in your event binding, you must also change it for the Raise Command Event.
Test the Configurator Extension from Configurator Developer by choosing the Test Model button, then choosing the Model Debugger, or the User Interface that you generated. When you click the button that triggers the Configurator Extension, it produces a secondary window and writes the specified message in it.
You can modify the characteristics of the secondary window in Configurator Developer. The Action Parameters for the Button element include an Output Window Options field, into which you can enter HTML attributes for the window. See the Oracle Configurator Developer User’s Guide for information on editing User Interface elements.
For another example of generating output, see Generating Output with a Configurator Extension (ShowStructureCX.java) in Generating Output Related to Model Structure.
Keep the following in mind when working with custom output:
If you bind multiple Configurator Extensions to the same command event, they share the same Button element in the User Interface. When you click that button in the runtime Oracle Configurator, it triggers all those bound Configurator Extensions.
If you use the limited edition of Oracle Configurator Developer to create a DHTML UI for a Model that already contains multiple Configurator Extension command bindings, then it generates a Button for each command binding. However, when you click a button in the runtime Oracle Configurator, only the first Configurator Extension runs.
Generating Custom Output (HelloWorldCX.java)
import java.io.IOException;
import javax.servlet.http.HttpServletResponse;
// This CX does not use the CIO, so no need to import CIO classes
public class HelloWorldCX {
public HelloWorldCX() {
}
public void helloWorld(HttpServletResponse resp) {
StringBuffer sb = new StringBuffer(511);
sb.append("<html>");
sb.append("<head>");
sb.append("<title>Simple CX Test</title>");
sb.append("</head>");
sb.append("<body bgcolor='#FFFFFF' text='#000000'>");
sb.append("HELLO WORLD. This is output from a Configurator Extension.");
sb.append("</body>");
sb.append("</html>");
resp.setContentType("text/html");
resp.setHeader ("Expires", "-1"); // required for MSIE
try {
resp.getWriter().println(sb.toString());
}
catch (IOException ioe) {
throw new RuntimeException();
}
}
}
You can define a Connection Filter Configurator Extension that filters the instances of a target Model that are displayed when an end user of the runtime Oracle Configurator clicks a Choose Connection button.
To define a Connection Filter Configurator Extension:
Define a Java class for your Configurator Extension.
See Developing Java Classes and Archives for the basic procedure. See Example of a Connection Filter Configurator Extension for example code.
Define a method that determines the criteria for filtering a list of valid targets for a Connector.
Filtering for Connectivity (TargetFilter.java) defines such a test in the body of validateEligibleTarget().
In Oracle Configurator Developer, define a Configurator Extension Rule, and create a binding for the onValidateEligibleTarget event.
Bind the Event Parameter named target as the argument to the parameter of your validateEligibleTarget() method named target.
Bind the Event Parameter named connector to the Connector node whose target instances you want to filter.
See the Oracle Configurator Developer User’s Guide for information about connectivity and creating Connectors.
In the runtime Oracle Configurator, when the end user clicks a Choose Connection button, Oracle Configurator gets the list of all target instances of the Connector, then invokes any Configurator Extension bindings that are listening for the onValidateEligibleTarget event on this Connector. If any of these bindings return false, then that instance is removed from the list of potential targets, and is not displayed in the Connection Chooser.
If there are no target instances that satisfy the filter, then Oracle Configurator displays a notification of that fact to the end user.
The same Connection Filter Configurator Extension can be associated with more than one Connector. The same filtering test is performed, but because the potential targets of the Connectors may be different, the resulting set of eligible instances may also be different.
Different Connection Filter Configurator Extensions can be associated with the same Connector, for example:
Model_A includes Connector_A
In Model_A, Configurator Extension CX_1 is associated with Connector_A
Model_A is referenced in Model_B (and so Connector_A is accessible through the reference)
In Model_B, Configurator Extension CX_2 is associated with Connector_A
In the runtime Oracle Configurator, when the end user clicks the Choose Connection button for Connector_A, Oracle Configurator displays a Connection Chooser containing all of the target instances that satisfy both CX_1 and CX_2.
For an example of a Connection Filter Configurator Extension, see Filtering for Connectivity (TargetFilter.java). This Configurator Extension searches the target Model for a Resource named Resource1, and returns False if the value of that Resource is less than 10; otherwise it returns True.
In the runtime Oracle Configurator, this Configurator Extension filters out any potential target instances in which the value of the Resource named Resource1 is less than 10. (If the potential target instance does not even contain a Resource named Resource1, then a NoSuchChildException is raised.)
Filtering for Connectivity (TargetFilter.java)
import oracle.apps.cz.cio.Resource;
import oracle.apps.cz.cio.Component;
import oracle.apps.cz.cio.NoSuchChildException;
public class TargetFilter {
public boolean validateEligibleTarget(Component target){
Resource resource = null;
try {
resource = (Resource)target.getChildByName("Resource1");
} catch (NoSuchChildException nsce) {
nsce.printStackTrace();
return true;
}
if (resource.getValue() < 10) {
return false;
} else {
return true;
}
}
}
Although you can make input for a Text Feature required when you define it in Oracle Configurator Developer (as described in the Oracle Configurator Developer User's Guide), you cannot use a configuration rule to make the input be required based on some dynamic runtime condition, such as the state of some other model node.
To make input for a Text Feature dynamically required, use TextFeature.setRequired(boolean required).
Example
In a Configurator Extension, implement a custom method that takes two arguments:
the Text Feature that you want to make dynamically required
a node (such as a Boolean Feature or Option) that logically controls whether the Text Feature is required
You can define more complex logic than is shown in this basic example to make the Text Feature required.
In your custom method, if the controlling node (or other logic) is True, call setRequired(True) on the Text Feature; otherwise call setRequired(False). Examples of controlling nodes might be:
a Boolean Feature named Required?
an Option named Yes of an Option Feature named Required? that has Options Yes and No
In a Configuration Rule, create an event binding that associates your method with the controlling node and the postValueChange event. Duplicate this event binding, but for the postConfigRestore event.
At runtime, when the end user selects a true value for the controlling node (for example, the Option Yes for the Option Feature Required?), then your Configurator Extension forces the user to enter a non-null value for the Text Feature in order for the configuration to be satisfied.
When using the CIO in the Telecommunications Service Ordering (TSO) flow, do not call TextFeature.setRequired() on passive instances. Doing so will produce a runtime error when the current transaction is committed or rolled back. From the standpoint of the CIO, a passive instance is one that returns False when tested with RuntimeNode.isEditable(). For background on passive instances, see the Oracle Telecommunications Service Ordering Process Guide. You should only call TextFeature.setRequired() in a Configurator Extension that is bound to the event postInstanceEditable.