CIO Basics

This chapter explains the basics of the Oracle Configuration Interface Object (CIO) and how to use it. For details about how to use the CIO for specific purposes, see other chapters in Part 2.

This chapter covers the following topics:

Background to the CIO

This section describes the CIO and its relationship to Configurator Extensions.

What is the CIO?

The Configuration Interface Object (CIO) is an API (application programming interface) that provides programs access to the Model used by a runtime Oracle Configurator, which you construct with Oracle Configurator Developer. The CIO is designed to enable you to programmatically perform any interaction with a configuration model that can be interactively performed by an end user during a configuration session.

The CIO is a top-level configuration server. The CIO is responsible for creating, saving and destroying objects representing configurations, which themselves contain objects representing Models, Components, Features, Options, Totals and Resources. The runtime configuration model can be completely controlled and manipulated through these interfaces, using methods for getting and setting logical, numeric and string values, and creating optional subcomponents.

Client Applications

The CIO is the only API supported by Oracle for programmatic interaction with the runtime Oracle Configurator. Consequently, any custom applications must use the CIO. Custom applications are those that integrate Oracle Configurator with a custom user interface (a UI not generated by Oracle Configurator Developer).

The CIO is also used by Configurator Extensions, as described in Configurator Extensions and the CIO. Be sure to review the Oracle Configurator Performance Guide for information on the performance impacts of Configurator Extensions.

Most of the techniques for using the CIO apply equally to custom applications and Configurator Extensions. This document points out selected cases where there is a distinction between these two applications.

Implementation Language

The Oracle Configuration Interface Object is written in Java, and implemented as the Java package oracle.apps.cz.cio. To use the functionality of the CIO you must import classes from this package.

Note: Unless stated otherwise, references in this document to classes, methods, and properties refer to the package oracle.apps.cz.cio, and all code examples are in Java.

The CIO and Configurator Extensions

A Configurator Extension is Java code that calls the CIO.

Configurator Extensions are invoked by the CIO through the runtime Oracle Configurator, and Configurator Extensions call the CIO to get information from the running Model. The CIO is like a broker for the runtime Oracle Configurator, in that it passes information both ways. Programmers writing Configurator Extensions need to know how to use the CIO.

Each Configurator Extension is an object class. For every component instance in your Model that is associated with a Configurator Extension, the CIO creates an instance of this class.

The CIO’s Runtime Node Interfaces

When you program against the CIO, you create one instance of the class CIO (see Initializing the CIO) and one or more instance of the classes Configuration and ConfigParameters (see Working with Configurations). You then use the public interfaces of the CIO, such as those listed in Important Runtime Node Interfaces for the CIO, to access fields in the runtime node objects created by your instances of CIO and Configuration. Apart from CIO and Configuration, your code should refer only to these public runtime node interface objects. You should not implement any of the runtime node interfaces, but only use them as references to runtime node objects.

In Java, an interface is a special type that allows programmers more flexibility in the way that they implement the internal details of classes. In Java terms, an interface is a named collection of method definitions, without implementations of those methods. For example, in the CIO, the interface IRuntimeNode specifies methods that are implemented in the class RuntimeNode.

Note: In normal circumstances, the only CIO classes that you should create (with the Java keyword new) are:

You only need to create these objects when working with a custom application. Configurator Extensions do not need to create them, because that task is performed by the runtime Oracle Configurator when it starts a configuration session.

The table Important Runtime Node Interfaces for the CIO lists some of the interfaces defined in the Java package oracle.apps.cz.cio that you are most likely to use in working with the CIO. For more detail about these and the other CIO interfaces, see Reference Documentation for the CIO.

Important Runtime Node Interfaces for the CIO
Interface Role of implementing classes
Component Interface for components.
IBomItem Implemented by all selectable BOM items.
ICount Implemented by objects that have an associated integer count.
IDecimal Implemented by objects that can both get and set a decimal value.
IInteger Implemented by objects that have an integer value.
IOption Implemented by objects that act as options. The defining characteristic of an option is that it can be selected and deselected.
IOptionFeature Implemented by objects that contain selectable options. This interface provides a mechanism for selecting and deselecting options, and for determining which options are currently selected.
IRuntimeNode Implemented by all objects in the runtime configuration tree. This interface implements behavior common to all nodes in the runtime configuration tree, including Components, Features, Options, Totals, and Resources.
IState Implemented by objects that have logic state. This interface contains a set of input states, used to specify a new state for an object, a set of output states, returned when querying an object for its state, and a set of methods for getting and setting the object's state.
IText Implemented by objects that have a textual value.

The functionality underlying the CIO interfaces is implemented by other classes in oracle.apps.cz.cio, which are subject to revision by Oracle. This interface/implementer architecture protects your code from the effects of such revisions, since the interfaces remain constant.

Initializing the CIO

In order to use any of the features of the CIO, an application must initialize it, using a JDBC driver to make a connection to the Oracle Configurator schema. This connection enables the CIO to obtain and store data about Model structure, Configuration Rules, and User Interface.

Use the following practice to initialize the CIO:

  1. Import the necessary classes.

    import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import oracle.apps.cz.cio.*;
import oracle.apps.cz.common.*;

    It is good practice to import only the classes that you actually need. The example here shows oracle.apps.cz.cio.* for simplicity.

  2. Load the database driver that you have installed. For instance:

    Class.forName("oracle.jdbc.driver.OracleDriver");

  3. Create a context object and pass to it the information needed to make a database connection: the full path and name of the DBC file. The context object manages the database connection. You should not create a separate connection object (for instance, by using java.sql.DriverManager.getConnection).

    contextObject = new CZWebAppsContext ("/fullpath/dbcFileName.dbc");

    In the current release, all DBC files should be installed in the directory identified by the system parameter FND_SECURE. This directory is distinct from FND_TOP. Your custom code must access DBC files through FND_SECURE.

    When creating a context object, it is necessary to set the Responsibility ID for the session.

    SessionManager  sm = contextObject.getSessionManager();
sm.setResp(appId,respId);

    Consult the Java API reference documentation for oracle.apps.fnd.common.Context.getSessionManager() and oracle.apps.fnd.security.SessionManager.setResp(int, int) for background.

  4. Create a single global CIO object. This object is shared by any Configuration objects that are created during the configuration session.

    CIO cioObject = new CIO();

Creating a Configuration Object (MyConfigCreator.java) shows how some of these steps are employed.