Saturday, September 29, 2012

Email notifications from BPMN processes using the pre-built VM for SOA and BPM Suite 11g

In tomorrow's OpenWorld session UGF10464 - ADF EMG User Group: Oracle Fusion Middleware Live Application Development Demo a team of developers will build and demo an application based on Fusion Middleware (ADF, SOA Suite, BPM Suite, Database). We will use the pre-built Virtual Machine for SOA Suite and BPM Suite 11g for this. The VM contains a fully configured and ready-to-use SOA Suite and BPM Suite installation (PS5). Note that this is a development VM that shouldn't be used for production environments.

The application implements the process of submitting, reviewing, and scheduling abstracts for a conference. An overview of its components is shown in the following figure:

Presenters will be notified of the progress of their abstract submission through email. For example after approving or rejecting the abstract and after evaluation of the presentation. This can be seen in the following figure that depicts the Abstract-to-Presentation process:

This blog explains how to configure the pre-built VM to send email notifications from BPMN processes.

Configure Email Server and Client

The VM is pre-installed with JAMES, an open-source Java mail server. JAMES is located in the following directory on the VM: /opt/ApacheJames/james-2.3.2. The mailserver is already prepopulated with several users. You can add your own users to it using Telnet (see

JAMES is preconfigured in the Virtual Machine to use as servername, meaning that any newly created email address will have the following format:; for example You can change this setting in the following file: /opt/ApacheJames/james-2.3.2/apps/james/SAR-INF/config.xml.

Next you can use an email client to connect to JAMES to verify that emails can be send and received. JAMES is configured with the following port numbers: 110 for POP3 and 25 for SMTP.

If you connect to JAMES from outside the VM you have to make sure that port forwarding in VirtualBox is configured so that the SMTP and POP3 ports are accessible to your email client.

Configure BPM Suite

You can send emails from BPMN processes by using a Notification activity and choosing email as Notification Type in the implementation properties. Make sure the To address evaluates to an emailadress that exists in JAMES.

Next you have to configure BPM Suite in Enterprise Manager so that the notifications are sent through JAMES. You have to configure both the Email Driver Properties of the usermessagingdriver-email (part of the User Messaging Services or UMS), as well as the Workflow Notification Properties. This is described in a blog by Craig Barr.

Take care that you also configure the Workflow Notification Properties. Workflow Notification is primarily configured to enable email integration for Human Tasks. This way task assignees of new tasks are notified through emails and actionable tasks can be completed through emails. However, these settings also need to be configured to enable email notifications sent from processes.

Friday, September 28, 2012

Running EclipseLink DBWS 2.4.0 on GlassFish 3.1.2

In a previous blog I explained how to create a web service using the EclipseLink DBWS utility. This blog explains how to deploy this to GlassFish 3.1.2.

The main challenge is getting the right classes to load. But let's start from the beginning: create the war file.

Create the war file

First we create the war file with the DBWSBuilder utility. I defined a builder file on the employees table in the standard hr schema as follows:

<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="">
<property name="projectName">Employee</property>
<property name="driver">oracle.jdbc.OracleDriver</property>
<property name="password">hr</property>
<property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property>
<property name="username">hr</property>
<property name="platformClassname"></property>
<property name="logLevel">all</property> 
<table schemaPattern="%" tableNamePattern="EMPLOYEES"/>

Second, I created the war file with the DBWS utility:
$ECLIPSELINK_HOME/utils/dbws/ -builderFile EmployeeTableBuilder.xml -stageDir . -packageAs glassfish employee.war

NB: don't forget to set the paths in in $ECLIPSELINK_HOME/utils/dbws/ directory.

Add libraries to the war file

The war file that is created assumes that the correct version of the  eclipselink.jar is on the classpath of the server.  So first we add two libraries to the WEB-INF directory:
  • eclipselink.jar
  • javax.persistence_2.0.4.v201112161009.jar
I would have liked it a lot better if I would have had the option in the DBWSBuilder utility to set a flag to include the eclipselink.jar and the persistence jar in the WEB-INF/lib directory, or to set a flag to tell it not to do that. Similar to the 'provided' property that Maven offers.
If you forget this step, there will be an exception in your $GLASSFISH_DOMAIN/logs/server.log file stating:|_ThreadID=21;_ThreadName=Thread-2;|Deployment failed
java.lang.TypeNotPresentException: Type ProviderHelper not present

Add libraries to your domain

The JDBC driver needs to be added to the lib/ext directory of your glassfish domain. 

cp $ORACLE_HOME/jdbc/lib/ojdbc6.jar $GLASSFISH_DOMAIN/lib/ext

If you skip this step, or put the jar in the WEB-INF lib, you will get a SOAP Fault that is caused by a ClassNotFoundException:

com.sun.enterprise.container.common.spi.util.InjectionException: Error creating managed object for class: class _dbws.DBWSProvider
Caused by: java.lang.NoClassDefFoundError: oracle/sql/TIMESTAMP

Test the service

Glassfish offers a tester for webservices. This does not work, because the container does not recognize the webservice. You get the following (incorrect) error:

Service {urn:EmployeeService}EmployeeService looks like a JAX-RPC based WebService.

Please note that the tester feature is supported for JAXWS based webservices only

Creating a project based on the deployed wsdl does work as expected.

Thursday, September 20, 2012

Fault Handling Slides and Q&A

AMIS organized its annual Oracle OpenWorld and JavaOne preview event last Tuesday. The event is organized for people that don't attend OpenWorld and for presenters to rehearse their sessions and get feedback from the audience. Vennster gave two presentations:

  • Using Eclipse DBWS to Interface with Legacy Applications - Lonneke Dikmans
  • Effective Fault Handling in Oracle Service Bus and SOA Suite 11g - Ronald van Luttikhuizen; co-presented at OpenWorld with Guido Schmutz, Technology manager at Trivadis

This blog includes the updated slides of the Fault Handling presentation and contains a Q&A section that answers questions from the audience at the preview event. Lonneke will post the slides of her presentation in a follow-up blog. Last but not least, thanks to AMIS for hosting the event!

Fault Handling 

It is one thing to architect, design, and code the “happy flow” of your automated business processes and services. It is another thing to deal with situations you do not want or expect to occur in your processes and services. This session dives into fault handling in Oracle Service Bus 11g and Oracle SOA Suite 11g, based on an order-to-cash business process. Faults can be divided into business faults, technical faults, programming errors, and faulty user input. Each type of fault needs a different approach to prevent them from occurring or to deal with them. For example, apply User Experience (UX) techniques to improve the quality of your application so that faulty user input can be prevented as much as possible. This session shows and demos what patterns and techniques can be used in Oracle Service Bus and Oracle SOA Suite to prevent and handle technical faults as well as business faults.


This section lists answers to the questions that were raised during the preview event.

Q: Where can retries be configured in Oracle Service Bus?
The retry mechanism is used to prevent faults caused by temporary glitches such as short network interruptions. A faulted message is resend (retried) and might succeed this time since the glitch has passed. Retries are an out-of-the-box feature that can be used in Oracle Service Bus and Oracle SOA Suite using the Fault Policy framework. By default, retries are disabled in Oracle Service Bus.

In Oracle Service Bus retries can be configured for several artifacts, among others the following:

  • Retries can be configured on Business Services as part of their Transport Configuration. 
  • Retries can be configured for inbound JCA-based Proxy Services as endpoint properties: jca.retry.countjca.retry.intervaljca.retry.backoff, and jca.retry.maxInterval.
  • Retries can be configured for outbound JCA-based Business Services using the same endpoint properties.
  • Retries can be configured for JMS Proxy Services and (S)FTP Proxy Services as part of the Advanced Settings.
See Oracle's Developer’s Guide for Oracle Service Bus 11g for all possible retry configurations.

Mind transaction boundaries and write operations when configuring retries. For example, consider a flow that is composed of two actions in which the first action inserts a record in the database and then commits, while the second action invokes a Web Service. When the second action fails and the entire flow is retried, you might end up with two new, identical records.

Q: What other load-balancing algorithms can be used besides round-robin?
When there are multiple instances of a service that are invoked from Oracle Service Bus, load-balancing can be configured on Business Services. Load-balancing can prevent faults by retrying messages that were sent to unavailable endpoints to other, hopefully active endpoints. Load-balancing is disabled by default. When enabled, the default algorithm that is used for load-balancing is round-robin.

The Oracle's Developer’s Guide for Oracle Service Bus 11g lists all possible load-balancing algorithms:

"Specify the load balancing algorithm as any one of the following values:
  • Round-robin - This algorithm dynamically orders the URLs that you enter in the Endpoint URI field for this business service. If the first one fails, it tries the next one, and so on until the retry count is exhausted. For every new message, there is a new order of URLs.
  • Random - This algorithm randomly orders the list of URLs that you enter in the Endpoint URI field for this business service. If the first one fails, it tries the next one, and so on until the retry count is exhausted.
  • Random-weighted - This algorithm randomly orders the list of URLs that you enter in the Endpoint URI field for this business service, but some are retried more than others based on the value you enter in the Weight field.
  • None - This algorithm orders the list of URLs that you enter in the Endpoint URI field for this business service from top to bottom."
Q: How is throttling implemented in Oracle Service Bus (in-memory, JMS, etc.)? Are messages in the throttling queue lost when the server fails?
Throttling introduces a message queue between a Proxy Service and a Business Service that temporarily stores messages to prevent backend systems from overloading. Whenever the number of messages exceeds the thresholds as configured in the throttling settings, the message is stored in a queue. When the number of messages that need to be processed decreases, messages are removed from the queue and sent to the backend system via the Business Service.

The Oracle Administrator’s Guide for Oracle Service Bus 11g discusses throttling and its configuration:

"A throttling queue is an in-memory queue. Messages that are placed in this queue are not recoverable when a server fails or when you restart a server. When you delete or rename a business service, all the messages in the throttling queue are discarded."

Q: What values can be used as key for the Result Cache feature?
The result cache in Oracle Service Bus can be used to store data in-memory. When data is queried that is present in the cache, the data is fetched from memory instead of the query being sent to, and executed by the backend system. This decreases the load on the backend system. Note that this feature only works for data that is static; meaning the data is seldom changed. If not, the cache will result stale and out-of-date information. As part of the Result Cache feature you need to configure the key that is used to determine if the associated data is in the cache.

The Oracle's Developer’s Guide for Oracle Service Bus 11g says:

"Cache Token Expression – Oracle Service Bus uses a cache key to identify cached results for retrieval or population, and the cache token portion of the cache key provides the unique identifier. You can use an expression—the Cache Token Expression—to generate the cache token part of the cache key to uniquely identify a cached result for the business service.

The Cache Token Expression must resolve to a String or the value of simple content, such as an attribute or an element with no child elements. If the expression evaluates to null or causes an error, results are not cached."

Thursday, September 13, 2012

Managing EclipseLink using JMX

EclipseLink is an open-source persistency framework for mapping Java objects to relational data and vice versa which is called Object-Relational Mapping (ORM). Besides implementing the Java Persistence API (JPA) standard, it also provides capabilities for Object-XML Mapping (OXM) and the creation of Database Web Services.

The JPA standard specifies caching functionality. Caching improves performance since data that is already queried and present in the cache can be fetched from memory instead of executing all queries in the backend database. However, this means that data should also be modified through the same cache managed by the JPA provider. If not, the cache won't be aware of changes and becomes out-of-synch with the actual data stored in the backend. This results in incorrect data being returned to the clients of the EclipseLink-based application. A typical situation in which this occurs is when IT operations directly changes data in the database on behalf of users or when solving issues and thereby bypassing the cache.

There are a few approaches to deal with such situations:

  • Restart the application server or application after the change to clear the cache;
  • Disable caching in the application altogether;
  • Expand the application (user interface, persistency layer) so that IT operations has dedicated functionality to modify data through the application instead of being forced to modify data in the backend database;
  • Implement a mechanism to automatically invalidate the EclipseLink cache triggered by events from the database;
  • Configure the persistency layer so that entities in the cache are automatically invalidated on a regular interval making sure that data can only be incorrect or incomplete for a certain time-period.
The above approaches have drawbacks such as additional coding, negative impact on performance when caching is disabled, or increased downtime of the application.

This blog describes a way to manage EclipseLink caches that we use at customer projects to help IT operations and application managers and doesn't have the disadvantages named earlier. It uses:

  • the out-of-the-box support by EclipseLink for Java Management Extensions (JMX); 
  • the MBeans provided by WebLogic Server; 
  • the monitoring application JConsole that is JMX-compliant and shipped with the Java Development Kit (JDK). 
Using JConsole, EclipseLink caches can be monitored, managed, and invalidated at runtime without impact on running applications.

One-time configuration of WebLogic to enable remote JMX connections

Weblogic Server needs to be configured to allow for remote JMX connections that are set up from JConsole and to enable the invocation of MBeans. The following blogs show you how to accomplish this:

Some pointers here:

  • Make sure you add the Java options and to the start script of the WebLogic Server on which the EclipseLink applications run. Adding these parameters makes sure that the EclipseLink MBeans show up in JConsole.
  • Restart the WebLogic Server after the configuration changes.

Using JConsole

After configuring and restarting WebLogic Server, the default WebLogic server logfile should include the endpoints for the JMX servers to which we connect using JConsole. For example:

<JMX Connector Server started at service:jmx:iiop://localhost:7001/jndi/ .> 
<JMX Connector Server started at service:jmx:iiop://localhost:7001/jndi/ .> 
<JMX Connector Server started at service:jmx:iiop://localhost:7001/jndi/ .>

After setting the JAVA_HOME and WEBLOGIC_HOME environment variables as indicated in the blogs, you can now start JConsole using the command line:

jconsole -J-Djava.class.path=%JAVA_HOME%\lib\jconsole.jar;%JAVA_HOME%\lib\tools.jar;%WL_HOME%\server\lib\wljmxclient.jar

Enter the credentials you provided in WebLogic Server for the IIOP protocol and enter the JMX endpoint for the mbeanservers.runtime to connect to WebLogi Server. JConsole now lets you inspect and manage all sorts of aspects such as memory, threads, classes, and so on.

To view the currently active EclipseLink sessions click on the "MBeans" tab and expand the node "TopLink". Every active EclipseLink session is shown as separate subnode. Expand a session and select "Attributes" to inspect the EclipseLink session. Clicking on the "NumberOfObjectsInAllIdentityMaps" shows a graph displaying the number of cached entities.

You can now clear the cache of an EclipseLink session at runtime by executing the operation "invalidateAllIdentityMaps" on the "Operations" page. This operation can be used to clear the cache after someone, e.g. IT operations, modifies the backend data directly and bypasses the EclipseLink persistency layer.

Note (thanks to Shaun Smith): You should be calling invalidateAllIdentityMaps() which has replaced initializeAllIdentityMaps(). Invalidation ensures that object identity is not lost in a running transaction. Initialization does not and should only be used safely in single threaded dev/test.

By using this approach, IT operations and application managers can do their job that includes direct data modifications to solve urgent issues and user requests, and be able to refresh the EclipseLink cache without downtime and impact for end users.