GOTECH - General Object To EJB Conversion Helper

Table of contents:

  1. Introduction
  2. Architecture
  3. Requirements and Configuration
  4. Example
  5. Tutorial
  6. Dependency Tool
  7. Links/Download
  8. Contact information

1. Introduction

GOTECH is a framework that can be used with a large class of unaware applications to turn their objects into distributed objects with minimal programming effort. A poster giving an overview of GOTECH can be found here. Our framework is developed on top of three main components:

Converting an existing Java class to conform to the EJB protocol requires several changes and extensions. An EJB consists of the following parts:


2. Architecture

In our approach this means deriving an EJB from the original class, generating the necessary interfaces and the deployment descriptor and finally redirecting all the calls to the original class from anywhere in the client to the newly created remote interface. The process of adding distribution consists of the following steps:

(The XDoclet templates used in step 4 are among the pre-defined XDoclet templates and not part of the GOTECH framework.)


3. Requirements and Configuration

GOTECH was tested with the following Versions of the required tools:

Using the GOTECH framework requires to configure it for the intended application. The settings for ant are stored in the file and will be explained below. All configuration settings must have valid values in order for GOTECH to work correctly.

Parameter Description
aspectj.home path to the AspectJ home directory
jboss.home path to the jboss home directory
jboss.configuration name of the jboss configuration to be used for deploying the application
xdoclet.home path to the xdoclet home directory

The following directories are used and created during the transformation process.

Directory Description
src contains the source of the original application
src.share contains the sources that are shared between client and server (note that the original non-EJB object is a shared source)
src.client contains the sources that are only used by the client (for example the client main class)
src.server contains the sources that are only used by the server
build contains the generated application and generated sources
build.bin contains batch files for setting the correct class path and for setting jndi properties
build.cclasses contains compiled classfiles for the client
build.client contains the jar’ed client files
build.deploy contains the jar’ed deployment files
build.META-INF contains the deployment descriptors
build.sclasses contains compiled classfiles for the server
build.generate contains the generated source files
buildfile contains the ant build file and the configuration file
xdoclet contains the XDoclet-templates and extensions


4. Example

In this section we present an example of applying the GOTECH framework to convert a scientific application into a distributed application interacting with an application server. The original application is a thermal plate simulator. Its back-end engine performs the CPU-intensive computations and its front-end GUI visualizes the results. The distribution scenario we want to accomplish is to separate the back-end simulation functionality from the rest of the application. and to place it on a powerful remote server machine. There are several benefits gained by this distribution scheme. First, it takes advantage of the superior computing power of a remote server machine. Second, multiple clients can share the same simulation server. Finally, if real heat sensors are used, the user does not have to be in the same physical location with the sensors to run the experiment.

The distribution scenario for the thermal plate simulator is one where the GUI is running remotely from the core application and used a facade class to communicate with it. A simplified UML diagram for the original version of the thermal plate simulator is shown below. We have laid out the class diagram so that the front-end and back-end are clearly visible. The hierarchy under interface Plate contains the types of the objects that form the connecting link between the application’s front-end and back-end. The graphical front-end creates a Plate object and several visual component objects reference it and query it to obtain the necessary data when performing their drawing operations. The Plate object gets modified by being sent as a parameter to the diffuse method in the Simulation class. Once the diffuse method returns having modified its Plate parameter, the front-end is signaled to repaint itself. The visual components can access the updated data of the Plate object and redraw.

Notice that making simulation classes remote while preserving the original execution semantics requires special handling for remote method parameters. The Plate object that participates in a complicated aliasing (i.e. multiple referencing) scenario now becomes a parameter of a remote call to an EJB. If a copy-restore mechanism is not provided by the application server, then the process of bridging the differences between local (by-reference) and remote (by-copy) parameter passing semantics becomes a tedious and complicated task. The use of NRMI (copy-restore semantics) completely eliminates the need for special purpose code to reproduce the back-end changes to the Plate object inside the front-end.

Distributing the application using GOTECH is done in six steps.

First step: Generating the bean
The enterprise java bean is generated by using a generic xdoclet task and the bean_generator.j template provided by the GOTECH framework. The following assumptions are made and limitations apply:

• the transformation is restricted to classes, interfaces currently cannot be converted into EJBs
• the necessary annotations have to be made (“@ejb:bean ….” and "@jboss:method-attributes ...." if copy-restore is needed)
• only non-private methods can be included in the remote interface
• all remote methods are made public during the transformation process

Second step: Making method parameters implement serializable
The EJB-standard requires all method parameters of EJBs to implement the serializable interface. The approach of GOTECH is quite naďve as to determine whether a class or interface is suitable for serialization or not has to be determined by the programmer. Also, using AspectJ for making classes serializable, the source code has to be available. The Aspect is created by a generic xdoclet task with a template file called serializable_generator.j, requiring no special extensions. The following assumptions are made and limitations apply:

• The classes affected by the xdoclet task are the same as in the first step.
• The generated aspect simply tries to make all parameter types implement Serializable, whether source is available or not.
• The AspectJ-compiler will issue warnings if the declare parent statement cannot be applied due to missing sources in the compilation step

Third step: Creating wrapper aspect
For catching and redirecting all calls to the original class, an aspect is used. The current aspect can deal with stateless and stateful session beans creating one connection for each instantiation of the wrapped object in the stateful case and one connection during initialization in the stateless case. The following assumptions are made and limitations apply:

• All calls made within the sources in the share and client directory get redirected
• Exceptions caused by the added remoteness cause just a stacktrace output leaving the system in an undefined state

Fourth step: Creating EJB interfaces
This step relies entirely on the functionality provided by XDoclet. It has its own section in the build file. For documentation please refer to In this step, the remote and home interfaces of the previously generated bean class are created as well as the necessary deployment descriptors for JBoss.

Fifth step: Compiling
In this step, the AspectJ-compiler is called to compile all sources. Two compiler runs are necessary, one for the client classes and one for the server classes. The classes are created in the specified output directories and the aspects created in the previous steps get interwoven into the original code.

Sixth step: Packaging and Deploying
In the packaging step, jar-files are generated for the client and the server. The server-jar is then deployed at the application server. The functionality provided by ant is sufficient for copying and jarring the files.


5. Tutorial

Click here to see the GOTECH tutorial.


6. Dependency Tool

The Dependency Tool analyzes a set of compiled class-files and determines which classes (respectively their source files) can be put in the client directory and which classes have to go to the shared directory. The tool requires the BCel libraries. A link is provided below. The usage is as follows:

java GOTECHDependencies <sourceDirectory> <Bean Candidate classname> [<Bean Candidate classname>]


7. Links/Downloads


8. Contact information

For questions, comments, and bug reports please contact Stephan Urbanski or Eli Tilevich.