Upgrading to this Release

This chapter contains information you should consider when upgrading from a previous release of Oracle Configurator.

This chapter covers the following topics:

Introduction

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.

Maintaining Custom Servlet Properties

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.

Maintaining or Migrating Functional Companions

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.

Functional Companion Migration Requirements

When deploying Models in this release of Oracle Configurator, your choice about whether or not to migrate existing Functional Companions depends on:

These factors are summarized in Scenarios for Migration of Functional Companions.

Scenarios for Migration of Functional Companions
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.

Functional Companion Migration Processing

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:

Migration of Functional Companion Methods to Configurator Extension Event Bindings
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

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.

Functional Companion Methods That Are Not Migrated
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.

Setup for Migrating Functional Companions

You must perform certain setup tasks when migrating Functional Companions.

Manual Migration of Certain Functional Companion Methods

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.

Example Functional Companion Requiring Manual Migration

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
    }}

General Procedure for Manual Migration

The following steps describe the general procedure for manually migrating this Functional Companion to a Configurator Extension.

  1. 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.

  2. In Oracle Configurator Developer, create a Configurator Extension Archive for the Java archive file containing your revised code.

  3. 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.

  4. 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.

  5. 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

Maintaining Functional Companions

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.

Maintaining Configuration Attributes

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.