mod4j User Guide

It is important to understand the principles behind the mod4j project. These principles have guided how the DSL's are designed and how they should be used.

The code generated by mod4j is designed to be extensible by handwritten code,. This allows the developer maximum flexibility. These so-called extension points are designed in such a way that a developer never needs to overwrite generated code, he always extends it. This ensures that code can always be regenerated keeping the model as the source for development during the lifetime of an application.

This section describes a number of code generation patterns that are used in the various code generators. These patters are applied in the code generators of the various DSLs.

1.2.1. Generation Gap Pattern or Empty Subclass Pattern

The problem is twofold:

• handwritten code may get lost when re-generating code from a model

• generated code may sometimes not do exactly what is needed

Solution:

Separate the handwritten and generated code in separate classes / files. Generate an abstract base class that contains all code that is generated. Generate an empty subclass in a separate file. In this way the generator may always regenerate the base class with all generated code, while it will never regenerate the subclass file with handwritten code.

The handwritten subclass file is used for two purposes:

• Extend the generated code in the base class with things that cannot be generated from the model. In this case the base class usually defines something like an abstract method such that this must be defined in the handwritten file

• Overwrite a method in the generated base class. This allows a developer to overrule the generated code. The system depends to a great extent on assumptions about the generated code. Therefore the developer should be intimately aware of the consequences and only use this in exceptional cases.

The empty-subclass pattern is used at several places within Mod4j. It is a well known pattern in Java code generation and allows a clear separation of generated and handwritten code. Code generated for a Java class or java interface is done in two parts. An abstract base class is generated which contains all the generated code. An empty concrete subclass is generated. handwritten code should be put into this subclass.

The generator will always regenerate the abstract base class. The generator will only generate the empty subclass once, if it is not there. In this way handwritten code is never overwritten by the code generator.

The solution is shown in Figure 1.1, “Empty subclass pattern”.

Figure 1.1. Empty subclass pattern

There are a few properties of this solution that we need to be aware of:

1. The empty subclass isn't completely empty. It needs to include the public constructors from the base class with a calls to super(). This means that whenever the generated constructors change, the constructors in the subclass will be outdated.

2. When the abstract base class is not generated anymore, the empty subclass will become superfluous. It refers to a non-existing base class. The java compiler will flag this as an error, and the developer needs to remove the subclass by hand.

class Customer inherits Person [
        // additional properties go here ...
        // additional rules go here ...
]
      

A Business Class may inherit from another business class. All properties, associations and rules defined for the class from which it inherits are applicable to the subclass as well.

A business class may inherit from one class at most, multiple inheritance is not supported.

An enumeration defines a data type which can be used as the type of an attribute of a business class. The enumeration definition includes a list of all enumeration values. The example below shown an enumeration definition.

"The severity level of a customer problem"
enumeration SeverityLevel [
    Low    = 1;
    Middle = 2;
    High   = 3;
]

The "= 1" defines the numeric value that is used for the enumeration literal in the code and the database. This is mandatory, because it is often neccesary to retain previous values when you need to address existing encoding schemes for enumerations, or when you are adding enumeration literals during development.

A business class may include business rules. Note that the concept of business rule here is limited. In this context a business rule is a rule that should be true at all times for every object of the given business class.

Other rules, for example one that trigger something when a certain condition is met, are not covered.

class SampleClass [
    // properties go here ...
    // rules go here ...
    rules [
        "A first rule"
        mustBeValid;
        "A second rule"
        isOriginal;
        "a unique rule"
        unique namesUnique [ firstname, lastname ]
    ]
]

There are two types of business rules that can be modeled.

The first type of business rule has a name only in the model. The actual implementation of the rule must be written in Java as an extension to the generated code. This type business rules are validated in the order they were declared. So in the Sample class above, first the "mustBeValid" rule will be validated and after that the "isOriginal" rule.

The second type of rule is a uniqueness rule, which is indicated by the unique keyword. A uniqueness rule specifies that the combination of values of one or more attributes of the class must be unique at all times. The names of the attributes are specified between brackets after the name of the rule.

The final part of a domain model defines all the relationships between the business classes.

association customer  Customer  one <-> many orders     Order    ;
association order     Order     one  -> many orderLines OrderLine;
association orderline OrderLine many  -> one record     Record   ;

This example shows one bidirectional association, which uses the <-> syntax and one unidirectional association using the -> syntax.

The qualifiers one and many denote the multiplicity of the association at the side of the object closest to it..

TODO: ordered associations and many-to-many associations

public abstract class CustomerImplBase {
  /**
   *  orders: One 2 Many Bidirectional: The customer has a number of orders
   */
  private Set<Order> orders = new HashSet<Order>();

  /**
   * @return orders (Set<Order>) 
   */
  public Set<Order> getOrders()

  /**
   * Implements adding single element to a collection
   */
  public void addToOrders(Order element)

  /**
   * Implements removal of a single element from feature 
   * 
   * @param element 
   */
  public void removeFromOrders(Order element)
 

public abstract class CustomerImplBase {

  /**
   * This operation should NOT be used by clients.  It implements the correct
   * addition of an element in an association.
   * 
   * @param element 
   */
  public void z_internalAddToorders(Order element) {

  /**
   * This operation should NOT be used by clients. It implements the correct
   * removal of an element in an association.
   * 
   * @param element 
   */
  public void z_internalRemoveFromorders(Order element)

The central concept in the Data Contract DSL is the Data Transfer Object, or DTO. A DTO is a value object that carries data only. The purpose of a DTO is to be able to send data to back and forth to and from clients.

Clients communicate with domain objects through services. The services and the service methods are defined by using the Service DSL. The DTO objects define the in- and out parameters for the service methods.

There are several types of DTOs. A customDto is a DTO that may have any attributes. A BusinessClassDto represents the data of a domain object as defined in the Business Domain DSL. A ListDto defines a collection of other DTOs. All these variants are described in detail below.

custom ExampleDto [
    // properties go here ...
]

A custom dto describes

A custom dto has properties of different types.

A BusinessClassDto is a DTO that represents the data of a business class from the Business Domain DSL. As a consequence, the attributes that are allowed within a BusinessClassDTO must map 1-to-1 to attributes of the corresponding business class.

from RecordShopDomainModel import Customer ;

class SimpleCustomerDto represents Customer [
    // attributes go here 
]

A BusinessClassDto always declares the business class that it represents as its base class. This business class must be defined in a Business Domain model. To ensure that the business class is in scope it must be imported first from its business domain model. Import statements are always at the top of a data contract model.

class SimpleCustomerDto represents Customer [
    name; 
    numberOfEars;    
    birthdate;       
    length;          
    "Description of the isMale attribute"
    isMale;
]

Attributes of a BusinessClassDto must have the same names as attributes in the base business class. Not every attribute has to be there, allowing a BusinessClassDto to contain a subset of attributes from its base business class.

The type of the attributes is derived from the type of the corresponding attribute in the business class in the business domain model. Therefore it is not specified in the data contract model.

class SimpleCustomerDto represents Customer [
    // attributes go here 

    references [ 
        orders as OrderNumberAndDateList ;  
    ]   
]

A business class may take part is associations as defined in the business domain model. A BusinessClassDto may represent such an association as well. There are restrictions on represented associations. The main restriction is that only one side of an association is represented as a reference. A Dto does not support bi-directional associations.

The references are contained in the references block. The same rule that applied to attributes also applies to associations. Only associations that are defined in the business domain model may be used. The name to be used is the role name of the opposite class in the association definition.

The type of a reference must conform to the type defined in the association in the business domain model. There are two possibilities.

The association has multiplicity of maximum one. In this case the type of the reference must be a BusinessClassDto based on the BusinessClass in the association.

If the association has a multiplicity larger than one, the type must be a ListDto based on a BusinessClassDto based on the BusinessClass in the association.

Shorthand

If you need a BusinessClassDto that represents all attributes from a BusinessClass, the following shorthand will achieve this. It will by default add all attributes to the BusinesssClassDto.

class FullCustomerDto represents Customer [

public synchronized Customer fromDto(final FullCustomerDto source, 
                                     Customer target) throws TranslatorException;

public synchronized FullCustomerDto toDto(final Customer source); 

The final part of a domain model defines all the relationships between the business classes.

list  CustomerList base FullCustomerDto ;

This example shows the ListDto named CustomerList which contains objects of type FullCustomerDto.

An enumeration defines a data type which can be used as the type of an attribute of a business class. The EnumerationDto definition includes a list of all enumeration values. As with the BusinessClassDto, this dto is connected to an Enumeration in the business class model. The example below shown an enumeration definition.

enumeration SeverityLevelDto represents SecurityLevelEnum [

The SecurityLevelEnum must be defined in a Business Class model and imported defines the numeric value that is used for the enumeration literal in the code and the database. This is optional, but useful when you need to address existing encoding schemes for enumerations.

A service method is method that is defined in the service model, but will be implemented by hand. A method is defined by the keyword "method", followed by the name of the method. A method may have zero or more input parameters and zero or one output parameter.

method addToOrders in [ OrderDto order;
                             SimpleCustomerDto customer 
                     out OrderDto;

In a layered architecture certain types of service methods often occur in applications. Methods for creating, reading, updating and deleting (CRUD) business objects are often needed.

For this purpose the service DSL includes special methods which are indicated by their respective keywords.

from RecordShopDataContract import SimpleCustomerDto

for SimpleCustomerDto create createCustomer ;
for SimpleCustomerDto read   readCustomer   ;
for SimpleCustomerDto update updateCustomer ;
for SimpleCustomerDto delete deleteCustomer ;

Because the Dto is defined in a data contract model it needs to be imported first. As these methods are used for defining CRUD functionality for business objects the DTO used must be a BusinessClassDto.

If you need all of the CRUD methods, you can use a shortcut to specify all four methods as follows:

from RecordShopDataContract import SimpleCustomerDto ;

for SimpleCustomerDto crud ;

In this case the names of the crud methods are derived from the name of the Dto and the business class it represents. In the above example the names will be createCustomer, readAsSimpleCustomerDto, updateCustomer, deleteCustomer. The read method has a slightly unappealing name, but that's for a reason. If multiple CRUD's are defined with different Dto's representing the same businessclass the name readCustomer would become ambiguous. The create, delete and uopdate methods have the SimpleCustomerDto as one of their parameters and haveing these with different Dto's of the same type will result in correctly working overloading. The read method pnly has the id (of type long) as parameter and cannot be overloaded.

/**
 * Create a new SimpleCustomerDto.
 * 
 * @param object 
 *            The SimpleCustomerDto to create.
 * @return the SimpleCustomerDto created, possibly modified during creation.
 */
public SimpleCustomerDto createCustomer(SimpleCustomerDto object);

/**
 * Read an existing SimpleCustomerDto.
 * 
 * @param object 
 *            The id of the SimpleCustomerDto to read.
 * @return 
 */
public SimpleCustomerDto readCustomer(Long id);

/**
 * Update an existing SimpleCustomerDto.
 *  
 * @param object
 *            The SimpleCustomerDto containing the modifications for the corresponding SimpleCustomerDto
 * @return the SimpleCustomerDto updated, possibly modified during update.
 */
public SimpleCustomerDto updateCustomer(SimpleCustomerDto object);

/**
 * Delete an existing SimpleCustomerDto 
 *
 * @param id
 *            The id of the SimpleCustomerDto to delete.
 */
public void deleteCustomer(SimpleCustomerDto object);