This appendix includes the following sections:
Getting Started with Troubleshooting the View Layer of an ADF Application
Using My Oracle Support for Additional Troubleshooting Information
In addition to this chapter, review Error Messages for information about the error messages you may encounter.
This section provides guidelines and a process for using the information in this appendix. Using the following guidelines and process will focus and minimize the time you spend resolving problems.
Guidelines
When using the information in this chapter, please keep the following best practices in mind:
After performing any of the solution procedures in this chapter, immediately retry the failed task that led you to this troubleshooting information. If the task still fails when you retry it, perform a different solution procedure in this chapter and then try the failed task again. Repeat this process until you resolve the problem.
Make notes about the solution procedures you perform, symptoms you see, and data you collect while troubleshooting. If you cannot resolve the problem using the information in this chapter and you must log a service request, the notes you take will expedite the process of solving the problem.
Process
Follow the process outlined in Table G-1 when using the information in this chapter. If the information in a particular section does not resolve your problem, proceed to the next step in this process.
Table G-1 Process for Using the Information in this Chapter
| Step | Section to Use | Purpose |
|---|---|---|
1 |
Getting Started with Troubleshooting the View Layer of an ADF Application |
Get started troubleshooting the view layer of an ADF application. The procedures in this section quickly address a wide variety of problems. |
2 |
Perform problem-specific troubleshooting procedures for the view layer of an ADF application. This section describes:
|
|
3 |
Using My Oracle Support for Additional Troubleshooting Information |
Use My Oracle Support to get additional troubleshooting information. The My Oracle Support web site provides access to several useful troubleshooting resources, including links to Knowledge Base articles, Community Forums, and Discussion pages. |
4 |
Using My Oracle Support for Additional Troubleshooting Information |
Log a service request if the information in this chapter and My Oracle Support does not resolve your problem. You can log a service request using My Oracle Support at |
Oracle ADF has builtin error messages that enable you to determine which layer of your application may be causing a problem. Error messages are the starting point for troubleshooting. You can look up error messages in Error Messages, and you may research a particular error message on the web. Error messages that originate from your ADF Business Components model layer will have a JBO prefix, whereas all other ADF layer components, including the ADF Face view layer, will appear as a Java error message with an Oracle package.
Once you are able to identify the layer, you may run diagnostic tools. You may also view log files for recorded errors. You can search the technical forums on Oracle Technology Network for discussions related to an error message. Each of the component layers for Oracle ADF has its own dedicated forum. You can access the forum home page for JDeveloper and Oracle ADF under the Development Tools list on Oracle Technology Network at https://forums.oracle.com/forums/main.jspa?categoryID=84.
Before you begin troubleshooting, you should configure the ADF application to make finding and detecting errors easier. Table G-2 summarizes the settings that you can follow to configure the view layer of an ADF application for troubleshooting.
Table G-2 Configuration Options for Optimizing ADF Faces Troubleshooting
| Configuration Recommendation | Description |
|---|---|
Enable debug output. |
To enable debug output, set the following in the <adf-faces-config xmlns=
"http://xmlns.oracle.com/adf/view/faces/config">
<debug-output>true</debug-output>
<skin-family>oracle</skin-family>
</adf-faces-config>
Improves the readability of HTML markup in the web browser:
|
Disable content compression. |
To disable content compression, set the following in the <context-param>
<param-name>
org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION
</param-name>
<param-value>true</param-value>
</context-param>
Improves readability by forcing the use of original uncompressed styles. Unless content compression is disabled, CSS style names and styles will appear compressed and may be more difficult to read. For more information about how disabling content compression affects readability, see the "Applying the Finished ADF Skin to Your Web Application" in Developing ADF Skins. |
Disable JavaScript compression. |
To disable JavaScript compression, set the following in the <context-param>
<param-name>
org.apache.myfaces.trinidad.DEBUG_JAVA_SCRIPT
</param-name>
<param-value>true</param-value>
</context-param>
Allows normally obfuscated JavaScript to appear uncompressed as the source. |
Enable client side asserts. |
To enable client side asserts, set the following in the <context-param>
<param-name>
oracle.adf.view.rich.ASSERT_ENABLED
</param-name>
<param-value>true</param-value>
</context-param>
Allows warnings of unexpected conditions to be output to the browser console. |
Enable client side logging. |
To enable client side logging, set the following in the <context-param>
<param-name>
oracle.adf.view.rich.ASSERT_ENABLED
</param-name>
<param-value>true</param-value>
</context-param>
Allows log messages to be output to the browser console. Unless client side logging is enabled, log messages will not be reported in the client. |
Enable more detailed server side logging. |
To enable more detailed server side logging, shut down the application server and then enter the following setting in the
or Use the WLST command:
or In Oracle Enterprise Manager Fusion Middleware Control, use the Configuration page to set Allows more detailed log messages to be output to the browser console. Unless server side logging is configured with a log level of CONFIG or higher, useful diagnostic messages may go unreported. Allowed log level settings are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL. Oracle recommends CONFIG level or higher; the default is SEVERE. |
Disable HTTP cache headers. |
To disable HTTP cache headers, set the following in the <context-param>
<param-name>
org.apache.myfaces.trinidad.resource.DEBUG
</param-name>
<param-value>true</param-value>
</context-param>
Forces reloading of patched resources. Unless HTTP cache headers are disabled, the browser will cache resources to ensure fast access to resources. After changing the setting, clear the browser cache to force it to reload resources. |
This section describes best practices for using the ADF Faces test automation framework.
You can enable test automation by setting the oracle.adf.view.rich.automation.ENABLED parameter in the application’s web.xml file. This parameter notifies ADF Faces that test automation is being used and turns on external component id attributes. Note that this parameter only enables the infrastructure for test automation; it does not initiate testing itself, which requires a tool such as the open source Selenium IDE.
Tests that you write that rely on the internal component id are always guaranteed to have a value. The disadvantage is that the internal component id values may change between ADF Faces releases to support framework enhancements. Therefore, the tests that you write must not rely on the component id. To build more robust automated tests, rely on absolute locator id attributes and check that these attributes have a value.
The oracle.adf.view.rich.automation.ENABLEDparameter accepts the following values:
OFF: Indicates the test automation is disabled. This is the appropriate setting for a production environment.
FULL: Notifies ADF Faces that test automation is being used and turns on external component id attributes. Use this setting with caution, and only in a protected testing environment.
Note:
When the test automation context parameter is set to FULL, the oracle.adf.view.rich.security.FRAME_BUSTING context parameter behaves as though it were set to never. The security consequence of disabling framebusting is that pages of your application will become vulnerable to clickjacking from malicious websites. For this reason, restrict the use of the test automation to development or staging environments and never enable test automation in a production environment. For more information, see Framebusting.
SAFE: Notifies ADF Faces that test automation is being used and turns on external component id attributes. This setting is the same as FULL, with the following differences in how it treats secure information.
It does not disable framebusting. That is, the oracle.adf.view.rich.security.FRAME_BUSTING context parameter does not behave as though it were set to never.
JSESSIONID will be encrypted.
Version number information, described in Version Number Information will not be shown.
Logging to the server is disabled.
Performance Tip
When you enable test automation, a client component is created for every component on the page. Therefore, set this parameter to OFF in a production environment.
The oracle.adf.view.rich.automation.ENABLED context parameter that you define in the application’s web.xml file is EL bindable. For example, you might want the application to programmatically set test automation mode for a single test user, for all users of the application, or for a particular user group. The following example shows how to use an EL expression to set test automation mode for a test user.
<context-param>
<param-name>oracle.adf.view.rich.automation.ENABLED</param-name>
<param-value>
#{securityContext.userName == 'testuser' ? 'SAFE' : 'OFF'}
</param-value>
</context-param>
Enabling test automation also enables assertions in the running application. If your application exhibits unexpected component behavior and you begin to see new assertion failed errors, you will need to examine the implementation details of your application components. For example, it is not uncommon to discover issues related to popup dialogs, such as user actions that are no longer responded to.
Here are known coding errors that will produce assertion failed errors only after test automation is enabled:
Your component references an ADF iterator binding that no longer exists in the page definition file. When assertions are not enabled, this error is silent and the component referencing the missing iterator simply does not render.
Your component is a partial trigger component that is defined not to render (has the attribute setting rendered="false"). For example, this use of the rendered attribute causes an assertion failed error:
<af:button id="hiddenBtn" rendered="false" text="Test"/> <af:table var="row" id="t1" partialTriggers="::hiddenBtn">
The workaround for this error is to use the attribute setting visible="false" and not rendered="false".
Your components were formed with a nesting hierarchy that prevents events from reaching the proper component handlers. For example, this nesting is incorrect:
<af:commandLink
<af:showPopupBehavior
<af:image
<af:clientListener
and should be rewritten as:
<af:commandLink
<af:image
<af:showPopupBehavior
<af:clientListener
Note:
System administrators can enable test automation at the level of standalone Oracle WebLogic Server by starting the server with the command line flag-Doracle.adf.view.rich.automation.ENABLED= automation-mode. Running your application in an application server instance with test automation enabled overrides the web.xml file context parameter setting of the deployed application.During test automation, you can simulate mouse events that you can use to test mouse events. To simulate mouse events, you need to first add a test harness that you can use to set up the environment for a test simulation mouse click before the test-engine mouse-click simulation occurs. The test harness calls the following function.
AdfPage.prototype.simulateMouse = function(locator, mouseEvent)Before you call the function, you need to update your test engine to call the API.
The sample API is given below:
/**
* Simulate mouse type event using locator.
* @param {String} locator locator string in the format <scopedId>#<subid>
* @param {Object} javascript object containing a sparse set of mouse event name value pairs that will
* be used to create a mouse event. Defaults will be used for any missing fields.
* The defaults are as follows:
* type: “click”
* canBubble: true
* cancelable:true
* view: the current window
* detail: 1
* screenX: 0
* screenY: 0
* clientX: the client location of the X coordinate of the center of the DOM
* element returned by the locator
* clientY: the client location of the Y coordinate of the center of the DOM
* element returned by the locator
* ctrlKey: false
* altKey: false
* shiftKey: false
* metaKey: false
* button: 0
* relatedTarget: null
* If no mouseEvent is provided, a mouseEvent with all of the defaults will be used.
* @abstract
*/
After you prepare the environment for the mouse event, this method defers to a test engine class instance that you will define. By doing so, you are pointing the test engine class instance back to your normal test engine to test the mouse event. That class continues to do the normal test procedure for a mouse event that you did before the start up of the mouse event.
Now create a test engine class to be an instance of the new abstract API class. Your test engine implementation needs to override this method:
AdfDhtmlTestEngine.prototype.simulateDomMouse = function(domElement, mouseEvent)Following is an example of an instance of AdfDhtmlTestEngine, where you need to add the call to the test framework mouse event code that you just created.
/**
* Used for testing a custom implementation of AdfDhtmlTestEngine.
*/
function CustomTestEngine()
{
}
// make CustomTestEngine a subclass of AdfDhtmlTestEngine
AdfObject.createSubclass(CustomTestEngine, AdfDhtmlTestEngine);
/**
* Simulate mouse event on a dom element.
* @param {String} domElement the domElement receiving the mouse event
* @param {Object} javascript object containing a sparse set of mouse event name value pairs.
* @Override
*/
CustomTestEngine.prototype.simulateDomMouse = function(domElement, mouseEvent)
{
// Here, call your custom test framework to actually do the mouse event, now that the environment is all ready for this event.
}
Finally, ADF should be aware of the new test engine class. You can specify this using the web.xml parameter. This is important for the functioning of test setup code, like AdfPage.PAGE.simulateMouse(), that needs to invoke the testing framework function after doing any necessary setup work.
<context-param>
<description>
This parameter specifies the automation test engine that is being used.
</description>
param-name>oracle.adf.view.automation.TEST_ENGINE</param-name>
<param-value>CustomTestEngine</param-value>
This section describes common problems and solutions.
The ADF application has a default skin that displays a simple or minimal look and feel. The background of the default skin will appear white.
Cause
The skin JAR files did not get deployed correctly to all applications.
Solution
To resolve this problem:
The skin application must be packaged as an ADF Library JAR file that includes the image files.
Cause
The skin JAR files were not packaged correctly.
Solution
To resolve this problem:
The ADF skin that you created defines style properties that do not render in the browser as expected.
Cause
Not all ADF skin selectors may be customized and customizing non-valid selectors may result in unexpected or inconsistent behavior for your application.
Solution
To resolve this problem:
web.xml file. Not all changes that you make to an ADF skin appear immediately if you set the CHECK_FILE_MODIFICATION parameter to true. You must restart the web application to view changes that you make to icon and ADF skin properties.Various ADF Data Visualization (DVT) components rely on Flash to display correctly and unless Flash is supported by the platform and browser, your application may not display visual aspects of the DVT components.
Cause
Not all platforms and browsers support Flash. This will force the application to downgrade to the best available fallback. If the platform is not supported, the application displays according to the flash-player-usage setting in the adf-config.xml file.
Solution
To resolve this problem, reinstall the latest Flash version available for your browser.
When you design an application to run in a clustered environment, you must ensure that all managed beans with a life span longer than one request are serializable.
Cause
When the Fusion web application runs in a clustered environment, a portion of the application's state is serialized and copied to another server or a data store at the end of each request so that the state is available to other servers in the cluster. Specifically, beans stored in session scope, page flow scope, and view scope must be serializable (that is, they implement the java.io.Serializable interface).
Solution
To resolve this problem:
You run the application in Microsoft Windows Internet Explorer and verify a problem but when you run the application in Mozilla Firefox, the problem does not reproduce. These problems are often visual in nature, such as unintended extra space separating areas within a web page.
Cause
Settings between browsers vary and can lead to differences in the visual appearance of your application.
Solution
To resolve this problem:
@agent at-rule in the ADF skin file of the application to define an appearance specific to the desired browser. For more information, see the "Working with At-Rules" chapter of Developing ADF Skins.The application pages may display areas that appear empty where content is expected.
Cause
The cause depends on the application design. For example, authorization that you enforce in the application may be unintentionally preventing the application from displaying content. Or, when portlets are used, the portlet server may be down.
Solution
To resolve this problem:
The application returns a runtime exception in a place that was not expected and is not handled.
Cause
ADF Faces has received an unhandled exception in some phase of the lifecycle and will abort the request handling.
Solution
To resolve this problem:
The application does not navigate to the expected page and displays an HTTP 404 file not found error or an HTTP 500 internal server error.
Cause
The cause may be traced to the application server.
Solution
To resolve this problem:
The application fails to navigate to and open an expected target web page.
Cause
The cause may depend on the application design or the cause may be traced to the application server.
Solution
To resolve this problem:
You can use My Oracle Support (formerly MetaLink) to help resolve Oracle Fusion Middleware problems. My Oracle Support contains several useful troubleshooting resources, such as:
Knowledge base articles
Community forums and discussions
Patches and upgrades
Certification information
Note:
You can also use My Oracle Support to log a service request.
You can access My Oracle Support at https://support.oracle.com.