This chapter tells you how to verify that the Oracle Configurator Servlet (OC Servlet) is set up correctly and describes all customizable OC Servlet properties.
This chapter covers the following topics:
To view a User Interface in a runtime Oracle Configurator, you must have the Oracle Configurator Servlet (OC Servlet) installed on your internet server.
Installing the OC Servlet includes:
Using Oracle Rapid Install to install Oracle Configurator, Oracle Configurator Developer, and Oracle Application Server 10g . Installing Oracle Application Server 10g also installs the Apache Web server and supporting software.
See Oracle Rapid Install.
Verifying OC Servlet setup by reviewing (and modifying, if necessary) the Apache configuration files.
For details, see Verifying Apache and OC4J Setup.
Verifying or modifying Java system properties for the OC Servlet.
Refer to Oracle Application Server documentation for additional information about installing or configuring the OC Servlet.
Note: These instructions assume that you are installing on the Solaris ™ Operating Environment platform, unless noted otherwise.
Note: Run the Oracle Configurator Servlet under the production version of the latest version of JDK 1.5 for your platform. The production version runs significantly faster than the reference version. (Oracle Rapid Install provides JDK version 1.5.) See Verifying oc4j.properties and cz_init.txt for details on verifying this setting.
Previous versions of Oracle Configurator Developer generated either DHTML or Java applet-style UIs. The current version of Configurator Developer generates User Interfaces that are based on the OA Framework, and cannot be used to generate or modify DHTML or Java applet UIs. If you are upgrading to the current version of Configurator Developer, you cannot use it to create or maintain DHTML or Java applet UIs, but must first upgrade to a previous release that supports maintenance of DHTML UIs or Java applet UIs and then convert them to OA Framework-based UIs.
For details about the Oracle Configurator servlet properties that support UIs created in the current version of Configurator Developer, see Descriptions of Oracle Configurator Servlet Properties.
For a description of servlet properties that support DHTML and Java applet UIs, see:
The Oracle Configurator Installation Guide specific to the Oracle Configurator release from which you recently upgraded.
For example, if you upgraded from release 11.5.8, refer to the release 11.5.8 version of the Oracle Configurator Installation Guide.
Current release or patch information for Oracle Configurator on MetaLink, Oracle's technical support Web site
After installing Apache and its supporting software by running Oracle Rapid Install, verify that the server is set up correctly. To do this, enter a command with the following structure in a Web browser:
URL of the Servlet?test=version
http://www.mysite.com:60/OA_HTML/configurator/UiServlet?test=version
The result should be the build and schema version of Oracle Configurator running on the server. For example:
Using configuration software build: 12.0.27.2 Expecting schema: 27b
Note: The property cz.uiservlet.versionfuncsavail must be set to true for this test to work properly. For details, see cz.uiservlet.versionfuncsavail.
If the build and schema version does not appear, refer to Oracle Application Server documentation for details about troubleshooting server configuration.
For details about Apache configuration files, refer to Apache documentation at http://java.apache.org.
You must log in as the owner of the configuration files in order to modify them.
Refer to the following for information about each configuration file:
Documents related to upgrading or installing Oracle Applications. See Oracle Applications Documentation Resources, on MetaLink, Oracle's technical support Web site.
For a description of the OC Servlet properties, see Oracle Configurator Servlet Properties.
Oracle Application Server reads Java system properties from the file oc4j.properties. The only Oracle Configurator-specific property in oc4j.properties that is read by the OC Servlet is cz_properties_file.
The property cz_properties_file identifies the location of the file cz_init.txt. Define any custom servlet properties in this file (for example, you may want to modify properties that have default values). For details, see Syntax and Context for Setting Parameters.
The other properties in oc4j.properties are provided only to support legacy User Interfaces (DHTML and Java applet UIs) that were created in previous versions of Oracle Configurator Developer.
For important information about preserving customized servlet files when installing or upgrading, see Maintaining Custom Servlet Properties.
You can leave obsolete OC Servlet parameters in a configuration file without triggering an error. You can also set unimplemented parameters without triggering an error, if you observe the rules for syntax. You may want to do this for testing purposes, to observe which parameters are passed to the OC Servlet.
Note: The cz_init.txt file is intended only for properties that are specific to Oracle Configurator. Defining non-Oracle Configurator, properties in cz_init.txt (such as those used for logging) may produce unintended results at runtime.
All OC4J properties are available as Java system properties and are available to both the OC Servlet and all Oracle Configurator Java classes. By default, Oracle Rapid Install places oc4j.properties and cz_init.txt in the following directory:
/ins/apps/EnvName/ora/10.1.3/j2ee/oacore/config
The properties are set on the Java Virtual Machine (JVM) that runs the OC4J container so they are available to the OC Servlet when it starts up.
Note: Oracle Containers for J2EE (OC4J) is the core J2EE runtime component of Oracle Application Server. Refer to Oracle Application Server documentation for details.
Oracle strongly recommends that you run Java 5 (JDK 1.5) or higher. Oracle Rapid Install installs this version by default.
Oracle also recommends a heap size of at least 600MB, but the required heap size may vary depending on your configuration.
You set custom values for JVM options in the system-specific context file that is created by Oracle Rapid Install. For example:
$APPL_TOP/admin/OAInstName.xml
where OAInstName is the name of your Oracle Applications instance.
These options must be set using the context variable s_oacore_jvm_start_options; otherwise the values will be lost when you apply patches or upgrade to a new release. The default value of this variable is:
<oacore_jvm_start_options oa_var="s_oacore_jvm_start_options">-server -verbose:gc -Xmx512M -Xms128M -XX:MaxPermSize=160M -XX:NewRatio=2 -XX:+PrintGCTimeStamps -XX:+UseTLAB -XX:+UseParallelGC -XX:ParallelGCThreads=2 -Dcom.sun.management.jmxremote -Djava.security.policy=$ORACLE_HOME/j2ee/oacore/config/java2.policy -Djava.awt.headless=true -Dhttp.webdir.enable=false -Doracle.security.jazn.config=/slot02/appmgr/inst/apps/czr12d19/ora/10.1.3/j2ee/oacore/config/jazn.xml-Doracle.security.jazn.config=/slot02/appmgr/inst/apps/czr12d19/ora/10.1.3/j2ee/oacore/config/jazn.xml>
The default values for the maximum and initial heap size are -Xmx512M and -Xms128M, respectively.
Note: When viewing the context variable s_oacore_jvm_start_options in a text editor, its value appears on a single line. The value is shown here on multiple lines to improve readability.
After modifying this context variable, run AutoConfig to populate the system configuration files with new values and make them permanent. For details about AutoConfig, see Oracle E-Business Suite Concepts.
If you have implemented a custom return URL servlet, then perform the following:
Note: This procedure assumes that you are installing a single Java class file for your servlet. If your class is located in a JAR file, then it must be added to the class path for OC4J. See Specifying the Location of Functional Companion Classes for information on how to add JAR files to the class path for OC4J.
Place the compiled Java class file for the servlet under your $JAVA_TOP directory.
Example: If you created a servlet Checkout.java in a package myorg.myservlets, then the location of the class file should be:
$JAVA_TOP/myorg/myservlets/Checkout.class
To register an alias name for the return URL servlet you modify the following file:
$INST_TOP/ora/10.1.3/j2ee/oacore/application-deployments/oacore/html/orion-web.xml
In the <servlet> section of orion-web.xml, enter a unique alias for the return URL servlet name, and then specify its fully-qualified class name.
Example:
<servlet> <servlet-name>Checkout</servlet-name> <servlet-class>myorg.myservlets.Checkout</servlet-class> </servlet>
In the <servlet-mapping> section, define a text pattern that associates your servlet's alias with the URL to the class file's location relative to $JAVA_TOP. ($JAVA_TOP is assumed to be in the runtime class path.)
Example:
<servlet-mapping> <servlet-name>Checkout</servlet-name> <url-pattern>/myorg/myservlets/Checkout</url-pattern> </servlet-mapping>
See the Oracle Configurator Implementation Guide for more information about implementing the return URL.
You set Apache parameters that determine any customized OC Servlet properties (that is, properties that are used only by Oracle Configurator) in the file cz_init.txt. Set Java system properties using the following syntax:
property_name=property_value
For example, use the following syntax to set the property cz.uiservlet.pre_load_filename:
cz.uiservlet.pre_load_filename=init_msg.txt
If you are using legacy Functional Companions, specify the location of required Java archive (JAR) files in orion-application.xml. To do this, use one of the following context variables:
s_oacore_prepend_classpath
s_oacore_append_classpath
The file orion-application.xml is located in the following directory:
$INST_TOP/ora/10.1.3/j2ee/oacore/application-deployments/oacore/
The following example shows how to specify a single Functional Companion JAR file in orion-application.xml, using the variable s_oacore_append_classpath:
<oacore_append_classpath oa_var="s_oacore_append_classpath"> FullPathToJARFile </oacore_append_classpath>
where FullPathToJARFile is the path to your JAR file.
The following example shows how to specify multiple JAR files in orion-application.xml:
<oacore_append_classpath oa_var="s_oacore_append_classpath"> <![CDATA[/FullPathToJARFile/File_1.jar"/> <library path="/FullPathToJARFile/File_2.jar"/> <library path="/FullPathToJARFile/File_3.jar]]> </oacore_append_classpath>
To temporarily add a JAR file (such as for testing purposes), edit orion-application.xml and add the following:
<library path="FullPathToJAROrZIPFile"/>
Important: Remember that this change is temporary, as the library path entry will be removed when you apply a patch or upgrade to a new release.
Note: The Java classes that implement the behavior of Configurator Extensions are located in Configurator Extension Archives, which are created in Oracle Configurator Developer and are stored in the database. The runtime Oracle Configurator loads Configurator Extensions from the database, so it is not necessary to install them relative to the OC Servlet.
See the Oracle Configurator Developer User’s Guide for information about creating Configurator Extension Archives. See the Oracle Configurator Extensions and Interface Object Developer’s Guide for information about creating the Java classes that implement the behavior of Configurator Extensions.
Note: When you modify and recompile a Functional Companion, you must restart the OC Servlet to load the new class file. It is not necessary to restart the OC Servlet when you modify Configurator Extensions, because they are loaded from the database.
OC Servlet properties are passed as Java system properties to the JVM in which the process for the OC Servlet is running.
You can modify the default runtime behaviors produced by the OC Servlet properties described in this section by defining them in cz_init.txt and specifying custom values. For details, see Verifying oc4j.properties and cz_init.txt.
This section lists the OC Servlet properties and their default values, which are included in the software code. To modify a property’s default behavior, define the property in cz_init.txt using the syntax listed in this section, and specify a custom value. For more information about cz_init.txt, see Verifying oc4j.properties and cz_init.txt.
The properties of the OC Servlet for which you can set Apache configuration parameters are listed in Properties for the Oracle Configurator Servlet.
This property controls optional behavior for the Dynamic Tree, which is a navigation aid included in certain User Interfaces that you design with Oracle Configurator Developer.
If you set the value of this property to ShowLinks, then the Dynamic Tree Navigation UI displays a pair of links that allow users to expand and collapse the tree. The links are positioned above the tree, and are labeled Expand All and Collapse All.
If this property is not defined, or is set to any other value, the links will not be shown. By default, the links are not displayed.
For more information about the Dynamic Tree Navigation UI templates, see the Oracle Configurator Developer User's Guide.
Syntax:
cz.runtime.treebehavior=[ShowLinks]
cz.runtime.treebehavior=ShowLinks
If your operating system is Macintosh version 9x running mrj 2.2x and you have implemented Secure Sockets Layer (SSL), this property sets the length of time that the Applet session "sleeps" between polls to the server, allowing the client session (Web browser) a free connection to the server. If your operating system is not the specific Macintosh version listed above or you have not implemented SSL, the OC Servlet ignores this property.
Background: In Macintosh version 9x, mrj 2.2x, legacy UIs (that is Java Applet and DHTML) and User Interfaces generated in Configurator Developer do not maintain separate connections when polling the server. This adversely affects the performance of the UI and may even cause it to fail.
See The Heartbeat Mechanism and Guided Selling for additional information.
The suggested range is 5,000 to 30,000 milliseconds. The default value is 15,000 milliseconds.
Note: Setting this property to a small value (such as 5,000) may affect runtime performance. Specifying a large value (such as 30,000) improves runtime performance, but increases the time required to return control to the OM Sales Order window when the Oracle Configurator session ends.
Syntax:
cz.uiserver.applet_client_poll_wait=milliseconds
cz.uiserver.applet_client_poll_wait=20000
This property controls the timeout for the UI Server’s checking of "heartbeat" events. (See The Heartbeat Mechanism and Guided Selling for a description of heartbeat events.) If the UI Server doesn’t receive any heartbeats from the Web browser after this time value, then the UI Server will end the configuration session and send a "terminate" message back to the Applet client. The default value for this property is 30,000 milliseconds.
Set this property to a value that is 3 times the value of cz.uiserver.heartbeat_interval and cz.uiserver.poll_timeout_applet (these properties should have the same value). For example, if each of these properties are set to 20000, then set cz.uiserver.check_heartbeat_timeout to 60000.
If loading a large configuration model, set this property to a value that is approximately how long it takes to load the Model. For example, if the configuration model takes 60 seconds to load, set this property to approximately 60000 milliseconds.
Syntax:
cz.uiserver.check_heartbeat_timeout=milliseconds
cz.uiserver.check_heartbeat_timeout=60000
When a Forms-based Oracle Applications product launches a User Interface that was generated in Configurator Developer, an Oracle Configurator Applet client runs but is not visible to the end user. The Applet client cannot determine the status of the end user’s client Web browser, so it does not know if the browser has experienced an error or the end user closed it prematurely.
To address this problem, Oracle Configurator uses a "heartbeat" mechanism, in which:
The client session (the Web browser) sends heartbeat events to a session that is running in the UI Server. Continued heartbeats indicate that the client is still "alive". A cessation of heartbeats indicate that the client has terminated. This cessation is detected by the session that is running on the UI Server.
The Applet client polls an Applet session running in the UI Server to check whether the UI Server has received a termination message from the client session.
If the frequency of heartbeats received by the client session are less than the amount specified by cz.uiserver.heartbeat_interval, then the UI Server sends the termination message to the Applet session, which is being polled by the Applet client running under Order Management.
Heartbeat Mechanism Properties lists the servlet properties that control the operation of the heartbeat mechanism.
| Property | Page Reference |
|---|---|
cz.uiserver.check_heartbeat_timeout |
cz.uiserver.check_heartbeat_timeout |
cz.uiserver.heartbeat_interval |
cz.uiserver.heartbeat_interval |
cz.uiserver.poll_timeout_applet |
cz.uiserver.poll_timeout_applet |
The value for all of these heartbeat parameters must be greater than zero, and must be less than the timeout value for the Web listener.
This property specifies the amount of time that the server session waits before contacting the database to indicate that the configuration session is still active (this is known as "polling" the database). This system property is used only by HTML User Interfaces (in other words, UIs created in Oracle Configurator Developer release 11.5.10 or later).
You may want to increase the default value if your environment has minimal system resources (for example, few database connections), since doing so will cause the server to contact the database less frequently, thereby reducing the possibility that the configuration session will expire prematurely.
The default value is 5000 milliseconds (5 seconds).
Syntax:
cz.uiserver.database_poll_timeout=value
cz.uiserver.database_poll_timeout=15000
This property controls the frequency at which the heartbeat is sent from the client browser to the UI Server. The default value is 10000 milliseconds. The suggested range for this property is between 10,000 and 60,000. This property and cz.uiserver.poll_timeout_applet should be set to the same value.
See The Heartbeat Mechanism and Guided Selling for background.
Syntax:
cz.uiserver.heartbeat_interval=milliseconds
cz.uiserver.heartbeat_interval=10000
This property sets the time after which the UI Server’s Applet session tells the Applet client to poll back, to check whether the UI Server session was terminated. The default value is 10,000 milliseconds. The suggested range for this property is between 10,000 and 60,000. This property and cz.uiserver.heartbeat_interval should be set to the same value.
See The Heartbeat Mechanism and Guided Selling for background.
Syntax:
cz.uiserver.poll_timeout_applet=milliseconds
cz.uiserver.poll_timeout_applet=10000
This property controls whether the UI Server running inside the OC Servlet shares configuration model data that is cached in the DIO between configuration sessions.
The default value of this property is true, which enables sharing of cached model data. Sharing cached model data improves the loading performance of sessions after the first one for a given configuration model, but requires that the OC Servlet be restarted for the runtime Oracle Configurator to reflect recent changes to generated logic. However, configuration sessions started with the Test Model button in Oracle Configurator Developer always ignore the cached model data and fetch the latest data from the database, thus reflecting changes to generated logic.
The default setting provides a convenience for Model developers while providing efficiency for runtime users. As a general rule, you should not change the default value (true).
Setting this property to false disables sharing of the cached Model for all configuration sessions on the same OC Servlet. In other words, a value of false counteracts the performance enhancement derived by preloading and caching configuration model data. For more information, see cz.uiservlet.pre_load_filename.
Syntax:
cz.uiservlet.dio_share=[true|false]
cz.uiservlet.dio_share=true
For information about decaching configuration model data, see the Oracle Configurator Performance Guide.
Define this property in cz_init.txt if you want to improve performance when the OC Servlet starts up by caching configuration model data. This property specifies an absolute path to a file containing an initialization message for the OC Servlet, and this file identifies the configuration model(s) to preload.
This property is not defined by default.
Syntax:
cz.uiservlet.pre_load_filename=absolute_path_to_initialization_file
cz.uiservlet.pre_load_filename=/home/apache/init_msg.txt
The contents of your initialization file must be a valid Oracle Configurator initialization message, the construction of which is described in detail in the Oracle Configurator Implementation Guide. Make sure that the initialization message appears on a single line with no line breaks in the message text. There can be multiple initialization messages in the file (that is, one message for each Model you want to preload), but each initialization message must be on its own line.
The following is an example of an initialization message (each parameter appears on a separate line here only to improve readability):
<initialize> <param name="database_id">dbc_filename</param> <param name="gwyuid">applsyspub/pub</param> <param name="user">apps</param> <param name="pwd">apps</param> <param name="ui_type">JRAD</param> <param name="context_org_id">5</param> <param name="model_id">1234</param> <param name="calling_application_id">671</param> </initialize>
To preload a servlet with Apache, its class name must also be specified on startup. As of Release 12, all servlets that need to be loaded on startup are specified in the file orion-web.xml. The required preload servlet classes for Oracle Configurator are predefined there by default.
To verify that configuration model data is being preloaded:
Enable logging.
Clear the Oracle Configurator log files.
Stop and then restart the server.
Launch Oracle Configurator.
Check the FND log files and verify that configuration model data is being preloaded.
Note: Preloading configuration models improves runtime performance by caching data when starting the OC Servlet. However, this enhancement is counteracted if you disable caching either by setting cz.uiservlet.dio_share to false or including the parameter share_dio=false in your initialization message.
For information about decaching configuration model data, see the Oracle Configurator Performance Guide.
Use this property to determine whether the servlet responds to the test=version message entered in a Web browser. The default value is true.
For details, see:
Syntax:
cz.uiservlet.versionFuncsAvail=[true|false]
cz.uiservlet.versionFuncsAvail=true
This property controls the appearance of options at runtime that have been set logically false (LFALSE) by Oracle Configurator. By default, this parameter is set to false, and all logically false options appear as if they have never been selected (that is, as if their logic state were actually UNKNOWN). Set this parameter to true if you want Oracle Configurator to indicate logically false options using an icon. The default status indicator icons are described in the Oracle Configurator Developer User's Guide.
Note: For best runtime performance, the default value (false) is recommended if you have large, complex Models with many options. Smaller, less complex models with fewer options usually perform better with this property set to true.
Syntax:
cz.uiserver.lfalse_is_not_available=[true|false]
cz.uiserver.lfalse_is_not_available=false
This property controls how UI pages are loaded when an end user begins a configuration session. Choose a value for this property based on how many child (referenced) Models are required in the configuration, as well as application page sizes and usage.
For example:
Accept the default value of 0 (zero) if you want to load only the top level nodes in the Model (for example, the root Model node and all of its child Component nodes).
This value is recommended if, for example, the Model contains many child Models that are required in the configuration (that is, the Instances Minimum value for multiple referenced Models is set to 1 or more in Configurator Developer).
Set this property to 1 if you want to load all of the top level nodes in the Model, and all required child Models.
Set this property to 2 if you want to load all of the top level nodes in the Model, all required child Models, and all of the UI pages for these nodes.
Set this property to 3 if you want to load all nodes, UI pages, and Model data.
If you set this property to a low value (such as 0 or 1), the initialization of the configuration session is faster, but the first visit to any page is potentially slower (this is because the OC Servlet loads a UI page only when the end user navigates to it). However, after a page is viewed once, it loads quickly whenever the end user returns to the page. This behavior may be more desirable if end users are likely to navigate to a specific page multiple times during a configuration session.
If you set this property to a higher value (such as 2 or 3), the initialization of the configuration session is slower, but the first visit to any UI page is potentially faster. This is because all of the UI pages are loaded when the configuration session is initialized. The pages also load quickly when an end user navigates to the page. Subsequent visits to a page are also fast. If an end user is likely to visit each page only once, and a fast initial load is not critically important, it may be appropriate to set this property to either 2 or 3.
Syntax:
cz.uiserver.lazyload=[0|1|2|3]
cz.uiserver.lazyload=0
Note: Consider the behavior of this property with regard to the behavior provided by cz.uiservlet.dio_share and cz.uiservlet.pre_load_filename.