Using JPA in SCA Spring Beans

When using  Oracle SOA Suite 11g SCA Spring Bean components you will likely be facing a decision about how to interact with your database from within the Spring Beans. The answer will ultimately depend on your overall system architecture. For instance you may wire a Spring Bean directly to a DB adapter, or you can encapsulate the data access inside a web service or an EJB session bean. In my last project we have decided to access the data directly from the Spring Beans, taking advantage of the flexibility provided by Spring's JDBC abstraction framework. In fact Spring makes JDBC access so simple that it is easy to miss other alternatives, one of them being especially noteworthy - the Java Persistence API.

Java Persistence API has greatly simplified the object-relational mapping in Java. Let's have a look at how JPA can be incorporated into an SCA application.

The Service

We will create a simple service inspired by my other passion, motorcycles. The service will provide these operations:

• createBike - creates an entity for a motorcycle with the specified manufacturer and model name and returns the entity's ID.
• getBikeDescription - retrieves the description of a motorcycle with the specified ID.

The Project

We start with an empty composite project and add a Spring Bean, following the code-first approach:

1. Create a Java interface for our SCA service: MotoService.java
2. Create a dummy implementation of the above interface MotoServiceImpl.java.
3. Create a Spring Context which uses the classes created in the above steps.

4. Wire the Spring Context to the Exposed Services lane - this step will generate MotoService.wsdl.

That's all we need for now, the next step is to add JPA artifacts to the project.

JPA Artifacts

To enable our SCA project for JPA, we follow these steps:

1. Add two predefined JDeveloper libraries to the project dependencies: EJB 3.0 and TopLink.

2. Create the entity class: Bike.java. Note that the class is not Serializable - it does not need to be (more on the topic here). The DDL to the create the SQL objects for the Bike entity is in create_tables.sql.
3. Create the DAO class: BikeDao.java. Note that the EntityManager field does not have the usual @PersistenceContext annotation. This is because we will use Spring Bean wiring to inject the property (see section Configure the Entity Manager below).
4. Create the JPA persistence definition: persistence.xml. If you plan on running the example project in your environment you will need to modify the jta-data-source property to match a JNDI data source configured in your WebLogic server instance.

Wire the Spring Bean to JPA

Now we can wire the JPA classes to the service Spring Bean:

1. Change the MotoServiceImpl.java implementation to use the DAO.
2. Add the BikeDao property to MotoSB.xml:

Configure the Entity Manager

Now we need to configure the entity manager by explicitly injecting it to the DAO class:

We use LocalContainerEntityManagerFactoryBean to obtain the entity manager factory. The factory's persistenceUnitName  property refers to the persistence unit defined in persistence.xml.

Since we need to inject an entity manager to the DAO class, we use a SharedEntityManagerBean to create an entity manager from the entity manager factory. If you try to create the entity manager programmatically - by calling the factory's createEntityManager method, as I did :-) - the entity manager will not bind itself to the transaction and as a result, the database changes will not be committed.

For more information on integrating Spring with JPA see the Spring documentation.

Configure Transactions

Finally, we will declaratively enhance the service Spring Bean with the transaction behavior - by using a

TransactionProxyFactoryBean wrapper:

Note that the above approach gives you full control over the transaction behavior of the Spring Bean component. This is much more flexible than the transaction semantics of BPEL and Mediator components.

Deploy and Test

That's it. The project is now ready to deploy and test. I tested with soapUI (project available here) by creating an entry for my favorite motorcycle (KTM Enduro 690R) and retrieving its description afterwards.

Conclusion

In the above I have shown how to integrate JPA with SCA Spring Beans. The ability to use JPA makes Spring Beans a great alternative to another SCA components which are limited to data access via a DB Adapter or an encapsulated service. As a matter of fact, you can add pure data access Spring Beans to your toolbox and use them to facilitate data access from another SCA components. Choosing the right SCA component type is a topic in itself and it has been addressed in this excellent blog of my former colleague Alex Suchier.

If you want to try the Spring Bean JPA integration for yourself, you can get the project fromSubversion or download it as a 7-zip archive.

Oracle Business Rules 11g - Best Practices for Decision Tables

Oracle Business Rules is a lightweight and powerful rules engine that is part of the Oracle SOA Suite. It supports two fundamental ways of entering the rules:

• an IF/THEN form which is the intrinsic form of rules in any production rule system
• a decision table - a spreadsheet-like form that will appeal a business savvy user

While Oracle does a pretty good job on documenting the decision table features - Working with Decision Tables - there is much less information available on how to actually design the decision tables.

In this post, I want to share my experience with the decision tables and describe what I consider the best practices in using them. I am looking forward to your feedback in the comments section.

  

Have a Case

The first and foremost question you should be asking yourself before you create a decision table is, "is the decision table the right vehicle for this job?". Sometimes this may be a no-brainer - like when your customer gives you a spreadsheet that neatly translates into a decision table. Other times the choice may not be that obvious.

Let's have a look at an example. Imagine a company that grants a company car to an employee if any of the following applies:

• The employee's job level is expert and the employee has been at least 3 years with the company
• The employee's yearly salary is at least 65,000 USD and the employee was hired before Nov 1, 2008
• The employee's job title is Sales Rep

It is questionable though whether a decision table is a good fit here. While it is still appealing thanks to its visually comprehensive layout, a solution with IF/THEN rules is going to be simpler and cleaner, especially if the number of rules increases in the future.

Now lets take a look at another imaginary company car policy:

• All employees in the Sales department are entitled to a company car.
• Employees in the Executive department are entitled to a company car if their job level is intermediate or expert.
• Employees in the IT department are entitled to a company car if their job title is Architect and their job level is expert.

Even though this policy has the same number of  conditions as the first one, it yields much more concise and coherent decision table. Why is that? The first policy uses disconnected conditions which do not blend very well into a decision table. The second policy has conditions shared by most of the rules which differ only by the condition input values.

My advice is to consider the structure and size of your to-be-implemented rule set, then take a mental picture of the decision table solutions and compare it to the IF/THEN rule solution.

Only use a decision table if it gives you an advantage compared to an IF/THEN rule solution.

Be Accurate

I mentioned above that you may get a spreadsheet from your customer that translates neatly into a decision table. In reality though, it's rarely that simple. More often than not, the specification will contain a few stumbling blocks. I once received a spreadsheet from the customer that contained two overlapping conditions which were supposed to yield opposite results. The good news is, if you accurately translate your specification into a decision table, the logical flaws in the specification will pop up as conflicts or gaps. This way the implementation can actually help improve the specification - isn't it amazing? On top of that, the more your decision table resembles the specification, the easier it will be to implement any future specification changes. For all above reasons:

Make your decision table match your specification as closely as possible.

Be Complete

When you look at either of the above decision tables, you will notice that they capture only the cases when the company car privilege is granted to the employee. I did it on purpose to keep the tables as simple as possible. In my experience the real world specification also tends to come that way - as an enumeration of cases when something happens or applies - rather than as a full list of all eventualities. Yet it pays off to consider all possible cases - and there is a nifty tool built in the Rules Designer that does exactly that - the Gap Analysis.

  

The above picture shows the gap analysis for the decision table implementing the second company car policy. I like to see it as an inverse version of the original decision table - as it is covering all the cases when the company car is not granted. It is very useful to examine the gaps to verify the completeness of a decision table. For instance, the fact that the Finance department is missing from the rules in our example may be a hint that the specification is incomplete (unless the company really hates their finance folks).

You may also choose to have the gaps automatically filled in - this is how I created the following gapless decision table from the original one:

Even when I choose to allow gaps in a decision table, I still employ the Gap Analysis to check that no eventuality has been overlooked.

Gap Analysis is your friend - seek its advice whenever you create or change a decision table.

Divide and Conquer

I bet you've seen this before - a source code method or function in your favorite programming language that spans across hundreds of lines. This is the infamous Taller Than Me anti-pattern. Unfortunately, decision tables are not immune to a similar anti-pattern. It is created by the same evil code-supersizing forces, but as a decision table tends to grow wide as more rules are added into it, let me dub it "Wider Than The Sky".

If you have to scroll horizontally to see all of your decision table, it's probably a good idea to split the table into several smaller partitions. To illustrate this, let's imagine that our fictitious company determines salary raises for its employees based solely on their job title and the last performance rating:

Huh? You can't see a thing? That's right - the table has grown too wide! Arguably the best refactoring  in this case is to have a dedicated table for every job title - here are two examples (check out the project from Subversion if you want to see more):

 Avoid creating decision tables that are Wider Than The Sky.

Be Consistent

The bucketsets used in decision tables can be defined either locally or globally. It may be tempting to quickly hack a local bucketset with just few values that you need (for example if a condition needs to check for two specific departments only), however in my experience you are almost always better off with a global bucketset that contains a complete list of values. The reasons are threefold:

• Gap Analysis is less reliable with partial bucketsets.
• It is very confusing when multiple local bucketsets with different sets of values are defined for the same entity.
• If you create a local bucketset, you will face rework if you need to add another condition for the same entity later.

 Avoid local bucketsets unless you have a really good reason to use them.

Control the Conflicts

If a decision table has overlapping rules that yield different results it will be marked as a conflict. Note that the decision table from the very first example has overlapping rules but there is no conflict as the corresponding actions do not differ.

This is the reason why you should avoid unnecessary stuff in your decision table actions. For many years I believed that it is a good practice to add a print action to debug which rule was actually fired. Now I don't think much about it as it is:

• Creating unnecessary conflicts
• Obscuring the business meaning of the rules
• Completely redundant - the rules that fired can always be tracked by other means (the server audit trail, test rule  function or explicitly by calling RL.watch.rules) 

If you do have a genuine conflict though, it's time to check your specification. If you modeled the rules closely to the specification, as I advocated in the Be Accurate section, then actually the specification itself must have a conflict. Your next course of action then depends on how the specification is fixed:

• A business user may fix the rules in the specification which in turn means a refactoring of the decision table.
• A business user may prioritize the conflicting rules - which is best implemented as manual conflict resolution.
• As a special case, a business user may implicitly assume that a more specific rule has higher priority than a less specific one. That's actually quite reasonable and it is supported by the Rules Designer as the auto override conflict policy. You just need to understand your business' assumptions or even better, let them articulate the assumptions explicitly.

For details on manual and auto override conflict resolution see Understanding Decision Table Conflict Analysis.

Avoid conflicts in a decision table by keeping the action part uniform for overlapping rules. For genuine conflicts let the specification drive the decision between conflict resolution and refactoring the decision table.

Conclusion

I hope you find the above useful. If you have already developed your own best practices I'd be happy if you leave a comment and share how they compare with these. If you want to try the examples, you can get the project from Subversion or download it as a 7-zip archive.