Standalone WLS ADF deployment – Be careful which URL you use

We hit a problem with JDeveloper 11g ADF applications deployed to WebLogic Server 10.3 that's worth sharing.

Under JDev 10.1.3 we could access our remotely deployed ADF applications on OAS through a URL similar to:

http://host:port/context-root/faces/page.jspx

...this is in fact how JDev 10.1.3 ran apps on the integrated OAS/OC4J container.

However on attempting to run a new ADF 11g application on a standalone WebLogic Server, if we used a similar URL as above, then attempted to navigate to any other page via a JSF navigation rule and command control, the original page would show, no navigation would occur, no errors in the logs would be reported.

It's very hard to debug without an error at least somewhere. This left us scratching our heads, and a SR to Oracle Support followed.

Turns out under JDev 11g you cannot include the page file extension in the URL any longer when accessing an ADF application (regardless if it's on an integrated or standalone WLS). You must use:

http://host:port/context-root/faces/page

If I'd carefully looked at how JDev 11g deploys and runs the ADF applications on the integrated WLS I would have realised this because that's what appears in the log window, but I hadn't noticed the subtle change in the URL. It's possibly something that wouldn't catch somebody new to JDev/ADF, but more likely to catch us old hands out with prior 10.1.3 knowledge. You're more likely to hit this problem on a standalone WLS as when running applications within JDev it forms the URL for you for the integrated WLS, but on the standalone WLS you need to work it out for yourself.

Note that the JDev 11g Fusion Guide under section 32.9 notes the URL syntax as:

"http://<host>:port/<context root>/faces/<page>"

....but what it doesn't bother to note is <page> should be the page name without the file extension.

Thanks to the Oracle Support staff and the Oracle JDev development team behind the scenes who discovered my error.

JAX-WS @SchemaValidation: suppressing the SOAP fault detail Java stack trace on WLS

This post gives a solution that has been given in numerous other locations and the solution is even fairly obvious, but I needed a location to record it, so here it is.

Recently Gerard Davison at Oracle UK detailed the JAX-WS @SchemaValidation tag.

The default behaviour of Oracle's WebLogic Server 10.3 on receiving a SOAP payload that doesn't conform to the WSDL/XSDs in a JAX-WS endpoint method with the @SchemaValidation annotation is to throw a SOAP fault.

Under SOAP 1.1 the SOAP fault payload returned to the client includes a faultcode, faultstring, faultactor (optional) and detail (optional) component.

Under SOAP 1.2 the SOAP fault includes a Code, Reason, Node (optional), Role (optional) and Detail (optional) component.

Assuming SOAP v1.2, given the @SchemaValidation annotation and invalid SOAP payload, we may see the following SOAP result from our JAX-WS web service:


(Click the picture to expand it)

As you can see the SOAP 1.2 fault includes the Code, Reason and Detail components. As can also been seen the Detail component includes the full Java stack trace(I've snipped the stack trace for brevity).

It may be undesirable to return the complete Java stack trace in the SOAP fault and you may wish to turn this off. If you look closely at the error message the answer in how to do this is revealed. Effectively we need to configure the WLS server to include the following option on startup:

-Dcom.sun.xml.ws.fault.SOAPFaultBuilder.disableCaptureStackTrace=false

For WLS 10.3 this entry should be included in your startWebLogic.cmd file.

For a standalone WLS this file is found under:

<WLS_HOME>/user_projects/domains/<YOUR_DOMAIN>/bin

For the integrated WLS within JDeveloper 11g it's found under:

<JDEV_HOME>\system\system11.1.1.0.31.51.88\DefaultDomain\bin

Locate the following entry in the startWebLogic.cmd file:

set JAVA_OPTIONS=%SAVE_JAVA_OPTIONS%

..and change it to:

set JAVA_OPTIONS=-Dcom.sun.xml.ws.fault.SOAPFaultBuilder.disableCaptureStackTrace=false %SAVE_JAVA_OPTIONS%

On restarting the WLS server, and reinvoking the web service with an invalid SOAP payload, the SOAP fault will now look like:

ADF Faces RC – displaying user help

ADF Faces RC under JDeveloper 11g supports different mechanisms for displaying runtime help to users linked with an on-screen component. I had a chance to play with this today and (once again) thought I'd document my findings here as I found the Oracle documentation somewhat confusing (or maybe it's just me).

The Oracle documentation that describes how to get this working can be found in section 16.5 Displaying Help for Components of the Oracle JDev 11g Fusion Web Developer's Guide. It's worth noting you should read the entire section 16 Displaying Tips, Messages, and Help as there are a few assumptions in section 16.5 that you've read the earlier parts.

Help types

A subset of the ADF Faces RC components include support for displaying help, through the inclusion of the helpTopicId attribute on the component's tag.

ADF Faces RC provides for 3 different help types for the components that support help:

· Definition – places a question mark icon near the component which when the user hovers the mouse over the component, help text is displayed. The exact location of the question mark icon relative to the component depends on the type of component. Section 16.5 of the Oracle documentation dictates this.


· Instructions – typically displays a note window (that looks like a speech bubble) over the component when the user clicks in the field, where the note window shows the help text. For panel headers and query object components the help text appears inline with the component rather than as a note window.


· External URL – displays a similar question mark icon to the "Definition" help type above, except when the user clicks on the icon (rather than hovers over the icon with the mouse pointer), launches a separate browser window opening an external URL.


Providing Definition or Instructions based help

The setup for providing either Definition or Instructions based help is as follows:

1. Within your ViewController project create a Java class that extends oracle.adf.view.rich.help.ResourceBundleHelpProvider. In the following example I've created the class MyHelpProvider under the package view.help


2. We next need to create the file adf-settings.xml to configure the custom ResoureBundleHelpProvider. This file is meant to go under the ADF META-INF node in the Application Resources options within the Application Navigator:


Unfortunately I can't find an easy way to create this file under this node. The easiest way seems to be to locate the <app_dir>\.adf\META-INF directory under Windows explorer or similar, and manually create the XML file in there. Once done return to JDeveloper and restart it. On JDeveloper reopening you should see the file added as per above.

(The Oracle documentation is incorrect in instructing you to create the adf-settings.xml file under the ViewController's META-INF directory. It should be the <app_dir>\.adf\META-INF directory as specified above).

The contents of the adf-settings.xml file are as follows:


Note the help-provider-class mapping that points to the package.name of our Java class, namely view.help.MyHelpProvider.

The <property>'s tags define the resource properties file that contain our help text to display for each help-enabled component. In this example I've created a file helpFile.properties (the extension is dropped in the adf-settings.xml file) in the view.resources package. We'll look at this next. The property-name as far as I can tell can be anything you want and has no effect elsewher. I'm not entirely sure why it's included; presumably it's possible to have multiple resource files?

3. The contents of helpFile.properties file are as follows:


As you can see in the properties file we have key-value pairs, specifically the help ID and the associated text. Of special note, see that each key is either completed with the word DEFINITION or INSTRUCTIONS. It is this that determines the help type for the component. (Somewhat confusingly INSTRUCTIONS is a plural, and DEFINTION is singular)

4. Finally we need to bind the help key from the properties file to the actual ADF Faces RC component on a web page:


Note for the 2 input text controls above the helpTopicId parameter. Note how these map back to what I had in the properties file minus the DEFINITION or INSTRUCTIONS suffix. Those suffixes are only included in the properties file. As such the properties file determines the behaviour of the help and components in this case.

Providing External URL based help

To configure the external URL help type we return to our custom MyHelpProvider class and override the super getExternalUrl method as follows:


In the 2nd if statement we've added the ability to capture the helpTopicId and return an alternative URL which will be used for the new browser window. As you add more components that require help, you simply add more if statements with associated URLs.

Further functionality

If you wish to configure multiple helper classes the adf-settings.xml file allows you to include a filter via the prefix attribute on the help-provider tag as follows:


In this case only helpTopicIds with the prefix MYHELP_ will be passed to the MyHelpProvider class.

In addition the Oracle documentation specifies how to use a managed bean help file, which is relatively simple, or XLIFF based help files. I don't have any experience with XLIFF files so I'll leave readers to read the Oracle documentation.

Credit

Thanks to user518058 and Frank Nimphius on the JDev OTN Forums for posting about a couple of the implementation issues with the user-help.