User Guides

This user guide aims to get you developing Causeway applications as quickly as possible.

Quick start resources

If you prefer learn by doing, you can use the HelloWorld and SimpleApp starter apps to get going in a few minutes. Also check out the reference app which provides a working example of much of the Causeway programming model.

This guide starts with a 10,000ft overview of the main building blocks that make up the framework. The following pages then look at each of those building blocks in a little more detail:

  • Domain Entities

    Domain entities hold persisted state of domain objects such as Customer or Order. They can and often do also include business logic, encapsulating the manipulations of their state.

  • Domain Services

    Domain services are (typically) singletons that act upon entities. Common implementations are repositories (to find domain entities) or factories (to create entities), but they might also be holders of business logic that for whatever reason you want to keep outside an entity; perhaps it easier to test that way. An example might be InvoiceCalculationServices.

  • Properties, Collections & Actions

    Properties and collections are the state that is maintained by domain entities (above), while actions can reside on either a domain entity or domain service. The framework automatically exposes this state and behaviour in the user interface (unless you otherwise suppress it).

  • UI Layout & Hints

    As noted above, Apache Causeway applications do not require you to write code to render your domain objects in the UI; the framework provides a generic UI. But the framework does allow you to provide optional hints so that the domain objects appear in the UI the way that you want them to appear.

  • Business Rules

    The framework has a well-defined set of conventions for expressing certain business rule contracts, either declaratively (framework-provided annotations) or imperative (supporting methods following a naming convention).

  • Drop-downs and Defaults

    To streamline the user experience, yuo can provide choices for action parameters (drop-downs) as well as default values.

  • View Models

    Not every domain object is an entity. We can also define view models; you might consider these as part of the "application" layer. These can also hold state, but their state is temporary (per user) rather than persistent. Sometimes a view model is a projection of some an underlying entity/ies for a particular use case (eg DocumentAndCommunication; sometimes they aggregate data from multiple locations (eg a CustomerDashboard), sometimes they manage a business process (eg PaymentBatchManager).

  • Modules, Mixins and Events

    Causeway emphasises rapid development and a fast feedback loop with your domain expert. Modularity is key to preserving that feedback loop as your application’s capability grows.

    Mixins provide a powerful mechanism to decouple the various concerns within your application, allowing even the largest of monolith applications to keep modular.

    Events are broadcast on an intra-process event bus, allowing subscribers in other modules to influence the domain logic being executed, hook into persistence or to refine the UI.

The first part of the user guide ends with a look at the background, context and theory that underpin the framework: domain driven design, the naked objects pattern, the hexagonal architecture and aspect orientation to name a few.

The second part of the user guide moves Beyond the Basics, exploring a number of more advanced topics.

The user guide finishes with a set of extensions that provide additional capabilities to the core framework.

  • Value types and Meta-annotations

    Both domain entities and view models are built from values. The framework does (of course) have built-in support for primitives, strings, dates and so on. But it also allows you to define your own custom value types, either scalar or composite.

    Meta-annotations provide an alternative way to factor out common rules, also extending the vocabulary (ubiquitous language) into your app.