FAQ #9 - How to configure unit testing an ADF BC project using JUnit in JDeveloper 11g

Introduction

Unit testing an ADF BC project in JDeveloper could be a straightforward task when using the JUnit ADF Business Components Test Suite Wizard. There are a few twists and turns on the way, which once straightened out should make unit testing a routine. Let’s take a closer look.

Main Theme

Prerequisites

Before beginning with unit testing your ADF BC project, the necessary components must be installed in JDeveloper. Start JDeveloper and using the Help | Check for Updates... wizard ensure that both the JUnit Integration and BC4J JUnit Integration library updates are downloaded and installed from the Official Oracle Extensions and Updates site.

Also, you should have created application modules in your BC project before you begin. Lastly, I will also advise you to create a separate application module configuration specifically for unit testing. There are a couple of reasons why you want to do so:

1. For JUnit, a JDBC URL connection string is needed to access the database since a JDBC datasource won't work outside the Java EE container, and
2. In order to overcome an "ORA-01005: null password given; logon denied" database connection error when running the unit tests, we must provide the database schema password ourselves.

To create the unit testing application module configuration, in the Model BC project, right-click on the application module and select Configurations... to bring up the Manage Configurations dialog. Select the Local configuration and click Copy to make a copy of it. Once copied, select the new configuration, click Edit... and change its name. Then, ensure that the Connection Type is set to JDBC URL. Click OK a couple of times to save the new configuration. In the attached example, we have copied the HrAppModuleLocal configuration to HrAppModuleJUnit.

Configure the Unit Tests

To configure unit testing for your ADF BC project, you need to first create a separate Java Project. From the New Gallery dialog - File | New...  - select Projects under the General category and Java Project from the Items list to create a generic Java project.

Name the project, setup the project package and source paths and click Finish to create it.

Once the unit test project is created, select it in the Application Navigator and run the New Gallery wizard once more, this time selecting Business Components Test Suite from the General | Unit Tests category.

In the Configure Tests page specify your Business Components Project, the Application Module and the Configuration to be unit tested. Ensure that you specify the application module configuration that you created earlier specifically for unit testing purposes.

Verify your selections and click Finish. The wizard will generate tests for each view object in the application module. Tests for exported application module methods will also be generated. If the application module does not have exported methods, the wizard will also generate a test for the application module itself.

For the sample project, the generated test files are shown below.

Before running the unit tests, build the unit test project.

Run the Unit Tests

We will run the unit tests as part of an Ant build script. In the ADF BC Model project, bring up the New Gallery dialog, select Ant from the General category and Buildfile from Project from the Items.

In the Create Buildfile from Project dialog accept the defaults and press OK. This will create the build.xml and build.properties Ant files under the Resources folder in the project.

In accordance with the official documentation, all it takes is the addition of an Ant target similar to this:

So, let's modify it accordingly and add it to the build.xml Ant script:

For the name attribute of the <test> tag element, we need to specify the all-tests class generated earlier - AllHrAppModuleTests in the example. The todir attribute of the same tag indicates the location of the unit test output result files: in this example we have defined the junit.output.dir macro to point to the ../JUnit/output directory in build.properties. Ensure that the output directory is created as well.

We should be about ready now. Let's right click on the build.xml Ant script in the Application Navigator, select the JUnit target and run it.

Twists and Turns ... or Adventures in Unit Testing

The first thing you see when you run the unit test target is an Ant error in the Apache Ant - Log console:

The error message is pretty straightforward: Ant does not like the nested <pathelement> tag, so let's remove it and re-run the unit test target.

This time the Log console shows:

This is definitely an improvement! A unit test output file is generated this time, in the ${junit.output.dir} directory. By examining its contents, it is obvious that the all-tests class could not be located by Ant.

In order to solve this issue, we need to add a <pathelement> tag with the location of the unit testing classes for the classpath <path> tag in build.xml as it is shown below:

Running it this time produces the following error:

OK, we are getting closer - the unit test Ant target runs just fine but the unit tests themselves all fail! For some unexplained reason, the database password is not supplied, the connection to the database fails and that makes the unit tests to fail. To bypass this annoyance, we need to supply the database password ourselves. In order to this, we need to create our own custom database transaction implementation and override the connect() method in order to supply the database password - if it is null that is. The process of creating a custom database transaction is explained thoroughly in the official documentation. Briefly:

1. Extend the DBTransactionImpl2 class in order to override the method(s) you need, in this case the connect() method to supply the password.
2. Extend the DatabaseTransactionFactory class, override the create() method and return the custom database transaction (step 1), and
3. Modify the application module configuration to use the custom transaction factory.

These steps are illustrated below:

1. Extend the DBTransactionImpl2 class in order to override the method(s) you need, in this case the connect() method to supply the password:

 2. Extend the DatabaseTransactionFactory class, override the create() method and return the custom database transaction (step 1):

3. Modify the application module configuration to use the custom transaction factory:

Bring-up the application module configuration that you created specifically for unit testing and specify your own custom transaction factory class for the TransactionFactory property.

Now re-build the BC project and re-run the unit tests. Everything should run smoothly and the unit test output file should look similar to this:

That's all folks, you've made it through a unit testing adventure!

[updated on May 26th, 2010]
Since this post was published, Oracle has come up with a series of How-to articles related to JDeveloper. One article in particular, related to JUnit can be found here: Unit Testing Your Application with JUnit.

Conclusion

Once you go through the hurtles of configuration, the process of unit testing your ADF Business Components project should be straightforward, automatic and hopefully routine. Assuming that your test cases make sense, it will prove to be another valuable tool in your toolbox.

Until the next time, keep on JDeveloping!

References

30.8.7 How to Run a JUnit Test Suite as Part of an Ant Build Script
36.8.4.2 Configuring an Application Module to Use a Custom Database Transaction Class

Code

http://jdeveloperfaq.googlecode.com/files/JDeveloperFAQNo9.rar

FAQ #8 - How to perform log analysis using the Diagnostic Log Analyzer in JDeveloper 11g

Introduction

When it comes to diagnostics logging, a possibly lesser known feature of JDeveloper is its ability to perform log analysis. Known as the Oracle Diagnostic Log Analyzer, it allows the developer to open a diagnostics log file and do a limited yet useful log analysis. Let's see how it works.

Main Theme

To demonstrate this FAQ, let's create a sample Fusion Web Application (Web) based on the HR schema. Let's create an Employee entity from the EMPLOYEES table and an Employees view based on the Employee entity. Finally, let's bundle the Employees view in the HrAppModule application module.

For the ViewController let’s create a View Activity called Employees directly in the unbounded adfc-config task flow and an Employees.jspx JSF page for the Employees View Activity. Finally, let’s drag the Employees view from the HrAppModuleDataControl in the Data Controls and drop it onto the Employees.jspx JSF page as an ADF Form.

In order to generate detailed diagnostic log entries, bring up the ViewController Project Properties dialog and in the Run/Debug/Profile page select the Default run configuration and click Edit.... In Launch Settings specify -Djbo.debugoutput=console for the Java Options.

Save the project settings and run the application. Detailed log entries should have been generated in the JDeveloper Log console.

Take a look at the Actions menu at the top right of the Log window. Clicking on it will display a menu from which we can select Analyze Log | Current in Console.

Let's do just that - go ahead and select it. This will bring up the Oracle Diagnostic Log Analyzer window.

We will use the Diagnostic Log Analyzer to do some elementary analysis for the log generated while running the sample application. Select all of the log levels (Incident Error, Error, Warning, Notification, Trace and Unknown for ODL Log Levels) and search for the word "select" in the Message Text. All SELECT SQL statements will be identified in the log and displayed in the Results section.

To group the log messages by time period or by request, in the Related column, select either Related by Time or Related by Request.

What makes things a bit more interesting is the ability to load a log file generated by some other application or by another server - a WLS log file for example - into the Diagnostic Log Analyzer and do some analysis on it. Let's try it: click on the Browse Log Files icon and select a WLS log file to open. Then do some analysis on it.

Finally, note that the Oracle Diagnostic Log Analyzer is also available directly from the Tools menu.

Conclusion

Using the Oracle Diagnostic Log Analyzer in JDeveloper to perform log analysis could prove to be just another "little" tool that does a "big" job when dealing with the chaos of thousand-line diagnostics log files. It is simple and easy to use, so give it a try.

Until the next time, keep on JDeveloping!

Code

http://jdeveloperfaq.googlecode.com/files/JDeveloperFAQNo8.rar

FAQ #7 - How to configure ADF diagnostics logging in standalone WLS using JDeveloper 11g R1

Introduction

In FAQ #6 - How to fine tune ADF diagnostics logging in JDeveloper 11g R1 we’ve seen how to configure diagnostics logging for the integrated WLS in JDeveloper. Configuration of diagnostics logging for the standalone WLS can be done in a similar fashion. Let’s take a look.


Main Theme

For some basic information regarding ADF diagnostics logging refer to FAQ #6 - How to fine tune ADF diagnostics logging in JDeveloper 11g R1. We will repeat some of the introductory information here as it applies to the standalone WLS.

ADF diagnostics logging is controlled via the usage of the jbo.debugoutput parameter. Using this parameter with the console value, i.e. -Djbo.debugoutput=console, produces diagnostic logs directly in the JDeveloper Log console window when deploying and running an application on the integrated WLS in JDeveloper. When set to the ADFLogger value, diagnostics are routed through the standard J2SE Logging API and are controlled through the logging.xml configuration file. For the standalone WLS this file can be found in the %MIDDLEWARE_HOME%\user_projects\domains\%DOMAIN_NAME%\config\fmwconfig\servers\%SERVER_NAME% for the Windows operating systems.

%MIDDLEWARE_HOME% is the installation directory of the standalone WLS, %DOMAIN_NAME% and %SERVER_NAME% are the WLS domain and server that we are configuring. For information on how to setup the standalone WLS, take a look at FAQ #1 – How to configue the standalone WebLogic server for deploying ADF applications from JDeveloper 11g R1 (11.1.1.2.0).

Let's locate the logging.xml file in the above directory and drag and drop it on JDeveloper.

JDeveloper will open the file and display it in the Overview tab.

In order to produce detailed diagnostic logs for the ADF BC oracle.jbo classes, we need to set the log Level to at least FINE. Let's set it to the most detailed level FINEST - TRACE:32 if using ODL Log Levels - for the oracle.jbo logger. Also let's ensure that the odl-handler log handler is configured to generate diagnostics for all log levels. To verify, select the odl-handler in the structure window and ensure that the level attribute is set to ALL.

Lastly we need to specify the -Djbo.debugoutput=adflogger -Djbo.adflogger.level=FINEST parameters when starting the standalone WLS, so let's open the setDomainEnv.cmd domain environment settings script in the %MIDDLEWARE_HOME%\user_projects\domains\%DOMAIN_NAME%\bin directory and add the following line:

set JAVA_OPTIONS=%JAVA_OPTIONS% -Djbo.debugoutput=adflogger -Djbo.adflogger.level=FINEST

That's all there is to it! Now let's start the standalone WLS, deploy and run our application. Take a look at FAQ #3 - How to deploy an ADF application on a standalone WebLogic server directly from JDeveloper for information on how to deploy an application onto WLS.

You should see those familiar ADF BC oracle.jbo diagnostic logs come flying in the WLS log window!

Conclusion

ADF Diagnostics Logging for the standalone WLS is done through the logging.xml file in a similar fashion as for the integrated WLS. It is a powerful feature that allows us to fine tune the log generation of our application and much more.

Until the next time, keep on JDeveloping!

FAQ #6 - How to fine tune ADF diagnostics logging in JDeveloper 11g R1

Introduction

FAQ #2 – How to enable debug information generation for an ADF BC project demonstrated a simple rather known technique to generate diagnostics logging in the JDeveloper Log window when testing an ADF BC application module with the BC tester. This barely scratched the surface of what is actually available in JDeveloper concerning diagnostics logging.

Main Theme

ADF diagnostics logging is controlled via the usage of the jbo.debugoutput parameter. Using this parameter with the console value, i.e. -Djbo.debugoutput=console, produces diagnostic logs directly in the JDeveloper Log window. When set to the ADFLogger value, diagnostics are routed through the standard J2SE Logging API and is controlled through the logging.xml configuration file. For the integrated WebLogic server this file can be found the C:\Users\username\AppData\Roaming\JDeveloper\ system11.1.1.x.x.x.x\DefaultDomain\config\fmwconfig\servers\DefaultServer for Windows 7 and in the C:\Documents and Settings\username \ApplicationData\JDeveloper\system11.1.1.x.x.x.x \DefaultDomain\config\fmwconfig\servers\DefaultServer for older Windows versions.

Let’s take a closer look:

In the Application Server Navigator – use View | Application Server Navigator to display if needed – expand the Application Servers node and right-click on the IntegratedWebLogicServer connection. This connection is generated automatically by JDeveloper for accessing the integrated WebLogic server. From the context menu select Configure Oracle Diagnostic Logging for “IntegratedWebLogicServer”.

JDeveloper opens the logging.xml diagnostics logging configuration file and displays it in the Overview tab. In the Loggers section expand the Root Logger (default) node to display all the loggers that are declared.

The three columns in the Overview tab display the Name of the logger, the diagnostics logging Level for the logger and any log handlers associated with the logger. The Name of the logger represents the Java package that will be generating the specific diagnostics logs. The Level value specifies the granularity of the diagnostic logs to be generated and it is defined either in terms of the ODL (Oracle Diagnostics Logging) Log Levels below

or as any of the Java Log Levels below

You can control the Log Level type (ODL or Java) through the drop down on the top right just above the Declares Handles column.

The Declares Handles column associates one or more log handlers to the specific logger. To illustrate, select a logger that has an associated log handler - an icon in the Declares Handles column - and expand the Handler Declarations section to display the associated log handlers.

The definition of the loggers in the Overview tab is hierarchical and is derived from top-down. For example: a logger that is specified at the oracle package level, applies to all other loggers below in the same hierarchy (oracle.*) unless it is overwritten.

All of this information and more is accessible in the Structure window. Let’s expand the logging_information node and then the log_handler node and let’s take a closer look at two of those log handlers:

 console-handler

This handler will log diagnostics to the console. Observe that the level attribute is set to ALL. This will allow the hander to log diagnostic messages for all log levels.

odl-handler
This handler will log ODL diagnostics to a log file. Expand the odl-handler log_handler node and observe the path property. It points to the location of the log file where the diagnostic logs will be saved. It is set to ${domain.home}/servers/${weblogic.Name}/logs/${weblogic.Name}-diagnostic.log, which is the C:\Users\username\AppData\Roaming\JDeveloper\system11.1.1.2.*.*.*\DefaultDomain\servers\DefaultServer\logs\ DefaultServer-diagnostic.log file in Windows 7.

OK. Let's generate some diagnostics now. Select the oracle.jbo logger in the Loggers tree and set its Level to FINEST – you may need to switch the log type to Java Log Types. This will override the default setting of the Root Logger in order to log all diagnostics generated by the oracle.jbo classes. There is no need to declare a specific handler, the one(s) defined for the Root Logger will be used as long as we ensure that the Use Parent Handlers checkbox remains selected. Make sure that you save the logging.xml file.

Before running your application open the ViewController Project Properties dialog, select the Run/Debug/Profile page and Edit… the Run Configuration. In the Edit Default Configuration dialog Launch Settings enter -Djbo.debugoutput=adflogger -Djbo.adflogger.level=FINEST in the Java Options.

Save the Project Properties and run your application. Observe the oracle.jbo diagnostic logs generated in the Log window. The same log entries are written in the C:\Users\username\AppData\Roaming\JDeveloper\system11.1.1.2.*.*.*\DefaultDomain\servers\DefaultServer\logs\ DefaultServer-diagnostic.log file as well.

Conclusion

ADF Diagnostics Logging is a powerful feature in JDeveloper. Through simple configuration, it allows you to fine tune the log generation of your application and much more.

Until the next time, keep on JDeveloping!

Code

http://jdeveloperfaq.googlecode.com/files/JDeveloperFAQNo6.rar