Introduction

jZeno contains support for seperating your business logic from you presentation logic. It provides an environment where your business logic is decorated with a stack of aspects that together function very similarly to a stateless session bean environment (persistency in jZeno is done via Hibernate). By default your business logic will have these aspects/services provided by jZeno (in order of execution) :

MonitoringAspect : this will gather statistics about the perfomance of your business facades in the production environment. This allows you to identify bottlenecks in your code easily.
LoggingAspect : this logs individual accesses to your business layer for more detailed profiling of your code in the production environment.
SecurityAspect : this aspect will perform a security check based on the property file security.properties.
RetryDeadlockAspect : this aspect detects dead-lock situations in your business facades and does a number of retries (randomized and delayed to greatly decrease the likelihood of a second/third/... deadlock) of the current business request.
OriginalValuesAspect : this aspect will take a snapshot of all domain model objects returned by your business facades to allow you to detect modifications that were applied in the presentation layer.
CallByValueAspect : provides isolation between the persentation layer and the business layer. Also necessary to do dead-lock retries.
TransactionAspect : Creates a new transaction and Hibernate session for your business method.
AutoSyncAspect : Manages the hibernate session for you - no need to use session.update/delete/lock/load/saveOrUpdate/....

After passing through this stack of aspects, your method call is passed to the implementation of the business class, which may then use hibernate's criteria API (or HQL) to query the domain model. In essence jZeno will allow you to use objects from the domain model transparently and not worry about how and when to load/update etc.. the database.

Creating a Business Facade

In this how-to we will be creating a simple business facade as an example. In order to create a business facade you need to create two things in your project :

The business facade interface. This is an interface that has method signatures for all public methods in your business facade.
The implementation class. This class will implement the interface, and will be named identical to the interface, but with the added postfix Impl.

In our example we will be implementing 2 methods, a query operation, and an operation that performs an update of an existing domain model bean. First of all we need to create the interface :

package get.started.business;
	
import get.started.model.Address;

public interface MyBusinessFacade {
	/** This operation retrieves all address model beans. */
	public List getAllAddresses();
	
	/** 
	 * This method updates an existing address model bean, 
	 * and does additional business logic. 
	 */
	public void updateAddress(Address address);
}

Note that this interface is defined in the package get.started.business. This package needs to be configured in jZeno (see below). Next we need to implement this interface in MyBusinessFacadeImpl :

package get.started.business;
	
import get.started.model.Address;

import net.sf.jzeno.aop.Criteria;
import net.sf.jzeno.aop.PersistencySupport;

import java.util.List;

public class MyBusinessFacadeImpl implements MyBusinessFacade {
	public List getAllAddresses() {
		List ret;
		
		Criteria q = PersistencySupport.createCriteria(Address.class);
		ret = q.list();
		
		return ret;
	}
	
	public void updateAddress(Address address) {
		// ...
		// Perform additional check/business logic
		// ...
		
		if(!everythingOk) {
			throw ReallySeriousException();
		}
	}
}

The BusinessFactory

For getting access to a business facade the application code uses BusinessFactory.getFacade() that creates the above mentioned aspects, the required business facade implementation and wires everything up for you. The returned object from this factory will (obviously) be a dynamic implementation of the interface you have defined (in the example the MyBusinessFacade interface).

Configuration

You should tell jZeno where business facades are located. In Admin - General you can specify the business package(s). Configure more than one package by specifying a comma seperated list of business packages. You probably also want to take a look at Admin - Security which allows you to restrict access to your business facade, based on the security context of the current user. Admin - Transactions allows you to specify what kind of transaction behaviour should be used for your business facade (We recommend you use the default - Required as much as possible and avoid complex transaction scenarios). If you need to have business operation that is called from both the presentation layer, and some other business method (or similar scenarios), using delegation to some common class can be very helpful.

Using Your Facade

Now use your new business facade from the presentation layer :

MyBusinessFacade facade = (MyBusinessFacade) BusinessFactory.getFacade("MyBusinessFacade");
List result = facade.getAllAddresses();

// Now use these model beans.. perhaps some DynaTable 
// will be bound to the property 'addresses' ...
setAddresses(result);

Automatic Synchronisation

As stated earlier jZeno will automatically synchronize any changes you make to persistent object to the database at the end of a business call. In order to give you some insight into what is happening here, here's a short description of what happens behind the scene :

Any arguments that are passed into your business facade are recursively scanned to find all reachable persistent entities.
For any entity that was never previously saved into the database (no identifier) jZeno will issue a save operation (INSERT).
For any entity that does have an identifier, but was modified since last exiting from a prevous business facade call, an update operation is issued (UPDATE).
Any entity that does have an identifier, and was not modified since last exiting from a previous business facade call, is re-associated with the new Hibernate session (LOCK).

Some more things you need to know when working with auto-sync facades. When creating new object inside of any business facade you need to use PersistencySupport.create(...). Furthermore you should only issue removal through PersistencySupport.delete(...)

Swizzling

When exiting from a business facade all your persistent objects are disconnected. This means that outside of the business facades objects can no longer retrieve extra (related) objects from the database. This means you must make sure that all related objects are allready loaded when exiting from a business facade method. In order to assist you with this jZeno offers a convenience function on it's PersistencySupport class.

PersistencySupport.swizzle(rootBeanOrCollection,"property.path1,another.property.path2");

Some More Tips

When passing in special communication objects, make these part of your business package. They are after all part of the business layer. What we often do is pass in Filter beans. These are java beans that contain a host of different filter parameters for queries that are implemented in the business facade.
When debugging your jZeno application you may want to step from you presentation layer into a method call on a business facade. As the invocation of such a call is first diverted to the aspects, it can be cumbersome to debug. We advise you to put a break point inside your business class implementation and let your debugger run to that break point, to avoid stepping into the aspect layer.
Don't use model objects for other purposes than they are originally intended for. Remember that the business layer automatically synchronizes domain objects to the database. If you misuse a model object to pass in filter parameters for a query, then you'll be saving that object to the database ! Model objects are not filter criteria !
It is possible to disable auto synchronisation on specific business methods by entering the fully-qualified class name + method name into a property file called autosync.properties. If you do so you need to manually manage Hibernate's session, which can be obtained by calling PersistencySupport.getSession()
If you throw an exception inside of a business call, none of the changes in that business call will be synchronized to the database. The current database transaction is then rolled back.