This chapter contains information you should consider when upgrading from a previous release of Oracle Configurator.
This chapter covers the following topics:
This chapter contains information about Functional Companions and legacy User Interfaces that you should consider when upgrading from a previous release of Oracle Configurator.
If you are upgrading from a previous version of Oracle Configurator Release 12, run adpatch to apply the latest patches to your Oracle Applications Release 12 environment. For the latest required patches, go to MetaLink, Oracle’s technical support Web site. See Maintaining Oracle E-Business Suite for information about applying these patches.
For additional information about this release of Oracle Configurator and Oracle Configurator Developer, see the current release or patch information for Oracle Configurator on MetaLink.
Note: Upgrading to a new version of Oracle Configurator does not prevent end users from restoring configurations that were saved using a previous version of the software. Additionally, restoring such a saved configuration does not adversely affect the configuration in any way; however, additional selections may be required if the Model structure or any rules have changed since the configuration was saved.
Note: When upgrading from Release 11.5.9 or earlier to Release 12, the table CZ_EXT_APPLICATIONS is created. This table is used by Configurator Developer when you publish configuration models. During the upgrade, this table is populated with all of the Oracle Applications products that can host Oracle Configurator. Any other application that has published Models are also added to this table. If you want to publish a Model to an application that does not appear in the list of values for the Applications applicability parameter in Oracle Configurator Developer, then you must add a record to the CZ_EXT_APPLICATIONS table using PL/SQL. For more information, see the Oracle Configurator Implementation Guide.
Before upgrading to this release, back up your cz_init.txt file and all customizations to Apache configuration files, such as jserv.properties, httpd.conf, and zone.properties (these configuration files are not used by Oracle Application Server). The upgrade process creates an empty cz_init.txt file and overwrites the existing version.
After the installation or upgrade is complete, copy any Configurator-related custom properties that were previously defined in zone.properties or jserv.properties to cz_init.txt.
For more information, see Verifying oc4j.properties and cz_init.txt.
Note: Do not copy or move any Java system properties that are defined in jserv.properties or zone.properties to cz_init.txt for logging purposes. Refer to Troubleshooting for information about logging.
User Interfaces that you create in the HTML-based version of Configurator Developer are called generated UIs. Generated UIs support all existing Functional Companions except those that interacted with DHTML UIs, since DHTML UIs are no longer supported.
Note: Oracle recommends that you use Configurator Extensions instead of Functional Companions wherever possible. Circumstances that might require you to maintain Functional Companions are described in this section.
If you want to modify existing Functional Companions and use them with a generated UI, then you must first migrate them to Configurator Extensions. A Configurator Extension that has been migrated from a Functional Companion is supported in generated UIs. For details about Configurator Extensions, see the Oracle Configurator Extensions and Interface Object Developer’s Guide and the Oracle Configurator Developer User’s Guide.
To determine whether you need to migrate Functional Companions, see Functional Companion Migration Requirements.
To understand what happens when Functional Companions are migrated, see Functional Companion Migration Processing.
If you need to run the migration concurrent programs, you must perform the tasks described in Setup for Migrating Functional Companions and use the instructions in the Oracle Configurator Implementation Guide to run either the Migrate All Functional Companions or Migrate Functional Companions for a Single Model concurrent program.
If you need to manually migrate any Functional Companions, as indicated in Functional Companion Methods That Are Not Migrated, see Manual Migration of Certain Functional Companion Methods.
If you wish to keep using an existing Functional Companion that is not already associated with a Model, you can do so by creating Configurator Extension bindings for it, since you cannot use the migration concurrent programs on it. See the current release or patch information for Oracle Configurator on MetaLink, Oracle's technical support Web site.
When deploying Models in this release of Oracle Configurator, your choice about whether or not to migrate existing Functional Companions depends on:
The need to change Functional Companion behavior
The type of User Interface used by the Model with which the Functional Companion is associated
These factors are summarized in Scenarios for Migration of Functional Companions immediately below.
Change Functional Companion Behavior? | User Interface Used | Migration Needed? | Migration Result |
---|---|---|---|
No | Legacy (DHTML) or generated in the HTML-based version of Configurator Developer | No | Existing Functional Companions still operate |
Yes | Legacy (DHTML) or generated in the HTML-based version of Configurator Developer | Yes | Functional Companions replaced with Configurator Extensions |
Functional Companions that interacted with DHTML User Interfaces (using IUserInterfaceEventListener.handleUserInterfaceEvent()) are not supported in generated UIs, and cannot be migrated. DHTML UIs themselves are no longer supported.
Certain Functional Companions that are registered through runtime events must be manually migrated. See Functional Companion Methods That Are Not Migrated in the section Manual Migration of Certain Functional Companion Methods.
Functional Companion migration transforms Functional Companion Rules into Configurator Extension Rules, transforming the data that associates existing Java classes with Models. Migration does not transform the Java classes, although you may need to do that task yourself, depending on the factors described in this document.
Migration of Functional Companion Methods to Configurator Extension Event Bindings shows the correspondences between the Java methods that are used by Functional Companions and the configuration events used by the Configurator Extension Rules produced by migration.
Other relevant facts about migration are as follows:
You cannot migrate an individual Functional Companion Rule. You can migrate all the Functional Companion Rules for a specified Model (and its referenced children), or for all Models in the database.
The migration process creates, where appropriate, a binding between the specified Functional Companion method and the corresponding configuration event. The migration process also creates any argument bindings required by the event, and sets the event scope for the bindings.
When migration completes successfully, the Functional Companion association data is logically deleted from the database.
If a method in a Functional Companion has no arguments, then after migration there are no argument bindings in the resulting Configurator Extension Rule.
There are certain configuration events used by Configurator Extensions that do not correspond with Functional Companion methods. Consequently, these events do not appear in Migration of Functional Companion Methods to Configurator Extension Event Bindings.
Functional Companions in published Models can not be migrated. Only Functional Companions in source Models can be migrated.
There are certain Functional Companion methods that cannot be migrated by the concurrent programs, and require manual migration. These are included in Functional Companion Methods That Are Not Migrated.
The Functional Companion methods listed in Migration of Functional Companion Methods to Configurator Extension Event Bindings override the methods of the classes FunctionalCompanion or AutoFunctionalCompanion.
The autoConfigure() method is migrated to an onCommand event binding in which the command name is generated by concatenating the internal Rule ID generated by Oracle Configurator for the new Configurator Extension Rule with a string indicating the Functional Companion type (_AC for "autoConfigure"). Example: 1000001_AC.
The generateOutput(HttpServletResponse) method is migrated the same way, except that the concatenated string for "generateOutput" is _GO. Example: 1000002_GO.
When you generate a User Interface for your Model, the generated command name is applied to the button that is created, as both its associated action and its default caption. For details on generating User Interfaces and modifying buttons, see the Oracle Configurator Developer User’s Guide.
Functional Companion Method | Configuration Event for Binding | When Migrated |
---|---|---|
initialize (IRuntimeNode, String, String, int) | postCXInit | Always. This binding is always created, even if the Functional Companion does not already implement initialize(). |
terminate() | preCXTerminate | If the Functional Companion extends the class FunctionalCompanion or AutoFunctionalCompanion. |
autoConfigure() | onCommand (Rule ID + _AC) | If Auto-Configuration was selected as the Type of the Functional Companion and if the Functional Companion extends the class FunctionalCompanion or AutoFunctionalCompanion. |
generateOutput (HttpServletResponse) | onCommand (Rule ID + _GO) | If Output was selected as the Type of the Functional Companion and if the Functional Companion extends the class FunctionalCompanion or AutoFunctionalCompanion. |
validate() | onConfigValidate | If Validation was selected as the Type of the Functional Companion and if the Functional Companion extends the class FunctionalCompanion or AutoFunctionalCompanion. |
validateEligibleTarget (Component) | onValidateEligibleTarget | If the Functional Companion extends the class FunctionalCompanion or AutoFunctionalCompanion. |
afterSave() | postConfigSave | If the Functional Companion extends AutoFunctionalCompanion |
onLoad() | onInstanceLoad | If the Functional Companion extends AutoFunctionalCompanion |
onNew() | postConfigNew | If the Functional Companion extends AutoFunctionalCompanion |
onRestore() | postConfigRestore | If the Functional Companion extends AutoFunctionalCompanion |
onSave() | preConfigSave | If the Functional Companion extends AutoFunctionalCompanion |
onSummary() | preConfigSummary | If the Functional Companion extends AutoFunctionalCompanion |
postLoad() | postInstanceLoad | If the Functional Companion extends AutoFunctionalCompanion |
postConfigInit
postInstanceAdd
postInstanceDelete
postInstanceEditable
postInstanceEditable
postInstanceNonEditable
postInstanceNameChange
postConnect
postDisconnect
postValueChange
preConfigCancel
preConfigDone
preConfigTerminate
There are a number of methods that might be used in Functional Companions that are not migrated by the concurrent programs described in this section. These methods are listed in Functional Companion Methods That Are Not Migrated in the section Manual Migration of Certain Functional Companion Methods..
Method | Reason Not Migrated |
---|---|
Functional Companion.generateOutput() |
This deprecated method requires a thick client connection, which is not compatible with Oracle Applications Release 12. |
ICompSetEventListener. notifyComponentAdded(Component) |
Requires manual migration. See Manual Migration of Certain Functional Companion Methods. |
ICompSetEventListener. notifyComponentDeleted(Component) |
Requires manual migration. See Manual Migration of Certain Functional Companion Methods. |
IConfigEventListener. notifyComponentAdded(Component) |
Requires manual migration. See Manual Migration of Certain Functional Companion Methods. |
IConfigEventListener. notifyComponentDeleted(Component) |
Requires manual migration. See Manual Migration of Certain Functional Companion Methods. |
IConfigurationEventListener. eventOccured(ConfiguationEvent) |
Only supported for legacy DHTML user interfaces to Oracle Configurator. DHTML UIs are no longer supported. |
IConnectionEventListener. notifyConnectionAssigned(Connector) |
Requires manual migration. See Manual Migration of Certain Functional Companion Methods. |
IConnectionEventListener. notifyConnectionUnassigned(Connector) |
Requires manual migration. See Manual Migration of Certain Functional Companion Methods. |
IUserInterfaceEventListener. handleUserInterfaceEvent(Event) |
Only supported for Legacy DHTML user interfaces to Oracle Configurator. DHTML UIs are no longer supported. |
You must perform certain setup tasks when migrating Functional Companions.
Before you run the concurrent programs to migrate Functional Companions, you must put the Java classes that implemented the Functional Companions (which might be in Java archive files in JAR or Zip format) into the class path of the Concurrent Manager. Assuming as an example that your Java classes are in an Java archive file named fc.jar, use the following procedure:
The file fc.jar must be in a directory that is accessible from the computer on which your Concurrent Manager is started. If it is not, then add the full class path of fc.jar (including fc.jar) to the variable AF_CLASSPATH in the file $APPL_TOP/admin/adovar.env.
Initialize your environment again, by logging out and logging in.
Restart your Concurrent Managers.
Before you run the concurrent programs to migrate Functional Companions, you must ensure that servlet.jar is in the system classpath.
After you run the concurrent programs to migrate Functional Companions, remove the Java classes that implemented the Functional Companions from the class path of your Web server. Then create Configurator Extension Archives for the Java classes, as described in the Oracle Configurator Developer User’s Guide. If you leave the Java classes in the class path, the runtime Oracle Configurator will use those versions instead of the versions in the Configurator Extension Archives.
This section describes in general terms how to manually migrate the methods that require manual migration (see Functional Companion Methods That Are Not Migrated). These methods cannot be migrated by the migration concurrent programs because they require identification of entities that exist only at runtime.
You must adapt the following instructions to the specific characteristics of your Functional Companions.
A Functional Companion might use the methods in question as shown in the fragment in Functional Companion Code Before Manual Migration.
Functional Companion Code Before Manual Migration
public class MyCompanion extends FunctionalCompanion implements IConfigEventListener { public void initialize(){ m_config.addConfigEventListener(this); // m_config is a Configuration } public void notifyComponentAdded(Component comp){ // FC method // do something } public void notifyComponentDeleted(Component comp){ // FC method // do something }}
The following steps describe the general procedure for manually migrating this Functional Companion to a Configurator Extension.
Rewrite, compile, and archive the Java code so that it resembles the fragment in Functional Companion Code After Manual Migration, which is compatible with Configurator Extensions. For details, see the Oracle Configurator Extensions and Interface Object Developer’s Guide.
Functional Companion Code After Manual Migration
public class MyExtension { // no need to extend CIO classes public void componentAdded(ComponentSet set, Component comp){ // custom method // do something } public void componentDeleted(ComponentSet set, Component comp){ // custom method // do something }}
For details on the remaining steps, see the Oracle Configurator Developer User’s Guide.
In Oracle Configurator Developer, create a Configurator Extension Archive for the Java archive file containing your revised code.
In Oracle Configurator Developer, create a Configurator Extension Rule, specifying your custom class (MyExtension).
Set the Base Node of the Rule to the desired node.
Set the Instantiation Scope of the Rule to With Model Node Instance Set.
In this Configurator Extension Rule, create an event binding for each method of your Java class. The following table shows a choice of events that is appropriate to the Java methods in the example. You must choose events that are appropriate to your own case.
Method Name | Event | Event Parameters |
---|---|---|
componentAdded(set, comp) | postInstanceAdd | compSet instance |
componentDeleted(set, comp) | postInstanceDelete | compSet instance |
For each binding, bind the arguments of the Java method to parameters that are required for the event. The following table shows a choice of argument bindings that is appropriate to both of the Java methods in the example. You must choose bindings that are appropriate to your own case.
Argument Type | Argument Name | Argument Specification | Binding |
---|---|---|---|
ComponentSet | set | Event Parameter | compSet |
Component | comp | Event Parameter | instance |
If you need to retain the functionality of DHTML UIs that include Functional Companions, then you must migrate your Functional Companions to Configurator Extensions. Functional Companions require DHTML UIs, and DHTML UIs are not supported in this release. The limited edition of Oracle Configurator Developer that is required for creating or modifying DHTML UIs is not available in this release. You should not create Functional Companion rules in a generated UI created with the HTML-based version of Oracle Configurator Developer.
For a legacy Model that has been upgraded to this release, each unmigrated Functional Companion is presented by default on a read-only page in the Rules area of the Workbench in Oracle Configurator Developer. This page enables you to examine the definition of the Functional Companion rule. To migrate the Functional Companion, you must run the Migrate Functional Companions for a Single Model concurrent program, as described in Maintaining or Migrating Functional Companions.
If you set the profile option CZ: Enable Creation of Functional Companions to Yes, then each unmigrated Functional Companion is presented on a page in the Rules area of the Workbench in Oracle Configurator Developer that enables you to edit its definition. (For details about this profile option, see CZ: Enable Creation of Functional Companions.) Functional Companion rules have the same attributes in this release as in the previous release: Name, Description, Type (Validation, Auto-Configuration, Output, and Event-Driven), and Program String.
If you were to set the profile option to Yes, then you could also create new Functional Companion rules, by clicking the Create icon in the Rules area of the Workbench, then choosing Functional Companion. In previous releases, you could create such rules in an upgraded Model, to be included in a legacy DHTML UI, but DHTML UIs are no longer supported. You should not ever create Functional Companion rules in a generated UI created with the HTML-based version of Oracle Configurator Developer.
See CZ: Enable Creation of Functional Companions for details about the profile option that enables editing or creation of Functional Companion rules.
To use configuration attributes with Release 11.5.10, you may need to use Configurator Extensions instead of Functional Companions. For details about configuration attributes, see the Oracle Configurator Methodologies documentation.