SimpleApp

This is a simple Apache Isis application, structured so it can be used as a starting point for developing your own applications.

Tip	If all you want is get a feel for what the framework is all about, then take a look at the HelloWorld starter app, which is even simpler.

Table of Contents

• Quick start
• Application Structure
• Development
• Testing
• Translations
• Flyway

Quick start

• install prereqs:

  • Java 8 LTS (eg Adopt OpenJDK distribution)

  • Maven 3.6 or later (download)

• download and unzip

  APP=simpleapp
  BRANCH=master
  
  REPO=isis-app-$APP
  curl "https://codeload.github.com/apache/$REPO/zip/$BRANCH" | jar xv
  mv $REPO-$BRANCH $REPO
  cd $REPO

• Build using Maven:

  mvn clean install

• Run using Maven:

  mvn -pl webapp spring-boot:run

• Browse to http://localhost:8080.

• Login to using:

  • username: sven

  • password: pass

  The app runs with H2 running in-memory, with sample data set up using fixture scripts.

• Build a Docker image

  export REVISION=...                 #(1)
  export DOCKER_REGISTRY_USERNAME     #(2)
  export DOCKER_REGISTRY_PASSWORD     #(3)
  
  mvn -pl webapp jib:build

  1. used as the image tag

  2. Docker Hub registry username

  3. 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:

Directory	Description
module-simple	Holds the "simple" module, consisting of the SimpleObject entity and supporting services. It also contains module-specific unit- and integration tests. Tip Larger applications should consist of multiple modules; each such module can be copied from this starter module.
webapp	Holds the bootstrapping classes, along with application-level scoped services and home page. It also contains application-wide integration tests. The pom.xml also provides goals to run the app from the command line, or to be assembled into a Docker image.

Development

Apache Isis 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:

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.

Table 1. Testing types

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 Isis supports i18n using GNU .po files. 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:

mvn -Dspring.profiles.active=SQLSERVER -pl webapp install
mvn -Dspring.profiles.active=SQLSERVER -pl webapp spring-boot:run

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.

• isis.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.