Overview

Most domain objects that the end-user interacts with are likely to be domain entities, such as Customer, Order, Product and so on. These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus annotations.

Some domain entities are really aggregates, a combination of multiple objects. A commonly cited example of this is an Order, which really consists of both a root Order entity and a collection of OrderItems. From the end-users' perspective, when they talk of "order" they almost always mean the aggregate rather than just the Order root entity.

Eric Evans' Domain Driven Design has a lot to say about aggregate roots and their responsibilities: in particular that it is the responsibility of the aggregate root to maintain the invariants of its component pieces, and that roots may only reference other roots. There’s good logic here: requiring only root-to-root relationships reduces the number of moving parts that the developer has to think about.

On the other hand, this constraint can substantially complicate matters when mapping domain layer to the persistence layer. DDD tends to de-emphasise such matters: it aims to be completely agnostic about the persistence layer, with the responsibilities for managing relationships moved (pretty much by definition) into the domain layer.

As a framework Apache Causeway is less dogmatic about such things. Generally the domain objects are mapped to a relational database and so we can lean on the referential integrity capabilities of the persistence layer to maintain referential invariants. Said another way: we don’t tend to require that only roots can maintain roots: we don’t see anything wrong in an InvoiceItem referencing an OrderItem, for example.

Nonetheless the concepts of "aggregate" and "aggregate root" are worth holding onto. You’ll probably find yourself defining a repository service (discussed in more detail below) for each aggregate root: for example Order will have a corresponding OrderRepository service. Similarly, you may also have a factory service, for example OrderFactory. However, you are less likely to have a repository service for the parts of an aggregate root: the role of retrieving OrderItems should fall to the Order root (typically by way of lazy loading of an "items" collection) rather than through an OrderItemRepository service. This isn’t a hard-n-fast rule, but it is a good rule of thumb.

Domain services are (usually) singleton stateless services that provide additional functionality. Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.

A very common type of domain service is a repository, that is used to look up existing instances of a domain entity. For example, for the Customer entity there may be a CustomerRepository, while for Order entity there may be an OrderRepository.

Similarly, entities might also have a corresponding factory service: a CustomerFactory or an OrderFactory; Evans' Domain Driven Design, draws a clear distinction between a factory (that creates object) and a repository (that is used to find existing objecpts).

On the other hand, from an end-users' perspective the act of finding an existing object vs creating a new one are quite closely related. For this reason, in Apache Causeway it’s therefore quite common to have a single domain service that acts as both a factory and a repository (and is usually called just a "repository").

The behaviour of these services is rendered in various ways, though the most obvious is as the menu actions on the top-level menu bars in the Web UI (Wicket viewer)'s UI.

Domain services can also be used for a number of other purposes:

Domain objects of any type (entities, other services, view models, mixins) can also delegate to domain services; domain services are automatically injected into every other domain object. This injection of domain services into entities is significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into supporting service layers. Said another way: it is the means by which Apache Causeway helps you avoid the anaemic domain model anti-pattern.

Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value.

View models are similar to entities in that (unlike domain services) there can be many instances of any given type. End users interact with view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other.

However, whereas domain entities are mapped to a datastore, view models are not. Instead they are recreated dynamically by serializing their state, ultimately into the URL itself (meaning their state it is in effect implicitly managed by the client browser). You will notice that the URL for view models (as shown in Web UI (Wicket viewer) or RestfulObjects viewer) tends to be quite long.

This capability opens up a number of more advanced use cases:

We explore these use cases in more detail below.

The final type of domain object is the mixin. These are similar to traits or extension methods in other programming languages. A mixin object allows one class to contribute behaviour - actions, (derived) properties and (derived) collections - to another domain object, either a domain entity or view model. Or rather, the mixin appears to contribute the behaviour/state in the UI; the underlying domain class being "decorated" does not know this is happening.

This is therefore a key technique to allow the app to stay decoupled, so that it doesn’t degrade into the proverbial "big ball of mud". There’s a lot more discussion on this topic in modules, below.

Mixins are also a convenient mechanism for grouping functionality even for a concrete type, helping to rationalize about the dependency between the data and the behaviour. Each mixin is in effect a single behavioural "responsibility" of the domain object.

In fact, we find mixins nicely balance inside-out vs outside-in ways of thinking about a system:

So, while Apache Causeway allows you to put behaviour onto the underlying domain entities, it can often be better to treat the domain entities as immutable. Instead, use mixins to implement behaviour. When using an agile development methodology, it’s common for a user story to correspond to a new mixin.

There are also practical reasons for moving behaviour out of entities even within the same module, because structuring your application this way helps support hot-reloading of Java classes (so that you can modify and recompile your application without having to restart it). This can provide substantial productivity gains.

The Hotspot JVM has limited support for hot reloading; generally you can change method implementations but you cannot introduce new methods. However, the DCEVM open source project will patch the JVM to support much more complete hot reloading support. There are also commercial products such as JRebel.

To allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon. The icon informally identifies the type of the domain object, while the title identifies the instance.

As well as defining a metamodel of the structure (domain classes) of its domain objects, Apache Causeway also manages the runtime instances of said domain objects.

When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an object identifier. Fundamentally this is a combination of its type (domain class), along with an identifier. You can think of it as its "primary key", except across all domain entity types.

For portability and resilience, though, the object type is generally an alias for the actual domain class: thus "customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer". This is derived from an annotation. The identifier meanwhile is always converted to a string.

Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by a given Apache Causeway application. With it, we have the ability to lookup any arbitrary domain objects.

Some examples:

Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects to obtain OIDs. These are represented as Bookmarks, obtained from the BookmarkService. Deep links meanwhile can be obtained from the DeepLinkService.

OIDs can also be converted into XML format, useful for integration scenarios. The common schema XSD defines the oidDto complex type for precisely this purpose.

Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another entity or view model).

For example (using Project Lombok to avoid some boilerplate), with:

From this the framework infers the Customer domain entity, which in turn has a firstName string property.

@Property is not mandatory, though in many cases it will be present in order to specify additional semantics.

@PropertyLayout is not mandatory either. Whether it is present or not depends to some extent on your preferred style: the UI semantics can be specified either in code within this annotation, or can be specified through the companion layout file.

Like properties, collections are also represented by a getter and setter, however the return type is a Collection or subtype.

For example (again, using Project Lombok), with:

From this the framework infers the orders collection.

As with properties, the @Collection annotation is not mandatory, though in many cases it will be present in order to specify additional semantics.

Similarly, @CollectionLayout is not mandatory either. Whether it is present or not depends to some extent on your preferred style: the UI semantics can be specified either in code within this annotation, or can be specified through the companion layout file.

While properties and collections define the state held by a domain object (its "know what" responsibilities), actions define the object’s behaviour (its "know how-to" responsibilities).

An application that consists only of domain entities with just "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn’t modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date"). Such applications are often called CRUD applications (create/read/update/delete).

In more complex domains, it’s not realistic/feasible to expect the end-user to have to remember all the different business rules that govern the valid states for each domain object. Actions allow those business rules to be encoded programmatically. Those actions can either be defined in the domain class itself, or can be contributed by way of a mixin.

The general philosophy for an Apache Causeway (naked objects) application is not to constrain the end-user in how they interact with the UI: it doesn’t attempt to define a rigid business process. However, it does aim to ensure that business rule invariants are maintained, that is that domain objects aren’t allowed to enter into an invalid state.

For simple domain applications, you may want to start prototyping only with properties, and only later introduce actions (representing the most common business operations). But an alternative approach, recommended for more complex applications, is actually to start the application with all properties non-editable. Then, as the end-user requires the ability to modify some state, there is a context in which to ask the question "why does this state need to change?" and "are their any side-effects?" (ie, other state that changes at the same time, or other behaviour that should occur). If the state change is simple, for example just being able to correct an invalid address, or adding a note or comment, then that can probably be modelled as a simple editable property. But if the state change is more complex, then most likely an action should be used instead.

Broadly speaking, actions are those public methods that do not represent properties or collections.

For example:

From this the framework infers a the placeOrder action.

Whether the @Action annotation is required to identify an action method is configurable; some teams prefer actions to be explicitly called out, others prefer that any "left over" public methods are identified as actions.

The use of @ActionLayout is optional, the UI semantics can be specified either in code within this annotation, or can be specified through the companion layout file.

As with properties, both @Parameter and @ParameterLayout are also optional. Note though that UI hints for parameters cannot be specified in the layout file.

Domain events are fired — through the internal event bus — for every user interaction with each object member (property, collection or action).

By default, rendering a property causes a PropertyDomainEvent to be fired, though the @Property#domainEvent() attribute allows a custom subclass to be specified if necessary. Similarly, rendering a collection causes a DomainEvent to be fired, and rendering an action causes an ActionDomainEvent to be fired.

In fact, each event can be fired up to five times, with the event’s getEventPhase() method indicating to the subscriber the phase:

For more details on the actual domain event classes, see the domain event section of the relevant reference guide.

As explained earlier, to allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.

Normally the code to return title and icon of an object is part of the domain object’s implementation. However, UI events allow this title and icon to be provided instead by a subscriber. UI events have higher precedence than the other mechanisms of supplying a title.

If annotated with @DomainObjectLayout#titleUiEvent(), the appropriate (subclass of) TitleUiEvent will be emitted. Similarly for #iconUiEvent(). In addition, it is possible to use events to obtain a CSS class to render with the domain object, using #cssClassUiEvent(), and to select an alternate layout file using #layoutUiEvent().

There are two use cases where this feature is useful:

In this second case a subscriber on the default events can provide a title and icon for such an object, with the behaviour provided using mixins.

Lifecycle events allow domain object subscribers to listen for changes to the persistence state of domain entities, and act accordingly.

The lifecycle events supported are:

For example, if annotated with @DomainObjectLayout#updatingLifecycleEvent, the appropriate (subclass of) ObjectUpdatingEvent will be emitted.

There is no lifecycle event for "entity creating" because (obviously) the framework doesn’t know about newly created objects until they have been created. Similarly, there is no lifecycle event for entities that have been removed because it is not valid to "touch" a domain entity once deleted.

The two main rule of thumbs for dependencies are:

By "unstable" we don’t mean buggy, rather this relates to its likelihood to change its structure or behaviour over time: in other words its stability as a core set of concepts upon which other stuff can depend. Reference data (calendars, tax rates, lookups etc) are generally stable, as are "golden" concept such as counterparties / legal entities or financial accounts. Transactional concepts such as invoices or agreements is perhaps more likely to change. But this stuff is domain specific.

Having broken up a domain into multiple modules, there is still a need for higher level modules to use lower level modules, and the application must still appear as a coherent whole to the end-user.

The key features that Apache Causeway provides to support this are:

A good example of this last is supporting (what in an RDBMS we would call) referential integrity. Suppose the customers module has a Customer object and a EmailAddress object, with a customer having a collection of email addresses. A communications module might then use those email addresses to create EmailCommunications.

If the customers module wants to delete an EmailAddress then the communications module will probably want to veto this because they are "in use" by those EmailCommunications. Or, it might conceivably perform a cascade delete of all associated communications. Either way, the communications module receives an internal event representing the intention to delete the EmailAddress. It can then act accordingly, either vetoing the interaction or performing the cascade delete. The customers module for its part does not know anything about this other module.

If we get the dependencies wrong (that is, our initial guess on stability is proven incorrect over time) then there are a couple of techniques we can use:

Mixins in particular allow dependencies to be inverted, so that the dependencies between modules can be kept acyclic and under control.

For example, suppose that we send out Invoices to Customers. We want the invoices to know about customers, but not vice versa. We could surface the set of invoices for a customer using a Customer_invoices mixin:

In the UI, when rendering a Customer, we would also be presented with the associated set of Invoices.

We can also use mixins for dependencies that are in the other direction. For example, suppose we have a mechanism to attach Documents to arbitrary domain objects. The documents module does not depend on any other modules, but provides a DocumentHolder marker interface. We can therefore attach documents to a Customer by having Customer implement this marker interface:

In the context of Java applications, modularity is a rather overloaded term. We have Maven modules, Java 9 modules and we also have Spring @Configurations, which define a set of domain services.

In the context of Apache Causeway, a module is actually the last of these, a Spring module.

The simpleapp starter app provide some structure and illustrates the idioms. To summarise:

By convention, we have just one Spring module to each Maven module. This means that the dependencies between Maven modules (using <dependency> are mirrored in the Spring module’s @Import statements). We can therefore rely on Maven to ensure there are no cyclic dependencies: the application simply won’t compile if we introduce a cycle.

If the above convention is too officious,then you could choose to have multiple Spring modules per Maven module, but you will need to watch out for cycles.

In such cases (proprietary) tools such as Structure 101 can be used to help detect and visualize such cycles. Or, (open source) libraries such as ArchUnit or jQAssistant can help enforce architectural layering to prevent the issue arising in the first place. (These tools can enforce other conventions, too, so are well worth exploring).