Mod4j 1.3.0 Upgrade Notes

The upgrade steps as described on this page are needed if you want to upgrade your project from Mod4j 1.2.1 to Mod4j 1.3.0 .

Unfortunately this release of Mod4j comes with a breaking change. Due to evolving insight we've changed the signature of two service methods for creating and updating business objects. So if you maintain one or more service models in your project, you should be prepared to make a view changes to your code.
In one of the upgrade steps below you will be guided in how to make these changes, so that your code will work with Mod4j 1.3.0 and later.

Please mail to user@mod4j.codehaus.org if you have any questions or need help.

If you want to upgrade from earlier released versions, you'll need to follow the required upgrade steps as described in the subsequent Upgrade Notes for each release. For an overview of of the releases and Upgrade Notes, see the Mod4j Releases page

Installation of Mod4j Eclipse plug-in 1.3.0

Before you install a new Mod4j Eclipse plug-in into Eclipse make sure you un-install older versions of the plug-in.

Here you can find download and install instructions, that will guide you to install Mod4j, by making use of the Mod4j updatesite.

Regenerate Mod4j-CrossX data files

This version of Mod4j generates new CrossX data files. So to prevent a mix-up between the old and the new files, the old ones must be removed from your filesystem.

  1. Open Eclipse and navigate to your -dslModules project
  2. Search for all files that end with the extentsion .crossx~
  3. Delete them all from your filesystem
  4. Restart Eclipse to start with a clean memory again.

Changes in Maven configuration

With this release there's only one thing to change in the parent-pom of your application. The parent-pom (pom.xml) is located at the root of your project (if you didn't change its location).

  • Adjust mod4j.version property to 1.3.0 :

Changes in services

If you have a service model and make use of one or more crud-services or individual create or update services, you must be prepared to make some changes in to your code that makes use of them.

What has changed?
The signature of the generated create and update service methods in the service-layer have changed. All create service methods now return a Long value, representing the unique id of the just created business object, instead of returning the full dto object.
Example:

public Long createCustomer(SimpleCustomerDto object);

The signature of the update service methods also has changed. Where it previously returned the just updated business object(s) as dto, as of this version of Mod4j it returns void.
Example:

public void updateCustomer(SimpleCustomerDto object);

Code changes
All your custom code that makes use of these service methods needs to be changed. After you have upgraded your project to Mod4j 1.3.0, your compiler will tell you exactly what code should be taking care of.

Why did this change?

  • First reason is that for update service methods we could not guarantee that the returned dto-structure was fully conistent for all possible scenario's. For simple dto-structures it was possible, but for complex dto-structutures with circulair references and multiple objects of the same type we run into a theoretical borders.
  • We want the service methods to satisfy the CQS (Command Query Separation) principle. Service methods should perform a command (create or update) or a query (read or find) but not both at the same time.
  • With returing the complete dto-structure for the update and create services you get more then you asked for. Sometimes this is kind of tie-in sale that you do not want. Especially when performance is an issue.

Changes for RuntimeExceptions

Validation errors resulting from rules in the business domain model are collected in a Errors object wrapped in a BusinessRuleException . Clients can catch this, retrieve the Errors object, analyze the errors and presumably show them to the user. Other exceptions that may be caught by the clients calling services are mostly RuntimeExceptions that are caused by programming errors. For example, IllegalArgumentExceptions when a null-object is passed to a service method.