Apache Cayenne is a powerful, full-featured Java Object Relational Mapping framework. It is open source and completely free. Cayenne cross-platform modeling GUI tools place it in the league of its own, making it a very attractive choice over both closed source commercial products and traditional "edit your own XML" open source solutions.
Cayenne-AXIS was planned as direct analogue of the Hessian based Cayenne Remote Object Persistence system (ROP) implementation.
As it said in the Cayenne ROP guide: "'Remote Object Persistence' is a low-overhead web services-based technology that provides lightweight object persistence and query functionality to 'remote' applications." So Cayenne provides object-relational mapping capabilities with opportunity to keep persistent objects synchronized with the back-end database, and by using Cayenne ROP remote applications can work with these objects nearly as they were their own.
Original Cayenne ROP uses Caucho Hessian Binary Web Service Protocol to transport objects by the network. Cayenne-AXIS is based on Apache AXIS web services framework - "an implementation of the SOAP ('Simple Object Access Protocol') submission to W3C".
With some decreasing of processing speed, use of the world standard XML network interchange protocol brings many advantages to Cayenne ROP system such as ability to implement clients on any platform (not only Java), ability to extend its functionality by using middle tier XML monitoring and processing tools, etc.
The following articles are intended for people who are familiar with Cayenne's ROP system. See "Links" section at the end of this document for information resources.
Cayenne-AXIS is an extension to Cayenne. It provides normal org.apache.cayenne.CayenneContext object with all its functionality for client use. This client side CayenneContext is back-ended with connection (implementing org.apache.cayenne.ClientConnection interface) to the web service. All client queries are translated to the server through this connection.
Server side of Cayenne-AXIS is represented as AXIS web service self-providing its WSDL definition (Web Service Definition Language) and XML Schema type hierarchy. It uses configured Cayenne DataContext which forms responses for all the remote requests.
Original Hessian-based Cayenne ROP implementation uses binary serialization of Java objects. So to be correctly serialized and deserialized Java classes of persistent objects are required on both client and server sides. But actually in many cases serialization is the only thing for which these classes are needed on the server.
Cayenne-AXIS does not require persistent classes on the server side. Its server operates with persistent objects of one common class - org.apache.cayenne.CayenneDataObject. Cayenne configuration files on the server side must have this class assigned for all of persistent entities. But on the client side every persistent entity has its own class. Conversion of server-side CayenneDataObjects to concrete business logic client-side classes is implemented at the AXIS serialization/deserialization layer and it is transparent for users.
Furthermore Cayenne-AXIS uses only entity names and XML Schema types to define object types in the SOAP interchange. No Java-dependent data is transported through the network. So clients for the Cayenne-AXIS web service can be implemented on any platform.
Cayenne-AXIS has its own configuration strategy which differs from the original Cayenne ROP.
Cayenne-AXIS server-side configuration is represented as normal Cayenne config. It consists of cayenne.xml, data mapping configuration files (*.map.xml) and db connection configuration files (*.driver.xml). The only claim for this config is that all entities in *.map.xml files must have org.apache.cayenne.CayenneDataObject as class definition.
Client configuration consists of collection of slightly changed data map definitions only. Main purposes of these changes are:
So currently these changes were made in the client config:
There is a special Ant task in Cayenne-AXIS distribution for generating client-side configuration files using normal server configuration as input - org.apache.cayenne.remote.axis.ant.GenerateClientDataMapTask.
Also there is an adapted version of CayenneGenerator Ant task for generating client-side classes by using client config as input - org.apache.cayenne.remote.axis.ant.CayenneAxisGenerator.
See usage instructions in the cayenne-axis-server project Ant scripts.
The main part of the Cayenne-AXIS distribution is cayenne-axis.jar library. It contains both client-side and server-side classes (most of them used on both sides).
Cayenne-AXIS is a normal AXIS web service. It can be deployed to any AXIS-enabled web application by using deployment descriptor in deploy.wsdd file. See AXIS documentation for deployment instructions.
Another variant is creating separate Cayenne-AXIS web application. Such application must contain AXIS installation (AXIS servlet, etc) and Cayenne-AXIS web service deployed on it. Also it can contain any specific data such as downloadable client-side classes (for easy client creation), some documentation or any other things (maybe other web services).
Cayenne-axis-server project is an example of such web application. It contains all required things for Cayenne-AXIS to work. See cayenne-axis-server/ant/readme.txt for information.
Cayenne-axis-server project can be used as base for creating concrete Cayenne-AXIS web applications.
A client for Cayenne-AXIS web service must contain following thigs:
"Cayenne-axis-server" projects allows downloading jar archive with client configuration and pre-generated client-side classes from the web app. This jar can be placed into client's classpath.
As it was said before, Cayenne-AXIS provides normal CayenneContext, back-ended with web service connection, for client use.
This context can be created on client-side by executing following code:
org.apache.cayenne.ObjectContext context = org.apache.cayenne.remote.axis.CayenneAxisContextFactory.createClientContext("http://localhost:8080/Cayenne/services/CayenneROP");
...where URL should be replaced with correct one.
There is an example of Cayenne-AXIS client in the "cayenne-axis-test-client" project.