This chapter describes how to interact with runtime configuration objects.
This chapter covers the following topics:
The Configuration object, oracle.apps.cz.cio.Configuration, represents a complete configuration. You can use the CIO to work with multiple configurations within the same configuration session.
For essential background information about Configuration objects, see the chapter on managing configurations in the Oracle Configurator Implementation Guide.
You communicate with a runtime configuration through the Configuration object, using methods such as those listed in the table Typical Methods of the Configuration Object:
The Configuration object also provides methods for starting, ending, and rolling back logic transactions performed on a configuration. Logic transactions maintain logic consistency; they are not database transactions. See Using Logic Transactions.
Note: This use of the CIO is intended for custom applications. Configurator Extensions do not need to create a Configuration object, because that task is performed by the runtime Oracle Configurator when it starts a configuration session.
To create a Configuration object, which is the top-level entry point to a configuration, use CIO.startConfiguration().
Note: The use of CIO.startConfiguration() completely replaces the use of all versions of CIO.createConfiguration(), which is now deprecated. Existing code that uses the deprecated method is still compatible with the CIO, but cannot use any new functionality.
This method takes as arguments a ConfigParameters object and a context object.
The context object provides the application context for the connection to the database. See Initializing the CIO for information on creating a context object.
The ConfigParameters object encapsulates all the information needed to create a configuration. To create a ConfigParameters object, invoke one of the constructors for ConfigParameters, depending on the type of configuration you need to create:
To create an entirely new configuration, provide a Model ID:
public ConfigParameters(int modelId)
This is the constructor shown in Creating a Configuration Object (MyConfigCreator.java).
To restore a saved configuration, provide its Configuration Header ID and Configuration Revision Number.
public ConfigParameters(long headerId, long revisionNumber)
To create a configuration for a BOM without a configuration model (sometimes known as a "native BOM" configuration), provide the Inventory Item ID, Organization ID, and effective date of the BOM to be exploded and configured:
public ConfigParameters(int inventoryItemId, int organizationId, Date explosionDate)
To control the initialization of the new configuration, use the methods in the ConfigParameters class to set the configuration parameters. For details on these methods, see the reference for the CIO (described in Reference Documentation for the CIO).
Use the methods in the following list to set the effective date for the configuration and the model’s publication lookup date.
If you do not set these dates, they default to the date when Oracle Configurator considers the configuration to have been created.
All other parameters to the ConfigParameters object are optional, and are defaulted.
Once a configuration has been created, changing a configuration parameter does not affect the configuration in any way.
To obtain access to the CIO object that created the configuration, use Configuration.getCIO().
Most of the constructor and method arguments to ConfigParameters correspond to one of the initialization parameters for the runtime Oracle Configurator. The correspondences are shown in the table Correspondence of Configuration Parameters to Initialization Parameters. See the Oracle Configurator Implementation Guide for more information on the initialization parameters.
Configuration Parameter | Argument | Initialization Parameter |
---|---|---|
Model ID | modelId | model_id |
Configuration Header ID | headerId | config_header_id |
Configuration Revision Number | revisionNumber | config_rev_nbr |
Inventory Item ID | inventoryItemId | inventory_item_id |
Organization ID | organizationId | organization_id |
Configuration Effective Date | effectiveDate | config_effective_date |
Model Lookup Date | modelLookupDate | config_model_lookup_date |
Creating a Configuration Object (MyConfigCreator.java) shows a technique for creating a Configuration object. For clarity, it omits some important tasks, such as using transactions and fully handling exceptions.
Creating a Configuration Object (MyConfigCreator.java)
import oracle.apps.cz.cio.CIO; import oracle.apps.cz.cio.ConfigParameters; import oracle.apps.cz.cio.Configuration; import oracle.apps.cz.cio.IRuntimeNode; import oracle.apps.cz.cio.IState; import oracle.apps.cz.cio.IOption; import oracle.apps.cz.cio.LogicalException; import oracle.apps.cz.cio.ModelLookupException; import oracle.apps.cz.cio.BomExplosionException; import oracle.apps.fnd.common.Context; import oracle.apps.cz.utilities.EffectivityUsageException; import oracle.apps.cz.common.CZWebAppsContext; import java.util.Calendar; public class MyConfigCreator { // Create the context object for this instance private static String dbcFileName = "/jdevhome/users/dbc_files/secure/server01_sid02.dbc"; private static CIO cio; private static Context context; public static void main(String [] args) { context = new CZWebAppsContext( dbcFileName ); CIO cio = new CIO(); // Create shared global CIO MyConfigCreator work = new MyConfigCreator(); // Create a configuration object, using the shared CIO work.createConfig1(); // Possibly use the same shared CIO to create more configurations // work.createConfig2(); // work.createConfig3(); // and so on ... } // Create a new Configuration object public Configuration createConfig1() { Configuration config1 = null; // Create the ConfigParameters object and set non-default parameters int modelId = 5005; // hypothetical model ID ConfigParameters cp = new ConfigParameters(modelId); java.util.Calendar modelLookupDate = Calendar.getInstance(); // current date and time cp.setModelLookupDate(modelLookupDate); try { // Create the Configuration object Configuration config = cio.startConfiguration(cp, context); } catch (LogicalException le) { // Perform exception handling here } catch (ModelLookupException mle) { // Perform exception handling here } catch (EffectivityUsageException eue) { // Perform exception handling here } catch (BomExplosionException bee) { // Perform exception handling here } return config1; } }
Note: If your custom application is running in standalone mode, then you may need to ensure that the Java system property JTFDBCFILE is set. This property is normally set correctly by Oracle Rapid Install, which is described in the Oracle Configurator Installation Guide.
This property is used by the Oracle Applications Framework to provide the Java virtual machine (JVM) with the location of the DBC file that contains the database information needed to create a database context.
If you connect to a different database while still in the same JVM, then you must reset JTFDBCFILE to specify the DBC file for that database.
If JTFDBCFILE is not set, then you will be unable to create configurations when running in standalone mode.
Note: This use of the CIO is intended for custom applications. Configurator Extensions do not need to close theConfiguration object, because that task is performed by the runtime Oracle Configurator when it terminates a configuration session.
To remove all runtime structure and memory associated with a configuration, use CIO.closeConfiguration(). Oracle recommends that you invoke this method when ending a configuration session and before exiting the runtime Oracle Configurator.
You save a runtime configuration so that you can operate on it later, after it has been closed at the end of a configuration session.
When you save a configuration, it is stored in the CZ schema of the Oracle Applications database. To later operate on a saved configuration, you must first restore it, as described in Restoring Configurations.
There are several methods for saving configurations. Choose the one that suits your requirements, as described in the following list.
Use Configuration.saveNew()to save an entirely new Configuration object.
The saved Configuration object has a new Configuration Header ID and a Configuration Revision Number of 1.
Use Configuration.saveNewRev() to save a new revision of a previously saved Configuration object.
The saved Configuration object has the same Configuration Header ID as the previously created Configuration object, but the Configuration Revision Number uses the next available Revision Number.
Use Configuration.save() to save subsequent changes to a previously saved Configuration object, overwriting the existing configuration data.
The saved Configuration object has the same Configuration Header ID and the same Configuration Revision Number as the previously created Configuration object.
For more information on saving configurations, see the Oracle Configurator Implementation Guide.
Caution: Do not save a Configuration object during a logic transaction (see Using Logic Transactions). You may miss some validation messages that are not available until the transaction is committed.
When changes are made to a configuration, the CIO monitors whether the configuration needs to be saved. You can access the flag that tracks this status.
During a runtime configuration session, the CIO monitors whether changes have been made to the current configuration, and whether those changes need to be saved. Changes can result either from end user actions in the user interface of the runtime Oracle Configurator, or from assertions made through the CIO by your Configurator Extensions or custom application code.
To keep track of whether a configuration needs to be saved, the CIO maintains a Boolean changed-state flag, whose values are interpreted as "clean" or "dirty". At the beginning of a configuration session, the flag is set according to the following rules:
Any new configuration having no assertions against it is marked as clean.
Any restored configuration having no assertions against it is marked as clean, regardless of whether it produces validation failures when restored.
Any new or restored configuration with assertions against it is marked as dirty.
During the configuration session, if there are unsaved changes, then the changed-state flag is set to dirty by the CIO.
When the configuration is saved, the changed-state flag is set to clean. It does not matter how the saving is performed: by a Configurator Extension or by a custom user interface.
When the Cancel button is clicked in the user interface of the runtime Oracle Configurator, the UI Server checks the changed-state flag; if it is dirty, the UI Server produces a dialog asking the user whether to continue exiting the session without saving the changes. If you write a custom user interface, it should do the same, using the technique described in How You Can Monitor Changes to Configurations.
You can get or set the value of the changed-state flag of a configuration.
To get the value of the changed-state flag, use the method Configuration.areAllChangesSaved().
This method returns TRUE the configuration is clean (that is, if all the changes that have been made to this configuration during the configuration session have been saved). This method returns FALSE if the configuration is dirty (that is, if there are changes that have been made to this configuration that have not been saved).
You can use this method when you want to determine whether a configuration needs to be saved.
To set the value of the changed-state flag, use the method Configuration.setAllChangesSaved(), which takes the boolean argument clean.
If you pass TRUE as the value of clean, then the changed-state flag is set to "clean". Any further changes to the configuration make it dirty again. If you pass FALSE as the value of clean, then the changed-state flag is set to "dirty".
You can use this method when you want to change the configuration through the CIO without interfering with the end user’s sense of what has changed during a configuration session. For example, if you use a Configurator Extension to create and rename of an instance of an instantiable component when the configuration is created, the changed-state flag is set to dirty. You can then use setAllChangesSaved() to set the flag to clean, so that if the end user clicks the Cancel button before making any changes, the UI Server does not produce the dialog asking whether to continue exiting the session without saving changes.
You restore a configuration in order to operate on it if it has been saved and closed (as described in Saving Configurations).
To restore a Configuration object from the Oracle Configurator schema, use CIO.startConfiguration(). For details about that method, see Creating Configurations and Creating a Configuration Object (MyConfigCreator.java).
Note: The use of CIO.startConfiguration() completely replaces the use of all versions of CIO.restoreConfiguration(), which is now deprecated. Existing code that uses the deprecated method is still compatible with the CIO, but cannot use any new functionality.
When you restore a configuration, any user requests (see User Requests) that cannot be applied are reported as validation failures. See Failed Requests.
You may be able to improve performance by restarting the current configuration, instead of restoring it. See Restarting Configurations.
You must be aware of the possible effects of changing the model structure or configuration rules in Oracle Configurator Developer between the time you save a configuration and the time you restore it.
If you change the Instantiability settings for a Model or Component to decrease or increase the Initial Minimum, this might change the number of previously saved instances that exist when restore a saved configuration. Unmodified initial instances are restored in the order they were initially created, until they possibly exceed the Initial Minimum. However, no instances that you modify or add will be lost.
Here is an example of the preceding point:
Define the Initial Minimum of an instantiable component as 5.
Create a configuration. The Initial Minimum of 5 is enforced, instantiating that number of components.
Modify 2 of the initially instantiated components. For instance, make them targets of Connectors, or select options of their children.
Add 1 new component instance, and delete 1 initial instance.
There are now 5 instances: 2 modified initial instances, 2 unmodified initial instances, and 1 added instance.
Save the configuration. All 5 instances are saved.
Change the Initial Minimum of the instantiable component to 3.
Restore the saved configuration.
The following 4 instances are restored:
The 1 added instance (because added instances are always restored). Added instances are not counted against changes in the Initial Minimum.
The 2 modified initial instances (because modified instances are always restored).
Only the first 1 of the unmodified initial instances (because the other 1 unmodified initial instance exceeds the new Initial Minimum of 3, and is not restored).
Only unmodified instances can be lost when a configuration is restored. Any modified or added instances are restored, regardless of the Initial Minimum.
If the Initial Minimum is increased, then the configuration might be restored with more instances than were saved.
Remember that it is only the User True configuration inputs to the model that are saved, not all the Logic True effects that those inputs may have when reapplied later. When you restore a configuration, any user requests that cannot be applied are reported as validation failures. Consequently, you should notify end users of changes to your configuration model or rules.
Here is an example of the preceding point:
Define a Logic Rule stating that Option1 Requires Option2.
In a configuration session, the end user selects Option1, which then has an input state of TRUE.
See Getting and Setting Logic States for an explanation of input and output states.
Your configuration rule causes the selection of Option2, which then has an output state of LTRUE. The end user observes the effect of this change to Option2. This effect might include the calculation of a price, or the inclusion of a certain item in the order.
The configuration is saved. Only the input state of TRUE for Option1 is saved.
The configuration rule "Option1 Requires Option2" is deleted or disabled.
The configuration is restored. Only the state of UTRUE for Option1 is restored. Because your configuration rule is no longer affecting Option2, its input state remains UNKNOWN. The end user observes, with confusion, that the previous selection of Option2 no longer occurs. The effect of this situation might be that a previously observed price or item no longer appears in the order.
For more information on restoring configurations, see the Oracle Configurator Implementation Guide.
Use Configuration.restartConfiguration() to restart the current configuration. You restart a configuration when you want to remove the effects of a configuration session without removing the components that you are configuring from the session. When you restart a configuration, the CIO:
Rolls back logic transactions
Removes requests
Reverses the assertions that had set logic states and values
Removes component instances added during the session, and restores component instances deleted during the session
You must be using the CIO with a custom user interface to use restartConfiguration(); this method cannot be used with a user interface generated by Oracle Configurator Developer.
You can define behavior that is executed whenever a configuration is processed in certain ways, by defining Configurator Extensions bound to certain events. The tableEvents for Processing Configurations describes some of these events, and the circumstances under which you should use them. For a list of types of events, see Types of Configuration Events. 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 | Triggered ... | Comments |
---|---|---|
postConfigNew | When a newly-created configuration is activated | See Creating Configurations for background on creating configurations. |
preConfigSave | Before a configuration is saved | You can save a configuration using the Model Debugger in Oracle Configurator Developer. |
postConfigSave | After a configuration is saved | Clicking the Finish button in the runtime Oracle Configurator terminates the configuration session and saves the configuration, if it is valid. |
postConfigRestore | After a configuration is restored | You can restore a saved configuration using the Model Debugger in Oracle Configurator Developer. |
preConfigSummary | Immediately before the Summary screen is displayed | Clicking the Summary button in the runtime Oracle Configurator displays the Summary screen. |
See the Oracle Configurator Developer User’s Guide for details on how to create Configurator Extensions that are bound to events.
In the runtime Oracle Configurator, the Configurator Extension runs when one of the events listed in Events for Processing Configurations is executed (such as after a configuration is saved).
If you are using the CIO with a custom user interface, then you must substitute your own event-dispatching mechanism for the one provided in user interfaces generated by Oracle Configurator Developer. Generated user interfaces call Configuration.dispatchEvent() internally for all events except command events. Command events are the only events that your custom code can raise, and the only way that your code can explicitly cause a Configurator Extension to run.
The example Dispatching a Command Event demonstrates how you can dispatch a command event, specifying the command string and the base node, to run any Configurator Extensions bound to that event.
Either a custom UI or a Configurator Extension can dispatch the onCommand event. Custom UI code can dispatch onCommand directly at any time (with the usual restrictions to avoid recursion or infinite loops).
... Configuration cfg = node.getConfiguration(); String command = "myOnCommand"; IRuntimeNode source = getSourceNode(); // custom method if (source == null) { CXEvent event = new CXCommandEvent(command); } else { CXEvent event = new CXCommandEvent(command, source); } Collection cxResults = cfg.dispatchEvent(event); ...
In the example, cxResults is a collection of CXResult objects, which you can use to get access to information about what rule was triggered, what value it returned, and what method was called. Use cxResults.getReturnedValue() to interpret the returned values.
If you are using Oracle Configurator in a Web deployment, you can use a Configurator Extension to obtain a list of the initialization parameters that are passed from the host application to your configuration Model.
To access initialization parameters, create a Configurator Extension that calls Configuration.getUserParameters(), which returns a NameValuePairSet object. This object contains all the parameter names and values stored by the runtime Oracle Configurator when it processes the initialization message sent by the host application to the Oracle Applications Framework.
The example Getting Initialization Parameters demonstrates how to obtain the set of parameters for the current configuration.
Getting Initialization Parameters
/** * Gets all the user init parameters for the current bound configuration. * * @param config in a CX, bind to the System Parameter "Configuration" */ public NameValuePairSet getParametersFromConfig(Configuration config) { // Get the user parameters for that current configuration NameValuePairSet userParams = config.getUserParameters(); return userParams; }
After you obtain the set of user parameters, you can obtain the value of a particular parameter, as shown in the example Getting an Initialization Parameter Value.
Getting an Initialization Parameter Value
... NameValuePairSet paramSet = getParametersFromConfig(config); String appID = getHostApplicationID(paramSet); ... /** * Gets the value of a particular parameter. * In this case, the Application ID of the calling application. * Calls the custom utility method getParamValue(). */ public static String getHostApplicationID (NameValuePairSet params) { return (getParamValue (params, "calling_application_id")); } /** * Utility method: get the string value of a user parameter * * @param params the set of all current user parameters. * @param paramName the name of the parameter whose value you want */ public static String getParamValue (NameValuePairSet params, String paramName) { Object value = params.getValueByName(paramName); return (value == null ? null : String.valueOf(value)); }
As a security measure, the initialization parameter pwd, which contains a password, is not returned by getUserParameters().
To add your own user-defined configuration parameters to those contained in the initialization message, making them a part of the configuration, use ConfigParameters.addUserParam(), which takes the name of the parameter (a string) and the value (an object). To obtain the value of one of these configuration parameters, call ConfigParameters.getUserParam().
See the Oracle Configurator Implementation Guide for more information about the initialization message.
During a configuration session, your application may require the ability to launch a custom user interface in a child window of the runtime Oracle Configurator window. This child UI might interact with the user and perform updates to the state of the configuration model. When these interactions are finished, the child UI returns control to the parent window containing the runtime Oracle Configurator UI.
If your application opens such a child window, that window needs shared access to the configuration model, through the Configuration object.
You can get the Configuration object from the HTTP session by using the key configurationObject. You can obtain a URL for returning to the parent window by requesting the session object czReturnToConfiguratorUrl. The example in Sharing a Configuration Session in a Child Window illustrates the use of these objects. You can obtain these objects by using one of the following methods from the Java servlet or JSP API:
javax.servlet.http.HttpSession.getValue ("czReturnToConfiguratorUrl")
javax.servlet.jsp.PageContext.getAttribute("czReturnToConfiguratorUrl", PageContext.SESSION_SCOPE)
During the period of user interaction with the child UI window, you should prevent any use of the parent window, since that might interfere with the changes to the state of the application or configuration model being made in the child window.
Caution: The custom UI in the child window must be running in the same HTTP session as the parent window containing the runtime Oracle Configurator. You must also ensure thread safety, as noted under Observing Thread Safety.
You can create the kind of child window that you need in the HTML-based version of Oracle Configurator Developer, by creating a UI element (such as a Custom Button) that supports the Open URL action in a generated Configurator UI, using the specifications provided in the table UI Specifications for Invoking Child Window. For background, see the Oracle Configurator Developer User’s Guide.
Option | Choice |
---|---|
Caption Source | Text Expression, indicating to the end user the action that the UI element performs |
Action Type | Open URL |
Target URL Source | Text Expression, pointing to your custom child UI (such as a JSP), which must be located in the OA_HTML directory. The specific expression for Sharing a Configuration Session in a Child Window (TestChildWin.jsp) is:
/OA_HTML/TestChildWin.jsp |
Target Window | Child Window Select the option to Lock Main Window while Displaying Child |
These specifications are used for Sharing a Configuration Session in a Child Window (TestChildWin.jsp).
If your Configurator Extension opens a child window in the Oracle Applications Framework and later returns to its parent window (as shown in Sharing a Configuration Session) then you need to get the message authentication code (MAC) for the URL of the parent window and apply it to the URL before returning. Without a valid MAC, the Framework will reject the return request as originating from an invalid session.
The following code fragment shows how to get the MAC and apply it to a URL.
CZWebAppsContext ctx = (CZWebAppsContext)contxt; String redirectURL = URLMgr.processOutgoingURL(url, URLTools.getHMAC(ctx));
The example Applying a Message Authentication Code shows the definition of a utility method, urlRedirect(), for applying a MAC.
Applying a Message Authentication Code
import oracle.apps.fnd.framework.webui.URLMgr; import oracle.apps.fnd.common.URLTools; import oracle.apps.cz.common.CZWebAppsContext; ... /** * @param response the HttpServletResponse from the calling CX method * @param url the destination page that requires FWK validation * @param contxt the context from the configuration */ public static void urlRedirect (HttpServletResponse response, String url, Context contxt) { try { // Add HMAC information to pass FWK validation checks CZWebAppsContext ctx = (CZWebAppsContext)contxt; String redirectURL = URLMgr.processOutgoingURL(url, URLTools.getHMAC(ctx)); response.sendRedirect(redirectURL); } catch (java.io.IOException ioe){ throw new CheckedToUncheckedException(ioe); } } ...
For an example of calling this method, see the redirectLocationSearch() method in the TSO Configurator Extension MaintainLocationCX.java, which is available on MetaLink, Oracle's technical support web site.
That example calls the urlRedirect() method, as shown in the following code fragment:
Configuration conf = trackableRoot.getConfiguration(); ... CXUtilities.urlRedirect (response, url, conf.getContext());
Note that the database context parameter is obtained from a Configuration object.