Apache Causeway™ software is a framework for rapidly developing domain-driven apps in Java. This repo contains a sample app to use as a template for getting you started.
APACHE-2.0 License
= SimpleApp :toc: :toc-placement!:
image:https://github.com/apache/causeway-app-simpleapp/workflows/Build%20w/%20Maven%20+%20Jdk%208/badge.svg[] image:https://github.com/apache/causeway-app-simpleapp/workflows/Build%20w/%20Maven%20+%20Jdk%2015/badge.svg[]
This is a simple link:https://causeway.apache.org[Apache Causeway] application, structured so that it can be used as a starting point for developing your own applications.
It consists of:
You can easily remove these extensions (or add others) in the AppManifest
.
toc::[]
== Quick start
** Java 11 LTS (eg link:https://adoptopenjdk.net/[Adopt OpenJDK] distribution) ** Maven 3.6 or later (http://maven.apache.org/download.cgi[download])
APP=simpleapp BRANCH=master
spring-instrument.jar
for load-time weaving (discussed in more detail xref:#orm-support[below]):Change "XXX" to the value that ${spring-framework.version}
resolves to in the webapp pom.xml
Browse to http://localhost:8080.
Login using:
** either the secman superuser:
*** username: secman-admin
*** password: pass
** or as a regular user:
*** username: sven
*** password: pass
The app runs with H2 running in-memory, with sample data set up using fixture scripts.
export REVISION=... #<.> export DOCKER_REGISTRY_USERNAME #<.> export DOCKER_REGISTRY_PASSWORD #<.>
<.> used as the image tag
<.> Docker Hub registry username
<.> Docker Hub registry password
+
To push to another container registry, change the <image>
tag in the pom.xml
== Application Structure
The following table explains the contents of each of the directories:
[width="100%",options="header,footer",stripes="none",cols="2a,4a"] |==================== |Directory |Description
|module-simple
|Holds the "simple" module, consisting of the SimpleObject
entity and supporting services.
|module-simple-tests
|Holds the unit- and integration tests for module-simple
.
|webapp
|Holds the bootstrapping classes, along with application-level scoped services and home page.
The pom.xml
also provides goals to run the app from the command line, or to be assembled into a Docker image.
|webapp-tests
|Contains application-wide integration tests.
|====================
It's more common for tests to reside within the same module, but we moved them into their own Maven modules because it makes them easier to be temporarily excluded, eg during initial explorations/prototyping.
[#orm-support] == ORM Support
This version of the application uses EclipseLink JPA as its ORM, configured with load-time weaving. This requires that the application be run with a Java agent.
The spring-boot plugin is configured to run with this agent already. If you want to run from an IDE:
Change "XXX" to the value that ${spring-framework.version}
resolves to in the webapp pom.xml
//This version of the application uses DataNucleus as its ORM, which requires that any entities are "enhanced", a post-compile process.
//
//Normally this is done as part of a "mvn clean install", but the entities can also be enhanced explicity using:
//
//[source,bash]
//----
//mvn -pl module-simple datanucleus:enhance -o
//----
//
//This is useful to know if the application or integration test fails to bootstrap, complaining of "unenhanced entities".
//
//TIP: You can also use enhance-all.sh
== Testing
The application has both unit tests and integration tests.
.Testing types [cols="5a,12a,6a,3a", options="header"] |===
| Test type | Report | Phase | Skip using
| Unit test
| target/surefire-unittest-reports
| test
| -DskipUTs
| Integ test
| target/surefire-integtest-reports
| integration-test
| -DskipITs
|===
These outputs can for example be processed within/published by a continuous pipeline.
== Translations
Apache Causeway supports i18n using link:https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html[GNU .po file]s.
The WEB-INF/translations.po
is the fallback (an empty value means that the key is used "as-is"), while WEB-INF/translations-XX.po
files provide translations for each "XX" locale.
Translations are required for all domain classes and all members (actions, properties and collections) of all classes.
This information is available from the metamodel, and so a new template translations.po
is generated as a side effect of running the integration tests (through a log4j2 logger).
A good integration test to run is ValidateDomainModel_IntegTest
.
In addition, translations are required for any validation messages triggered by the test.
Running an integration tests that trigger validations will result in these messages being captured as keys, for example Smoke_IntegTest
.
The generated file should be merged with any existing translations in WEB-INF/translations.po
, and translations obtained for any new keys (there are numerous online services that support the format).
== Flyway
The application also demonstrates how to use Flyway to migrate the database schema.
By default the app runs using an in-memory database. The Flyway example is activated using the "SQLSERVER" Spring Boot profile, eg:
This causes the properties defined in config/application-SQLSERVER.properties
file to be used in preference to those in the default config/application.properties
file.
It defines the following:
spring.flyway.url
, spring.flyway.user
and spring.flyway.password
The presence of these is enough to enable the Flyway integration
spring.flyway.enabled
This is explicitly set to true
, to override the value in the default config/application.properties
.
causeway.persistence.jdo-datanucleus.impl.datanucleus.schema.autoCreateAll
This is set to false
, also overriding the value in the default config/application.properties
.
It instructs the JDO/DataNucleus object store not to automatically create any tables etc.
The Spring Boot profile is also used to add the dependency to the SQL Server driver is included (it is hidden behind a Maven profile).
The prerequisites to try this out are a SQL Server database running on localhost
and with the credentials as specified in config/application-SQLSERVER.properties
; adjust as necessary.