This chapter provides essential information about implementing Configurator Extensions, explains what Configurator Extensions are, and describes the different types available. It also explains the relationship of Configurator Extensions and the CIO.
This chapter covers the following topics:
Configurator Extensions extend the behavior of the runtime Oracle Configurator. A Configurator Extension is a custom-coded Java class that uses an established interface to access a configuration at runtime. The interface is called the Oracle Configuration Interface Object (CIO); it is described in the chapters of Part 2.
This chapter contains an overview of how Configurator Extensions work and how to implement them. It also provides important facts about Configurator Extensions and prerequisites for developing them.
Note: Be sure to check Prerequisite Skills for Developing Configurator Extensions, which describes the Java development skills required for success with Configurator Extensions.
Note: Review the Oracle Configurator Performance Guide for information on the performance impacts of Configurator Extensions.
Configurator Extensions extend your runtime Oracle Configurator by attaching custom code through established interfaces.
The term Configurator Extension includes the following:
A Configurator Extension class is the Java class containing the methods that implement desired behavior
A Configurator Extension instance is the event-driven execution (the Java object) of the Java class at runtime
A Configurator Extension Rule is the set of arrangements that you make in Oracle Configurator Developer to associate the CX class to a Model
For additional information, see the chapter on Configurator Extensions in the Oracle Configurator Developer User’s Guide, which explains the following essential topics related to incorporating Configurator Extensions into your configuration model:
Configurator Extension Rules
Configurator Extension Archives and the Archive Path
Events and Event Binding
Arguments and Argument Binding
To effectively develop a Configurator Extension, an appropriate level of Java development proficiency is required. The specific level of Java proficiency required depends on the specific functionality required by the desired Configurator Extension.
In general, the Configurator Extension developer should have the following knowledge:
A basic understanding of these structures:
Oracle Applications Bills of Material (BOMs), which consist of Models, Option Classes, and Standard Items
Oracle Configurator Models, which consist of Components, Features, and Options
The relationship of these BOM and Model structures to the CIO
Java programming experience that should include solid familiarity with:
The Collections class and its subclasses
Concurrency issues
CIO transaction handling (see Using Logic Transactions)
Exception handling
Using Java Interfaces
HTML and the Java class HttpServletResponse (for writing Configurator Extensions that generate custom output)
A working understanding of Oracle databases, including the principles of JDBC.
A familiarity with the Oracle Configurator documentation, including the CIO reference documentation (see Reference Documentation for the CIO.
The skills listed above are fundamental. Other specific expertise may be required for developing Configurator Extensions to the specific requirements for your project.
Keep these facts in mind when working with Configurator Extensions and the CIO.
Configurator Extension Rules have many of the same attributes as other Rules, and the procedure for defining them is similar. For example, Configurator Extensions have effectivity, can be disabled, and can participate in rule sequences. For more details about defining configuration rules, see the Oracle Configurator Developer User’s Guide.
When the runtime Oracle Configurator starts up, it creates an instance of the CIO. During the resulting configuration session, the CIO creates a Configuration object. Then Oracle Configurator creates runtime instances of all mandatory model structure, and, for each instance of each instantiated base node associated with a Configurator Extension, an instance of the class that you defined for your Configurator Extension. Oracle Configurator then attaches the Configurator Extension instance to the associated node.
You can associate more than one Configurator Extension with a particular node; the CIO will create instances of all of the Configurator Extensions at runtime.
In order to communicate with your application’s Model, a Configurator Extension uses Oracle’s CIO API. The CIO can also be used to develop a custom user interface that allows the runtime Oracle Configurator to access the Model. See Configurator Extensions and the CIO, and all of Part 2.
Note: As a point of information, the user interfaces generated with Oracle Configurator Developer for the runtime Oracle Configurator communicate in this way with the configuration model.
You must observe certain requirements and restrictions when working with Configurator Extensions and the CIO.
Keep these requirements in mind when working with Configurator Extensions and the CIO.
To build a Configurator Extension, you implement an object class in Java. Oracle requires that Configurator Extensions be implemented only in Java. Configurator Extensions can run on any Oracle platform that supports Java.
Web server sizing and tuning are necessary steps in the development of a Configurator project and must not be overlooked. The addition of your own custom code, such as Configurator Extensions, may affect the memory usage of your application. For advice on planning configuration models that use memory efficiently, see the Oracle Configurator Modeling Guide. For strategies to cope with possible "out of memory" runtime errors, consult Note #239913.1 on the Oracle Support Web site.
The runtime Oracle Configurator automatically sets up a JDBC database connection for use by the CIO. Custom applications that take the place of the runtime Oracle Configurator must perform this task. See Initializing the CIO and Managing JDBC Connections for details.
If your host application uses a custom user interface in an MLS deployment, you may need to create ICX session tickets in order to correctly set the current language.
If you have written Configurator Extensions that use custom messages, then those messages must be stored into and retrieved from the FND_NEW_MESSAGES table. You are responsible for translating these messages. See the information on MLS in the Oracle Configurator Implementation Guide.
Keep these restrictions in mind when working with Configurator Extensions and the CIO.
Configurator Extensions cannot be used to customize Oracle Configurator Developer.
CIO interfaces are not thread-safe. See Observing Thread Safety for more details.
If any Configurator Extensions cannot be loaded when you create a new configuration (for instance, due to internal errors or an incorrect class path or Archive Path), the configuration will fail to open.
Your Configurator Extension is a client of the CIO. When you program against the CIO, the CIO creates instances of a set of public interface objects that you work with. These interfaces are defined in the package oracle.apps.cz.cio. Your code should refer only to these public interface objects. See The CIO’s Runtime Node Interfaces.
Configurator Extensions are invoked by the CIO through the runtime Oracle Configurator, and Configurator Extensions call the CIO to get information from the runtime configuration model. The CIO is like a broker for the runtime configuration model, in that it passes information both into and out of the model. Programmers writing Configurator Extensions need to know how to use the CIO.
This section describes the elements that need to be installed to develop, compile, and test Configurator Extensions. For details, see the Oracle Configurator Installation Guide and current release or patch information for Oracle Configurator on the Oracle Support Web site.
In order to develop Java Configurator Extensions, you must install a Java development environment that enables you to compile Java classes, such as:
If a Configurator Extension requires database access, you need JDBC drivers to compile a Configurator Extension. The required driver classes are contained in the Oracle Applications environment.
Note: If you use a class from the collections library, such as List, then for compatibility with the CIO’s package structure you must import the class using this syntax:
import com.sun.java.util.collections.List;
In order to compile Configurator Extensions:
Your class path should be the same as the class path for Oracle Application Server.
You should compile using the latest certified patch release of the Java Development Kit (JDK) for your platform. For the JDK release number, see the current release or patch information for Oracle Configurator on the Oracle Support Web site.
The shared object files described in the table Required Software for Configurator Extensions must be installed and recognized by your operating system environment in the appropriate locations. This table lists file names and platforms.
See the Oracle Configurator Installation Guide and the Oracle Configurator Implementation Guide for complete details on installation and environment. For background on JDBC drivers, consult the Oracle database documentation resources for the current JDBC developer's guide and reference.
If you have installed and set up Oracle Configurator Developer so that the Test Model button runs the Model Debugger successfully, then this setup should also be correct for testing Configurator Extensions.
The classes that implement your Configurator Extensions should be contained in Configurator Extension Archives, as described in the Oracle Configurator Developer User’s Guide.
It is also possible to install your classes in the class path for Oracle Application Server, which takes precedence over the Configurator Extension Archive Path. However, if you do so you will not obtain important advantages provided by using Archives. See the Oracle Configurator Developer User’s Guide for details.
If you are running a custom application in standalone mode, then you may need to ensure that the Java system property JTFDBCFILE is set. For more information, see the note after Creating A Configuration Object.
In examples, an implied carriage return occurs at the end of each line, unless otherwise noted. You must press the Return key at the end of a line of input.
The table below lists other conventions that are also used in this guide.
| Convention | Meaning |
|---|---|
| . . . | Vertical ellipsis points in an example mean that information not directly related to the example has been omitted. |
| . . . | Horizontal ellipsis points in statements or commands mean that parts of the statement or command not directly related to the example have been omitted |
| boldface text | Boldface type in text indicates a new term, a term defined in the glossary, specific keys, and labels of user interface objects. Boldface type also indicates a menu, command, or option, especially within procedures |
| italics | Italic type in text, tables, or code examples indicates user-supplied text. Replace these placeholders with a specific value or string. |
| [ ] | Brackets enclose optional clauses from which you can choose one or none. |
| > | The left bracket alone represents the MS DOS prompt. |
| $ | The dollar sign represents the DIGITAL Command Language prompt in Windows and the Bourne shell prompt in Digital UNIX. |
| % | The per cent sign alone represents the UNIX prompt. |
| name() | In text other than code examples, the names of programming language methods and functions are shown with trailing parentheses. The parentheses are always shown as empty. For the actual argument or parameter list, see the reference documentation. This convention is not used in code examples. |
| & | Indicates a character string (identifier) that can display text dynamically in Configurator Developer or a runtime Oracle Configurator. For example, "&PROPERTY" can be used to dynamically construct and display a Property of a Model structure node. |
The mission of the Oracle Support Services organization is to help you resolve any issues or questions that you have regarding Oracle Configurator Developer and Oracle Configurator.
To report issues that are not mission-critical, submit a Technical Assistance Request (TAR) using the Oracle Support Web site.
You can also find product-specific documentation and other useful information on the Oracle Support Web site.
Oracle Configurator Developer and Oracle Configurator use the standard Oracle Applications methods of logging to analyze and debug both development and runtime issues. These methods include setting various profile options and Java system properties to enable logging and specify the desired level of detail you want to record.
For more information about logging, see:
The Oracle E-Business Suite System Administrator’s Guide for descriptions of the Oracle Applications Manager UI screens that allow System Administrators to set up logging profiles, review Java system properties, search for log messages, and so on.
The Oracle E-Business Suite Developer's Guide, which includes logging guidelines for both System Administrators and developers, and related topics.
The Oracle Application Framework Developer's Guide, which describes the logging options that are available via the Diagnostics global link. This document is available on the Oracle Support Web site.