Mod4j Application Architecture

The purpose of this document is to describe the architecture of web applications generated by Mod4j. Users of Mod4j need to understand this in order to be able to extend the generated application.

Chapter 2 describes the logical structure of an application generated by Mod4j , while chapter 3 describes its technical structure.

This chapter describes the logical composition of the Mod4j Reference Architecture. It defines the layers, the component types in each layer and the responsibilities of these component types.

Figure 2.1. Logical view

The Layers architectural pattern itself is described in [Busch96]. The Presentation Layer provides an interface to the system to a human user, presenting information and interpreting actions of the user. It uses the Service Layer to obtain the information or execute other operations that the Service Layer offers. The Service Layer provides access to the services of the Business Layer using a particular access protocol, like SOAP, EJB, RMI or local method invocation. The Business Layer provides services that implement functionality and business logic. The Data Layer provides access to persistent data on behalf of the Business Layer. The Domain Model consists of classes that model the part of the world that the application is about. The next paragraphs describes the responsibilities and the structure of the layers in more detail.

The Presentation Layer contains components that present information to a user and interprets his actions by executing functions of the system.Typical responsibilities of the Presentation Layer include:

This Presentation Layer should not execute business functionality by itself, but instead delegate that responsibility to the Service Layer by calling its operations. Data is transferred to and from the Service Layer in the form of Data Transfer Objects.

TODO: expand this section when the User Interface DSL is nearer to completion.

The primary responsibility of the Service Layer is to isolate the business layer from the various protocols in use for remotely invoking its service operations. Examples of such protocols are SOAP or RESTful Web Services, messaging, EJB, RMI or plain old local mehod calls. A service layer presents the interface of the business layer in the form required for one particular access protocol. Therefore, a separate service layer is needed for each protocol by which the system will be accessed. This makes it clear that the presentation layer should not contain any business functionality, because that would have to be duplicated for each separate service layer. Code duplication is bad: it violates the DRY (Don't Repeat Yourself) principle.^[1]

In addition, the service layer is reponsible for:

The Business Layer is a facade for the Domain Model. It exposes the business functionality of the application in the form of methods, with arguments and return values from the domain model. These methods:

The responsibility of the Data Layer is to persist and retrieve data. The data is transferred between the data layer and its calling business layer in the form of arguments and return values based on the domain model. The persistence logic is dependent on the particular persistence technology in use, like a relational database, textfiles, XML documents or an XML database, or another application that exposes services for accessing data.

The data layer contains a number of data access objects, in principle one for each domain model class. Each such object:

The Domain Model contains classes that model the part of the world that the application is about. The domain model is developed in an object oriented way as advocated by [Fowler02] and [Evans03]. As much business functionality as possible is implemented as methods on domain model classes. Domain model objects:

The application is implemented as a Maven project, consisting of a parent project of type pom, and a number of modules, one for each layer of the Logical View. The modules are contained in subdirectories of the directory of the parent project.

The names of the modules are formed by concatenating the Mod4j Project Name, a dash ("-") and a keyword derived from the architectural layer the module implements. For a hypothetical Mod4j project "RecordShop", the module names would be: RecordShop-service, RecordShop-business, RecordShop-data and RecordShop-domain.

The Maven project can be built by Maven from the command-line. Alternatively, the modules may be imported into Eclipse with the Q4E -plugin, and built from within Eclipse.

The Java classes are organised in Java packages. The package names are prefixed with a root package name provided by the user at the time the Mod4j project was created by the Mod4j Project Creation Wizard. After project creation the root package name is stored in the file src/model/mod4j.properties as the value of the property rootPackage. This file can be edited manually to change the root package name. The packages names below this common prefix start with a package name corresponding with the component name, that in turn is derived from the architectural layer that it implements.

The Spring framework is used as a general application framework. The objects making up the application are being wired up by the Spring framework based on a number of XML configuration files, generally one per layer. The Spring ContextSingletonBeanFactoryLocator class is used to create multiple hierarchical Spring IoC container instances, also called bean factory or application context in Spring parlance, from these XML configuration files. For the container of each layer, the container of the lower layer is the parent container.

Beans defined in a direct or indirect parent context are visible in the child context, but not vice versa. This hierarchical container is then used as the parent container of a web application container. In this way, containers and the beans contained in them, may be shared between several web applications, and loaded only once. Moreover, the hierarchical composition of the container guarantees that dependencies between them are parallel to the depencencies between the layers of the logical view. See section 3.9 Glue code and the evil singleton in [Spring25] and the Javadoc for ContextSingletonBeanFactoryLocator for more details.

Hibernate is an object-relational mapping framework used to implement the data layer. This section document the choices made in several area' of this framework.

<version name="version" unsaved-value="negative"/>

@SuppressWarnings("unused")
private int version = -1;

<property name="sexe">
    <type name="org.company.recordshop.data.GenericEnumUserType">
        <param name="enumClass">
            org.company.recordshop.domain.SexeEnum
        </param>
    </type>
</property>

package org.company.recordshop.domain;

import java.util.EnumSet;
import java.util.HashMap;
import java.util.Map;

/**
 * Sexe enumeration.
 */
public enum SexeEnum {

    FEMALE(1), MALE(2);

    private static final Map<Integer, SexeEnum> lookup =
        new HashMap<Integer, SexeEnum>();
    static {
        for (SexeEnum s : EnumSet.allOf(SexeEnum.class))
            lookup.put(s.id(), s);
    }

    private Integer id;

    private SexeEnum(Integer id) {
        this.id = id;
    }

    public Integer id() {
        return id;
    }

    public static SexeEnum value(Integer id) {
        return lookup.get(id);
    }
}

The domain model classes need very little framework support. They are implemented as Plain Old Java Objects (POJO's). The business rule implementations do rely on some classes of the Spring framework, but they are implemented as separate classes. The domain model classes are not in any way dependent on them.

Domain model objects are designed to be at all times in a consistent state. To be in a consistent state means that all mandatory properties have a value, and that the object satisfies all business rules defined for the class. This principle is enforced by providing

The busines rules must be checked whenever the state of an object changes. For example, at the end of the constructor with the mandatory properties, and at the end of every setter.