Getting Started

Prereqs

You’ll need:

Java 21

Apache Causeway works up to at least Java 21, but stick with Java 11 for now.
Maven 3.9.x

Maven 3.9.x or later is recommended.
git

The tutorial includes worked example/solution, provided in a github-hosted repo. This has multiple tags for the various checkpoints so you can pick up the tutorial at any point.
a Java IDE with support for Maven.

The Apache Causeway website has detailed documentation for setting up to use IntelliJ or Eclipse. For this tutorial, also make sure that your IDE is configured to support Lombok.

Ex 1.1: Starter apps / clone the repo

Apache Causeway provides two starter apps, HelloWorld and SimpleApp. These are identical in terms of functionality, but the simpleapp provides more structure and includes example tests.

there are JPA and JDO variants of the starter apps. This tutorial uses JPA as it is the more commonly used persistence mechanism.

We start the tutorial simply with a copy of SimpleApp; in subsequent exercises we’ll refactor and build upon it to morph it into the petclinic domain.

Clone the repo:

git clone https://github.com/apache/causeway-app-petclinic

(optional) Load the git repo into a GUI tool such as SourceTree or GitKraken

This will make it easier to inspect differences between different tags.

Checkout the first tag, and build:

git checkout tags/v3/01-01-starter-app
mvn clean install

The code at this tag was created by copying the v2-jpa tag of SimpleApp:

curl https://codeload.github.com/apache/causeway-app-simpleapp/zip/v2-jpa | jar xv

run the app:
```
mvn -pl webapp spring-boot:run
```

Ex 1.2: Explore the Simple App

Although we’ll be refactoring the codebase in the next exercise, take a few minutes to familiarize yourself with the functionality of the simpleapp.

Check your understanding by using the app to:

create new objects
search by name
list all objects
Use the Prototyping Fixture Scripts menu to run in the "DomainAppDemo" fixture script.

This will create some sample data.

Ex 1.3: Running from the IDE

Running from the command line isn’t ideal, so

load the project into your IDE as a Maven project, build and run.
The app is a Spring boot application, so locate the class with a main() method, and run.
alternatively, your IDE might also have specialised support for Spring Boot apps, so run the app that way if you wish.

If you want to go deeper, use the Simple App docs to explore the structure of the application.

Ex 1.4: Naked Objects pattern

Apache Causeway is an implementation of the naked objects pattern, which means that entities (and later, as we’ll see view models) are automatically exposed in the UI.

An ORM such as JPA (EclipseLink or Hibernate) maps domain objects into an RDBMS or other datastore. Apache Causeway does a similar trick, but in the opposite direction: it maps the domain objects to the UI layer.

Common to both is an internal metamodel, which is where much of the power comes from.

We can explore this by looking at the classes provided by the starter app:

locate the SimpleObjects domain service, and notice the methods annotated with @Action.

Map these to the "Simple Objects" menu.
locate the SimpleObject entity, and notice the methods annotated with @Property and @Action.

Map these onto the fields of the "simple object" entity, and the action buttons (eg to "update name").

It’s common for each entity (or more precisely, aggregate root) to have a corresponding domain service, acting as its repository. This abstraction hides the details of interacting with the persistence data store. Domain services are automatically injected wherever they are required, using @javax.inject.Inject.

Apache Causeway applications therefore generally follow the hexagonal architecture (aka the ports and adapters architecture).

As well as writing our own domain services, there are also many framework-provided domain services, for example RepositoryService (to persist objects). See the Reference Guide: Domain Services docs for the full list.

Ex 1.5: UI Hints

The framework derives as much of the UI as possible from the domain objects' intrinsic structure and behaviour, but there are some supporting structures and conventions that are there primarily to improve the UI.

Titles

A title is the identifier of a domain object for the end-user.

For SimpleObject, this is defined declaratively:

SimpleObject.java

@Title
// ... other annotations omitted ...
private String name;

It can also be specified imperatively using either the title() or toString() method.

Each domain object is also associated with an icon. Typically this is static and in the same package as the class; see SimpleObject.png.

Mini-Exercise:

(no solution is provided for this exercise).

replace the @Title annotation with a title() method:
SimpleObject.java
```
public String title() {
    return getName();
}
```

You can learn more about UI Hint Methods in the reference guide, here.

Object layout

Frameworks that implement the naked objects pattern automatically provide a default representation of domain objects. In many cases the details of that representation can be inferred directly from the domain members. For example the label of a field for an object’s property (eg SimpleObject#name) can be derived directly from the name of the object property itself (getName()).

In the absence of other metadata, Apache Causeway will render a domain object with its properties to the left-hand side and its collections (if any) to the right. The order of these properties and collections can be specified using the @PropertyLayout annotation and the @CollectionLayout annotation. There are other annotations to group properties together and to associate action buttons with either properties or collections.

The downside of using annotations is that changing the layout requires that the application be restarted, and certain more complex UIs, such as multi-columns or tab groups are difficult or impossible to express.

Therefore Apache Causeway also allows the layout of domain objects to be specified using a complementary layout file, eg SimpleObject.layout.xml. This is modelled upon bootstrap and so supports arbitrary rows and columns as well as tab groups and tabs.

Mini-Exercise:

(no solution is provided for this exercise).

locate the SimpleObject.layout.xml file
compare the structure of the layout file to that of the rendered object
change the file, eg the relative widths of the columns
use the IDE to copy over the file to the classpath; the new version will be picked up automatically
- for example, with IntelliJ use Run Debugging Actions Reload Changed Classes.

You can learn more about file-based layouts in the fundamentals guide describing at Object Layouts.

It’s also possible to change the order of columns at runtime, using the SimpleObject.columnOrder.txt file. For more on this topic, see the section of the fundamentals guide describing Table Columns.

menubars.layout.xml

In a similar fashion, the actions of the various domain services are grouped into menus using the menubars.layout.xml file.

Mini-Exercise:

(no solution is provided for this exercise).

locate the menubars.layout.xml file
compare the structure of the layout file to that of the rendered menu bar
change the file, eg reorder menu items or create new menus
again, use the IDE to copy over the file to the classpath
- for example, with IntelliJ use Run Debugging Actions Reload Changed Classes/

To learn more, see the section of the fundamentals guide describing file-based menu bar layout.