Apache Causeway in Pictures
On this page we want to show you what an Apache Causeway application looks like, running on the Web UI (Wicket viewer). The screenshots below are taken from a "Todo" application.
| these screenshots are based on an app running against v1.13 and v1.10 of the framework. There have been a number of UI improvements since these releases. |
Basics
Let’s start with the basics…
Sign-in
Apache Causeway integrates with a variety of authentication mechanisms, including Apache Shiro, Spring Security and Keycloak.
The SecMan extension provides a well-features subdomain of users, roles and permissions against features derived from the Apache Causeway metamodel.
Install Fixtures
Apache Causeway has lots of features to help you prototype and then fully test your application. One such are fixture scripts, which allow pre-canned data to be installed in the running application. This is great to act as the starting point for identifying new stories; later on when the feature is being implemented, the same fixture script can be re-used within that feature’s integration tests. (More on tests later).
Dashboard and View Models
Most of the time the end-user interacts with representations of persistent domain entities, but Apache Causeway also supports view models which can aggregate data from multiple sources. The todoapp example uses a "dashboard" view model to list todo items not yet done vs those completed.
In general we recommend to initially focus only on domain entities; this will help drive out a good domain model. Later on view models can be introduced in support of specific use cases.
Domain Entity
The screenshot below is of the todoapp’s ToDoItem domain entity.
Like all web pages, this UI is generated at runtime, directly from the domain object itself.
There are no controllers or HTML to write.
In addition to the domain entity, Apache Causeway allows layout metadata hints to be provided, for example to specify the grouping of properties, the positioning of those groups into columns, the association of actions (the buttons) with properties or collections, the icons on the buttons, and so on. This metadata can be specified either as annotations or in XML form. The benefit of the latter is that it can be updated (and the UI redrawn) without restarting the app.
Any production-ready app will require this metadata but (like the view models discussed above) this metadata can be added gradually on top of the core domain model.
Edit properties
By default properties on domain entities are editable, meaning they can be changed directly. In the todoapp example, the `ToDoItem’s description is one such editable property:
Note that some of the properties are read-only even in edit mode; individual properties can be made non-editable. It is also possible to make all properties disabled and thus enforce changes only through actions (below).
Actions
The other way to modify an entity is to an invoke an action.
In the screenshot below the ToDoItem's category and subcategory can be updated together using an action:
There are no limitations on what an action can do; it might just update a single object, it could update multiple objects. Or, it might not update any objects at all, but could instead perform some other activity, such as sending out email or printing a document.
In general though, all actions are associated with some object, and are (at least initially) also implemented by that object: good old-fashioned encapsulation. We sometimes use the term "behaviourally complete" for such domain objects.
Mixins
As an alternative to placing actions (business logic) on a domain object, it can instead be placed inside a mixin object. When an object is rendered by Apache Causeway, the mixin "contributes" its behaviour to the domain object (similar to aspect-oriented traits).
In the screenshot below the highlighted "export as xml" action, the "relative priority" property (and "previous" and "next" actions) the "similar to" collection and the two "as DTO" actions are all contributed by mixins:
Extensible Views
The Apache Causeway viewer is implemented using Apache Wicket, and has been designed to be extensible. For example, when a collection of objects is rendered, this is just one of several views, as shown in the selector drop-down:
Similarly the Fullcalendar2 extension will render any domain entity (such as ToDoItem) that implements its Calendarable interface:
The Tabular Download component is rather simple: it simply allows the table to be downloaded as a spreadsheet:
Security, Auditing and more…
As well as providing extensions to the UI, the extensions provide a rich set of modules to support various cross-cutting concerns.
Under the activity menu are four sets of services which provide support on user session logging/auditing, command module (profiling and replay), audit module (audit object changes) and (inter-system) event publishing:
In the security menu is access to the rich set of functionality provided by the SecMan extension:
In the prototyping menu is the ability to download a GNU gettext .po file for translation.
This file can then be translated into multiple languages so that your app can support different locales.
Multi-tenancy support
One significant feature of the SecMan extension is the ability to associate users and objects with a "tenancy". The todoapp uses this feature so that different users' list of todo items are kept separate from one another. A user with administrator is able to switch their own "tenancy" to the tenancy of some other user, in order to access the objects in that tenancy:
For more details, see the SecMan extension.
Me
Most of the SecMan extension's services are on the security menu, which would normally be provided only to administrators. Kept separate is the "me" action:
Assuming they have been granted permissions, this allows a user to access an entity representing their own user account:
If not all of these properties are required, then they can be hidden either using security or though Apache Causeway' internal event bus (described below). Conversely, additional properties can be "grafted onto" the user using the contributed properties/collections discussed previously.
Themes
Apache Causeway' Wicket viewer uses Twitter Bootstrap, which means that it can be themed. If more than one theme has been configured for the app, then the viewer allows the end-user to switch their theme:
REST API
In addition to Apache Causeway' Wicket viewer, it also provides a rich REST API with a full set of hypermedia controls, generated automatically from the domain objects (entities and view models). The framework provides two default representations, one an implementation of the Restful Objects spec, the other a simplified representation suitable for custom JavaScript apps. Other representations can be plugged in.
The screenshot below shows accessing the Restful Objects representation API accessed through a Chrome plugin:
The framework also automatically integrates with Swagger, generating a Swagger spec from the underlying domain object model. From this spec REST clients can be code-generated; it also allows developers to play with the REST API through the Swagger UI:
Integration Testing Support
Earlier on we noted that Apache Causeway allows fixtures to be installed through the UI.
These same fixture scripts can be reused within integration tests.
For example, the code snippet below shows how the FixtureScripts service injected into an integration test can then be used to set up data:
The tests themselves are run in junit. While these are integration tests (so talking to a real database), they are no more complex than a regular unit test:
To simulate the business rules enforced by Apache Causeway, the domain object can be "wrapped" in a proxy.
For example, if using the Wicket viewer then Apache Causeway will enforce the rule (implemented in the ToDoItem class itself) that a completed item cannot have the "completed" action invoked upon it.
The wrapper simulates this by throwing an appropriate exception:
Internal Event Bus
Contributions, discussed earlier, are an important tool in ensuring that the packages within your Apache Causeway application are decoupled; by extracting out actions the order of dependency between packages can effectively be reversed.
Another important tool to ensure your codebase remains maintainable is Apache Causeway' internal event bus.
It is probably best explained by example; the code below says that the "complete" action should emit a ToDoItem.Completed event:
Domain service (application-scoped, stateless) can then subscribe to this event:
And this test verifies that completing an action causes the subscriber to be called:
In fact, the domain event is fired not once, but (up to) 5 times. It is called 3 times prior to execution, to check that the action is visible, enabled and that arguments are valid. It is then additionally called prior to execution, and also called after execution. What this means is that a subscriber can in either veto access to an action of some publishing object, and/or it can perform cascading updates if the action is allowed to proceed.
Moreover, domain events are fired for all properties and collections, not just actions. Thus, subscribers can therefore switch on or switch off different parts of an application. Indeed, the example todoapp demonstrates this.