Working with Configurations

This chapter describes how to interact with runtime configuration objects.

This chapter covers the following topics:

Overview of Configurations

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:

Typical Methods of the Configuration Object
To do this ... Use this method of Configuration ...
Access the CIO object that contains the Configuration object getCIO()
Access the component object for which the Configuration object represents a configuration getRootComponent()
Obtain a collection of current validation failures getValidationFailures()
Obtain an indication of whether the complete configuration is satisfied isUnsatisfied()
getUnsatisfiedItems()
Obtain a collection of the selected nodes in the configuration getSelectedItems()
Save the current configuration saveNew()
saveNewRev()
Close the current configuration close()

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.

Creating Configurations

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

Correspondence of Configuration Parameters to 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.

Removing Runtime Configurations

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.

Saving Configurations

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.

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.

Monitoring Changes to Configurations

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.

How the CIO Monitors Changes to Configurations

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:

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.

How You Can Monitor Changes to Configurations

You can get or set the value of the changed-state flag of a configuration.

Restoring Configurations

You restore a configuration in order to operate on it if it has been saved and closed (as described in Saving Configurations).

Restarting Configurations

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:

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.

Automatic Behavior for Configurations

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.

Events for Processing Configurations
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).

Dispatching Command Events

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

Dispatching a Command Event

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

Access to Configuration Parameters

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.

Sharing a Configuration Session

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:

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.

UI Specifications for Invoking Child Window
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).

Redirecting to a Framework Page

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.