warning this documentation is still somewhat incomplete. We are working hard to improve both the feature set and the documentation. So do have a browse around, but definitely come back later to see how things evolve.

equanda purpose

equanda is a tool which should help you to build enterprise grade (J2EE based) application with minimal effort, focussing not only on the initial version, but considering that most of the cost will be in maintaining and evolving the application.

This is done by generating as much as possible directly from an XML description of the the data and interactions (the domain model or "dm"). Some more thoughts about the concept (generation) can be found here.

There are many ways to enhance/improve the generated application, but this is always done in such a way that most changes in the domain model don't cause any problems. You just recompile (which re-generates all the files which needs modifying) and all the manual changes are preserved.

The idea is that application development should be focussed on doing the important stuff (the unique features of the application), and that common aspects should only be done once (even more so because this improves consistency). The goal is to work towards a vision of how application development should be (original thoughts in this blog).

Model based programming

In equanda, the definition of the domain or domain model is very important. This is a (xml) description which contains your data structure enriched with possible declarative constraints on your data, hints for the user interface, information about user rights etc.

From this model various aspects of your application can be built. This is done using code generation based on Velocity templates. The templates are written in such a way to allow programmatic customizations and extensions without affacteing the generation proces. So when your domain model changes, you can just re-generate your application. The changes in the model will be propagated and your customizations will still be in place. No cut and paste or other manual labour is needed.

equanda is built to have many aspects where flexibility is offered, to allow you to choose what kind of application is built.

Some examples :

• the persistence layer is built to use EJB3, but you could replace this to use web services to query the data (though currently only EJB3 templates exist).

• user interface widgets can be replaced globally (by type or fieldname), on a per-field basis or in specific locations.

• the user interface could be built using the interface of your choice (provided the templates exist).

• the domain model has been used in projects to generate custom (non-soap) web services.

• the domain model has been used in projects to generate data schema, data lists,...

Generated application features and options

General features

equanda is intended to help you build enterprise grade (business) applications with minimal effort.

The application can run in a client server environment and can be deployed on several tiers.Specifically, you could deploy the web server, the business tier and the database on different machines. Moreover, while the business tier needs to have access to the database tier, the (web) client tier only needs access to the business tier. This way it is possible to secure that all access to the database is forced through the business tier and to ensure that all the constraints which are enforced by the business tier cannot be evaded.

Internationalization is built into the system. All the information in the system can be translated, both the messages on the user interface and the error messages. There is specific support and tools to manage the translations. This to allow separate people (non-programmers) to manage the translations without the properties hell (where you have translation in tens or hundreds of properties files).

The generation has some extra support for useability. There are efforts to make the templates as readable as possible, but to aid you the generated (java) files can be source formatted, the generated xml files can be formatted and/or validated. However, in both cases this can be disabled as well (to make generation faster).

The following aspects of the application can be generated.

EJB3 persistence layer

Domain model description options

• (multiple) inheritance

• declarative constraints

• programmed constraints

• int, double, string, blob, clob fields

• fields with multiple values

• hard linked records (normal db links)

• soft linked records (using an ordinary field reference, the linked record may not exist)

• field values can be limited (choices) either statically (xml description) or programmatically (validation)

• for removing records cascade-delete, cascade-keep (don't delete when there are references to the record) or normal null all references behaviour can be used

• field (type) templates can be used

Implementation

• powerful proxies are used which make objects available remotely. Similar to detached objects, but completely transparent (no need to instantiate)

• lazy collection instantiation, when a selector contains lots of objects, the results are still batched (and counting works too)

• inheritance sensitive selectors

• filters and sort orders can be defined on the selectors

As a bonus, when your client only uses the proxies, it is straightforward to replace the backend (this way the data could for example be based on webservices instead of EJB3 entity beans).

More details about the generated EJB3 persistence layer.

tapestry5 user interface

• thin client, all browsers, no need for ActiveX activation of client side java

• easy/efficient keyboard navigation

• powerful automatic cross linking of records

• fields can be distributed over (tab) pages with some fields be visible on all tabs

• fields can be grouped

• setting links using suggest values (*)

• powerful user management with customization of rights (*)

• possible choice of visible fields per user (*)

• possible printout (pdf doc) of the result of selectors, with user configurable fields (screen and pdf), and column width (pdf) (*)

• inclusion of reporting in the user interface (*)

• generated components can be used to build custom pages

• highly customizeably, layout components define how things are combined on screen

• possible to change the components used for a specific type or field or on a case by case basis

(*) ^Items marked like this are available in the old tapestry4 version and will be available again for the tapestry5 version.^

More details about the generated tapestry5 user interface.

user management support

equanda uses an internal mechanism to configure the very granular access rights for the user interface. This is based on user information in the database. This module allows you to generate a login module which prevents duplication of user information between the application and the JAAS module.

More details about the generated user management support.

import data

It is possible to generate code which can be used to import data from a CVS-like text file.

More details about the generated import data.

ddltool

This allows generation of a tool which handles database update (and optionally partial cleanup).

More details about the generated ddltool.

domain model documentation

Documentation for the domain model can be generated. This includes html documentation, a Freemind mindmap and owl.

More details about the generated domain model documentation.

equanda modules

equanda contains several modules.

• client : client side code. This module needs to be included by the client components for equanda applications.

• server : server side code which is needed for the equanda framework.

• generate : module which handles the code generation, processing the domain model and contains the templates.

• maven-plugin : maven plugin which allows the generation to be done as part of a maven build cycle, but also for editing the translations and doing a database update.

• tapestry5 : collection of tapestry5 components which can also be used outside of equanda applications.

• t5navigation : tapestry5 extension which allows easy building of breadcrumbs, helping in navigations and removes a limitations from tapestry's default persistence mechanism.

• t5gui : collection of tapestry5 components which are specific for equanda generated applications.

• tool : tool provided for import, export, remote printing of reports.

• util : contains several utility classes containing (amongst others) ean128 barcode support, FScript extensions, useful Swing classes.

• test : this module is used to do integration testing. It is only included when the "-Dfulltest" switch is used in maven.

Technology

• The generated program uses EJB3 for the entity and session beans

• JBoss AS is used for development of the framework

• Firebird database is used for testing

• The Tapestry framework is used for the user interface

• maven (or Ant) and Velocity are used to drive the generation

• Javolution is used (mainly) to avoid garbage creation and for some extra speed.

• FScript for a simple, extensible scripting language

• junit for unit testing

• log4j for logging support

• commons httpclient

History of the project.

Thanks to

• Equanda is based on Uni-d, for which the development was sponsored by CAB-software. The principles have proven themselves there for the implementation of IC-trace.

• The development is supported by synergetics where equanda is used for the development of the competency analyzer and employability portfolio.