CIO Emulation for the FCE
This chapter covers the following topics:
- About CIO Emulation for the FCE
- Tasks for Implementing CIO Emulation for the FCE
- Converting Source Files with Substitution
- Compiling and Archiving Converted Files
- Converting Configurator Extension Rules
- Verifying Post-Conversion Behavior
About CIO Emulation for the FCE
CIO Emulation for the FCE is a facility that assists you in modifying existing Configurator Extensions that were written for the Original Configurator Engine (OCE) so that they might be able to operate with the Fusion Configurator Engine (FCE).
Why CIO Emulation for the FCE Is Needed
When you convert a Model to use the FCE, as described in Converting Existing Models to Use the Fusion Configurator Engine, the Model Conversion Utility does not convert the Configurator Extensions associated with that Model so that they also use the FCE.
Configurator Extensions that are associated with OCE Models interact with the Model through the Java API called the Configuration Interface Object (CIO), oracle.apps.cz.cio. The CIO is tailored specifically to the OCE. The FCE is entirely different in architecture from the OCE, and a different API is provided for interacting with FCE Models. This new API for the FCE is the Core API, oracle.apps.cz.core, which is documented by the Oracle Configurator API Reference, available through My Oracle Support.
The CIO API cannot access FCE Models. Therefore, CIO-based Configurator Extensions associated with an OCE Model will not work when the Model is converted to an FCE Model. Consequently, you must consider what to do with your Configurator Extensions. The options are described in the table Options for CIO-Based Configurator Extensions.
| Option | Advantages | Disadvantages |
|---|---|---|
| Rewrite CX to use the Core API. | Takes advantage of FCE capabilities, and provides optimal functionality. | Significant development effort. Requires Java expertise. Not necessary, if CX functionality is duplicated by FCE. |
| Use CIO Emulation for the FCE . | Requires potentially small amount of work, since conversion is mostly automated. Potentially requires less Java expertise. |
Functionality of CX after conversion must be verified. Differences in behavior may require new programming. May require some Java work to resolve compilation errors and other incompatibilities. |
| Discontinue use of CX. | If CX functionality is duplicated by FCE, no loss by discontinuing CX. | If CX functionality is not duplicated by FCE, effect of CX is lost. |
Intended Audience for CIO Emulation for the FCE
CIO Emulation for the FCE was designed primarily to provide a relatively straightforward migration path to the FCE for developers who have written Configurator Extensions that perform relatively straightforward tasks. If you have used the CIO to build a large-scale custom application, then the CIO Emulation for the FCE is not likely to help you migrate to the FCE, and you should consider rewriting your code using the Core API.
Elements of CIO Emulation for the FCE
The following elements constitute the CIO Emulation for the FCE facility:
-
CIO Emulation API (oracle.apps.cz.cioemu)
This API provides classes and methods that emulate the syntax of the CIO, while indirectly accessing the Core API. The API is documented by the Oracle Configurator API Reference, available through My Oracle Support. The relationship of this API to the CIO and Core APIs is shown in the figure APIs Related to CIO Emulation.
-
Substitution Script
This script modifies the source code of your Configurator Extensions, changing certain identifiers to refer to the CIO Emulation API rather than to the CIO API. For details, see Converting Source Files with Substitution.
-
Configurator Extension Status
This modification to Oracle Configurator Developer enables you to convert existing Configurator Extension Rules so that they refer to the CIO Emulation API rather than to the CIO API. For details, see Converting Configurator Extension Rules.
For an overview of the process that these elements support, see Tasks for Implementing CIO Emulation for the FCE.
Differences Between FCE and CIO Emulation
This section describes features how differences in behavior between the Fusion Configurator Engine and the Original Configurator Engine are handled in the CIO Emulation API, where possible.
| CIO (or FCE) Feature | FCE Behavior | CIO Emulation Behavior |
|---|---|---|
| Configuration transactions (ConfigTransaction) | No true equivalent for configuration transactions. The FCE has the concept of SavePoints. | This feature is not supported A warning is provided by the substitution script. The Configuration object provides "no-operation" methods that allow compilation but produce no results. There is no support for transaction levels. |
| StatusInfo | No equivalent concept in the Core API. | This feature is not supported. Any use of StatusInfo will not compile. |
| RestoreValidationFailure | The Core API has different handling of failed inputs when restoring a configuration, generating informational messages instead of validation failures. | This feature is not supported. A warning is provided by the substitution script. An emulation object is provided for compilation, but the Core API will not create objects, and CX code using this class will never be executed. |
| TSO (MACD) | The Telecommunications Services Ordering (TSO) functionality is not available for the Fusion Configurator Engine. | This feature is not supported. Since TSO functionality is not available for the FCE, there is no need for CIO Emulation support for TSO. Attempts to compile converted CX code using TSO features will raise compiler errors. |
| Configuration attributes (TSO-based) | A new implementation of configuration attributes for the FCE is provided, and described elsewhere in this document. | TSO-based configuration attributes are not supported. Attempts to compile CX code using TSO-based attribute features will raise compiler errors |
| Total and Resource objects | These OCE objects are converted to DecimalValue. During upgrade, domain definitions will be set as needed. | Replaced by cioemu.Total and cioemu.Resource objects. |
| Unbound Values | If a value is requested before being bound, Core API throws exception. | All Emulation getter methods will catch NodeUnboundException and provide a value consistent with the CIO behavior. Value is Unknown for state nodes and 0 for numeric nodes. |
| Logical exceptions | The FCE supports Logical Exceptions, as the CIO does, but the implementation is different. | Supported with emulation Logical Exceptions, which provide equivalent behavior. |
| CIO Exceptions (such as InsufficientCountException) | The Core API (for the FCE) does not throw all the same exceptions as the CIO API (for the OCE). CIO exceptions not needed by the Core API are not supported. | Emulation versions of these types of exceptions are provided. Any converted CX code using these exceptions will compile but the code will never be executed since the Core API does not throw these types of exceptions. |
| Connectors Note: Connectors are not yet supported for the FCE. This information is provided for planning. |
A ConnectorPort can have multiple connections. | Supported. But if cardinality of connections is greater than 1, then throws an exception when trying to create the emulation object, since OCE models can only have 1 target per connection. If there is more than 1, then either the conversion has an issue or the model has been changed. |
| Editable Totals and Resource | Not supported. | Not supported. Any calls in code to set the value of a Total or Resource will not compile. |
| FCE Proposed True and Proposed False states (Recommended (Proposed Selected) and Not Recommended (Proposed Excluded). |
These are new values returned from calls with getState(). Customer code not using existing static CIO helper methods (such as isTrue(int state)) may not behave as expected. | Since OCE doesn’t have the concept of PTRUE the emulation layer will return PTRUE as LTRUE and PFALSE as LFALSE. |
| InformationalMessage | There is no equivalent object in the Core API. Informational messages are now text-based. | The CIO Emulation API provides an equivalent object for InformationalMessage. |
| ValidationFailure | The Core API never creates ValidationFailure objects as the CIO does. The Core API only supports custom validation failures created by user-written CXs. | The CIO Emulation API provides an equivalent object for ValidationFailure. |
| CustomValidationFailure | There is no equivalent object in the Core API. | The CIO Emulation API provides an equivalent object for CustomValidationFailure, extending cioemu.ValidationFailure. |
| Intermediate Values | Problematic intermediate values do not arise with the FCE, so this concept is not supported in the Core API. In the Core API, methods representing the value of a numeric feature return zero until the value is bound. | Problematic intermediate values can arise in the OCE, so in the CIO methods representing the value of a numeric feature may return intermediate values. Because of the fundamental difference between OCE and FCE handling of intermediate values, no emulation support can be provided to bridge the gap between them. |
Candidate Implementations for Rewriting
This section suggests some Configurator Extension implementations that may be better served by rewriting the CXs than by converting them to use CIO Emulation for the FCE, since emulation does not completely provide the desired functionality.
Most of these CX implementations were intended to remedy shortcomings in the Original Configurator Engine that are described in Original Configurator Engine: Known Issues and Limitations. The Oracle Configurator Modeling Guide provides more detail on several of the issues related to the Original Configurator Engine.
It may be better to rewrite the following types of Configurator Extensions:
-
CXs that implement non-trivial configuration transactions.
The FCE does not use configuration transactions. Emulation provides "no-operation" transaction methods that allow the emulated CX code to compile and execute, but produce no results.
-
CXs that work around limitations in using the NotTrue logical operator or logical function.
These limitations do not occur with the FCE, because items in the configuration can never be in an "Unknown" state.
-
CXs that work around Numeric Rules being unidirectional.
In an FCE Model, Numeric constraints propagate in both directions.
-
CXs that work around intermediate numeric values in Comparison Rules.
This limitation does not occur with the FCE, due to the way in which it propagates rules.
-
CXs that work around Default limitations.
These limitations do not occur with the FCE, because the FCE implements Defaults in a significantly different way than the OCE.
-
CXs that implement auto-instantiation.
These actions are unnecessary with the FCE, because the FCE is able to dynamically instantiate components to satisfy constraints.
-
CXs that implement a Search.
This implementation is unnecessary with the FCE, because the Auto-Complete process of the FCE searches for a solution to a configuration.
Limitations of CIO Emulation for the FCE
Keep in mind the following limitations:
-
Emulation cannot fulfill every application of the CIO API for Configurator Extensions, since the CIO Emulation API cannot completely emulate all CIO behavior in the FCE. The FCE has capabilities that surpass the CIO, including some that overcome limitations of the CIO. In such cases, you should consider rewriting your Configurator Extensions and redesigning your configuration model to take advantage of the FCE. Keep in mind that the FCE makes many uses of Configurator Extensions unnecessary. See Candidate Implementations for Rewriting for suggestions.
-
You should evaluate the expected lifetime of the Configurator Extensions created by converting them to use CIO Emulation for the FCE, because methods in the CIO Emulation API cannot directly access the Core API. Therefore, you cannot add Core API methods into Configurator Extensions created by the conversion process. This means that you cannot combine OCE functionality and FCE functionality together in a single Configurator Extension. You can, however create new CXs that use only the CIO Emulation API, or new CXs that use only the Core API.
Caution: The use of objects from oracle.apps.cz.cioemu and oracle.apps.cz.core in the same method is explicitly unsupported. Such methods may compile, but will fail at runtime.
-
Before deploying Configurator Extensions using CIO Emulation for the FCE, it is essential to verify their behavior against your expectations, since there may be differences related to the basic differences between the Original Configurator Engine and the Fusion Configurator Engine.
-
Due to the limitations described in this chapter, it may not be possible to successfully convert all of your Configurator Extensions.
Tasks for Implementing CIO Emulation for the FCE
To implement CIO Emulation for the FCE, perform the tasks listed in Table Summary of Tasks for Using CIO Emulation for the FCE. For information about the tasks, refer to the sections cited in the Details column.
| Task | Description | For Details |
|---|---|---|
| 1 | Run the substitution script on the source files for your package. | Converting Source Files with Substitution |
| 2 | Compile the converted source files, resolve compilation errors, then create a Java archive file for the converted classes. | Compiling and Archiving Converted Files |
| 3 | Create a Configurator Extension Archive for the Java archive, then use Oracle Configurator Developer to convert existing Configurator Extension Rules that use the converted classes. | Converting Configurator Extension Rules |
| 4 | Verify the behavior of your Model when using the converted classes. | Verifying Post-Conversion Behavior |
Requirements for Implementing CIO Emulation
The following are required to perform the procedures described in this chapter:
-
Linux operating system, or other OS with support for the Perl scripting language
-
Perl scripting language, as normally provided in Oracle installations
-
It is assumed that your source file directory structure mirrors the structure of your Java packages.
Converting Source Files with Substitution
Before you can use CIO Emulation for the FCE in your Configurator Extensions, you must modify your Java classes to refer to the CIO Emulation API. To assist you in doing this, Oracle provides a substitution script that performs certain modifications on your Java source files.
Note: Note: As described elsewhere in this section, the script is named ciocxemu.pl, and it is installed by default, in $APPL_TOP/cz/12.0.0/bin.
What the Substitution Script Does
The substitution script performs a set of simple text substitutions on all the Java source files in your current working directory. Subdirectories are never processed.
Important: If you have multiple packages that reference classes in each other, then you should use custom substitution. See Custom Substitution for details.
The substitution script performs the text substitutions described in the tableSubstitutions Performed by the Script.
| Location in Code | Substitution Performed by the Script |
|---|---|
| import declarations | Changes all references to oracle.apps.cz.cio to oracle.apps.cz.cioemu |
| package declarations | Changes the package name of the class defined in the file, adding the suffix .emu. For example, my.pkg.cx is changed to my.pkg.cx.emu |
| variable declarations, parameter declarations, and type casts | Changes fully qualified class, interface, and exception names as shown in the table Substitutions Performed on the Supported Set of CIO Objects |
| code comments | Substitutions are applied in comment text. The conversion does not distinguish comments from code. |
| CIO Object Name | Substituted Object Name |
|---|---|
| oracle.apps.cz.cio.AtpUnavailableException | oracle.apps.cz.cioemu.AtpUnavailableException |
| oracle.apps.cz.cio.BomExplosionException | oracle.apps.cz.cioemu.BomExplosionException |
| oracle.apps.cz.cio.BomInstance | oracle.apps.cz.cioemu.BomInstance |
| oracle.apps.cz.cio.BomModel | oracle.apps.cz.cioemu.BomModel |
| oracle.apps.cz.cio.BomNode | oracle.apps.cz.cioemu.BomNode |
| oracle.apps.cz.cio.BomOptionClass | oracle.apps.cz.cioemu.BomOptionClass |
| oracle.apps.cz.cio.BomStdItem | oracle.apps.cz.cioemu.BomStdItem |
| oracle.apps.cz.cio.BooleanFeature | oracle.apps.cz.cioemu.BooleanFeature |
| oracle.apps.cz.cio.Component | oracle.apps.cz.cioemu.Component |
| oracle.apps.cz.cio.ComponentNode | oracle.apps.cz.cioemu.ComponentNode |
| oracle.apps.cz.cio.ConfigParameters | oracle.apps.cz.cioemu.IConfigParameters |
| oracle.apps.cz.cio.Connector | oracle.apps.cz.cioemu.Connector |
| oracle.apps.cz.cio.ConnectorInfo | oracle.apps.cz.cioemu.ConnectorInfo |
| oracle.apps.cz.cio.ConfigurationMessage | oracle.apps.cz.cioemu.ConfigurationMessage |
| oracle.apps.cz.cio.CountFeature | oracle.apps.cz.cioemu.CountFeature |
| oracle.apps.cz.cio.CustomValidationFailure | oracle.apps.cz.cioemu.CustomValidationFailure |
| oracle.apps.cz.cio.DecimalFeature | oracle.apps.cz.cioemu.DecimalFeature |
| oracle.apps.cz.cio.DecimalNode | oracle.apps.cz.cioemu.DecimalNode |
| oracle.apps.cz.cio.IAtp | oracle.apps.cz.cioemu.IAtp |
| oracle.apps.cz.cio.IBasicPrice | oracle.apps.cz.cioemu.IBasicPrice |
| oracle.apps.cz.cio.IBomItem | oracle.apps.cz.cioemu.IBomItem |
| oracle.apps.cz.cio.ICount | oracle.apps.cz.cioemu.ICount |
| oracle.apps.cz.cio.IDecimal | oracle.apps.cz.cioemu.IDecimal |
| oracle.apps.cz.cio.IDecimalMinMax | oracle.apps.cz.cioemu.IDecimalMinMax |
| oracle.apps.cz.cio.IInteger | oracle.apps.cz.cioemu.IInteger |
| oracle.apps.cz.cio.IIntegerMinMax | oracle.apps.cz.cioemu.IIntegerMinMax |
| oracle.apps.cz.cio.InformationalMessage | oracle.apps.cz.cioemu.InformationalMessage |
| oracle.apps.cz.cio.InsufficientCountException | oracle.apps.cz.cioemu.InsufficientCountException |
| oracle.apps.cz.cio.IntegerFeature | oracle.apps.cz.cioemu.IntegerFeature |
| oracle.apps.cz.cio.IntegerNode | oracle.apps.cz.cioemu.IntegerNode |
| oracle.apps.cz.cio.IOption | oracle.apps.cz.cioemu.IOption |
| oracle.apps.cz.cio.IOptionFeature | oracle.apps.cz.cioemu.IOptionFeature |
| oracle.apps.cz.cio.IPrice | oracle.apps.cz.cioemu.IPrice |
| oracle.apps.cz.cio.IReadOnlyDecimal | oracle.apps.cz.cioemu.IReadOnlyDecimal |
| oracle.apps.cz.cio.IRuntimeNode | oracle.apps.cz.cioemu.IRuntimeNode |
| oracle.apps.cz.cio.IState | oracle.apps.cz.cioemu.IState |
| oracle.apps.cz.cio.IText | oracle.apps.cz.cioemu.IText |
| oracle.apps.cz.cio.ModelLookupException | oracle.apps.cz.cioemu.ModelLookupException |
| oracle.apps.cz.cio.ModifiedConfigOverwriteException | oracle.apps.cz.cioemu.ModifiedConfigOverwriteException |
| oracle.apps.cz.cio.NeighborhoodBoundaryException | oracle.apps.cz.cioemu.NeighborhoodBoundaryException |
| oracle.apps.cz.cio.NoAtpCalculatedException | oracle.apps.cz.cioemu.NoAtpCalculatedException |
| oracle.apps.cz.cio.NoConfigHeaderException | oracle.apps.cz.cioemu.NoConfigHeaderException |
| oracle.apps.cz.cio.Option | oracle.apps.cz.cioemu.Option |
| oracle.apps.cz.cio.OptionFeature | oracle.apps.cz.cioemu.OptionFeature |
| oracle.apps.cz.cio.OptionFeatureNode | oracle.apps.cz.cioemu.OptionFeatureNode |
| oracle.apps.cz.cio.OptionNode | oracle.apps.cz.cioemu.OptionNode |
| oracle.apps.cz.cio.PricedNode | oracle.apps.cz.cioemu.PricedNode |
| oracle.apps.cz.cio.PricingUnavailableException | oracle.apps.cz.cioemu.PricingUnavailableException |
| oracle.apps.cz.cio.Property | oracle.apps.cz.cioemu.IProperty |
| oracle.apps.cz.cio.PropertyNotAvailableException | oracle.apps.cz.cioemu.PropertyNotAvailableException |
| oracle.apps.cz.cio.Reason | oracle.apps.cz.cioemu.Reason |
| oracle.apps.cz.cio.Request | oracle.apps.cz.cioemu.Request |
| oracle.apps.cz.cio.Resource | oracle.apps.cz.cioemu.Resource |
| oracle.apps.cz.cio.RuntimeNode | oracle.apps.cz.cioemu.RuntimeNode |
| oracle.apps.cz.cio.StateCountNode | oracle.apps.cz.cioemu.StateCountNode |
| oracle.apps.cz.cio.StateNode | oracle.apps.cz.cioemu.StateNode |
| oracle.apps.cz.cio.TargetInfo | oracle.apps.cz.cioemu.TargetInfo |
| oracle.apps.cz.cio.TextFeature | oracle.apps.cz.cioemu.TextFeature |
| oracle.apps.cz.cio.TextNode | oracle.apps.cz.cioemu.TextNode |
| oracle.apps.cz.cio.Total | oracle.apps.cz.cioemu.Total |
| oracle.apps.cz.cio.ValidationFailure | oracle.apps.cz.cioemu.ValidationFailure |
The substitution script only changes class and package names. It does not attempt to reimplement your CIO-based code in terms of the API for the FCE. See Differences Between FCE and CIO Emulation.
Running the Script
Procedure
To run the substitution script:
-
Identify the Java source files for the package that you want to convert to use the CIO Emulation API. It is assumed that your source file directory structure mirrors the structure of your Java packages.
For example, the source files for a package named my.pkg.cx would be located in a directory named /mydev/pkg/cx.
You can only process a single package at a time. You cannot run the script recursively over subdirectories.
-
Change to the directory containing the files that you want to convert.
cd /mydev/pkg/cx
-
Enter the command to run the substitution script. See Syntax and Parameters for information on the syntax of the command and its parameters.
perl yourpath/ciocxemu.pl parameters
Example command for the package mentioned in step 1 (my.pkg.cx):
perl $APPL_TOP/cz/12.0.0/bin/ciocxemu.pl my.pkg.cx
By default, the script is installed in $APPL_TOP/cz/12.0.0/bin.
-
The script processes all the Java source files in the current working directory (but not in any subdirectories), performing substitutions on each line of each file where a substitution is needed. See What the Substitution Script Does.
-
The script writes a series of informational messages to the console. For details on these messages, see Output of the Script.
-
The script creates a new subdirectory of the current working directory, named emu. This directory contains the modified Java files produced by the script, and a log file that contains the informational messages that were written to the console by the script. The code in the Java files has been modified as described in What the Substitution Script Does. Your original Java files in the current working directory are left unchanged.
-
Proceed to the next step under Tasks for Implementing CIO Emulation for the FCE.
Syntax and Parameters
The syntax for running the substitution script is:
[perl] [yourpath]ciocxemu.pl [-nologfile] [-noscreen] original_package [custom_target custom_replacement]
[perl] [yourpath]ciocxemu.pl [ –help | -manual ]
The parameters and command-line options for the substitution script are described in the table Options and Parameters for the Substitution Script.
| Option or Parameter | Description |
|---|---|
| perl | If necessary, invocation of the perl processor. Details are dependent on site and operating system. |
| yourpath | If necessary, your path to the substitution script ciocxemu.pl. By default, the script is installed in $APPL_TOP/cz/12.0.0/bin. |
| -nologfile | Suppresses generation of the log file. |
| -noscreen | Suppresses display of conversion messages to the console. |
| original_package | (Mandatory.) The package named in the package declaration in the Java source files being processed. |
| custom_target | When using custom substitution, the string in the original files to be replaced by custom_replacement in the modified Java files produced by the script. See Custom Substitution. |
| custom_replacement | When using custom substitution, the string to replace custom_replacement. See Custom Substitution. |
| -help | Displays basic command information about the script, in plain text format. |
| -manual | Displays basic command information about the script, in man page format. |
The common form of the command for running the script is shown in the example Simple Substitution Syntax. The example command shown in the example Simple Substitution Example makes the changes shown in the table File Modifications Performed by Simple Substitution.
ciocxemu.pl original_package
ciocxemu.pl my.pkg.cx
| Original File | Modified File |
|---|---|
| package my.pkg.cx; | package my.pkg.cx.emu; |
| import oracle.apps.cz.cio.IRuntimeNode; | import oracle.apps.cz.cioemu.IRuntimeNode; |
| postCXInit(java.lang.String, oracle.apps.cz.cio.IRuntimeNode) | postCXInit(java.lang.String, oracle.apps.cz.cioemu.IRuntimeNode) |
Custom Substitution
Custom substitution allows you to make arbitrary substitutions on the package being processed. It replaces a specified string in your original Java source files with a specified replacement string that will appear in your modified files.
ciocxemu.pl original_package custom_target custom_replacement
ciocxemu.pl my.pkg.cx my.pkg.util my.pkg.util.emu
Custom substitution is especially useful for the common situation in which a package references classes in another package. Consider an example in which one of your classes (my.pkg.cx.MyCXClass) calls a method (formatDate()) in another package (my.pkg.util.Toolkit). The table Cross-Package References with Simple Substitution shows how simple substitution can result in references that point to the incorrect package and class. The table Cross-Package References with Custom Substitution shows how custom substitution helps to modify the referencing package to correct many of the references.
| Stage | Class in Referenced Package | Class in Referencing Package |
|---|---|---|
| my.pkg.util.Toolkit | my.pkg.cx.MyCXClass | |
| Before simple substitution | package my.pkg.util; import oracle.apps.cz.cio.IRuntimeNode; public class Toolkit { void formatDate() } |
package my.pkg.cx; import oracle.apps.cz.cio.IRuntimeNode; import my.pkg.util.Toolkit; d = my.pkg.util.Toolkit.formatDate(); |
| Simple substitution on referenced package | ciocxemu.pl my.pkg.util | |
| Simple substitution on referencing package | ciocxemu.pl my.pkg.cx | |
| After basic substitution, the packages are changed, but not the references between them | package my.pkg.util.emu; import oracle.apps.cz.cioemu.IRuntimeNode; public class Toolkit { void formatDate() } |
package my.pkg.cx.emu; import oracle.apps.cz.cioemu.IRuntimeNode; import my.pkg.util.Toolkit; d = my.pkg.util.Toolkit.formatDate(); |
| At runtime, the class reference is incorrect | The new class is in a new package that uses the CIO Emulation API: my.pkg.util.emu.Toolkit |
The method call in the new class references the original package, which does not use the CIO Emulation API: my.pkg.util.Toolkit |
| Stage | Class in Referenced Package | Class in Referencing Package |
|---|---|---|
| my.pkg.util.Toolkit | my.pkg.cx.MyCXClass | |
| Before simple substitution | package my.pkg.util; import oracle.apps.cz.cio.IRuntimeNode; public class Toolkit { void formatDate() } |
package my.pkg.cx; import oracle.apps.cz.cio.IRuntimeNode; import my.pkg.util.Toolkit; d = my.pkg.util.Toolkit.formatDate(); |
| Simple substitution on referenced package | ciocxemu.pl my.pkg.util | |
| Custom substitution on referencing package | ciocxemu.pl my.pkg.cx my.pkg.util my.pkg.util.emu | |
| After custom substitution, the packages are changed, and also the references between them | package my.pkg.util.emu; import oracle.apps.cz.cioemu.IRuntimeNode; public class Toolkit { void formatDate() } |
package my.pkg.cx.emu; import oracle.apps.cz.cioemu.IRuntimeNode; import my.pkg.util.emu.Toolkit; d = my.pkg.util.emu.Toolkit.formatDate(); |
| At runtime, the class reference is correct | The new class is in a new package that uses the CIO Emulation API: my.pkg.util.emu.Toolkit |
The method call in the new class references the new package, which uses the CIO Emulation API: my.pkg.util.emu.Toolkit |
Important: Custom substitution does not perform all the modifications required to make your files ready for CIO Emulation for the FCE. It is possible that your packages will compile successfully but still contain incorrect references.
Output of the Script
When the substitution script runs, it creates the following output:
-
A new subdirectory of the current working directory, named emu.
-
In the emu subdirectory, the new Java files produced by the script, which have been modified as described in What the Substitution Script Does.
-
Your original Java files in the current working directory are left unchanged.
-
Files in the emu subdirectory are not overwritten. This behavior allows you to run the script multiple times over the same working directory without reconverting files that have already been converted. This avoids extra processing if you add files to the working directory after the initial run. It also preserves changes that you may have made to the emu files if you inadvertently run the script again on the working directory. See Errors from the Script for more information.
-
-
In the emu subdirectory, a log file that contains the informational messages that were written to the console by the script. The name of the log file is CxEmuConversionyyyymmdd.log, where yyyymmdd is the year, month, and date when the script was run.
-
The header of the log file is shown in the example Conversion Log File: Header. It shows the original_package parameter that you specified. It also shows your custom_target and custom_replacement parameters, if any, or NOT PROVIDED otherwise.
Example 5. Conversion Log File: Header
Conversion to Cio Cx Emulation: Started at 2009/03/06 10:46:23 Input Directory: /my/pkg/cx/ Output Directory: /my/pkg/cx/emu/ Input Package : my.pkg.cx Output Package : my.pkg.cx.emu Input Custom : my.pkg.util Output Custom : my.pkg.util.emu
-
A typical log file entry for a file being converted is shown in the example Conversion Log File: File Entry. The warning message indicates that the original file contained a CIO class that is not fully supported in emulation. See Errors from the Script for more information.
Example 6. Conversion Log File: File Entry
====================================================================== Convert: /my/pkg/cx/AddClonedInstances.java to /my/pkg/cx/emu/AddClonedInstances.java WARNING: At line: 13. oracle.apps.cz.cioemu.TransactionException. Not supported but provided for CX compilation. Review usage and behavior. Completed: /my/pkg/cx/AddClonedInstances.java
-
The concluding block in the log file is shown in the example Conversion Log File: Tail. The Pre Directory Java File Count is the number of Java source files in the current working directory when you start the substitution script. All of those files are considered for processing when the script runs. The Converted CX File Count is the number of files actually created by the script in the emu subdirectory. If Converted CX File Count is smaller than Pre Directory Java File Count, it should indicate that some files already have converted versions in the emu subdirectory, and thus were not overwritten.
Example 7. Conversion Log File: Tail
Pre Directory Java File Count: 28 Converted CX File Count : 28 Conversion to Cio Cx Emulation: Completed at 2009/03/06 10:46:44
Errors from the Script
When the substitution runs, it may generate some of the messages described in the table Substitution Script Error Messages.
| Message | Explanation |
|---|---|
| Custom substitution: New text is required | If you provided more than one parameter, the script assumes that you are using custom substitution, which requires three arguments. See Custom Substitution. |
| WARNING: path/emu/FileName.java already exists. File not converted | A file with the same name as one being converted already exists in the emu subdirectory. Such files are not overwritten. |
| The import was converted. References to unsupported classes will not compile. | If your converted code refers to classes that do not have equivalents in the CIO Emulation API, it will not compile. See Differences Between FCE and CIO Emulation. |
| WARNING At line: n. oracle.apps.cz.cioemu.ClassName. Not supported but provided for CX compilation. Review usage and behavior | Your original file refers to a CIO class that is not fully supported in emulation. |
The above table omits self-explanatory error messages such as "Incorrect number of arguments".
Compiling and Archiving Converted Files
After you run the substitution script to modify your Java class source files, compile them and archive them so that the classes can be used by Configurator Extension Rules in your configuration model.
Procedure
To compile and archive your converted files:
-
Compile the converted Java source files created by the substitution script in the emu subdirectory.
It is likely that some of your class references could not be resolved by the substitution script. See About CIO Emulation for the FCE for an understanding of what the CIO Emulation API can provide.
-
Resolve any compilation errors.
-
Create a Java archive file for the compiled classes, in the usual way.
See the Oracle Configurator Extensions and Interface Object Developer's Guide for information on developing Java classes and archives.
-
Proceed to the next step under Tasks for Implementing CIO Emulation for the FCE.
Converting Configurator Extension Rules
After the substitution script has modified your Java class source files to refer to the CIO Emulation API, it is still necessary to modify the bindings in all of the Configurator Extension (CX) Rules that used your original classes, so that they, too, refer to the CIO Emulation API. This conversion of Rules is performed in Oracle Configurator Developer, as described in this section.
Assumptions
This task assumes the following:
-
You have converted your Models to use the FCE, using the Model Conversion Utility.
-
You have run the substitution script on your Java source files for your Configurator Extensions, and have compiled and archived your resulting Java class files (which now refer to the CIO Emulation API).
-
Your converted Models contain CX Rules (which at this point still refer to the CIO API rather than the CIO Emulation API or Core API).
Limitations
Take note of the following limitations of the Rule conversion operation:
-
You can only convert the CX Rules for one Model at a time, and this Model must already have been converted to use the FCE.
-
All of the CX Rules in your Model are processed for conversion. You cannot include or exclude specified CX Rules from conversion, since CIO-based CX Rules that are not converted cannot operate with your converted FCE Model and are thus no longer useful.
-
CX Rules marked as Disabled are converted, and remain Disabled after conversion. Disabling a CX Rule does not exclude it from conversion.
-
CX Rules are converted without creating backup copies in your converted FCE Model. The original CX Rules remain in your original unconverted Model, but are not retained in your converted FCE Model.
Procedure
To convert your CX Rules:
-
Log in to Oracle Configurator Developer.
-
Create a Configurator Extension (CX) Archive, using the Java class archive that you created for your modified source files.
See the Oracle Configurator Developer User's Guide for information on creating CX Archives.
Tip: As you proceed with converting your CX Rules, you can use this new CX Archive for all the Models whose CX Rules referenced your original classes.
-
Edit a Model that contains CX Rules that may need to be converted, and go to the General area of the Workbench.
If a Model has CX Rules that need conversion, then the General area of the Workbench includes a new section named Configurator Extensions Status. The section displays a message stating that the Configurator Extension Rules in the model were created with bindings whose arguments refer to Original Configurator Engine classes (that is, to the CIO API). Such Rules need to be converted to use the CIO Emulation API that are referenced in the new CX Archive.
-
If the Configurator Extensions Status section indicates a need for conversion, click Convert.
You need to add your new Emulation-based CX Archive to the Archive Path for your Model. The Edit Archive Path page appears, listing all CX Archives in the Main area of the Repository, subject to the current focus level and folder expansion.
-
Locate your new Emulation-based CX Archive and select it.
Click the check box in the Select column to select an Archive.
-
Click Add to Selected List.
The selected Archive appears at the end of the Selected List, meaning that it has been placed at the end of the Archive Path. See the section of the Oracle Configurator Developer User's Guide about archive path precedence for important information about the Archive Path.
-
When you are satisfied with the order of Archives in the Selected List, click Apply. This step triggers the actual conversion of the Rules.
When the conversion operation finishes, you return to the General area of the Workbench.
If the Rule conversion was not successful, then the Configurator Extensions Status section still appears, and an error message appears in the information area.
If the Rule conversion was successful, then the Configurator Extensions Status section no longer appears, and a message in the information area tells you that the Configurator Extension bindings in this model were successfully converted to use the classes for the Fusion Configurator Engine.
Important: The CX Rule conversion operation ensures that your Rules are modified to use the appropriate classes and interfaces from the CIO Emulation package. However, you must review your converted rules to verify their expected behavior.
-
If you examine the definitions of your CX Rules, you will find that they have been modified in accordance with the changes shown in the table Substitutions Performed by the Script.
-
The package name for the Java Class has been changed to refer to the package created by the substitution script. For example, my.pkg.cx.MyCXClass is changed to my.pkg.cx.emu.MyCXClass.
-
In the event bindings, any references to CIO API objects have been changed to refer to CIO Emulation API objects. For example, oracle.apps.cz.cio.IRuntimeNode is changed to oracle.apps.cz.cioemu.IRuntimeNode.
-
-
Repeat steps 3 through 7 for your other converted FCE Models.
Tip: If the set of classes in your new Emulation-based CX Archive corresponds to the set of classes in your old CIO-based CX Archive, then you can more easily determine which Models used the CIO classes (and thus need to have their CX Rules converted to use the CIO Emulation API classes referenced in the new Archive) by examining the list of Models Referencing This Archive in the old Archive.
-
Proceed to the next step under Tasks for Implementing CIO Emulation for the FCE.
Verifying Post-Conversion Behavior
To ensure the success of your conversion to CIO Emulation for the FCE, you must verify that your Configurator Extensions behave as expected after you have converted their code to use the emulation classes. Some suggestions for performing this verification are:
-
Use logging in your Configurator Extension code, as described in the Oracle Configurator Extensions and Interface Object Developer's Guide. Logging output can help verify that a block of code was executed as expected. Your converted code should be using the method oracle.apps.cz.cioemu.Configuration.writeCXLogEntry().
-
Ensure that all of the uses of Configurator Extensions in your application's UI are exercised.
-
Review your converted Configurator Extension Rules in Oracle Configurator Developer.