Abstract

These pages describe an AndroMDA feature called Manageable Entities, probably better known as CRUD. This feature is something which can optionally be applied on existing <<Entity>> elements so that it becomes very easy to manage them: creation, searching, updating and deleting.

Please NOTE that the manageable entities feature MUST use the Spring Cartridge in order to take advantage of data access object(DAO) feature of Spring.

Features

An always recurring feature in J2EE applications is the one where it needs to be possible to directly maintain or manage the data in the database. Customers expect pages or windows which nicely integrate with the rest of the application and that allow them to apply any kind of change against the existing database content.

AndroMDA supports this, and can generate the complete set of required files and resources as to be able to manage the entities. Here's what's currently supported:

  1. Inserting new data (create)
  2. Searching for data based on any of the entity's attributes and associations (read)
  3. Updating existing data (update)
  4. Binary data can be uploaded and downloaded
  5. Data can be exported to Excel, CSV, XML and PDF
  6. Deleting data, possibly many at once (delete)
  7. Hide database specific details from the user, such as auto-generated identifiers or entire columns
  8. Easily switch to another entity
  9. Easily switch to an entity referred to by the current entity
  10. Easily switch to an entity refering to the current entity
  11. Allowing actors to be associated to an entity when security has been enabled, this will authenticate only those users with the corresponding role
  12. Fetched records are pageable
  13. Fetched records are sortable
  14. Generated code easily integrates into an existing AndroMDA generated application by making use of the same stylesheets and XML deployment descriptors
  15. Generated code is optimized for performance; since the only thing it needs to do is very straightforward it has been stripped of all generic overhead so that only the minimum set of objects is created, a minimal set of SQL queries are executed (there's still room for improvement though, and will be optimized even more in the future)
  16. The generated pages are internationalized and translation should be as simple as adding a new resource bundle
  17. No manual coding is required: you run AndroMDA on your model and you deploy
  18. Tuning the generation process can be done by means of namespace properties and tagged values

images/crud-thumb.gif (Larger View)

Here's the online sample: CRUD sample application

Configuration

In order not to fetch thousands of records everytime you perform a search query it is possible to set an upper limit, the maximum number of records to fetch in a single call. Use the defaultMaximumListSize namespace property.

Associated entities will be represented by their identifiers, but you might want to consider using <<Unique>> entity attributes, when the CRUD feature sees such an attribute it will take that one instead of the identifier (only for displaying of course). When more than one such attribute is present, the first one found will be used.

Pitfalls

In order to enable entities associated with a certain entity the association ends to those other entities need to be navigable. The entities are required to also be Manageable.

Todo: write the necessary OCL constraints where applicable, and make the associated entities work even when they don't have the Manageable stereotype.

Future improvements

Database error messages should be translated into something more readable, in the case where a record is to be deleted but there are foreign keys pointing to it HSQLDB will complain with a message saying Batch failed, which isn't exactly very indicative of the actual problem.

Input should be validated using the Struts validator plugin, this will avoid unnecessary calls to the backend.

The returned lists should be pageable with a direct link to the database, this will yield better performance and memory management as only the displayed records will be loaded and the next and previous pages will be auto-loaded on DB idle-time, such as solution scales much better than the current one which simply loads all records (it is possible to set an upper limit though).

So what do I do ?

It's extremely simple: just add a <<Manageable>> stereotype to each class carrying an <<Entity>> stereotype you wish to manage. Currently there is a restriction where you also will need to add this stereotype on the entities associated with this one.

Make sure the bpm4struts cartridge knows how to call the back-end, set this namespace property: <code><manageableServiceAccessorPattern>${pom.package}.ManageableServiceLocator.instance().get{1}()</manageableServiceAccessorPattern></code>. (when not using EJB session beans, this feature's compatibility has not yet been fully tested with EJBs enabled)

Make sure the schema in your database exists before actually calling the manageable actions, or you'll get an exception saying the operation could not be performed (obviously).

More to come later...

This documentation is a work-in-progress, in time more will be added.