Red Heap

ADF Session Replication on a Cluster for High Availability

2015-10-09T13:31:00.003+02:00

Running an ADF application on a weblogic cluster is fairly simple. Just deploy the application to the cluster and your done. This gives you scalability as the load is distributed over multiple managed servers. However, it does not give you protection against machine failure out of the box. For that to work, you need to make sure all state in your ADF application is replicated across multiple nodes in the cluster. This post will explain the things you have to think about when setting up this session replication.

Most of this information is based on Configuring High Availability for Fusion Web Applications chapter of the Fusion Web Applications Developer's Guide but we've added some undocumented features and best practices based on our experience.

View

First thing you need to do is tell weblogic to replicate a http session to other nodes in the cluster. This is done by setting persistent-store-type to replicated_if_clustered in your weblogic.xml file:
```
<weblogic-web-app>
  <session-descriptor>
    <persistent-store-type>
      replicated_if_clustered
    </persistent-store-type>
  </session-descriptor>
</weblogic-web-app>
```
During development on my local workstation I like to set the session-description slightly differently:
```
<weblogic-web-app>
  <session-descriptor>
    <persistent-store-type>file</persistent-store-type>
    <persistent-store-dir>c:/temp/</persistent-store-type>
    <cache-size>0</cache-size>
  </session-descriptor>
</weblogic-web-app>
```
This tells weblogic to write the http session request to file after each request. Since the cache-size is set to 0 it will not keep any session in memory. This means each subsequent request from the same session has to restore the session from file first. Since this (de)serializes the http session on each request it behaves the same as a session failover on a cluster after each request. This is a great way to test if you application is really cluster-safe and if none of the managed beans or other objects will loose their state.
In your web.xml you have to set CHECK_FILE_MODIFICATION to false:
```
<web-app>
  ...
  <context-param>
    <param-name>
      org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION
    </param-name>
    <param-value>false</param-value>
  </context-param>
<web-app>
```
Having this on could lead to errors when a failover occurs. It is best practice to disable this for a production system anyhow. If you want this on during local development you should look into deployment plans to override such a setting per environment.

Controller

Next thing you have to do is to tell the ADF Controller you're running in a replicated cluster so all managed beans will be replicated. You do this by setting adf-scope-ha-support to true in your adf-config.xml:
```
<adf-controller-config xmlns="http://xmlns.example.com/adf/controller/config">
    <adf-scope-ha-support>true</adf-scope-ha-support>
</adf-controller-config>
```
If you're application is also using database based MDS and that database is also a (RAC) cluster you need to tell the ADF Controller to retry any failed database connection in case a database failover occurs. You do this in the persistence-config section of adf-config.xml where you already configured MDS:
```
<persistence-config>
  <metadata-namespaces>...
  <metadata-store-usages>...
  <external-change-detection enabled="false" />
  <read-only-mode enabled="true"/>
  <retry-connection enabled="true"/>
</persistence-config>
```
Managed beans that live longer than a single request need to implement Serializable to enable them to transfer "over the wire" to other nodes in the cluster. This means this is not needed for request-scope and backingbean-scope beans as the do not live longer than a single request and will not be replicated to other nodes in the cluster. You do need to do this for every viewScope, pageFlowScope and sessionScope bean.
According to the documentation you need to let the ADF Controller know each time a managed bean changes so it knows to replicate that bean (or that scope) to the other node in the cluster. You have to do this by invoking ControllerContext.markScopeDirty and giving it the viewScope or pageFlowScope that contains the changed bean. This sounds like a useful performance optimization that only the changed scopes are replicated across the cluster. However, if you inspect the source code it doesn't really matter which scope you pass to the markScopeDirty. It sets a global flag on the request that will replicate all ADF Controller scopes at the end of the request, not just the ones that you marked dirty. Obviously this might change in a future version so you're safest bet is to nicely invoke markScopeDirty whenever you change a bean. One other caveat is that ADF (at least version 12.1.3) internally always changes two internal values in a scope in every request. This means that ADF internally invokes markScopeDirty on each request which means all scopes are replicated on each request regardless what you do. We've filed bugs for this so this might also change in the future and you shouldn't rely on these bugs and assume that everything is replicated anyhow.
I typically create a number of base classes that I use as superclasses for all of my viewScope or pageFlowScope beans. Than all you need to do is invoke markDirty from the superclass in each setter or other method that alters the state of its bean:
```
public abstract class ManagedBean implements Serializable {
  public ManagedBean() {
    /* Workaround voor Oracle bug #18508781. When bean is
       instantiated by the scope itself on first usage it
       does not automatically mark the scope as dirty
       even though the documentation states it does */
     markDirty();
  }
  protected void markDirty() {
    ControllerContext.getInstance().markScopeDirty(getScope());
  }
  // use this in a setter to only mark dirty if a property really changes
  protected void markDirty(Object oldValue, Object newValue) {
    if (!((oldValue == null && newValue == null) ||
          (oldValue != null && newValue != null &&
           oldValue.equals(newValue)))) {
      markDirty();
    }
  }
  // should return the scope map the managed bean lives in
  protected abstract Map<String, Object> getScope();
}
```
```
public class ViewScopeBean extends ManagedBean {
  @Override
  protected Map<String, Object> getScope() {
    return ADFContext.getCurrent().getViewScope();
  }
}
```
```
public class PageFlowScopeBean extends ManagedBean {
  @Override
  protected Map<String, Object> getScope() {
    return ADFContext.getCurrent().getPageFlowScope();
  }
}
```

Model

Finally you also need to make sure the state (data) in your ADF data controls is replicated across the cluster. This is not handled by the normal state replication by the http session or the ADF controller. It is the responsibility of the data control itself.

ADF Business Components

For ADF Business Components you only have to change jbo.dofailover in the bc4j.xcfg configuration file. This is easiest done through the declarative editors in JDeveloper. Alternatively you could also set this as a system property on the command line to start your weblogic server: -Djbo.dofailover=true
This ensures that ADF business components writes it entire state to a XML document at the end of each request so that other nodes in the cluster can read the XML and continue the session. You can configure whether this state is saved to a shared filesystem that all nodes in the cluster can access or to a shared database. You do this by setting jbo.passivationstore to either file or database, where database is the default. When persisting to a database it is advised to setup a special JDBC datasource to be used for this using the jbo.server.internal_connection property. If you do not set one the normal datasource of your ADF BC application module will be used to save this state. Having a dedicated datasource for state saving allows you to store this in a different database schema or tune the datasource for this behaviour.
Also be sure to periodically clean up this persisted ADF business components state for situations where ADF BC failed to clean it up automatically. On a file system this is fairly straightforward and for database storage Oracle supplies a adfbc_purge_statesnapshots.sql script in your oracle_common/common/sql directory.
When using the database as a store for ADF Business Component state and the database is also a cluster or some other type of database that supports failover, be sure to use a GridLink data source for state passivation as GridLink data sources are capable of switching between nodes in a database cluster when a failover of the database node occurs.
The same applies for the normal data source used by ADF BC to get your business data. If it connects to a clustered database it should be using a GridLink data source to support failover.

Data Controls that are not ADF BC

When you are not using ADF Business Components, but another type of ADF Data Control like the bean data control or the XML Data Control things get a bit more complicated. As stated before the datacontrol is responsible for replicating its state across a cluster. The Oracle documentation even describes how a datacontrol should create and restore snapshots. Unfortunately this doesn't really work in real life, at least not in version 12.1.3 and earlier (this might be fixed in future versions). The reason behind this is that a data control can replicate its state using this method but your ADF Model is more than just the raw data. It is also the state of every iterator in your page that "knows" which row in a collection is the current row. These iterators are not implemented by the data controls themselves but are supplied by the ADF framework. In fact, ADF uses an ADF Business Components wrapper around each non-BC data control to get these iterators, the so called InternalDCAM (internal data control application module).

This made us wonder if we can get this InternalDCAM to also replicate its state across a cluster. Since it is just an ADF Business Components Application Module we might have a chance. Since this is an internal application module there is no bc4j.xcfg configuration file that is normally used to configure ADF Business Components. But you can also use system properties to set the default for ADF BC configuration and these defaults should also be used for this internal application module. For this we added a number of system properties to the weblogic startup script:
-Djbo.dofailover=true -Djbo.passivationstore=file -Djbo.tmpdir=C:\work\wlssessions\ -Doracle.adf.model.bean.supports-passivation=true

Here's the reasoning behind these system properties:

jbo.dofailover=true enables the failover behaviour of ADF BC to write its state to XML after each request
we force jbo.passivationstore to file to write the session state to the file system and not to the database. Looking at oracle.adf.model.bean.DCBeanDataControl#findApplicationPool we discovered that writing to the database for a non-BC data control isn't supported anyhow which makes sense.
when writing the state to the file system we also set jbo.tmpdir to specify the directory where to save these files
finally, we set oracle.adf.model.bean.supports-passivation=true to enable ADF BC state passivation for non-BC data controls. This seems to be an experimental feature as there is no documentation about this parameter. This system property is not yet supported in 11.1.1.7 but it does exist in 12.1.3. This seems to be the missing link that enables state passivation for non-BC data controls

We found that for simple data controls this actually works. Having oracle.adf.model.bean.supports-passivation to enable the InternalDCAM to passivate its state in combination with having the data control itself save and restore its state makes this work on a failing cluster. This can easily be demonstrated with the tip at the beginning of this article to use a file based weblogic http session store without any in-memory caching. Unfortunately when having a data control with more than one level this will fail with an exception. For example, you could have a bean data control or XML Data Control with a findAllDepartments() method. That method returns a collection of departments. Each department has a collection of employees and each of those employees has a collection of accounts. In such a scenario with nested collections the failover of the iterators in the InternalDCAM will fail with missing parent key relations and throws ArrayIndexOutOfBoundsException. Perhaps this is the reason why oracle.adf.model.bean.supports-passivation is an undocumented feature. Let's hope Oracle will fully support this in a future release and it will also work with these more complex data controls. Until then, I guess you're out of luck for replicating your ADF application state in a cluster when using anything else than ADF Business Components.

Without the oracle.adf.model.bean.supports-passivation system property things get even worse. Since the InternalDCAM is not replicating its state without this property, it will reset all iterators to the first row even though the underlying data control might have replicated its state. This means a user might haven been working on row 5 in a collection. When a failover occurs the server-side iterator resets to row 1, but the user still sees row 5 in his browser. Any changes made by the user are submitted to the server and applied to row 1 without any error message or warning, leading to data corruption.

Networking

One final word about the networking architecture in front of your multi-node weblogic cluster. Since failover of a session to a different node in the cluster is relatively expensive we want to prevent this as much as possible and only move a session to a different node when the original node really fails. When the node stays up we should do our best to route each request for the same session to the same node. This is known as session stickiness. When you use an Oracle HTTP Server in front of your weblogic cluster this is handled automatically. Oracle HTTP server knows about the weblogic cluster architecture and will try to route each request. By the way, you might want to look in the mod_weblogic plugin parameters to fine tune the clustering behaviour and perhaps change some of the timeout settings.

When not using an Oracle HTTP server, but for example a hardware load balancer that directly routes to the weblogic cluster you need to ensure session stickiness yourself. You need to learn your load balancer about the structure of a weblogic session cookie. The format of a session cookie is sessionid!primary_server_id!secondary_server_id. The load balancer should be able to pick up the id of the primary server between the two exclamation points and use that id to route each request to that primary server. Only when that server fails it should use the id of the secondary server and route the request to that server as that server is the one that already has the replicated session in memory. If you would route to any other node in the cluster it would still work but it would add the delay of first getting the state from another node in the cluster. By the way, once a session has failed over to a different node the client will get a new session cookie with new server id's that can be used in routing subsequent requests.

ADF Faces 12c Components Demo and Test Automation

2015-02-17T23:20:00.000+01:00

You might have noticed that I am working on a series of blog articles on using Selenium to automate testing of Oracle ADF applications. This includes work on a little framework to make this easier and a set of sample JUnit tests against the public Oracle ADF Faces 12c Components Demo.

Getting the Faces 12c Component Demo running with test automation had some challenges. I wanted to write them down here in case somebody wants to try the same. It starts by downloading the Oracle ADF Faces Components Demo from OTN. This also includes instructions on how to run this application in your integrated weblogic server, but those instructions have some caveats and are for JDeveloper 11g, not version 12c. Please follow the instructions below as an alternative (I've marked the differences with the normal Oracle instructions and included screenshots at the end).

In the end this needed more work than I expected, so I also offer the fixed versions for download. If anyone from Oracle feels that this is a problem please contact me and I'll remove the download and you can follow the instructions below to create your own fixed version.

JDeveloper 12.1.3 project if you want to make changes to it
ADF 12.1.3 deployable WAR that you can just deploy on your integrated weblogic or any other weblogic server
JDeveloper 12.2.1 project if you want to make changes to it
ADF 12.2.1 deployable WAR that you can just deploy on your integrated weblogic or any other weblogic server

If you want to start from the downloads from Oracle and not use my fixed versions you would have to follow these steps:

Download the ADF Faces 12c Components Demo WAR file, but don't unpack it.
Start JDeveloper 12.1.3
Instructions updated from 11g: Choose File > New > From Gallery from the menu to create a new application. Select General > Applications in the tree and select Custom Application as application type and press Ok.
In the Create Application dialog type adffacesdemo as the application name, select a directory, leave the rest of the options alone and press Finish. This creates new application workspace and project.
Instructions updated from 11g: The default created project is not needed and you may delete the project. Right click it and select Delete Project. In the subsequent dialog choose to not only delete the project form the application but also delete it from disk.
Instructions updated from 11g: In the now empty workspace choose File > New > From Gallery from the JDeveloper menu. In the list of items select Projects and on the right hand side Project from WAR and press Ok. In the next dialog provide a name for the project, e.g. adffacesdemo, and keep the directory information. On the second panel, use the file browser to select the downloaded ADF Faces demo WAR file and finish the wizard.
Double click onto the project node to open the project properties and select the Run > Debug > Profile option. Press the Edit button and select the Tool Settings. In the Before Running section, uncheck the Make Project and Dependencies option and close the dialog pressing Ok.
Extra step added by me: Unfortunately some files are missing from the exploded WAR which will result in javascript errors and missing images.

Manually copy the META-INF directory from the src directory to the classes directory so you end up with classes/META-INF
Copy the src/oracle/adfdemo/view/js directory (and all of its subdirectories) to classes/oracle/adfdemo/view/js
Copy the two .properties files from src/oracle/adfdemo/view/resource to classes/oracle/adfdemo/view/resource
Copy the src/oracle/adfdemo/view/resource/fileExplorer directory and the .properties file it contains to classes/oracle/adfdemo/view/resource/fileExplorer
Copy all xml file from src/oracle/adfdemo/view/components/rich/tageditor to classes/oracle/adfdemo/view/components/rich/tageditor
Copy the xml and csv file from src/oracle/adfdemo/view/feature/rich/diagram/data to classes/oracle/adfdemo/view/feature/rich/diagram/data
Copy the src/oracle/adfdemo/view/feature/rich/dvt/data/election directory to classes/oracle/adfdemo/view/feature/rich/dvt/data/election
Copy all xml files from src/oracle/adfdemo/view/feature/rich/hv to classes/oracle/adfdemo/view/feature/rich/hv

Extra step added by me: To be able to use test automation on this ADF sample application, enable automation by opening public_html/WEB-INF/web.xml in JDeveloper and remove the comment markers around the existing oracle.adf.view.rich.automation.ENABLED context parameter.
For test automation to work you also have to copy JDEV_HOME/oracle_common/modules/oracle.adf.view_12.1.3/adf-richclient-automation-11.jar to the public_html/WEB-INF/lib directory of the project.
Extra step added by me: As a final step I prefer a simple URL when running the application. Double click the project to open the project properties. In the Java EE Application section change both the application name and context root to adf-richclient-demo
Finally, expand the project and select index.jspx under the Web Content node. Choose Run from the right mouse context menu.

Screenshots of these steps are below for your reference:

New Gallery dialog to create Custom Application

Create Custom Application dialog

Delete the default project

Delete the default project from disk

Create new project from WAR

Step 1 of importing WAR

Step 2 of importing WAR

Disable Make Project in Run Profile

Uncomment/activate existing oracle.adf.view.rich.automation.ENABLED

Add adf-richclient-automation-11.jar to public_html/WEB-INF/lib

Setting application name and context root in project properties

This post is part of a series on how to get Selenium to work with Oracle ADF.

ADFLogger 12.1.3 ignoring message parameters and resource keys

2015-02-15T16:05:00.001+01:00

In JDeveloper 12.1.3 Oracle made a switch to a new log formatter that has its shortcomings. It no longer knows how to replace resource bundle keys with their actual message and also fails to replace the {0}, {1}, ... placeholders with their actual values. You can end up with logging looking like this:

<oracle.adf.view> <RichRenderKit> <isAutomationEnabled> <AUTOMATION_ENABLED_WITHOUT_AUTOMATION_JAR> 
<oracle.adf.common> <ADFConfigFactory> <findOrCreateADFConfig> <Resource {0} not found on the classpath.>

Notice the AUTOMATION_ENABLED_WITHOUT_AUTOMATION_JAR that is not replaced with its actual message as well as the Resource {0}... message which should clearly mention the missing resource.

I don't know how this made it past basic QA, but this is now the default configuration for your Integrated WebLogic server in JDeveloper 12.1.3. Luckily there is an easy fix to revert to the 12.1.2 behaviour which is working fine.

Either start your integrated weblogic server in JDeveloper and click the actions button the log window and select Configure Oracle Diagnostics Logging or directly edit the JDEV_USER_HOME/system12.1.3.0.41.140521.1008/DefaultDomain/config/fmwconfig/servers/DefaultServer/logging.xml file.

Find the log_handler declaration at the beginning of the file for the console-handler. Change its formatter attribute from oracle.adf.share.logging.internal.diagnostic.ConsoleFormatter to oracle.core.ojdl.weblogic.ConsoleFormatter.

Restart your integrated weblogic server for the changes to take effect. You can now notice the resource keys and message parameters are correctly replaced:

<Feb 15, 2015 3:59:01 PM CET> <Warning> <oracle.adfinternal.view.faces.renderkit.rich.RichRenderKit> <ADF_FACES-60118> <Your application is running with the automation enabled in your web.xml file but the automation jar is unavailable. Please ensure that the jar is in the classpath.> 
<Feb 15, 2015 3:59:01 PM CET> <Warning> <oracle.adf.share.config.ADFConfigFactory> <BEA-000000> <Resource META-INF/adf-config.xml not found on the classpath.>

Waiting for Oracle ADF Partial Page Rendering in Selenium tests

2015-02-08T13:52:00.000+01:00

One of the main reasons people fail to use Selenium (or any other tool) for automated web testing with Oracle ADF is timing issues. The test automation tool typically wants to execute its actions as quickly as possible. This can be a challenge in dynamic applications that load parts of the pages on demand or in response to user interactions. This is what ADF typically does with partial page rendering requests.

For example, the test could "click" on a tab in a af:pannelTabbed component. The content of the new tab will be retrieved with a partial page rendering request. If the test automation tool would continue immediately after "clicking" the tab and try to interact with elements on the new tab it would be too early and fail. Most automated testing tools have features to wait for new page DOM elements to appear before interacting with them. But even this can be too soon. When the response to the partial page rendering request is processed by the web browser client it adds the new elements to the page and then binds all sorts of javascript events and other goodies to them. Most automated testing tools will not wait for this to complete and will still fail to interact with the new elements.

One quick and dirty solution is to introduce sleep statements in your test and just wait a second or two for the request to complete. This will unnecessarily slow down your tests if the partial request is completed in less than your sleep time and will still break your test whenever the page load will take longer then normal and thus longer than your sleep time.

A much better way is to actually tell Selenium (or your other testing tool of choice) when the partial page rendering request is fully completed and the browser is ready for its next command. ADF includes a javascript method that does just that; AdfPage.isSynchronizedWithServer.

This has been available in older ADF versions as well. In version 12c Oracle even introduced AdfDhtmlPage.whyIsNotSynchronizedWithServer which tells you why the client is not ready yet. Please not this is part of the Oracle internal AdfDhtmlPage class and therefor not part of the public javascript API which means it might change or disappear in future versions.

Selenium WebDriver has the notion of explicit waits where you can instruct Selenium to wait for a certain condition. I figured it would be nice if we could just hook into that mechanism. As part of my effort to automate ADF testing I've created a subclass of org.openqa.selenium.support.ui.ExpectedCondition called ClientSynchedWithServer:

public class ClientSynchedWithServer implements ExpectedCondition<Boolean> {
    // return false if AdfPage object and functions do not exist
    // if they do exist return true if page is fully loaded and ready or reason why this is not completed yet
    String js =
        "return typeof AdfPage !== 'undefined' && " + 
        "typeof AdfPage.PAGE !== 'undefined' && " +
        "typeof AdfPage.PAGE.isSynchronizedWithServer === 'function' && " +
        "(AdfPage.PAGE.isSynchronizedWithServer() || " +
        "(typeof AdfPage.PAGE.whyIsNotSynchronizedWithServer === 'function' && " +
        "AdfPage.PAGE.whyIsNotSynchronizedWithServer()))";

    @Override
    public Boolean apply(WebDriver driver) {
        JavascriptExecutor jsDriver = (JavascriptExecutor) driver;
        Object result = jsDriver.executeScript(js);
        System.out.println("client ready: " + result);
        return Boolean.TRUE.equals(result);
    }
}

The javascript tries to be as careful as possible not to throw an exception when not on an ADF page by first checking if AdfPage, AdfPage.PAGE and AdfPage.PAGE.isSynchronizedWithServer are available. If so, it will execute AdfPage.PAGE.isSynchronizedWithServer() to see if the client is completely finished processing all events. If this is not the case it will check if the whyIsNotSynchronizedWithServer function is available and will invoke it if it is. This would return the reason why the client is not finished yet. If the whyIsNotSynchronizedWithServer function is not available it would just return the false result from isSynchronizedWithServer.
In the end the javascript function will only return true if isSynchronizedWithServer returned true, otherwise it might return the reason why the page is not finished or any other non-true value.

The apply method from this ExpectedCondition will invoke the javascript and would print the reason why the page is not finished yet. If you don't want any System.out.println in your tests you could just remove this. The important part is that it checks if the javascript returned true. If it did, the apply method will also return true and Selenium would know the condition has been met and it no longer needs to wait.

Using this class to wait for PPR after interacting with the page is similar to any explicit wait in Selenium WebDriver:

public void test() throws Exception {
    FirefoxProfile profile = new FirefoxProfile();
    profile.setEnableNativeEvents(true);
    profile.setPreference("app.update.enabled", false);
    WebDriver driver = new FirefoxDriver(profile);
    System.out.println("load demo page...");
    driver.get("http://jdevadf.oracle.com/adf-richclient-demo");
    System.out.println("wait for completion...");
    new WebDriverWait(driver, 10).until(new ClientSynchedWithServer());
    System.out.println("click search button...");
    driver.findElement(By.id("tmplt:gTools:glryFind:doFind")).click();
    System.out.println("wait for completion...");
    new WebDriverWait(driver, 10).until(new ClientSynchedWithServer());
    driver.quit();
}

This will setup a new Selenium session in lines 2 through 5. It will then navigate to the Oracle Rich Client Demo site. This already includes quite some client side javascript processing, so we need to wait for this to complete in line 9. We then click on the search button and again wait for that to complete in line 13. Both waits use a timeout of 10 seconds. If the condition is not met within that timeout Selenium will throw an exception.
Without the new waits this script would fail as it would try to click the search button before the page has completely rendered and attached all of its javascript listeners. With the new waits you can see the results in the console and why the page wasn't ready yet in lines 3-5 and 9-10:

.load demo page...
wait for completion...
client ready: WAITING_FOR_USER_INPUT_PHASE
client ready: WAITING_FOR_USER_INPUT_PHASE
client ready: Event queue is not empty
client ready: true
click search button...
wait for completion...
client ready: DTS is not ready
client ready: WAITING_FOR_USER_INPUT_PHASE
client ready: true

Time: 9.756

OK (1 test)

This post is part of a series on how to get Selenium to work with Oracle ADF.

Configuring an Oracle ADF Project for Selenium testing

2015-02-08T12:44:00.000+01:00

Running Selenium testing against an ADF application requires direct interaction with the HTML DOM, JavaScript and CSS. An ADF application is normally optimised for performance and scalability which means CSS classes and javascript are minified and obfuscated. This makes testing with Selenium very difficult and brittle.

Fortunately you can configure quite a few settings in your project's web.xml file to make it more development friendly. I've written about these before but some are even more important for automated testing. The ADF Faces documentation also states a number of configuration changes have to be made for automated testing.

These are the settings to change when using automated testing:

oracle.adf.view.rich.automation.ENABLED should be set to true in web.xml. This ensures a javascript client component is created for each ADF component regardless the value of the clientComponent attribute on the JSF component. This makes interacting with the page from Selenium much easier. It also seems to enable some other client and server side features. Search for isAutomationEnabled in the ADF source code to get a feeling for things that will change when enabling this. One of the things it enables is to find objects using scope IDs (also known as Sub IDs). This is explained in the Oracle Application Testing Suite Open Script User Guide.
For this to work you also need to put adf-richclient-automation-11.jar in your project classpath. The simplest way is to just put this JAR in the WEB-INF/lib folder of your project. The file itself can be found in JDEV_HOME/oracle_common/modules/oracle.adf.view_12.1.3/
org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION to true in web.xml which will disable the compression of CSS classes like af_button to something like x7k. Having readable and deterministic CSS class names makes it possible to use CSS selectors in your Selenium scripts.
org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT to true in web.xml o disable the minification of ADF's javascript files. This gives you human readable javascript which makes it easier to figure out how to interact with those scripts from Selenium. You should also get a copy of the ADF Source code from Oracle Support so you even have the versions with all the inline comments in place. But don't let this scare you. For simple testing scenarios you won't be needing javascript interactions. It's just when you want to go all the way and have very detailed interactions or tests with ADF components.
javax.faces.PROJECT_STAGE to Development in web.xml as your application will otherwise fail to start since you have enabled a number of development-only features. You can revert this to Production with deployment plans for other environments.
The aforementioned Oracle Application Testing Suite documentation also advises to set animation-enabled to false in trinidad-config.xml. This is not only to speed up the running of the testing script as it won't have to wait for the animations but will also make sure tests don't fail as they want to interact with things like tree nodes before the expanding animation of a tree node is finished. In my own testscripts I also make sure to execute the javascript AdfPage.PAGE.setAnimationEnabled(false) on each page for situations where we forgot to set this parameter. Unfortunately values in trinidad-config.xml cannot be overridden with deployment plans, but there is a neat trick where you can refer to web.xml context param values from trinidad-config.xml.

You can revert these settings to the optimised values with deployment plans. No need to change this in the source code or build artefact each time. Just set the development optimised versions in your source files so local runs in JDeveloper use the correct values. Then use deployment plans to override these for production and other environments.

This post is part of a series on how to use Selenium automated tests with Oracle ADF.

Testing Oracle ADF with Selenium WebDriver Page Objects

2015-02-08T09:55:00.000+01:00

Selenium is an awesome (and free) tool to automate browser-based user interface testing. Selenium offers two ways of working; Selenium IDE; a firefox add-on for simple record-and-playback of interactions with your browser and Selenium WebDriver; a collection of language specific bindings to drive a browser -- the way it is meant to be driven.

For testing ADF applications you'll need to use Selenium WebDriver as that sends native events to the browser it is controlling. This means it will fire actual mouse, keyboard, and other events, which is something the javascript-heavy ADF framework needs.

I've built an example on how to test the public Oracle ADF Faces 12c Components Demo for a real life demo using JUnit and Selenium WebDriver. The example project is at github and I'll explain the important parts in a number of blog posts. This first post will show how the JUnit test classes interact with the page objects. The nitty gritty details on how to work with ADF and Selenium will be covered in separate posts.

My advice is to follow the Page Objects Pattern proposed by the Selenium team. It creates a clear separation between Page Objects and Test Objects. Page Objects know about the HTML, the page components and how to interact with them while the Test Objects drive these page objects and contain the real test logic and assertions. An alternative approach would be the Bot Style tests which combines page logic and Selenium interactions in a single class.

In an ideal world making changes to the ADF page itself only involves updating the Page Objects while the Test Objects can remain the same. Unless you're actually changing functionality on the page that requires changes to the tests itself. But even then it helps you to separate these two objects. The Page Object is more "developer oriented", while the Test Object is more "tester oriented".

Let's look at an example that drives the public Oracle ADF Faces Components Demo:

@Test
public void testNavigationToFileExplorer() throws Exception {
    FileExplorer page = getPage().clickFileExplorerLink().clickTreeTableTab();
    page.getScreenshotAs(new ScreenshotFile(new File("explorer-tree-table.png")));
}

This is a JUnit test method in the RichClientDemoTest test class. It starts in line 3 by navigation to the component demo homepage by invoking getPage(). This method returns a RichClientDemo page object. This is one of the aforementioned page objects that allow interaction with the web page.

ADF 12c Rich Client demo page with File Explorer link highlighted

Invoking the clickFileExplorerLink() method on the RichClientDemo page object will find the link on the page to navigate to the File Explorer demo and click that link to navigate to that page. Navigation methods on page objects will return other page objects. In this example we invoked a navigation method on RichClientDemo which returns a FileExplorer page object.

File Explorer page with Tree Table tab highlighted

Finally we invoke the clickTreeTableTab() method to click on the Tree Table tab in the right hand side af:pannelTabbed. Methods on Page Objects return the same page object instance or another when navigation occurs. In either case this means you can chain numerous of these methods on a single line when needed.

The last line of the test method shows how you can take a screenshot of what the browser is showing at the time. This can be very helpful especially with failing test cases where it could be useful to have a screenshot of the failed state.

Screenshot taken by Firefox ran by Selenium WebDriver

This example showed how to interact with page objects and it will fail if any of the required links or other elements are not available on the page. But it doesn't have any real test assertions yet. One final example shows how to assert that the number of expanded nodes in an af:tree should have increased when clicking one of the (collapsed) nodes in the tree:

@Test
public void testExpandTagGuideNodeA() {
    RichClientDemo page = getPage();
    int expandedNodesBefore = page.getTagGuideTreeExpandedNodeCount();
    page.clickLayoutTreeNode();
    Assert.assertEquals("number of expanded node should increase", 
                        expandedNodesBefore + 1,
                        page.getTagGuideTreeExpandedNodeCount());
}

Line 3 shows how we again first navigate to the rich client demo homepage as that is the starting point for all of our tests. Line 4 uses the RichClientDemo page object to retrieve the number of expanded nodes in the af:tree component. Notice how the knowledge on how to interact with the page to get this information is contained in the page objects and not exposed to the tester. Line 5 clicks the node in the tree labeled Layout. Again notice the knowledge on how to locate and click this node is hidden from the tester class. Finally in line 6 we have a JUnit assertion that the number of expanded nodes in the tree should have been increased by 1. If that is not the case this JUnit test will fail.

By the way; a Page Object doesn't have to represent a full page. Especially with ADF regions it is conceivable that each region would have its own Page Object (or rather Page Fragment Object). For complex page fragments this could be split up even further to keep the code manageable. More on that in other blog posts. I'll explain the other bits and pieces of this demo in separate blog posts. If you want to look at the full demo just hop over to github.

This post is part of a series on how to get Selenium to work with Oracle ADF.

showPopupBehavior align property examples

2015-01-23T14:43:00.000+01:00

I always struggle to understand the official descriptions for the align attribute of the af:showPopupBehavior tag. A picture is worth a thousands words so I just created screenshots of all the possible values:

afterStart: The popup appears underneath the element with the popup's upper-left corner aligned with the lower-left corner of the element. The left edges of the element and the popup are aligned

afterEnd: The popup appears underneath the element with the popup's upper-right corner aligned with the lower-right corner of the element. The right edges of the element and the popup are aligned.

beforeStart: The popup appears above the element with the popup's lower-left corner aligned with the upper-left corner of the element. The left edges of the element and the popup are aligned.

beforeEnd: The popup appears above the element with the popup's lower-right corner aligned with the upper-right corner of the element. The right edges of the element and the popup are aligned.

endAfter: The popup appears to the right of the element with the popup's lower-left corner aligned with the lower-right corner of the element. The bottom edges of the element and the popup are aligned.

endBefore: The popup appears to the right of the element with the popup's upper-left corner aligned with the upper-right corner of the element. The top edges of the element and the popup are aligned.

startAfter: The popup appears to the left of the element with the popup's lower-right corner aligned with the lower-left corner of the element. The bottom edges of the element and the popup are aligned.

startBefore: The popup appears to the left of the element with the popup's upper-right corner aligned with the upper-left corner of the element. The top edges of the element and the popup are aligned.

Host a Soap Web Service on Google App Engine with JAX-WS

2014-04-10T22:36:00.000+02:00

We are about to release a great addon for JDeveloper that can access a SOAP web service. For demonstration purposes we want to have a publicly available web service that anyone can use. Having this web service hosted on Google App Engine has two major benefits: it is free and is accessible for anyone on the internet 24x7.

We wanted to implement a simple Java (JAX-WS) webservice on Google App Engine, but unfortunately this is not fully supported. All the javax.xml.* classes are available on Google App Engine, but not the com.sun.xml.ws.* classes that are normally used to implement a JAX-WS service. But with a little bit of custom code we can get a JAX-WS service to run on Google App Engine as can be seen in the SoapUI screenshot. You can download the public WSDL at https://redheap-jaxws.appspot.com/HelloWorldService.wsdl

SoapUI test invoking HelloWorld service on Google App Engine

You can use the normal JAX-WS annotations in your service class and use JAXB to marshal and unmarshal the request and responses. This is all very similar to a JAX-WS service on a JEE container. The thing you need extra is a custom HttpServlet that handles the HTTP POST, unmarshals the request payload to a java object using JAXB, invoke the actual web service class, marshal the web service class response back to XML and send it to the client.

This post describes all the steps to create a project using maven and complete it in JDeveloper 12c as well as deploying it to a local and remote server. If you prefer other build tools, like Apache ANT, or other Java IDE's you can still use similar steps but you might need to adjust them for your environment. The key part is the custom servlet which is the same for each setup.

Navigate to the directory where you want to create a subdirectory for a project. No need to create the project directory yourself, just navigate to its parent. Then run mvn archetype:generate. Search for com.google.appengine.archetypes:skeleton-archetype and select the entry for com.google.appengine.archetypes:appengine-skeleton-archetype. Finish the wizard by specifying a unique groupId and artifactId. The rest can be left at their defaults:

C:\work\redheap\jdev12120>mvn archetype:generate
[INFO] Scanning for projects...
[INFO] 
[INFO] Using the builder org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder with a thread count of 1
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] >>> maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom >>>
[INFO] 
[INFO] <<< maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom <<<
[INFO] 
[INFO] --- maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
..... [[snip long list]] .....
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): 361: com.google.appengine.archetypes:skeleton-archetype
Choose archetype:
1: remote -> com.google.appengine.archetypes:appengine-skeleton-archetype (-)
2: remote -> com.google.appengine.archetypes:skeleton-archetype (-)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1
Define value for property 'groupId': : com.redheap.samples
Define value for property 'artifactId': : AppEngineJaxWs
Define value for property 'version':  1.0-SNAPSHOT: : 
Define value for property 'package':  com.redheap.samples: : 
Confirm properties configuration:
groupId: com.redheap.samples
artifactId: AppEngineJaxWs
version: 1.0-SNAPSHOT
package: com.redheap.samples
 Y: : Y

In JDeveloper 12c go to Tools > Preferences and change the location of maven to use a recent version you downloaded yourself. The maven version included with JDeveloper 12.1.2.0.0 is too old for Google App Engine as that requires maven to be at least version 3.1:

Use at least version 3.1 of maven in JDeveloper 12c

Next steps are for Oracle JDeveloper, but you can take similar steps from the command line or your favorite Java IDE. Create a new JDeveloper workspace from the maven pom files. JDeveloper will warn that the project already exists and it will be overwritten. Just click Yes even though this is a new project.

Start maven import wizard from New Gallery

Import all pom's

Point to parent directory of project as subdir is implied

Open the pom.xml at application level and update the appengine.target.version property to the latest App Engine version. Currently this is 1.9.2 but you might want to check the latest Java SDK version at https://developers.google.com/appengine/downloads.

Open the application level maven pom

Update appengine.target.version

Go to https://console.developers.google.com and create a new project. Use the same project name as you used when setting up the maven project, AppEngineJaxWs in this example. The project ID has to be globally unique across all App Engine customers and will become the first part of your URL. For example, typing redheap-jaxws will create http://redheap-jaxws.appspot.com

Open the project properties for the AppEngineJaxWs-ear project and add the src/main/application directory to the Java Source Paths.

Add src/main/application as source directory

Then open the application/META-INF/appengine-application.xml file and update the application name with the globally unique project ID (not the name) that was created in the Google developer console:

Update application name with App Engine Project ID

Next, create a Java class Person in the war project that we will be using as an argument to our webservice, just to demonstrate how to handle complex payloads:

package com.redheap.appengine;

public class Person {
    private String firstName;
    private String lastName;

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getLastName() {
        return lastName;
    }
}

Next create the HelloWorld class that we will be exposing as a JAX-WS service:

package com.redheap.appengine;

public class HelloWorld {
    public String sayHello(Person person) {
        return "Hello " + person.getFirstName() + " " + person.getLastName();
    }
}

Right click the HelloWorld class in the application navigator and create a web service out of it. When running this for the first time it will ask if you want a WebLogic specific web service or JAX-WS Reference Implementation version. Be sure to check the RI one as we want to deploy to a non-weblogic environment. Other than that, accept all default values. If you are not using JDeveloper, you can also use the command line wsgen tool that ships with the JDK.

This will have added a number of annotations to the HelloWorld class. Change the @WebParam annotation for more meaningful argument name than arg0 as this name will end up in the XSD for the web service.

@WebService
public class HelloWorld {
    @WebMethod
    public String sayHello(@WebParam(name = "person") Person person) {
        return "Hello " + person.getFirstName() + " " + person.getLastName();
    }
}

Now right click HelloWorld again and generate a WSDL file.

Right click the generated wsdl file and use the Move option from the Refactor menu to relocate it to webapp directory itself (two levels up) so the file is no longer in the WEB-INF folder and accessible through the web. Repeat the same steps for the xsd file so it will also be available on the web.

Open the generated WSDL file and update the soap:address at the end of the file to the URL at your appengine instance. For example, mine is https://redheap-jaxws.appspot.com/HelloWorldService

Open the generated XSD file and add elementFormDefault="qualified" to the root element to ensure we will be using namespaces in the web service requests and responses.

Use namespace qualified elements

Now right click the XSD file and create a JAXB Content Model. Be sure to select the correct source directory for the JAXB classes in the wizard as you don't want them to end up in your test directory since those are not included in a deployment.

Google App Engine doesn't include the com.sun.xml.ws.* classes that are normally used by a JAX-WS service. So we need to create our own servlet that handles the requests and invokes the HelloWorld class. This is where the magic happens. Most of the code in this class is generic for any webservice. We implemented everything in a single class for this example, but in a real application you want to refactor the generic code to a super class that can be reused for each web service.

public class HelloWorldServlet extends HttpServlet {

    public static final String NS = "http://appengine.redheap.com/";
    public static final QName QNAME_SAY_HELLO = new QName(NS, "sayHello");
    public static final QName QNAME_OTHER = new QName(NS, "otherOperation");

    private final HelloWorld serviceImpl = new HelloWorld();

    private static final MessageFactory messageFactory;

    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException,
                                                                                           IOException {
        try {
            MimeHeaders headers = getHeaders(request);
            InputStream in = request.getInputStream();
            SOAPMessage soapReq = messageFactory.createMessage(headers, in);
            SOAPMessage soapResp = handleSOAPRequest(soapReq);
            response.setStatus(HttpServletResponse.SC_OK);
            response.setContentType("text/xml;charset=\"UTF-8\"");
            OutputStream out = response.getOutputStream();
            soapResp.writeTo(out);
            out.flush();
        } catch (SOAPException e) {
            throw new IOException("exception while creating SOAP message", e);
        }
    }

    public MimeHeaders getHeaders(HttpServletRequest request) {
        MimeHeaders retval = new MimeHeaders();
        Enumeration headerNames = request.getHeaderNames();
        while (headerNames.hasMoreElements()) {
            String name = headerNames.nextElement();
            String value = request.getHeader(name);
            StringTokenizer values = new StringTokenizer(value, ",");
            while (values.hasMoreTokens()) {
                retval.addHeader(name, values.nextToken().trim());
            }
        }
        return retval;
    }

    protected SOAPMessage handleSOAPRequest(SOAPMessage request) throws SOAPException {
        Iterator iter = request.getSOAPBody().getChildElements();
        Object respPojo = null;
        while (iter.hasNext()) {
            // find first Element child
            Object child = iter.next();
            if (child instanceof SOAPElement) {
                respPojo = handleSOAPRequestElement((SOAPElement) child);
                break;
            }
        }
        SOAPMessage soapResp = messageFactory.createMessage();
        SOAPBody respBody = soapResp.getSOAPBody();
        if (respPojo != null) {
            JAXB.marshal(respPojo, new SAAJResult(respBody));
        } else {
            SOAPFault fault = respBody.addFault();
            fault.setFaultString("Unknown SOAP request");
        }
        return soapResp;
    }

    protected Object handleSOAPRequestElement(SOAPElement reqElem) {
        QName reqName = reqElem.getElementQName();
        if (QNAME_SAY_HELLO.equals(reqName)) {
            return handleSayHello(JAXB.unmarshal(new DOMSource(reqElem), SayHello.class));
        } else if (QNAME_OTHER.equals(reqName)) {
            //
        }
        return null;
    }

    protected SayHelloResponse handleSayHello(SayHello request) {
        SayHelloResponse response = new SayHelloResponse();
        response.setReturn(serviceImpl.sayHello(request.getPerson()));
        return response;
    }

    static {
        try {
            messageFactory = MessageFactory.newInstance();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

}

Remove all entries from web.xml that were created by the web service wizard in JDeveloper and register our own servlet. The url-pattern has to match the endpoint you configured in the soap:address in the WSDL file.

<web-app version="2.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xsi:schemalocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    <servlet>
        <servlet-name>HelloWorldServlet</servlet-name>
        <servlet-class>com.redheap.appengine.HelloWorldServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>HelloWorldServlet</servlet-name>
        <url-pattern>/HelloWorldService</url-pattern>
    </servlet-mapping>
</web-app>

Finally all we need to do is add some maven goals to JDeveloper so we can select them from the build menu. To do this, go to the Tools menu and select Preferences. Then go to the Maven > Phases/Goals and add a goal to the list of Selected Phases/Goals:

Add a goal to Maven preferences

Add two goals: com.google.appengine:appengine-maven-plugin:devserver and com.google.appengine:appengine-maven-plugin:update. The first one is to start a local AppEngine server for testing and the second one is to deploy your application to the real Google App Engine.

Add Maven goals

If everything is well, you can now run your application:

Right-click the pom.xml in the Application Resources > Build Files and run maven phase install from the Run Maven Goal Profile "Default" popup menu. This should compile and build your project
Right-click the pom.xml in the AppEngineJaxWs-ear project and run the appengine:devserver phase from the same popup menu. This should launch the local AppEngine server and you should be able to download the WSDL at http://localhost:8080/HelloWorldService.wsdl and invoke the local webservice at http://localhost:8080/HelloWorldService
Once this is fine, you can run the appengine:update phase from the AppEngineJaxWs-ear project. This installs the project at your Google AppEngine server. Be sure to run this from the command line the first time and not from JDeveloper. The reason is it will launch a web browser to authenticate yourself and you have to enter a code from the web browser into the maven build. This cannot be done when building from JDeveloper as it doesn't allow you to enter information.

You're done. Enjoy your Google AppEngine JAX-WS Soap WebService. You can also give my instance a try. The WSDL is available at https://redheap-jaxws.appspot.com/HelloWorldService.wsdl. Give it a try in SoapUI.

As always you can download the full sample application or browse the subversion repository to look at the source code. If you want to have a quick look at the solution start with the com.redheap.appengine.HelloWorldServlet servlet that does most of the important work.

Managed Bean changes should mark their ADF Scope dirty in a HA cluster

2014-03-31T17:45:00.001+02:00

We're starting development on a new ADF application and the plan is to run this in a high-available weblogic cluster. The documentation clearly states it is the responsibility of the developer to make ADF aware of any changes to managed beans in an ADF scope with a lifespan longer than one request. This means it is up to you to notify ADF of each change in a viewScope or pageFlowScope bean with the following code:

Map viewScope = ADFContext.getCurrent().getViewScope();
ControllerContext.getInstance().markScopeDirty(viewScope);

That's not too difficult but it's a matter of time before a developer forgets about this. That would mean the ADF scope is not marked dirty and the changed managed bean is not replicated to the other nodes in the cluster. We wanted to implement a check (at least during development) that developers do not forget about this. JSF PhaseListener to the rescue!

Full source code is at the end of this posting, but I'll explain the vital parts first. We've create a JSF PhaseListener that listens to each JSF phase transition:

public PhaseId getPhaseId() {
    return PhaseId.ANY_PHASE;
}

In the beforePhase method for the RESTORE_VIEW phase we retrieve the viewScope and pageFlowScope maps. Next, we serialize these and calculate a MD5 hash. These hashes are store in the requestScope

In the afterPhase method for the RENDER_RESPONSE phase we calculate the same MD5 digests and compare these with the ones stored at the beginning of the request. We know we're in trouble when the digests changed and the developer has not invoked ControllerContext.markScopeDirty. When this happens we simple log an exception to the console without actually throwing it. This is more of a development/debugging tool and shouldn't actually abort JSF processing as that would also cancel any other PhaseListeners. We don't want to make things worse.

You probably want this enabled during development all the time. However, there is a performance overhead in serializing the viewScope and pageFlowScope twice per request and calculating a MD5 digest. It might be a good idea to disable this in production. That's why we opted to use the ADF logging framework for this. First, you can set the log levels that will be used for the output through web.xml context-parameters. By default, these are set to WARNING to ensure all logging is enabled in a default development environment. In production you want to use deployment plans to override this to something like FINE or FINEST. Once you know the logging level that is being used, you can even enable/disable these checks in a deployed application by tweaking the log levels of your weblogic container. The JSF PhaseListener is smart enough to not even perform the serialization and digest calculation of logging levels are setup so that logging doesn't occur. This means you could even leave the loggers in there for production so you could still enable them when cluster replication issues occur.

The demo workspace includes a singe page application to demonstrate the DirtyScopePhaseListener. Simply run that page and press the button marked "change viewState without marking dirty". This will log an error in the console that neatly explains the internal state of myViewScopeBean in the ADF viewScope was changed:

Hopefully this JSF PhaseListener can be a valuable tool for anyone building a ADF application intended to run on a session-replicating cluster.

As always you can download the full sample application or browse the subversion repository to look at the source code. If you want to have a quick look at the solution start with the com.redheap.dirtyscope.DirtyScopePhaseListener phase listener and the com.redheap.dirtyscope.ADFScopeChecker class that does all the digest calculating and checking.

Update: The sample code is broken. It only looks at the pageFlowScope and viewScope of the unbounded taskflow and does not consider any state in bounded taskflows and viewScopes running in regions. I am working on an improved version and will post a new blog entry once that is finished.

ADFLogger JAX-WS SoapHandler to log request, reponse and faults

2014-02-24T23:45:00.002+01:00

Lately I see a lot of ADF projects consuming SOAP web services. This is typically done by creating a JAX-WS Proxy in JDeveloper and invoking this proxy from java beans exposed through the Bean Data Control or through programmatic ADF Business Components. This post will show how to instrument your JAX-WS proxy so it can log the SOAP request, payload and potential fault to an ADFLogger. This can be a very valuable tool during development and when diagnosing production issues.

Let's start with the final result, the weblogic console when invoking a web service that returns a soap fault. The nice thing is that it not only logs the fault but also the request that caused it:

SOAP request and response logged when receiving SOAP fault

When you crank up the log level you can even see all requests and responses that complete successful. As I described earlier this also allows for performance analysis with the Log Analyzer. This breaks down your entire request and our LoggingSoapHandler times the milliseconds it took to invoke the web service.

Log Analyzer showing this web service call took 5 msecs

This magic is performed by a JAX-WS SoapHandler. It can be registered with a JAX-WS proxy and has access to the web service request and response messages. Handlers can even change these, but in this example all we do is logging to the ADFLogger. You can setup handlers when creating the web service proxy or by right clicking an existing one and changing its properties.

Add LoggingSoapHandler as a Handler on the JAX-WS Proxy

You can get the full source code for the com.redheap.soaplog.LoggingSoapHandler class so you can add it to your own project or library. The embedded documentation is rather elaborate but I'll also explain the most important bits here.

JAX-WS will invoke the handleMessage method when sending or receiving a message. We check if this is an outbound message (aka request) or an inbound message (aka response):

    public boolean handleMessage(final SOAPMessageContext context) {
        if (Boolean.TRUE.equals(context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY))) {
            handleRequest(context);
        } else {
            handleResponse(context);
        }
        return true; // return true to continue processing other handlers
    }

When the log levels are set to verbose, the handleRequest method will log the fact that a web service is being invoked including the end point URL and it will log the actual request payload. Regardless the log level it will also invoke ADFLogger#begin to start a performance timer so the time spent invoking the web service will show up in the log analyzer. Finally, it also adds the request payload as well as a timestamp to the SOAPMessageContext. More on this later.

The handleResponse method will stop the performance timer by invoking ADFLogger#end. When the log levels are set to verbose, it will log the response payload and get the starting timestamp from the SOAPMessageContext (which was put there by handleRequest) and calculate the time spent and log this to the normal ADFLogger.

When an error occurs, such as receiving a soap fault from the web service, the JAX-WS proxy will not invoke the handleMessage method but it will invoke handleFault. Similar to handleResponse we stop the timer and when being verbose log the time spent on invoking the web service. But the really nice thing it does is log the fault response payload as well as the original request payload at warning level. This is why handleMessage put the request itself in the SOAPMessageContext, so handleFault can get the request there. It is a method for sharing state between the different methods of the (stateless) handler. The result can be seen in the first screenshot of this post.

We also made sure each service and service operation uses a distinct ADFLogger. In this example we are invoking the divideTen operation on the MyTestService web service which means we are using the com.redheap.soaplog.LoggingSoapHandler.MyTestService.divideTen logger. Since log levels work like a hierarchy this allows you to set the default log level for all LoggingSoapHandlers at com.redheap.soaplog.LoggingSoapHandler, or you can override this for all operations of a specific service at com.redheap.soaplog.LoggingSoapHandler.SERVICENAME or use the full name of the logger to set it for a specific operation. This can prove to be very valuable in a production environment where you can enable very specific logging at runtime without overwhelming your log files.

As always you can download the full sample application or browse the subversion repository to look at the source code. All you really need is the single com.redheap.soaplog.LoggingSoapHandler class, but the workspace also includes a very simple JSF page to invoking a (local) web service that divides 10 by the given input. This was used to create the screenshots and entering 0 as an input will give a nice divide by zero soap fault for testing.

The workspace also includes the com.redheap.soaplog.Tester class to demonstrate the logger from a plain java program. You can simply run that class, but be sure to first run the com.redheap.soaplog.test.MyTestService service to ensure it is deployed to your local weblogic. Switch between the two run profiles in the project properties to set the verbosity of the logger when running the Tester.

Configuring ADF Faces for development

2014-01-03T11:25:00.000+01:00

This post will describe how to configure your ADF Faces project for development through web.xml context parameters as well as enabling debug mode in trinidad-config.xml. It will also show how to override these settings for production deployment with a deployment plan even though the setting in trinidad-config.xml cannot be altered directly with a deployment plan.

More background information on all ADF Faces configuration parameters can be found in the appendix of the Web User Interface Developer's Guide. The ones we want to change during development are:

org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION to true to check for source files being modified on disk while the application is running and reloading them. Be sure to clear your browser cache after changing this value to clear out any old cached versions.
org.apache.myfaces.trinidad.resource.DEBUG to true to enable resource debugging and prevent the client from caching resources (eg javascript libraries, images, CSS, etc)
org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION to true to disable CSS content compression and use human-readable CSS class names for skinning
org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT to true to non-obfuscated javascript
oracle.adf.view.rich.LOGGER_LEVEL to FINE to enable client side javascript logging. Other allowed values are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, and ALL
oracle.adf.view.rich.ASSERT_ENABLED to true to enable client-side javascript assertions

All you have to do is copy and paste the context parameters below and add them to your WEB-INF/web.xml file:

  <context-param>
    <description>If this parameter is true, there will be an automatic check
                 of the modification date of your JSPs, and saved state will
                 be discarded when JSP's change. It will also automatically
                 check if your skinning css files have changed without you
                 having to restart the server.</description>
    <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <description>Set to true to have ADF Faces set HTTP response headers to
                 let the browser know that resource (such as javascript
                 files, images, and CSS) should not be cached</description>
    <param-name>org.apache.myfaces.trinidad.resource.DEBUG</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <description>Set to true to disable compression of CSS class names for
                 skinning keys and have more human readable class
                 names</description>
    <param-name>org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <description>Set to true to disable obfuscation and compaction of ADF
                 javascript that also removes comments and
                 whitespace.</description>
    <param-name>org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <description>Set the level of client side javascipt logging. Default is
                 OFF, other allowed values are SEVERE,WARNING,INFO,CONFIG,
                 FINE,FINER,FINEST, and ALL</description>
    <param-name>oracle.adf.view.rich.LOGGER_LEVEL</param-name>
    <param-value>FINER</param-value>
  </context-param>
  <context-param>
    <description>Set to true to enable assertions in client side 
                 javascript. This is frequently used to assert valid
                 argument types to JS methods</description>
    <param-name>oracle.adf.view.rich.ASSERT_ENABLED</param-name>
    <param-value>true</param-value>
  </context-param>

Most of these parameter have a performance impact and should not be enabled on production environments, or user acceptance and performance testing environments. This can be achieved using deployment plans. These can make changes to deployment descriptors during deployment and the WEB-INF/web.xml file is one of these deployment descriptors. Simple save the file below as plan-nodev.xml and use it during deployment to override these settings. You do need to change the application-name and module-name elements to match your application.

If you read the deployment plan you can see it defines two variables: developMode and adfJavascriptLoggerLevel that are used in the overrides to make changes to the WEB-INF/web.xml file. I opted to use a single developMode variable to change all booleans to false. You could also create individual variables for each parameter and change the override to use these separate variables. That would give you individual control over each parameter. Without further ado here is the deployment plan:

<?xml version='1.0' encoding='UTF-8'?>
<deployment-plan xmlns="http://xmlns.oracle.com/weblogic/deployment-plan" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://xmlns.oracle.com/weblogic/deployment-plan http://xmlns.oracle.com/weblogic/deployment-plan/1.0/deployment-plan.xsd"
                 global-variables="false">
  <application-name>DeploySample.ear</application-name>
  <variable-definition>
    <variable>
      <name>developMode</name>
      <value>false</value>
    </variable>
    <variable>
      <name>adfJavascriptLoggerLevel</name>
      <value>NONE</value>
    </variable>
  </variable-definition>
  <module-override>
    <module-name>DeploySample.war</module-name>
    <module-type>war</module-type>
    <module-descriptor external="false">
      <root-element>web-app</root-element>
      <uri>WEB-INF/web.xml</uri>
      <variable-assignment>
        <name>developMode</name>
        <xpath>/web-app/context-param/[param-name="org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
      <variable-assignment>
        <name>developMode</name>
        <xpath>/web-app/context-param/[param-name="org.apache.myfaces.trinidad.resource.DEBUG"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
      <variable-assignment>
        <name>developMode</name>
        <xpath>/web-app/context-param/[param-name="oracle.adf.view.rich.ASSERT_ENABLED"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
      <variable-assignment>
        <name>developMode</name>
        <xpath>/web-app/context-param/[param-name="org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
      <variable-assignment>
        <name>adfJavascriptLoggerLevel</name>
        <xpath>/web-app/context-param/[param-name="oracle.adf.view.rich.LOGGER_LEVEL"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
    </module-descriptor>
  </module-override>
</deployment-plan>

In the intro I also promised to change a parameter in the WEB-INF/trinidad-config.xml file. You can set debug-output to true to get better human readable HTML. It will be properly indented and even have HTML comments before each component to show its full ID. This makes it much easier to look at the generated HTML or PPR responses. The problem with the WEB-INF/trinidad-config.xml file is that it is not an official JEE deployment descriptor so you cannot override its value in a deployment plan. But we most definitely don't want this debug mode in a production environment. Fortunately you can use EL expressions in this file and you can use those to refer to context parameters from the web.xml file. I have opted to simply look at the org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT parameter so we enable javascript debugging and HTML debug output with the same parameter. You could also create a separate context parameter to control this behavior. Here is the WEB-INF/trinidad-config.xml file with EL expression:

<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
  <skin-family>skyros</skin-family>
  <skin-version>v1</skin-version>
  <debug-output>#{initParam['org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT']}</debug-output>
</trinidad-config>

If, for whatever reason, the initParam expression doesn't work you can also try to use #{facesContext.externalContext.initParameterMap['org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT']}

I hope this helps you to setup your project for development while also having a proper production deployment without the need to change your sources or repackage your application.

JDeveloper Extension To Suppress Warnings

2013-11-19T15:16:00.000+01:00

The JDeveloper auditing framework can be a very valuable tool in delivering high quality code. It not only gives you warnings and errors during development, but can also be run from the command-line on a build server. One thing that always annoyed me is the limited possibilities for suppressing individual warnings. Sure, there is the @SuppressWarnings annotation for Java code. JDeveloper 12c can even use this annotation to suppress any warning, not only the ones supported by the java compiler.

However, much of an ADF (or SOA) application is XML files, not java. JDeveloper 12c doesn't offer a way to suppress warnings in these files. Luckily the auditing framework is highly pluggable and after some inspection how the @SuppressWarning annotation is implemented in the auditing framework, I could create something similar for XML files.

Suppressing a warning in a JSF file

The screenshot above shows how the extension works. See the warning for the value property of the af:outputText component and how it marks this entire document as warning. Simply click the balloon in the gutter of the editor and select to suppress this warning. This adds a comment to the XML file to suppress the warning, very similar to a @SuppressWarnings annotation in java.

Suppressed warning in a JSF file

Notice how the document is now marked green an no more warnings appear. With this extension you can keep the number of warnings down so the real warnings get the attention they need.

I have plans on building a SonarQube extension to run ojaudit (the command line JDeveloper auditing tool) to keep track of your quality. Suppressing warnings can be especially valuable in that situation where you can use SonarQube to keep metrics and track unexpected warnings and errors.

The extension is already live, so simply start JDeveloper 12c and use the Help > Check for Updates feature. Be sure to check "Open Source and Partner Extensions". You should be able to find the "Suppress Audit Warnings" extension. Please leave a comment below if you have any questions or suggestions for a future version.

If you want to see how a custom suppression scheme is built you can download the full workspace or simply browse the subversion repository to look at the source code.

Overriding Entity doDML or prepareForDml Causes Locking Issues

2013-11-13T22:28:00.001+01:00

It is not uncommon for people to override the doDML or prepareForDml method in an ADF BC Entity to do some additional work just before posting changes to the database. The official documentation even describes this extension point as being an equivalent to the Oracle Forms Post Processing triggers.
Today I discovered this can lead to locking issues in the database when this additional work changes other view objects or entities. The investigation is based on JDeveloper version 11.1.1.7 and this behavior might differ for other versions.

Update Nov 14: The issue doesn't reproduce in ADF 12.1.2.0. Inspecting of the source code seems to indicate (unpublished) bug 11896369 is to blame. Currently working with Oracle support to further investigate and ask for fix backport to 11.1.1.7

Update Jan 2: Oracle development acknowledged this behavior is caused by bug 11896369 and a backport request has been filed to bring the fix to 11.1.1.7.

Update Jan 10: Patch 11896369 is now available for download.

Let's start with an simplified example of an entity mutation another one. Below is the doDML method of the Department entity. Whenever a change happens to a department it sets the commission of its first employee to 99%. Not a very likely business scenario, but enough to demonstrate the issue.

@Override
protected void doDML(int i, TransactionEvent transactionEvent) {
    RowIterator employees = getEmployees();
    EmployeeImpl firstEmployee = (EmployeeImpl)employees.first();
    try {
        firstEmployee.setCommissionPct(new Number(0.99));
    } catch (SQLException e) {
        throw new JboException(e);
    }
    super.doDML(i, transactionEvent);
}

What we also need is a entity level validation on Employee that will be violated by this change. For demonstration purposes I've setup a range validation for CommissionPct to be between 0.00 and 0.50:

Entity-level Validation Rule

Now let's build a very simple ADF page to change a department and try to save the changes to the database. Here is what happens:

Validation Error in ADF Application

Everything appears to be okay. The user is confronted with the validation error as expected. But now let's try to update the same record from a different database session:

Database record locked after validation exception

This shows the database record is still locked. This is strange as this ADF BC application is set to its default of pessimistic locking. This means it should only lock the record while doing the DML and not keep the lock across requests. Further investigation points to the commitInternal method in the oracle.jbo.server.DBTransactionImpl class. I've simplified its code in pseudo-code below:

try {
  while (hasObjectsToPost()) {
    while (hasObjectsToValidate()) {
      JboException jboEx = null;
      try {
        validateAllObjects();
      } catch (JboException e) {
        jboEx = e;  // remember exception
        break; // abort hasObjectsToValidate loop
      }
    }
    if (jboEx != null) throw jboEx;
    setSavepoint();
    passivateStateForUndo();
    try {
      postChanges();
    } catch (RuntimeException r) {
      rollbackToSavepoint();
      throw r; // abort hasObjectsToPost
    }
  }
  try {
    doCommit();
  } catch (RuntimeException r) {
    rollbackToSavepoint();
    activateStateForUndo();
  }
} finally {
  clearSavePoint();
}

Let's ignore the loops for now. In line 6 all objects with pending changes are validated. In our example this is only the Department as that is the only entity the user changes from the user interface. This Department has no validation issues, so no exception is caught in lines 7-9 and no exception is re-thrown in line 12.

So the process continues at line 13 to set a database savepoint and then continues posting the real changes (performing DML) in line 16. This is where the prepareForDml and doDML on all changes entities is invoked. This is where DepartmentImpl is performing its SQL UPDATE statement. This is also where our DepartmentImpl makes changes to an EmployeeImpl entity. This does not throw any exception since EmployeeImpl has an entity-level validation which is not validated directly when changing an attribute but is postponed until the entity is saved to the database. So we never get to the exception handling in line 18 that might have performed a rollback.

We have now finished the first try of validation and posting changes but we have changed entities left. This means the loop at line 2 is going for another iteration. In line 6 we are again validating all entities with pending changes. In this second iteration, that is only the EmployeeImpl. This time the entity-level validations occur and an exception is thrown. We end up in the exception handling in line 7-9 where we keep the validation exception and abort the validation loop. The validation exception is then re-thrown in line 12. This immediately jumps to line 29 where the database savepoint is cleared, but we never rollback to that savepoint as the exception handling around postChanges and doCommit would have done. This means the already changed row in the Departments table is still changed (and thus locked).

I think this is a bug in ADF and a service request has been filed with Oracle Support. As long as this is not fixed, you can implement a workaround. Whenever you manipulate other objects from the prepareForDml or doDML be sure to force validation yourself. This would not only abort the DML on the entity itself but it also means the postChanges in line 16 of our DBTransactionImpl::commitInternal pseudo-code would throw an exception and a rollback of any changes posted by other entities occurs. To implement this you only need a simple change to the code in DepartmentImpl (see line 10):

@Override
protected void doDML(int i, TransactionEvent transactionEvent) {
    RowIterator employees = getEmployees();
    EmployeeImpl firstEmployee = (EmployeeImpl)employees.first();
    try {
        firstEmployee.setCommissionPct(new Number(0.99));
    } catch (SQLException e) {
        throw new JboException(e);
    }
    firstEmployee.validate();
    super.doDML(i, transactionEvent);
}

As always you can download the full sample application or browse the subversion repository to look at the source code.

Vodafone Content Tampering Making Sites Very Slow On Wi-Fi

2013-11-08T22:53:00.002+01:00

I've had issues with this blog sometimes being very slow on my iPhone when using Wi-Fi. I finally figured out what is going and it seems like Vodafone (Netherlands) are to blame.

I noticed my browser is trying to download http://1.2.3.50/jsi/flash.php?file=gordon.js&max-age=3600 which never succeeds on Wi-Fi. A whois search seems to indicate the entire 1.2.3.0/24 address block is invalid and shouldn't be used on the public internet. All traffic to this address block is dropped along the route and it takes the browser (or TCP/IP stack) a full minute to give up and continu loading my blog. Strangely enough downloading this script on a Vodafone NL 3G connection does succeed.

But why is my client requesting this bizarre URL? It is actually part of http://googleads.g.doubleclick.net/pagead/blank.html which is used on my blog pages. When requesting this page over a Vodafone NL 3G mobile connection the content of this blank page is:

<html><script src="http://1.2.3.50/jsi/flash.php?file=gordon.js&max-age=3600" language="javascript"></script>
<body style="background-color: transparent"></body></html>

There it is; this blank.html page contains a script tag to load the mysterious resource from 1.2.3.50. When requesting this same blank.html from my Wi-Fi connection I get a trully blank page:

<html><body style="background-color: transparent"></body></html>

You don't really notice the difference while your are on Vodafone NL 3G network. Your browser will download the file from 1.2.3.50 and the site seems to function okay. But what happens when your device (re)connects to Wi-Fi? Google sends response headers with blank.html telling your browser it is okay to cache the page for 24 hours. So your device will simply use the cached (tampered) version of blank.html it retrieved through Vodafone's network. But now you are on Wi-Fi and your device can't load the file from 1.2.3.50 and the site is dead slow.

Okay, this is bad, but let's hope the problem clears after 24 hours. After all your browser is only allowed to cache the tampered blank.html page for 24 hours. Unfortunately the problem doesn't disappear after 24 hours. This is caused by Google sending an ETag response header with blank.html as well. An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL. If the resource content at that URL ever changes, a new and different ETag should be assigned. Google sending an ETag is a good thing, but Vodafone is altering the content so they should also change the ETag. Unfortunately they don't so your browser is caching this altered version under Google's original ETag. So even when the cache expires after 24 hours and your browser is asking for a fresh copy of blank.html it will include the ETag with this request. Whether you are on Wi-Fi or 3G, Google will always respond that blank.html hasn't changed since your request includes their original ETag. This instructs your browser to keep using the (tampered) cached version. In the end, you are stuck with the altered version of blank.html until you clear your browser cache.

Vodafone is altering pages I request from the internet and to make things worse they are altering them in such a way that these pages won't work outside of their network while allowing my browser to cache this crippled content. This really sucks! I want the real internet and not some crippled version! Vodafone support is acknowledging they are injecting javascript through a transparent proxy. They state the only way to get rid of this is to use a different APN setting on your mobile device which first has to be activated for your account through technical support. This sucks big time! Sure I can get my account fixed, but who knows how many more people are running into this issue without ever figuring out what is going on.

Hopefully this rant can help others understand what is going on when they see this failed downloads from the 1.2.3.50 or 1.2.3.4 IP address.

Decimal Comma with Numeric Keypad as ADF Client Behavior

2013-11-07T16:31:00.000+01:00

According to wikipedia 24% of the world's population uses a comma as decimal separator, including The Netherlands where I live. This means entering numeric information with the numeric keypad on the keyboard can be challenging. You can only use it to type a decimal point (.) while we need a decimal comma (,). To make things ADF simply ignores the decimal point in our locale. When a user enters 1.23 it is converted to 123 and wrong information is entered into the system.

Numeric keypad decimal point

We came up with a solution based on a custom ADF Behavior tag. I've recently posted how to create your own ADF (client side) behavior. The first post was a simple version without properties, while the second post expanded this example with properties. Now it is time for the sequel showing how you can handle key presses in an input item and replace any decimal point keystroke with a decimal separator (possibly comma) keystroke. The user can simply use the decimal point on the numeric keypad and when using a European locale it will simply type a comma.

Read these previous posts to learn how to create custom ADF behavior tags. This post will only focus on the parts that are specific for this solution: the BehaviorTag class, the javascript implementation and a sample page. Let's start with the DecimalCommaBehaviorTag class. This represents the redheap:decimalCommaBehavior JSP tag and constructs the client side snippet of javascript:

package com.redheap.decimalcomma;

import java.text.DecimalFormatSymbols;
import java.util.Locale;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import org.apache.commons.lang.StringEscapeUtils;
import org.apache.myfaces.trinidad.context.RequestContext;

/**
 * Implementation of redheap:decimalCommaBehavior JSP tag.
 * @author Wilfred van der Deijl, www.redheap.com
 */
public class DecimalCommaBehaviorTag 
  extends oracle.adfinternal.view.faces.taglib.behaviors.BehaviorTag {

    /**
     * Returns the snippet of javascript code that needs to be executed
     * on the client to construct the client behavior object.
     * @param component JSF component this behavior tag is attached to
     * @return snippet of javascript that instantiates an object
     */
    @Override
    protected String getBehavior(UIComponent component) {
      return "new RedHeapDecimalCommaBehavior('" +
          StringEscapeUtils.escapeJavaScript(getDecimalSeparator()) + 
          "')";
    }

    /**
     * Returns the name of a JavaScript library feature that provides
     * the client-side implementation of this listener/behavior.
     * This feature will be added to the set of features required for
     * this page/request, ensuring that corresponding JavaScript
     * library partition is available.
     * @return a javascript library feature name
     */
    @Override
    protected String getFeatureDependency() {
      return "RedHeapDecimalCommaBehavior";
    }

    protected String getDecimalSeparator() {
      DecimalFormatSymbols dfs = new DecimalFormatSymbols(getLocale());
      return String.valueOf(dfs.getDecimalSeparator());
    }

    protected Locale getLocale() {
      Locale locale =
          RequestContext.getCurrentInstance().getFormattingLocale();
      return locale != null ? locale :
            FacesContext.getCurrentInstance().getViewRoot().getLocale();
    }

}

Line 25-27 returns the javascript script to instantiate the client-side implementation object. This gets the decimal separator character as argument to the constructor. This decimal separator character is determined in the getDecimalSeparator() methods which uses getLocale() to determine the locale for the current request/page.

Next is the most important part of this solution: the client-side javascript implementation:

/**
 * javascript constructor that invokes the Init function
 */
function RedHeapDecimalCommaBehavior(decimalSeparator) {
  this.Init(decimalSeparator);
}

// register as a subclass of AdfClientBehavior
AdfObject.createSubclass(RedHeapDecimalCommaBehavior,
                         AdfClientBehavior);

/**
 * initialize this behavior
 * @override
 */
RedHeapDecimalCommaBehavior.prototype.Init = function(decimalSeparator) {
  // be sure to invoke initialization by superclass
  RedHeapDecimalCommaBehavior.superclass.Init.call(this);
  this._decimalSeparator = decimalSeparator;
}

/**
 * as part of the AdfClientBehavior behavior contract, initialize is
 * called when the component is created to give the behavior a chance
 * to register event listeners.
 * @param {AdfUIComponent} component
 */
RedHeapDecimalCommaBehavior.prototype.initialize =
function(component) {
  AdfAssert.assertPrototype(component, AdfUIComponent);
  component.addEventListener(AdfUIInputEvent.KEY_PRESS_EVENT_TYPE,
                             this._handleKeyPress, this);
}

/**
 * handle invoking a command component with this behavior.
 * @param {AdfUIInputEvent} event
 */
RedHeapDecimalCommaBehavior.prototype._handleKeyPress =
function(event) {
  AdfAssert.assertPrototype(event, AdfUIInputEvent);
  if (event.getKeyCode() == '.'.charCodeAt(0)) {
    // this looks like the '.' is pressed and we might want to replace it
    if (event.getNativeEvent && event.getNativeEvent().charCode==0) {
      // Firefox wrongfully raises this keyPress event on the DELETE
      // button as well. Look at the native event to distinguish and
      // abort. Also see "Special keys" at 
      // http://www.quirksmode.org/dom/events/keys.html
      return;
    }
    if ('.' == this._decimalSeparator) {
      // no need to do anything if decimal-separator of current locale
      // uses decimal dot
      return;
    }
    // replace keystroke of dot on numeric keypad with decimal separator
    // of current locale
    var source = event.getSource();
    AdfLogger.LOGGER.logMessage(AdfLogger.FINE, 
                                "replacing . keystroke with " +
                                this._decimalSeparator + " for " +
                                source.getClientId());
    var input = AdfDhtmlEditableValuePeer.GetContentNode(source);
    if (input) {
      event.cancel(); // cancel normal event to suppress '.' character
      if (typeof(input.selectionStart) !== 'undefined') {
        // gecko, webkit or IE9+ support selection properties
        AdfLogger.LOGGER.logMessage(AdfLogger.FINE, 
          "using selection properties for modern browsers");
        // determine future caret position before we start messing with
        // selection and content
        var newPos = input.selectionStart + this._decimalSeparator.length;
        // inject decimal separator while keeping text before and after
        // selection (thus removing selection)
        var oldtext = input.value;
        input.value = oldtext.substring(0, input.selectionStart) + 
                      this._decimalSeparator +
                      oldtext.substring(input.selectionEnd, 
                                        oldtext.length);
        // set caret position after the decimal separator
        input.selectionStart = newPos;
        input.selectionEnd = newPos;
      } else if (document.selection && document.selection.createRange) {
        AdfLogger.LOGGER.logMessage(AdfLogger.FINE, 
          "using document.selection for older IE versions");
        var sel = document.selection.createRange();
        // replace current selection with decimal-sep or insert at caret
        sel.text = this._decimalSeparator; 
        // collapse selection so caret is after decimal-separator
        sel.setEndPoint("StartToEnd", sel); 
        sel.select();
      }
    }
  }
}

The code should be well documented so reading a couple of times should make clear what it does. Basically we are canceling the key-press event for "." and injecting the decimal separator in the value of the current item at the cursor position or replacing any existing selected text within this item.

Finally the sample page:

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:h="http://java.sun.com/jsf/html"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
          xmlns:redheap="http://redheap.com/taglib">
  <jsp:directive.page contentType="text/html;charset=UTF-8"/>
  <f:view>
    <af:document id="d1">
      <af:form id="f1">
        <af:panelFormLayout>
          <af:inputText label="Browser locale (should use comma decimal separator)"
                        value="#{facesContext.viewRoot.locale}" readOnly="true"/>
          <af:inputText label="Try typing point on decimal keyboard" id="it1">
            <redheap:decimalCommaBehvior/>
          </af:inputText>
        </af:panelFormLayout>
      </af:form>
    </af:document>
  </f:view>
</jsp:root>

As always you can download the full sample application or browse the subversion repository to look at the source code.

Check for postChanges without commit or rollback in ADF BC

2013-10-14T10:34:00.000+02:00

It is not uncommon for an ADF application to invoke DBTransactionImpl::postChanges() to perform database DML without invoking commit (or rollback). This is typically done in environments where we also want to invoke PL/SQL logic in the database that already needs to see these pending changes.

The developer should make sure a commit or rollback is executed in the same JSF request. If this is not done, the database session has pending changes and as we know there is no guarantee a subsequent request by the same user will get the same Application Module and JDBC Connection. It is considered bad practice to have these pending changes survive a single request and today we had a situation where this accidentally happened with all sorts of nasty side-effects. One of the things that happens is that the pending changes also could mean long-lived database locks. We added some code to our ADF BC base classes to detect this and throw an exception so we at least know what is going on and to alert a developer he/she is implementing this bad practice.

First thing we need is to configure our application module to use a custom database transaction class. This is described in the ADF documentation. First we need to create our own DatabaseTransactionFactory so we can use our own subclass of DBTransactionImpl2:

import oracle.jbo.server.DBTransactionImpl2;
import oracle.jbo.server.DatabaseTransactionFactory;

public class MyDatabaseTransactionFactory
  extends DatabaseTransactionFactory
{
  @Override
  public DBTransactionImpl2 create()
  {
    return new MyDBTransactionImpl2();
  }
}

Then we need to make sure this factory class is used instead of the default by setting the TransactionFactory property of the ADF Application Module configuration to the full class name of our own transaction factory:

Set TransactionFactory property of AM Configuration

Next, we can create our own subclass of DBTransactionImpl2 that keeps track of pending postChanges. It sets a flag when postChanges is executed and clears this flag when performing a commit or rollback. We are going to check this flag later on when releasing an Application Module at the end of a request:

import oracle.jbo.server.DBTransactionImpl2;
import oracle.jbo.server.TransactionEvent;

public class MyDBTransactionImpl2
  extends DBTransactionImpl2
{
  private boolean postedChanges = false;

  @Override
  protected void postChanges(TransactionEvent te)
  {
    super.postChanges(te);
    setPostedChanges(true);
  }

  @Override
  protected void doCommit()
  {
    setPostedChanges(false);
    super.doCommit();
  }

  @Override
  protected void doRollback()
  {
    setPostedChanges(false);
    super.doRollback();
  }

  private void setPostedChanges(boolean postedChanges)
  {
    this.postedChanges = postedChanges;
  }

  public boolean isPostedChanges()
  {
    return postedChanges;
  }

}

Final step is to check for pending postChanges at the end of each request. We can do this from our Application Module. This would typically be code you add to your own ADF BC base classes:

import oracle.jbo.ApplicationPoolSvcMsgContext;
import oracle.jbo.JboException;
import oracle.jbo.server.ApplicationModuleImpl;
import oracle.jbo.server.DBTransaction;

public class MyBaseAppModuleImpl
  extends ApplicationModuleImpl
{
  /**
   * This is invoked by the Application Module Pool whenever an 
   * application module is being used, released, removed or recycled
   * from the pool.
   */
  @Override
  public ApplicationPoolSvcMsgContext doPoolMessage(ApplicationPoolSvcMsgContext ctx)
  {
    if (ctx.getMessageType() == 
        ApplicationPoolSvcMsgContext.MESSAGE_TYPE_RELEASING)
    {
      DBTransaction txn = getDBTransaction();
      if (txn instanceof MyDBTransactionImpl2 && 
          ((MyDBTransactionImpl2) txn).isPostedChanges())
      {
        // throwing exception will mark AM as dead and close tainted
        // DBTransaction and JDBC connection
        throw new JboException("Application Module released to the pool with pending posted changes");
      }
    }
    return super.doPoolMessage(ctx);
  }

}

ApplicationModule::doPoolMessage is invoked whenever the pool uses, releases, removes or recycles an application module instance. This can be seen by inspecting ApplicationPoolSvcMsgContext::getMessageType() and comparing to any of the MESSAGE_* constants in ApplicationPoolSvcMsgContext. We check for uncommitted postChanges whenever the application module instance is released to the pool (aka at the end of each request). If these exist we simply throw a JboException. This will not be visible to the end-user as the JSF response has already been completed by then. It will show up in the log for administrators and developers. Because we are throwing an exception during pool management the AM instance will be destroyed together with its JDBC connection. This is actually good as we don't want the AM instance with pending changes, and potential database locks, to linger around.

Update 2 jan: We changed the code to no longer throw an exception thus destroying the applicationModuke, but only log a warning message. Due to an ADF bug we have quite a few AM instances with posted changes at the end of their request. When they get destroyed all ViewObjects loose their where clause and other (or all) records are fetched on the next page request. So until that bug is we fixed we reverted to only logging a warning.

JDeveloper installer very small on Mac OS X

2013-08-22T10:35:00.000+02:00

I have previously installed JDeveloper 11 on my MacBook Pro running Mac OS X Mountain Lion (10.8). Basically you download the generic installer from Oracle and run:

java -jar jdevstudio11124install.jar

Today I tried it again and the installer does start but with a very small screen only showing the exit button:

JDeveloper Installer with only Exit button

As it turns out this is caused by a recent install of JDeveloper 12c on the same machine. That had forced me to install JDK version 7 which is now the default java runtime environment on my machine. Apparently the JDeveloper version 11 installer doesn't like java version 7, at least on Mac OS X.

The solution is rather simple. Run the following commands in a terminal window to start the JDeveloper 11 installer:

wMac:~ wilfred$ /usr/libexec/java_home -v 1.6
/System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
wMac:~ wilfred$ /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home/bin/java -version
java version "1.6.0_51"
Java(TM) SE Runtime Environment (build 1.6.0_51-b11-457-11M4509)
Java HotSpot(TM) 64-Bit Server VM (build 20.51-b01-457, mixed mode)
wMac:~ wilfred$ /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home/bin/java -jar jdevstudio11124install.jar 
Extracting scripts to /var/folders/vl/qsk0dkgn39b2_4sdngwvcf840000gn/T/
Executing MacOS-specific pre-installation scripts
You may be prompted to enter your Mac OS X password in order to create required directories and symbolic links
Extracting 0%....................................................................................................100%

Line 1 runs java_home to get you the full path to the java version 6 home directory. Line 3 uses this path and adds "/bin/java -version" to run java from that directory to check its exact version. Make sure it is in fact a 1.6.0_xx version. Then finally line 7 uses java from that directory to run the installer. This time it just starts fine:

JDeveloper 11 installer runs fine with JDK 6

Credential Store Framework

2013-06-17T17:37:00.000+02:00

Sometimes you have the need for credentials (username/password) in your ADF, or other Fusion Middleware, application. I've seen numerous solutions with property files, web.xml context parameters, deployment plans, etc. Most of these run into problems with SysOps or anyone else worried with security. You don't want these credentials scattered around in plain text files and you don't want developers to know the passwords for each environment. This is better left to configuration by a sys-admin after deployment.

Not everybody seems to know Oracle Fusion Middleware, more specifically Oracle Platform Security Services (OPSS), provides a great solution with the Credentials Store Framework. This is a set of APIs that applications can use to create, read, update, and manage credentials securely.

A credential store is a repository of security data (credentials) that can hold user name and password combinations, tickets, or public key certificates. A credential store can be file-, LDAP- (Oracle Internet Directory), or DB-(Oracle RDBMS)based. A file-based credential store, also referred to as wallet-based and represented by the file cwallet.sso, is the out-of-the-box credential store.

The Credentials Store Framework also limits which application (or components thereof) are allowed to retrieve or modify credentials. This allows for a very secure setup where only trusted libraries that go through extensive auditing are allowed to retrieve credentials.

This post describes the basic steps to get started with the Credentials Store Framework, but more information can be found in the official documentation (Fusion Middleware Application Security Guide):

Chapter 24 - Developing with the Credential Store Framework on how to use the CSF API from your Java application whether it is deployed to a WebLogic server or running as a standalone Java application.
Chapter 8 - Configuring the OPSS Security Store especially if you want to change the default file-based credential store to a database- or LDAP-store which Oracle advices for production usage.
Chapter 10 - Managing the Credential Store on enabling encryption for LDAP- and file-based stores which are clear-text by default and on how to create, update, and delete credentials through Fusion Middleware Control or WLST scripts

The Credential Store is a collection of maps, each with its own name. Each of these maps can store and retrieve credentials or certificates based on a unique key. It's common practice to name each map specific for an application so we can grant as little privileges as possible to this map (and keys).

Step 1 - Add Credentials to a Credential Store

The first step in this example is to add credentials to a credential store. You can use WLST or Fusion Middleware Control. When using the embedded weblogic server that comes with JDeveloper you will have to use WLST scripting as it doesn't have Fusion Middleware Control. I'll explain both approaches below.

Creating credentials with WLST

Ensure the (integrated) WebLogic server is running and start WLST with ORACLE_HOME/oracle_common/common/bin/wlst

Connect to the WebLogic Server from WLST with the correct credentials and t3 URL, for example:

connect('weblogic', 'weblogic1', 't3://localhost:7101')

create a credential with createCred:

createCred(map="mapName", key="keyName", user="secretUsername", password="secretPassword", desc="Description")

I advice to keep the name of the map equal to the adfAppUID as defined in the META-INF/adf-config.xml file of your application:

<adf-config xmlns="http://xmlns.oracle.com/adf/config"
            xmlns:config="http://xmlns.oracle.com/bc4j/configuration"
            xmlns:adf="http://xmlns.oracle.com/adf/config/properties">
  ....
  <adf:adf-properties-child xmlns="http://xmlns.oracle.com/adf/config/properties">
    <adf-property name="adfAppUID"
                  value="ApplicationName.com.redheap.sample"/>
  </adf:adf-properties-child>
</adf-config>

An example would be:

createCred(map="ApplicationName.com.redheap.sample", key="workflowRMI", user="weblogic", password="forYourEyesOnly", desc="Account for RMI calls to Human Workflow Service")

You can use updateCred and deleteCred for other operations.

As a final step you can check if your newly create credential is available in the store:
listCred(map="mapName", key="keyName")

Creating credentials with Fusion Middleware Control

An alternative to WLST scripting is to use the Fusion Middleware Control web interface. The steps are similar although you have to create the map itself first and then create a key within that map. Keep in mind that the credential store is for the entire weblogic domain and not for a specific server or cluster. The credential store can be managed through Domain > Security > Credentials. For more details see Managing Credentials with Fusion Middleware Control

Editing credentials using Fusion Middleware Control

Step 2 - Authorising an a application to retrieve credentials

Credentials from the Credential Store cannot simply be retrieved by any application. A system administrator first has to grant privileges through system policies.

Integrated WebLogic Server in JDeveloper

When developing with a local JDeveloper and WebLogic installation it is easiest to use relaxed security and to give all applications read-access to all credentials. This removes the need to grant permissions to each (test) application over and over again. For a very relaxed policy shutdown your Integrated WebLogic server and edit its system-jazn-data.xml file. On windows this is typically located at %APPDATA%\JDeveloper\system11.x.x.x.x.x.x\DefaultDomain\config\fmwconfig\system-jazn-data.xml. Add the following grant as a child of jazn-data/system-policy/jazn-policy (be very sure to check the location as there is also a admin-policy under system-policy and that's not the one you want):

<grant>
  <grantee>
    <codesource>
      <url>file:/-</url>
    </codesource>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
      <name>context=SYSTEM,mapName=*,keyName=*</name>
      <actions>read</actions>
    </permission>
  </permissions>
</grant>

Managed WebLogic Server

With a properly managed server you don't want to grant every application access to all credentials. Here you want to limit the grants as much as possible. You can add a grant directly in the config file or through Fusion Middleware Control.

Manually granting directly in jazn-data.xml

You can add the necessary grant as a child of jazn-data/system-policy/jazn-policy in DOMAIN_HOME/config/fmwconfig/jazn-data.xml (again be very sure to check the location as there is also a admin-policy under system-policy and that's not the one you want):

<grant>
 <grantee>
  <codesource>
   <url>file:${oracle.deployed.app.dir}/ApplicationName${oracle.deployed.app.ext}</url>
  </codesource>
 </grantee>
 <permissions>
  <permission>
   <class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
   <name>context=SYSTEM,mapName=CredentialMapName,keyName=CredentialKeyName</name>
   <actions>read</actions>
  </permission>
 </permissions>
</grant>

Replace ApplicationName with the name of the deployed application. This is the same as the directory that is created in .../user_projects/domains/DomainName/servers/ServerName/tmp/_WL_USER. Also replace CredentialMapName and CredentialKeyName with the names of the credential map and key to identify which credential can be read by the application.

Adding using Fusion Middleware Control

A less error prone method is to use Fusion Middleware Control to add the grant. Navigate to Domain > Security > System Policies in Fusion Middleware Control. Then press Create... and use the following properties:

Grant to: codebase
Codebase: file:${oracle.deployed.app.dir}/ApplicationName${oracle.deployed.app.ext} (replace ApplicationName with the name of the application, see manual granting for more details)
Press the Add button for permissions

Check Select here to enter details for a new permission. This is a tiny checkbox at the bottom of the popup to start creating a new permission.
Permission Class: oracle.security.jps.service.credstore.CredentialAccessPermission
Resource Name: context=SYSTEM,mapName=CredentialMapName,keyName=CredentialKeyName (replace CredentialMapName and CredentialKeyName with the name of the map and key used when creating the credentials)
Permission Actions (if available): read

WARNING: After making these changes all Managed Servers AND the Admin Server have to restarted to activate these changes.

TIP: More information on the syntax of the codebase URL, and the use of wildcards, can be found in Appendix B - File-Based Identity and Policy Store Reference

Step 3 - Retrieving Credentials in Application

In Java we need to use the AccessController to execute the code to retrieve credentials from the store with elevated privileges. The code itself will use oracle.security.jps.service.credstore.CredentialStore to retrieve the credentials. See the simplified example below for a factory class that can create a Connection object with credentials form the credential store. Most connection objects won't expose the credentials used for that connection to their user. This means you can package this factory class in a separate library and only allow that library access to the credential store. That way you only have to audit/review this single library and not all other application code for places where the credentials might leak out.

import java.security.AccessController;

import java.security.PrivilegedActionException;
import java.security.PrivilegedExceptionAction;

import oracle.adf.share.ADFContext;

import oracle.security.jps.JpsException;
import oracle.security.jps.service.JpsServiceLocator;
import oracle.security.jps.service.ServiceLocator;
import oracle.security.jps.service.credstore.PasswordCredential;
import oracle.security.jps.service.credstore.CredentialStore;

public final class ConnectionFactory {

    /**
     * Retrieves credentials from the Credential Store where the current
     * application UID is used as the name of the credential map.
     * This method must be called through AccessController.doPrivileged
     * @param key name of the key in the credential map to retrieve
     * @return PasswordCredential if exists, null otherwise
     * @throws JpsException
     */
    private PasswordCredential _readCredentials(String key) throws JpsException {
        ServiceLocator locator = JpsServiceLocator.getServiceLocator();
        CredentialStore store = locator.lookup(CredentialStore.class);
        // always use application UID as name for the credential map to ensure
        // each application uses its own map and credentials aren't shared
        String map = ADFContext.getCurrent().getADFApplicationUID();
        return (PasswordCredential)store.getCredential(map, key);
    }

    /**
     * Retrieves credentials from the Credential Store by invoking
     * {@link #_readCredentials} as a privileged action.
     * @param key name of the key in the credential map to retrieve
     * @return PasswordCredential if exists, null otherwise
     * @throws JpsException
     */
    private PasswordCredential readCredentials(final String key) {
        PasswordCredential credentials;
        PrivilegedExceptionAction<PasswordCredential> action =
            new PrivilegedExceptionAction<PasswordCredential>() {
            public PasswordCredential run() throws JpsException {
                return _readCredentials(key);
            }
        };
        try {
            credentials = AccessController.doPrivileged(action);
        } catch (PrivilegedActionException e) {
            throw new RuntimeException(e);
        }
        return credentials;
    }

    /**
     * Factory method to create connection with credentials from Credential
     * Store.
     * @return new connection
     */
    public Connection createWorkflowConnection() {
        // use fixed key so the user of this factory is not allowed to
        // create a connection based on any arbitrary credential
        PasswordCredential cred = readCredentials("workflowRMI");
        // TODO: create and return connection with information from
        //       cred.getName() and cred.getPassword();
        return null;
    }
}

If the oracle.security.jps.* classes are not available to your project be sure to include the JRF Client or JRF Runtime library in your project settings.

TIP: If you miss the necessary system policy grant your application won't be allowed to retrieve the credentials. The raised AccessControlException is normally not shown to the end user or logged to your console. Add -Djps.auth.debug=true to your application startup parameters (and restart weblogic) to display these errors in your console. If you also want to see which codebase is used to retrieve the credentials, you can also add -Djps.auth.debug.verbose=true but be warned that this also logs every successful access so your console will quickly fill up. This way we found out that the codebase for one of our sample applications running on Windows was file:/C:/Users/xxx/AppData/Roaming/JDeveloper/system11.x.x.x.x.xx.x/DefaultDomain/servers/DefaultServer/tmp/_WL_user/ApplicationName/36wlms/war/WEB-INF/lib/credentials-1.0.jar. Together with the previous information on wildcards in the codebase URL this can help you fine tune the system policies.

Keep in mind that declarative ADF Connections (the ones you can edit in the JDeveloper IDE) can be changed through Fusion Middleware Control or WLST as described by Edwin Biemond from AMIS. The Oracle Credential Store Framework is more for situations where you are programmatically creating connections to backend systems or other situations where you need credentials. If you have any remaining questions just post them below and I'll try to answer them.

Customizing JDeveloper Preferences

2013-05-08T10:47:00.000+02:00

I like to tweak some of the preferences in the Tools menu of JDeveloper. I thought I would document them here for my own reference and in case anyone else is interested. I'll try to list all the settings I typically change from their default. These are ordered and grouped by their panels in the preferences dialog so you should be able to locate them easily.

Environment

Line Terminator to "Line Feed (Unix/Mac)" especially if you are in a mixed environment with windows and linux/mac developers as it prevents a lot of problems if everyone creates the files in the same way.
Encoding to "UTF-8". I have no idea why the default is platform dependent (MacRoman or some obscure windows code page). I like all developers in the team to use the same encoding. This is also used as encoding in XML files you create. Changing it afterwards can be a lot more work as existing files might need recoding

Environment > Log

Maximum Log Lines to something like 50000. The default of 3000 can be too small if you crank up the logging levels in a development session.

ADF Business Components

Look at all these settings carefully (and read below). Lots of these settings are used when creating new ADF BC objects so be careful to set these up before you start developing as it can safe a lot of rework later

ADF Business Components > Base Classes

You can set the default base classes for any ADF BC object you will create in JDeveloper. It is wise to create company wide extension classes for these and configure JDeveloper to use your company extended classes instead of the JDeveloper base ones. You could even create a layer of extension classes for your project (extending from company classes) and setup the per-project settings to use these application level extension classes

ADF Business Components > Packages

A lot of developers like to group their ADF BC objects per type in separate sub packages. For instance put all view objects in a subpackage .views or .queries. In stead of remembering to set these sub packages each time you are creating ADF BC objects simply set the defaults here.

ADF Business Components > View Objects

You could set the default fetching tuning parameters for new view objects here. But in reality they need consideration for each view object you create. One trick we used in the past is to set a ridiculous default value here and then check for that ridiculous value in your extended ADF ViewObject classes. If the developer left the ridiculous initial value simply throw an exception telling the developer to set reasonable values.

Audit

The JDeveloper Audit framework is under-appreciated. I would advise to tweak the Code Assist Rules that you see while developing. Go over the rules that are disabled by default and see if you want to enable them. My guess is you can enable most of them, especially to warn developers about missing or incorrect javadoc. Also be sure to check the "Audit During Compile" with perhaps a slightly less restrictive set to prevent your developers from violating certain rules. The next step would be to monitor these quality issues from your continuous build server

Code Editor

I like to enable "Reformat Code Block When Pasting". That is mainly since I tend to keep most of my code auto-formatted so reformatting when pasting someone else's code seems like a good idea.
One other thing I like to enable is "Show Total Number of Lines in the Status Bar" just to remind to keep the files small and simple.

Code Editor > Code Templates

You can add your own code templates here. We've added a bunch to easily use ADFLogger in your Java source code. More on that in a future post.

Code Editor > Display

Enable Text Anti-Aliasing because it just looks better :-)

Code Editor > Line Gutter

Enable "Show Line Numbers"

Code Editor > Save Actions

These are actions that JDeveloper should perform on each file you save. I typically add "Organize Imports", "Trim Trailing Whitespace" and "Clear All Highlighting". I've tried using Reformat as well which is great for Java sources which should always be formatted by a tool for consistency. But JDeveloper will then also reformat all XML files including JSF pages. In those files it is much more common to perform manual formatting and I don't like the always-auto-format of these save actions.

Compiler

Enable "Clean Project Before Project Rebuild". If you are rebuilding your entire project I see no reason why you don't want to start with a clean project first. Otherwise you might run the risk of keeping compiled artifacts for source objects you have already removed.

CSS Editor

If you do anything with ADF skinning be sure to set the CSS level to Level 3 (and on JDev 11gR1) enable the ADF Faces Extensions checkbox

Debugger

Check "Show Action Buttons" to get the debugger buttons (step, continue, etc) also in the log window of JDeveloper.

Debugger > Beakpoints

Set the scope for new breakpoints to Global. Especially if you are building on a large system with multiple workspaces. With the default setting your debugger will not stop if you set a breakpoint in one workspace and run the application from another workspace. My workflow is to keep the number of breakpoints limited and I frequently clean them. I would like the confidence that a breakpoint is always used.

Debugger > Data

I personally don't like the new Tree View in the 11gR2/12c debugger where you drill down into objects and have to traverse back up. I prefer the old-style Table View so I change the default view here.

Debugger > Smart Data

I like to increase the "Number of Lines to Analyze" to something like 5 to show a bit more information in this debugger panel.
I personally don't like the new Tree View in the 11gR2/12c debugger where you drill down into objects and have to traverse back up. I prefer the old-style Table View so I change the default view here.

Debugger > Watches

I personally don't like the new Tree View in the 11gR2/12c debugger where you drill down into objects and have to traverse back up. I prefer the old-style Table View so I change the default view here.

File Types

I like to change the default editor panel used for certain files. I don't like JSF files to open in design WYSIWYG mode as initializing that editor can be slow. I prefer these to start in source view and I can always switch to the design tab if needed. You can set this in the Default Editors tab of these preferences. I like to set this to "Source" for "ADF Fragment File", "HTML Source", "HTML Template", "JSFF Label", "JSP Segment", "JSP Source", "XHTML/Facelets Source" and "XHTML Source" (not all of these exist in every version of JDeveloper)

News (JDev 12c only)

Add http://feeds.feedburner.com/RedHeap to the list of News Feeds to get Red Heap posts in JDeveloper :-)

Run > WebLogic

On 11gR2 only enable FastSwap deployment to you can make more changes to a deployed application without doing a full redeploy. Unfortunately this feature is not available on 11gR1.

Web Browser and Proxy

If your organisation uses a web proxy be sure to fill in these details so JDeveloper can access the internet for things like checking for updates. You can also set you default web browser here in case that is different from the default browser of your operating system. I like to use Google Chrome as my development browser and sometimes you cannot change the default web browser of your operating system due to administrator restrictions.
When using Chrome as your browser be sure to start it in incognito mode. This ensures you start with a clean browser each time you start your application. In JDeveloper 11g you can simply add --incognito to the command line of chrome while JDeveloper 12c allows you to specify --incognito ${URL} as command line parameters.

Some other things I would like to chance with a default JDeveloper installation:

Select Tools > External Tools and let JDeveloper create the default external tools when running on Microsoft Windows. This gives you a convenient right-click on all your objects to start a windows explorer in that specific source directory. Something I frequently use, for example to get access to TortoiseSVN on that file. On Mac I like to setup this to run a terminal from the selected directory.
Change the memory options in JDEV_HOME/ide/bin/ide.conf. On a 32-bit JVM I like to set both -Xmx and -Xms to 1200M. On a 64-bit JVM you could even go a bit higher, like 1500M or 2000M.
When running with non-English regional settings on your operating system, edit JDEV_USER_HOME/system11.x.x.x.x.x.x/DefaultDomain/bin/setDomainEnv.cmd, search for the lines where EXTRA_JAVA_PROPERTIES are set and add a line
set EXTRA_JAVA_PROPERTIES=-Duser.language=en -Duser.country=US %EXTRA_JAVA_PROPERTIES%
This enforces WebLogic to use en_US as locale so error messages in the JDeveloper Log window are English and not the language from your operating system. This makes googling for these error messages much easier ;-)
While you're already editing JDEV_USER_HOME/system11.x.x.x.x.x.x/DefaultDomain/bin/setDomainEnv.cmd you might just as well increase the memory for WebLogic. Search for the lines where XMS_SUN_64BIT, XMS_SUN_32BIT, XMX_SUN_64BIT and XMX_SUN_32BIT are set. My advice is to change all four to 1024 but you might want to tweak this for your situation.
When using JDeveloper 12.1.2 you can set memory arguments in JDEV_USER_HOME/system12.1.2.x.x.x.x/DefaultDomain/bin/setStartupEnv.cmd in the section for AdminServerStartupGroup.

ADF Faces Client Behavior with Attributes

2013-03-15T22:35:00.002+01:00

Last month I posted about the basics of creating custom ClientBehavior in ADF Faces. Now it is time to take the next step and enhance that example with ways to set attributes on the JSP client-behavior tag, pass these on to the client-side javascript implementation and use them in the actual functionality.

We'll take the (simplified) example of the previous post that could show a javascript alert and adopt it to get the message from an attribute which we specify in the JSF page using the component. We'll also make sure we can use an EL expression to specify this values (this is the tricky part). We will be able to do something like:

<af:forEach begin="1" end="5" varStatus="vs">
  <af:commandButton text="click to see message #{vs.index}" id="cb">
    <redheap:showAlertBehavior message="This is message #{vs.index}"/>
  </af:commandButton>
</af:forEach>

Add Attribute to Tag Library Descriptor

The Tag Library Descriptor (TLD) describes the JSP tag itself and which attributes it supports. This is used when parsing the JSP/JSF files and also by JDeveloper for things like code completion and the property palette. Add the attribute to the tag in the TLD file:

<tag>
  <description>Describe your component here</description>
  <name>showAlertBehavior</name>
  <tag-class>com.redheap.clientbehavior.ShowAlertBehaviorTag</tag-class>
  <body-content>JSP</body-content>
  <attribute>
    <description>Message text to show in JS alert</description>
    <name>message</name>
    <required>true</required>
    <deferred-value/>
  </attribute>
</tag>

Adding Attributes to the JSP Tag Handler

Next part is the Java code. The JSP Tag Handler class is the Java implementation of the tag in the JSPX/JSF document. This is the com.redheap.clientbehavior.ShowAlertBehaviorTag class from our previous example. First thing to add is a member variable and a setter method:

    private ValueExpression message;

    /**
     * Set the message to show in the javascript alert.
     * @param message message to show in the alert
     */
    public void setMessage(ValueExpression message) {
        this.message = message;
    }

Evaluating EL Expression Attributes

In our previous sample without attributes we implemented the getBehavior method to return a snippet of javascript to instantiate a javascript object that implements the client side behavior. This time we have to pass the message text to this client side implementation. Complicating factor is that this message text can come from an EL expression and we have to evaluate this EL expression with the correct context. Let's take the example from the introduction:

<af:forEach begin="1" end="5" varStatus="vs">
  <af:commandButton text="click to see message #{vs.index}" id="cb">
    <redheap:showAlertBehavior message="This is message #{vs.index}"/>
  </af:commandButton>
</af:forEach>

In this example we not only have to evaluate the #{vs.index} expression but we also have to do it at the correct time. We cannot do it when the tag handler is created but we have to wait until it is actually asked to create the javascript snippet as we need the correct ELContext to resolve vs.index to the actual row we are currently handling. The trick is to implement getBehaviorExpression instead of getBehavior. This can return a javax.el.ValueExpression that is evaluated at the correct time with the correct ELContext:

    @Override
    protected String getBehavior(UIComponent component) {
        return null;
    }

    @Override
    protected ValueExpression getBehaviorExpression(UIComponent component) {
        return new ShowAlertValueExpression(message);
    }

Now the burden is on com.redheap.clientbehavior.ShowAlertValueExpression which is a subclass of javax.el.ValueExpression. It has to return the value of this expression in the getValue method that gets the correct ELContext from the framework:

public class ShowAlertValueExpression extends ValueExpressionImpl {

    private ValueExpression message;

    public ShowAlertValueExpression(ValueExpression message) {
        this.message = message;
    }

    @Override
    public Object getValue(ELContext context) {
        Object msg = message.getValue(context);
        String strmsg = msg == null ? "" : msg.toString();
        return "new RedHeapShowAlertBehavior('" +
            StringEscapeUtils.escapeJavaScript(strmsg) + "')";
    }
}

It returns a snippet of javascript that instantiates a client side javascript object that handles the implementation. The actual message to show is supplied to the constructor as an argument, for example:

new RedHeapShowAlertBehavior('this is the message');

Pro Tip: we use the StringEscapeUtils from org.apache.commons.lang. This is already available on your weblogic server (albeit an older 2.1.0 version). All you have to do is to add the "WebLogic 10.3 Remote-Client" library to your project to extend your compile time classpath. Runtime is already taken care of since it is on your weblogic server.

Client Side JavaScript

Final step is to change the client side javascript object to receive and use the message attribute. We add an argument to the constructor and pass it to the initialization method which stores it in a member variable of the javascript object:

function RedHeapShowAlertBehavior(msg) {
  this.Init(msg);
}

RedHeapShowAlertBehavior.prototype.Init = function(msg) {
  RedHeapShowAlertBehavior.superclass.Init.call(this);
  this._msg = msg;
}

And of course the actual event handling code must use this value in showing the alert:

RedHeapShowAlertBehavior.prototype._handleAction =
function(event) {
  AdfAssert.assertPrototype(event, AdfUIInputEvent);
  alert(this._msg);
  event.cancel(); // cancel normal event processing
}

Usage in JSPX

Finally here is the JSPX source of a simple test page that uses the client behavior to show a message:

<af:commandButton text="click for static message" id="cb1">
  <redheap:showAlertBehavior message="static sample message"/>
</af:commandButton>
<af:commandButton text="click for dynamic message" id="cb2">
  <redheap:showAlertBehavior message="#{'dynamic sample message'}"/>
</af:commandButton>
<af:forEach begin="1" end="5" varStatus="vs">
  <af:commandButton text="click foreach message #{vs.index}" id="cb3">
    <redheap:showAlertBehavior message="message number #{vs.index}"/>
  </af:commandButton>
</af:forEach>

And here is the final result:

Custom Client Behavior triggering a javascript alert

Sample Application

As always you can download the full sample application or browse the subversion repository to look at the source code. The subversion project started as a copy of the previous sample without parameters, so look at the revision history to so the details of what was changed to support attributes. And even though it is not the most fancy application you can also see it live on Oracle Cloud.

Custom ADF Faces Client Behavior 11.1.1 JSP tag

2013-02-02T12:03:00.000+01:00

This post will show how to create your own ADF Faces client behavior JSP tags which makes them suitable for ADF version 11gR1, also known as version 11.1.1, and version 11gR2 (11.1.2) when not using Facelets.

ADF Faces client behavior tags provide declarative solutions to common client operations that you would otherwise have to write using JavaScript, and register on components as client listeners.

Using tags makes behavior much more reusable. All a page developer has to do is drag-and-drop the client behavior tag on the appropriate component and not worry about writing JavaScript and attaching the appropriate client listeners. ADF Faces 11gR1 has a number of client behavior tags and a couple more were added in version 11.1.2. Some examples are the af:showPopupBehavior to disclose a popup or the af:scrollComponentIntoViewBehavior to scroll the page.

Wouldn't it be great if we can create our own client behavior tags for things that ADF doesn't support out of the box? There are a number of blogs out there that describe something like that, such as placeholder watermarks by Duncan Mills and setting the initial focus component by Donatas Valys. Unfortunately those blogs describe how to do this with facelets which requires JDeveloper 11.1.2 We needed a solution for JDeveloper 11.1.1 and thus JSP tags.

Update: A follow-up post is available that explains how to add support for attributes to your custom client behavior.

There are a number of things we need to get this to work:

JSP tag handler java class
Tag library descriptor (.tld) file to register the JSP tag
javascript file with the object that implements the client behavior
adf-js-features.xml to register with the ADF Faces JavaScript Library Partitioning framework to dynamically load the javascript when needed
Deploy this as a library so we can consume it in any project we want
Optionally enhance the tag and behavior to accept attributes to customize the behavior

Read on as we discuss these step by step based on a overly simplified example of showing a javascript alert when clicking a command component like a button. Remember this blog post is about showing how to wire everything up not about an actual useful client behavior. I will cover some real world examples in future posts.

JSP Tag Handler

First let's start with writing the JSP tag handler. This is a java class that represents the actual tag in a JSP document. It is responsible for receiving any attribute values from the JSP document and normally instantiates the JSF component. In this case we don't really have a server side JSF component as we are implementing client behavior. The easiest way to accomplish this is to extend the class that the out-of-the-box ADF Faces behaviors also use. The class to extend is oracle.adfinternal.view.faces.taglib.behaviors.BehaviorTag. Unfortunately this class is in the oracle.adfinternal package which means it is not part of the public javadoc and it might change in a future version as it is not an official public API. The easiest way to understand what is going on is to get a copy of the ADF source code from Oracle support and have a look for yourself.

package com.redheap.clientbehavior;

import javax.faces.component.UIComponent;

/**
 * Implementation of showAlertBehavior JSP tag.
 * @author Wilfred van der Deijl, www.redheap.com
 */
public class ShowAlertBehaviorTag
  extends oracle.adfinternal.view.faces.taglib.behaviors.BehaviorTag {

    /**
     * Returns the snippet of javascript code that needs to be executed
     * on the client to construct the client behavior object.
     * @param component JSF component this behavior tag is attached to
     * @return snippet of javascript that instantiates an object
     */
    protected String getBehavior(UIComponent component) {
        return "new RedHeapShowAlertBehavior()";
    }

    /**
     * Returns the name of a JavaScript library feature that provides
     * the client-side implementation of this listener/behavior.
     * This feature will be added to the set of features required for
     * this page/request, ensuring that corresponding JavaScript
     * library partition is available.
     * @return a javascript library feature name
     */
    @Override
    protected String getFeatureDependency() {
        return "RedHeapShowAlertBehavior";
    }

}

The javascript class that is returned by getBehavior will be implemented in a javascript file below, while the behavior returned by getFeatureDependency is registered in a xml file below.

Pro Tip: As an alternative to getBehavior(UIComponent) you can also implement getBehaviorExpression(UIComponent) that doesn't return javascript itself but a ValueExpression that should evaluate to the javascript snippet. The benefit of this approach is that the ValueExpression is executed with the correct ELContext. An example would be a behavior in an ADF Table or Iterator where you need access to the iterator or row variable.

Tag Library Descriptor

Next thing we need is a tag libary descriptor file so the JSP parser understands our <redheap:showAlertBehavior> tag and links it to the java class we just created. Use the New Gallery (from the File menu) to add a JSP Tag Library:

new gallery for JSP taglib

Most of the time you will be making these behaviors with reuse in mind, so we opt to create a deployable tag library that is intended to be used in a library that we include with all of our projects. If you want behavior tags just for your one project you could also create a project based taglib:

deployable taglib

Finally we have to supply the information for the taglib itself. Use sensible values in your situation and remember the taglib URI doesn't have to be a real URL it just has to be a globally unique identifier, much like a XML namespace:

supplying taglib information

Finish the wizard with all default values and you should end up in the editor for your new taglib file which should be located in the src/META-INF directory. Add a single tag to the taglib xml file and point it to the tag class we just created:

<?xml version = '1.0' encoding = 'UTF-8'?>
<taglib xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-jsptaglibrary_2_1.xsd"
        version="2.1" xmlns="http://java.sun.com/xml/ns/javaee">
  <description>Describe the purpose of your library here</description>
  <display-name>redheap</display-name>
  <tlib-version>1.0</tlib-version>
  <short-name>redheap</short-name>
  <uri>http://redheap.com/taglib</uri>
  <tag>
    <description>Describe your component here</description>
    <name>showAlertBehavior</name>
    <tag-class>com.redheap.clientbehavior.ShowAlertBehaviorTag</tag-class>
    <body-content>JSP</body-content>
  </tag>
</taglib>

One thing to note is that the short-name of the taglib itself will be used as the prefix of the tags in JSP documents (the redheap in <redheap:showAlertBehavior>) while the display-name will show up in the dropdown of component families in the component palette in JDeveloper.

Javascript Client Behavior Implementation

The tag handler java class returned a snippet of javascript that instantiates a RedHeapShowAlertBehavior. Next thing we need to do is to actually implement this class in a javascript file.

new gallery for javascript file

This file doesn't have to be in the publicly accessible public_html directory but can be safely tucked away in the java src directory as it will be loaded by the ADF framework from the classpath and not directly by the client browser (more on that later). I opted to put the javascript file in the same package as the tag handler:

put the javascript file in the src directory

All that is left is to actually implement the javascript:

/**
 * javascript constructor that invokes the Init function
 */
function RedHeapShowAlertBehavior() {
  this.Init();
}

// register as a subclass of AdfClientBehavior
AdfObject.createSubclass(RedHeapShowAlertBehavior,
                         AdfClientBehavior);

/**
 * initialize this behavior
 * @override
 */
RedHeapShowAlertBehavior.prototype.Init = function() {
  // be sure to invoke initialization by superclass
  RedHeapShowAlertBehavior.superclass.Init.call(this);
}

/**
 * as part of the AdfClientBehavior behavior contract, initialize is
 * called when the component is created to give the behavior a chance
 * to register event listeners.
 * @param {AdfUIComponent} component
 */
RedHeapShowAlertBehavior.prototype.initialize =
function(component) {
  AdfAssert.assertPrototype(component, AdfUIComponent);
  component.addEventListener(AdfActionEvent.ACTION_EVENT_TYPE,
                             this._handleAction, this);
}

/**
 * handle invoking a command component with this behavior.
 * @param {AdfUIInputEvent} event
 */
RedHeapShowAlertBehavior.prototype._handleAction =
function(event) {
  AdfAssert.assertPrototype(event, AdfUIInputEvent);
  alert('Yes we managed to trigger the client behavior');
  event.cancel(); // cancel normal event processing
}

We are registering this behavior class as a subclass of AdfClientBehavior just as the default ADF behaviors. This ensures the initialize method (lines 28-32) is called with a reference to the JSF component we are adding behavior to. All we do there is register appropriate event listeners on the component, in this instance for the action (click) event. There are many types of events you can choose from but all of them are subclasses of AdfComponentEvent. In this example we listen to the action event which is defined in AdfActionEvent while keyboard events live in AdfUIInputEvent.

Whenever the user clicks the JSF command component our handler (lines 39-43) will be invoked. In this example we only show a javascript alert and cancel the event itself to prevent normal processing. This prevents the default handling of a button to submit the page to the server.

Register Javascript Feature

Registering an ADF javascript feature has the benefit of ADF taking care of dynamically loading the necessary javascript files when needed and as an added bonus it will take care of appropriate http headers to influence caching of these resources. Start by adding a XML file to your project:

new gallery for XML document

Be sure to name the file adf-js-features.xml and it has to be located in the src/META-INF directory otherwise the framework cannot find it:

creating src/META-INF/adf-js-features.xml

Register your javascript feature in this file. The feature-name has to match the name that was returned by getFeatureDependency() in your tag handler class while feature-class is the path to your javascript file within the classpath:

<?xml version="1.0" encoding="UTF-8" ?>
<features xmlns="http://xmlns.oracle.com/adf/faces/feature">
  <feature>
    <feature-name>RedHeapShowAlertBehavior</feature-name>
    <feature-class>com/redheap/clientbehavior/RedHeapShowAlertBehavior.js</feature-class>
  </feature>
</features>

Library Deployment And Usage

All that is left is to bundle this all up as a library and consume it in any project you like. First thing you have to do is set the compiler options in your project properties to also include javascript files. Double click the project in JDeveloper and add ;.js to the file types to copy to the output directory:

setup project to copy javascript to output directory

If you added the tag library through the wizards JDeveloper already added a deployment profile to the project. This profile is fine for these simple cases although you could also setup an ADF Library that includes both this behavior and some reusable ADF components. For now, let's just use the default taglib deployment profile:

deploy using default taglib deployment profile

Now open the project where you want to consume this library. Double click the project to open the project properties. Navigate to the JSP Tag Libraries and add a new one to the project:

adding JSP taglib to the project

add JAR library to the project

Browse to the JAR file we just created. When returning to the JSP Tag Library dialog check the checkbox to execute the tags in the visual editor. For behaviors there isn't really a need to run these in the visual editor in JDeveloper but we might add JSF or ADF components at a later stage that actually render something in the visual editor:

execute tags in visual editor

Now finally build a simple page an in the visual editor select the new component family in the component palette:

select component family

Drag and drop the behavior on the component where you want to use it:

drag-and-drop behavior on component

Finally run the page and click the button to see the behavior in action as it shows a javascript alert:

running sample

Future Posts

This post has already grown too big, so I'll try to wrap up and keep the other stuff for future posts. Things I still have to cover is how to pass parameters to the behavior (like customizing the message in this alert), how to complement the sample with a facelets tag library so it will also work in version 11.1.2 when using facelets and one real world sample where we use keyboard listener to insert a comma as decimal mark when the user is using the dot on the numerical keyboard.

Sample Application

As always you can download the full sample application or browse the subversion repository to look at the
source code. And even though it is not the most fancy application you can also see it live on Oracle Cloud.

Update

A follow-up post is available that explains how to add support for attributes to your custom client behavior.

Deploy a simple ADF application to Oracle Cloud

2013-02-01T21:41:00.001+01:00

I write sample applications to accompany blog posts. You can typically download the project as a zip file or get access to the subversion repository. But I also wanted to make it as easy as possible for people to see the running application. This where the Oracle Cloud comes in. I currently still have a free trial java cloud and this posts explains how I deployed one of the sample applications to that cloud.

First thing you need is the latest version of JDeveloper 11.1.1.6. If you already have JDeveloper installed be sure to check Help > About for the version number. For reasons beyond my comprehension Oracle decided to give the JDeveloper version with cloud support the same version number. The one you need is build 6229 and not the original build 6192:

Get the credentials that you use to logon to your Oracle cloud. This is a username, password and identity domain:

get credentials for oracle cloud

Then we need to register an Application Server connection to the Oracle Cloud with these credentials. From the resource palette (View > Resource Palette) add a new connection:

Be sure to select "Oracle Cloud" as the connection type:

select Oracle Cloud as connection type

;

enter your Oracle Cloud credentials

enter identity domain and name of the service instance

When using a trial cloud instance your service instance is typically called "java". You can see this in your Oracle Cloud dashboard.

I want my applications to be publicly available on the Oracle Cloud and not requiring any logon credentials. To accomplish this add an empty login-config entry to the web.xml file:

  ......
  <!-- empty logon-config to allow anonymous access on Oracle Cloud -->
  <login-config/>
</web-app>

I also added a welcome-file to the web.xml so requests to xxx.oraclecloudapps.com/Application get redirected to xxx.oraclecloudapps.com/Application/faces/defaultPage:

  ......
  <!-- set welcome file so requests to / get redirected to the default page -->
  <welcome-file-list>
    <welcome-file>/faces/demo</welcome-file>
  </welcome-file-list>
</web-app>

If I forgot either of the above steps I would get an Error 403 - Forbidden when trying to access the homepage of my application:

403 error when not disabling security or setting homepage redirect

Now you can deploy from within JDeveloper as you would always do to a remote application server:

deploying the application

log of deploying the application

If you now visit your Oracle Cloud console you can monitor the application and get the URL to run it. (BTW the run URL was also in the deployment log in JDeveloper)

open the java service console from your dashboard

monitor the instance and applications

So here it is my very first live sample application on the Oracle Cloud. It is the sample from a previous blogpost on a DateTimeConverter that accepts dates without separators.

Performance diagnostics with ADFLogger

2013-01-30T20:07:00.000+01:00

This post will show how to use the ADF Logger for performance analysis and how to instrument your own code so it shows up in this analysis. Every ADF developer should know, or learn, about the ADF Logger. If you are new to the logger than read up on it at the official documentation or the great Adventures in Logging series by Duncan Mills.

Configuring Oracle Diagnostic Logging

First thing we need to do is to configure the proper ADF Logger levels as the default levels will only show warning and errors. Run your application so the integrated WebLogic server starts. The log window in JDeveloper will have an Actions pull down menu where you can opt to configure Oracle logging:

configuring Oracle Diagnostic Logging

This will open an editor to the logging configuration file at DefaultDomain/config/fmwconfig/servers/DefaultServer/logging.xml which is typically in JDEV_USER_HOME/system11.1.1.6.38.61.92

All the logging for performance diagnostics is done at the CONFIG level so be sure to set the Root logger and Oracle logger to CONFIG. While developing you might even want to crank up the levels for oracle.adf, oracle.adfinternal and oracle.jbo to FINEST but be aware that this will show a lot more logging which has a performance impact of its own.

Run bad performing application

Once this is done we return to our simple example application and apply a filter to an af:table that is based on a bean datacontrol:

filtering af:table that re-fetches data from slow data control

From the logging we can see that the employees are fetched again. This might be a surprise since the page had already retrieved the list of employees from the bean datacontrol. Why would filtering need to request the data from the data control again? When we experience bad performance in an application it would be nice if we can quickly analyze the logs and discover where time is spent.

logging showing up in console

Analyze Log

Luckily we instrumented our code to use the ADFLogger. This not only writes a line to the log window, but also makes it part of the log analysis. To see this working invoke the log analyzer from the same pull down menu in the log window:

starting log analyzer

We can now inspect individual requests and drill down in the separate phases. We can quickly see our fetchEmployees method was executed in this last request and it took 2973 milliseconds to complete.

log analyzer showing our own instrumented code

Instrument Your Code

The key to making this work is to invoke ADFLogger::begin and ADFLogger::end in your code. You should do this before and after any code that can be time consuming, for example requesting a URL, invoking a webservice, very expensive calculations, interacting with the file system, etcetera.

Once you invoke ADFLogger::begin you have to make absolutely sure you also invoke ADFLogger::end even when exceptions occur. For this reason, you would typically use a try-catch-finally construct:

logger.begin("[[DESCRIPTION]]");
try {
  // TODO: do your stuff here
} finally {
  // make sure you always call ADFLogger::end with same description
  logger.end("[[DESCRIPTION]]");
}

One other nice feature about Oracle Diagnostic Logging is that you can supply additional context with a log message that will not clutter the default console logging but is available in the more advanced viewers such as the log analyzer. In this example you can see the java.specification.version but in a real application you would typically log information about the resource intensive task such as the URL being retrieved, query being performed or file being read.

log analyzer showing supplied context

Unfortunately ADFLogger::begin requires a full blown java.util.HashMap with this context. First of all it is bad practice to require specific classes when the java.util.Map intreface would suffice. But more annoying is that constructing a HashMap can require quite some lines of code which would clutter your java code. For this, I created a utility class that accepts a set of Strings as varargs. The list of strings you supply as arguments are alternating keys and values hence the requirement for an even number of parameters.

public class LoggingUtil {
  private LoggingUtil() {}
  public static void begin(final ADFLogger logger, final String action,
                           final String... context) {
    if (context.length % 2 != 0) {
      throw new IllegalArgumentException("even number of context parameters required (alternating keys and values)");
    }
    final HashMap<String, String> map = new LinkedHashMap<String, String>();
    for (int i = 0, cnt = context.length; i < cnt; i += 2) {
      map.put(context[i], context[i + 1]);
    }
    logger.begin(action, map);
  }
  public static void end(final ADFLogger logger, final String action) {
    logger.end(action);
  }
}

This keeps the actual java code very clean of logging code as constructing the HashMap is done in the utility class and only if the logging level actually needs this additional context:

public List<Employee> getEmployees() {
  LoggingUtil.begin(logger, "fetchEmployees",
                    "java.specification.version",
                    System.getProperty("java.specification.version"));
  try {
    fetchFromSlowSource();
    return employees;
  } finally {
    LoggingUtil.end(logger, "fetchEmployees");
  }
}

You can download the full sample application or browse the subversion repository to look at the source code. When running this application yourself be sure to setup the logging levels of your WebLogic server appropriately.

SyntaxHighlighter at Blogger

2013-01-30T15:30:00.000+01:00

Running a tech/developer blog means I will be posting source code and other technical text. This requires proper syntax highlighting and use of monospaced fonts. Unfortunately blogger.com doesn't really support this out of the box so we need to resort to 3rd parties. Alex Gorbatchev created an awesome syntax highlighter purely in javascript. This means it doesn't need a server side component and we can easily integrate it into blogger.

To integrate SyntaxHighlighter into blogger you have to edit the HTML of your template:

how to get to editing your blogger template

Next you have to insert some javascript and CSS just after the title tag:

editing the template html

Here is the snippet I inserted:

<script src="http://alexgorbatchev.com/pub/sh/current/scripts/shCore.js" type="text/javascript"></script>
<script src='http://alexgorbatchev.com/pub/sh/current/scripts/shBrushJava.js' type='text/javascript'></script>
<script src='http://alexgorbatchev.com/pub/sh/current/scripts/shBrushXml.js' type='text/javascript'></script>
<script type='text/javascript'>
  SyntaxHighlighter.config.bloggerMode = true;
  SyntaxHighlighter.defaults['auto-links'] = false;
  SyntaxHighlighter.defaults['tab-size'] = 2;
  SyntaxHighlighter.defaults['toolbar'] = false;
  SyntaxHighlighter.all();
</script>
<link href="http://alexgorbatchev.com/pub/sh/current/styles/shCore.css" rel="stylesheet" type="text/css">
<link href="http://alexgorbatchev.com/pub/sh/current/styles/shThemeDefault.css" rel="stylesheet" type="text/css">

The first line loads the core javascript and then I load the javascript for each type of brush I intend to use. A full list of brushes/syntax files and the required javascript can be found at Alex' site.

After loading the brushes there are a few lines of inline javascript. Prior to running the SyntaxHighlighter with SyntaxHighlighter.all() I enable bloggerMode as we are using this at blogger.com and I setup defaults. Documentation on configuration of the highlighter itself and defaults for each highlighted element can be found at Alex' site. You might want to tweak these for your site.

Finally I add the core css file to the page as well as a css file with the theme I choose. You can pick your own theme that matchs your site.

Finally, please consider hosting these files on your own server (although that can't be blogger). If you are using the files hosted by Alex himself, as in the examples, please consider making a donation to cover his bandwidth costs and to show your appreciation with the work he's done.

Global DateTimeConverter without separators

2013-01-29T07:25:00.000+01:00

We are developing an application where data processing speed is important and users have to enter a lot of dates into the system. This is replacing a legacy Oracle Forms system where people were used to entering dates without any separators. For example they want to enter 120613 for June 12th 2013 (or December 6th 2013 if you're from the US).

ADF Faces (and MyFaces Trinidad) has its own DateTime converter that is already pretty advanced and lenient. You can give it a pattern and it will try to parse any input in several variations of the supplied pattern. For example, both "Jan/4/2004" and "01.4.2004" will be parsed with a pattern of "MMM/d/yyyy". For months it will try MMM, MM and M and it will try any of the separators - or . or /

But we wanted the converter to also try a pattern without any separators. You could specify a secondary pattern for a converter and it will also try to parse any input with this secondary pattern while still using the primary pattern for displaying the date/time. But I don't like the idea of manually setting a secondary pattern on each and every date field in the application.

So we replace the default DateTime converter with our own. This custom converter extends from the default ADF Faces/Trinidad converter:

public class LenientDateTimeConverter extends
       org.apache.myfaces.trinidadinternal.convert.DateTimeConverter

It can then override the getSecondaryPattern method and return a pattern without any separators:

@Override
    public String getSecondaryPattern() {
        final String secPattern = super.getSecondaryPattern();
        if (secPattern != null) {
            // use secondary pattern when explicitly set
            return secPattern;
        }
        // get primary pattern (or default if none defined)
        final DateFormat dateFormat =
            getDateFormat(FacesContext.getCurrentInstance(), getPattern(),
                          true, null);
        if (dateFormat instanceof SimpleDateFormat) {
            return getPatternWithoutSeparators(((SimpleDateFormat)dateFormat).toPattern());
        }
        return null;
    }

The final trick is to register this custom converter as the default one for the entire application. The challenge is that there are a number of ways the ADF/JSF framework looks for a datetime converter and we have to replace all of them. This requires the registration of a number of converters in the faces-config.xml file:

  <!-- for inputDates without explicit converter so they will use default JSF converter -->
  <converter>
    <display-name>Date Time Converter</display-name>
    <converter-id>javax.faces.DateTime</converter-id>
    <converter-class>com.redheap.datenosep.LenientDateTimeConverter</converter-class>
  </converter>

  <!-- for input- and output-components that use explicit af:convertDateTime -->
  <converter>
    <display-name>Date Time Converter</display-name>
    <converter-id>org.apache.myfaces.trinidad.DateTime</converter-id>
    <converter-class>com.redheap.datenosep.LenientDateTimeConverter</converter-class>
  </converter>

  <!-- for outputText without explicit converter who determine converter based on java class -->
  <converter>
    <display-name>Date Time Converter</display-name>
    <converter-for-class>java.util.Date</converter-for-class>
    <converter-class>com.redheap.datenosep.LenientDateTimeConverter</converter-class>
  </converter>
  <converter>
    <display-name>Date Time Converter</display-name>
    <converter-for-class>java.sql.Date</converter-for-class>
    <converter-class>com.redheap.datenosep.LenientDateTimeConverter</converter-class>
  </converter>

The sample application comes with a demo page to test the different locale and input types (date, time or both). Below are some screenshots that show the computed secondary pattern as well as the accepted and parsed input in both en_US and nl locale:

entering date without separators in en_US locale

finished entering date in en_US locale

entering date without separators in nl locale

finished entering date in nl locale

Sample application: DateWithoutSeparator
Source code repository: DateWithoutSeparator