This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch CAUSEWAY-3866 in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 21b514c239b6c50aba94bd94638039fdf9ccd86a Author: Dan Haywood <[email protected]> AuthorDate: Sat Oct 18 15:19:32 2025 +0100 CAUSEWAY-3866: cleaned up docs for simpleapp and helloworld app some --- starters/adoc/antora.yml | 5 +- .../simpleapp-modules-dependencies.pptx | Bin 48298 -> 50097 bytes .../simpleapp/simpleapp-modules-dependencies.png | Bin 65172 -> 108658 bytes .../adoc/modules/starters/pages/helloworld.adoc | 49 +++------- .../adoc/modules/starters/pages/simpleapp.adoc | 108 ++++++++------------- 5 files changed, 55 insertions(+), 107 deletions(-) diff --git a/starters/adoc/antora.yml b/starters/adoc/antora.yml index 8dd4e4a4ad7..fe1f86285ac 100644 --- a/starters/adoc/antora.yml +++ b/starters/adoc/antora.yml @@ -20,9 +20,6 @@ version: latest asciidoc: attributes: -# fwk-version: '2' -# fwk-jdk-version: '11' -# jdk-version: '11' - fwk-version: '3' + fwk-version: '4' fwk-jdk-version: '17' jdk-version: '21' diff --git a/starters/adoc/modules/starters/attachments/simpleapp-modules-dependencies.pptx b/starters/adoc/modules/starters/attachments/simpleapp-modules-dependencies.pptx index e7cd8066240..d65c13f2029 100644 Binary files a/starters/adoc/modules/starters/attachments/simpleapp-modules-dependencies.pptx and b/starters/adoc/modules/starters/attachments/simpleapp-modules-dependencies.pptx differ diff --git a/starters/adoc/modules/starters/images/simpleapp/simpleapp-modules-dependencies.png b/starters/adoc/modules/starters/images/simpleapp/simpleapp-modules-dependencies.png index 5aa8884b2af..f7517146751 100644 Binary files a/starters/adoc/modules/starters/images/simpleapp/simpleapp-modules-dependencies.png and b/starters/adoc/modules/starters/images/simpleapp/simpleapp-modules-dependencies.png differ diff --git a/starters/adoc/modules/starters/pages/helloworld.adoc b/starters/adoc/modules/starters/pages/helloworld.adoc index d1f6736e242..228992c5802 100644 --- a/starters/adoc/modules/starters/pages/helloworld.adoc +++ b/starters/adoc/modules/starters/pages/helloworld.adoc @@ -4,9 +4,7 @@ The quickest way to start learning about Apache Causeway is to use the `helloworld` starter app. - -There are two variations of the application (and so two branches in the git repo). -One variation uses JDO as the ORM, the other uses JPA, so you can focus on whichever ORM you prefer. +It uses the xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] object store for persistence. The application is also built nightly as a docker image, so you can quickly try it out: @@ -15,8 +13,6 @@ The application is also built nightly as a docker image, so you can quickly try docker run -d -p 8080:8080 apache/causeway-app-helloworld:v{fwk-version}-jpa-SNAPSHOT ---- -Replace "v{fwk-version}-jpa" with "v{fwk-version}-jdo" if using the JDO ORM. - Using the instructions <<Downloading & Running,below>>, you can download a minimal Apache Causeway app, consisting of a single domain entity (`HelloWorldObject`) with supporting domain services. Both the business logic and supporting bootstrapping classes are in a single Maven module. @@ -36,12 +32,8 @@ Apache Causeway is a Java based framework, so in terms of prerequisites, you'll + Apache Causeway v{fwk-version} requires Java {fwk-jdk-version}, and the helloworld app itself is currently configured for Java {jdk-version}. -* link:http://maven.apache.org[Apache Maven] 3.9.7+ - -If using JDO as the ORM, you'll also need to run the Datanucleus enhancer (this post-processes the byte code of the entities). -The xref:setupguide:ROOT:about.adoc[Setup Guide] explains how to do this for either IntelliJ and Eclipse. +* link:http://maven.apache.org[Apache Maven] 3.9.11+ -If using JPA as the ORM, the equivalent process to enhancement is performed at run-time, so there are no special setup considerations. == Downloading & Running @@ -68,8 +60,9 @@ Choose the generic Wicket UI, and navigate to the login page: image::helloworld/using/020-login-to-wicket-viewer.png[width="600px"] -The app itself is configured to run using xref:security:ROOT:about.adoc[shiro security], as configured in the `shiro.ini` config file. -You can login with: + +The app itself is configured to run using xref:security:simple:about.adoc[Simple security module], with the `SimpleRealm` bean defining the users and roles. +You can log in with: * username: _sven_ * password: _pass_ @@ -236,8 +229,6 @@ src/main/java/ webapp/ AppManifest.java <!--.--> HelloWorldApp.java <!--.--> - META-INF / - persistence.xml <!--.--> ---- <.> For simplicity, all the Java source files reside in a `domainapp` top-level package. @@ -252,7 +243,7 @@ Modules may have other packages, common ones include ``types`` (as below), also <.> Holds classes for the `hwo` ("hello world object") entity/aggregate, consisting of the entity definition itself (`HelloWorldObject`) and a corresponding repository (`HelloWorldObjects`). The associated `.layout.xml` and `.png` are optional but provide metadata/resources for rendering (Maven is configured to also treat `src/main/java` as a resource location). -<.> For the `jpa` branch only, uses Spring Data JPA to automatically provide the query implementation. +<.> Uses Spring Data JPA to automatically provide the query implementations. <.> The `types` package contains meta-annotations to describe the usage of common value types such as ``String``s. @@ -266,7 +257,6 @@ This is discussed in more detail xref:#appmanifest[below]. It's pretty much boilerplate - the important piece is that it references `AppManifest`. + This is discussed in more detail xref:#helloworldapp[below]. -<.> For the `jdo` branch only, the `persistence.xml` file is required boilerplate. [#helloworldmodule] @@ -298,9 +288,9 @@ If there were, these would be expressed in terms of module classes (each being a <.> specifies this class' package as a root to scan for Spring link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/stereotype/Component.html[@Component]s. -<.> for `jpa` branch only, enables Spring Data JPA repositories +<.> enables Spring Data JPA repositories -<.> for `jpa` branch only, to automatically discover JPA entities +<.> automatically discovers JPA entities The scanning mechanism is also leveraged by Apache Causeway to pick up three types of classes: @@ -313,7 +303,7 @@ Depending on their nature, domain services are used to build up the menu, or are + In the helloworld starter app, the main domain services is `HelloWorldObjects`. This appears in the menu, and also acts as a repository for the `HelloWorldObject` entity. -The `jpa` branch also has the `HelloWorldRepository` Spring Data service. +It also has the `HelloWorldRepository` repository interface for which Spring Data provides the query implementations. * all entities. + @@ -361,11 +351,10 @@ public class AppManifest { <.> Provides various optional framework-provided mixins in the UI, such as the `objectIdentifier` and `logicalTypeName` properties <.> Mandatory - specifies the core of the Apache Causeway framework -<.> Enables the Simple security mechanism. +<.> Enables the xref:security:simple:about.adoc[Simple] security mechanism. There are several security implementations, precisely one must be selected <.> Enables xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] for persistence. -Optional (though if omitted then only xref:userguide:ROOT:view-models.adoc[view models] may be used, with hand-rolled persistence). <.> Enables the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)] @@ -431,7 +420,6 @@ src/main/resources banner.txt <!--.--> log4j2-spring.xml <!--.--> menubars.layout.xml <!--.--> - shiro.ini <!--.--> ---- <.> By convention, we use `config/application.properties` to hold configuration properties that change between environments (dev, test, prod). @@ -445,16 +433,10 @@ Typically this just holds JDBC connection strings, etc. <.> The `banner.txt` is shown when bootstrapping. -<.> The `log4j2-spring.xml` configures log4j2 (the logging system used by Apache Causeway) +<.> The `log4j2-spring.xml` configures log4j2 <.> The `menubars.layout.xml` arranges the actions of the domain services into menus. -<.> The `shiro.ini` file configures Shiro security integration (see the `CausewayModuleSecurityShiro` module imported in the `AppManifest`, above). -+ -[TIP] -==== -The xref:security:shiro:about.adoc[Shiro security] integration is much more flexible than simple file-based authentication. -==== To call out some of the files under `static`: @@ -481,7 +463,7 @@ You will find tests in the xref:docs:starters:simpleapp.adoc[SimpleApp starter a === pom.xml -Finally, at the root directory we of course have the `pom.xml`. +Finally, at the root directory is the top-level `pom.xml`. This inherits from `causeway-app-starter-parent`: [source,xml] @@ -494,7 +476,7 @@ This inherits from `causeway-app-starter-parent`: </parent> ---- -\... which builds upon Spring Boot's own `org.springframework.boot:spring-boot-starter-parent`. +\... which in turn depends upon Spring Boot's own `org.springframework.boot:spring-boot-starter-parent`. This means: * the set of third party dependencies declared have been validated as compatible by Spring Boot team @@ -513,11 +495,6 @@ Here's what the setup looks like in IntelliJ IDEA: image::helloworld/helloworld.png[width="600px"] -If using JDO as the ORM (rather than JPA), then the DataNucleus enhancer must be run beforehand. -With IntelliJ this can be done by setting up a different _Run Configuration_ to be executed beforehand: - -image::helloworld/helloworld-before-launch.png[width="600px"] - == Experimenting with the App diff --git a/starters/adoc/modules/starters/pages/simpleapp.adoc b/starters/adoc/modules/starters/pages/simpleapp.adoc index 98aceff1f20..eb560d818b3 100644 --- a/starters/adoc/modules/starters/pages/simpleapp.adoc +++ b/starters/adoc/modules/starters/pages/simpleapp.adoc @@ -3,9 +3,7 @@ :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] The quickest way to get started building an application "for real" is to use the `simpleapp` starter app. - -There are two variations of the application (and so two branches in the git repo). -One variation uses JPA as the ORM, the other uses JDO, so you can focus on whichever ORM you prefer. +It uses the xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] object store for persistence. The application is also built nightly as a docker image, so you can quickly try it out: @@ -14,20 +12,17 @@ The application is also built nightly as a docker image, so you can quickly try docker run -d -p 8080:8080 apache/causeway-app-simpleapp:v{fwk-version}-jpa-SNAPSHOT ---- -Replace "v{fwk-version}-jpa" with "v{fwk-version}-jdo" if using the JDO ORM. - As with the xref:docs:starters:helloworld.adoc[HelloWorld] starter app, the instructions <<Downloading & Running,below>> will download a minimal Apache Causeway app consisting of a single entity (`SimpleObject`) with supporting domain services. -However, unlike HelloWorld, this app also provides more structure to assist you as your application grows, with business logic placed in a separate Maven module (`simpleapp-...-module-simple`) to the module that bootstraps the webapp (`simpleapp-...-webapp`). -Replace "..." with either "jpa" or "jdo", as appropriate. +However, unlike xref:docs:starters:helloworld.adoc[HelloWorld], this app also provides more structure to assist you as your application grows, with business logic placed in a separate Maven module (`simpleapp-jpa-module-simple`) to the module that bootstraps the webapp (`simpleapp-jpa-webapp`). -The idea is that as your application grows in scope that you put each new area of functionality in its own module (copy-n-paste the `simpleapp-...-module-simple` module). +The idea is that as your application grows in scope that you put each new area of functionality in its own module (copy-n-paste the `simpleapp-jpa-module-simple` module). These modules can depend on each other, but Maven will to ensure that dependencies between these areas of functionality are unidirectional. In this way your application will be a "modular monolith"; said another way it will prevent your application from degenerating into a link:https://en.wikipedia.org/wiki/Big_ball_of_mud[big ball of mud]. See also the discussion <<structure-of-the-app,below>>. The application also includes examples of unit tests and integration tests. -You'll find these in their own Maven modules (`simpleapp-...-module-simple-tests` and `simpleapp-...-webapp-tests`). +You'll find these in their own Maven modules (`simpleapp-jpa-module-simple-tests` and `simpleapp-jpa-webapp-tests`). Normally we recommend that tests should be in the same Maven module as the code that they exercise. The simpleapp doesn't do it this way just to give you the option to exclude them while initially prototyping/exploring a domain. You can use them as a reference once your ideas have solidifid and you need to start writing proper "production" code. @@ -42,12 +37,7 @@ Apache Causeway is a Java based framework, so in terms of prerequisites, you'll + Apache Causeway v{fwk-version} requires Java {fwk-jdk-version}, and the simpleapp itself is currently configured for Java {jdk-version}. -* link:http://maven.apache.org[Apache Maven] 3.9.7+ - -If using JDO as the ORM, you'll also need to run the Datanucleus enhancer (this post-processes the byte code of the entities). -The xref:setupguide:ROOT:about.adoc[Setup Guide] explains how to do this for either IntelliJ and Eclipse. - -If using JPA as the ORM, the equivalent process to enhancement is performed at run-time, so there are no special setup considerations. +* link:http://maven.apache.org[Apache Maven] 3.9.11+ == Downloading & Running @@ -74,8 +64,8 @@ Choose the generic Wicket UI, and navigate to the login page: image::simpleapp/using/020-login-to-wicket-viewer.png[width="600px"] -The app itself is configured to run using xref:security:ROOT:about.adoc[shiro security], as configured in the `shiro.ini` config file. -You can login with: +The app itself is configured to run using xref:security:simple:about.adoc[Simple security module], with the `SimpleRealm` bean defining the users and roles. +You can log in with: * username: _sven_ * password: _pass_ @@ -162,8 +152,8 @@ As well as running in fixtures from the UI, you can also specify a configuration [source,ini] .config/application.properties ---- -# causeway.testing.fixtures.initial-script = \ -# domainapp.webapp.application.fixture.scenarios.DomainAppDemo +causeway.testing.fixtures.initial-script = \ + domainapp.webapp.application.fixture.scenarios.DomainAppDemo ---- @@ -305,19 +295,17 @@ The application consists of five modules: [plantuml] .simpleapp dependencies ---- -[webapp-...-tests] <<maven module>> #LightBlue -[webapp-...] <<maven module>> -[module-...-simple-tests] <<maven module>> #LightBlue -[module-...-simple] <<maven module>> - -[webapp-...-tests] .l-> [webapp-...] -[module-...-simple-tests] .l-> [module-...-simple] -[webapp-...] .u-> [module-...-simple] +[webapp-jpa-tests] <<maven module>> #LightBlue +[webapp-jpa] <<maven module>> +[module-jpa-simple-tests] <<maven module>> #LightBlue +[module-jpa-simple] <<maven module>> + +[webapp-jpa-tests] .l-> [webapp-jpa] +[module-jpa-simple-tests] .l-> [module-jpa-simple] +[webapp-jpa] .u-> [module-jpa-simple] ---- -where "..." is either "jdo" or "jpa", depending on the branch. - -The main business logic resides in `module-...-simple`, with the `webapp` module acting as an aggregator. +The main business logic resides in `module-jpa-simple`, with the `webapp` module acting as an aggregator. Each of these modules have unit and/or integration tests. To allow them to be easily excluded (while prototyping/exploration), they have been placed into their own respective modules. @@ -359,12 +347,10 @@ The link:{attachmentsdir}/simpleapp-modules-dependencies.pptx[diagram] below sho .Module Dependencies image::simpleapp/simpleapp-modules-dependencies.png[width="800px"] -(For a JPA branch, the `JdoDataNucleus5` dependency is replaced by `JpaEclipseLink`). - Let's now review the contents of each of the modules in the simpleapp starter app. -=== module-...-simple's src/main/java +=== module-jpa-simple's src/main/java Under `src/main/java` we have: @@ -388,8 +374,6 @@ src/main/java/ Name.java Notes.java SimpleModule.java <!--.--> - META-INF/ - persistence.xml <!--.--> ---- <.> For simplicity, all the Java source files reside in a `domainapp` top-level package. Change as required. @@ -402,7 +386,7 @@ Modules may have other subpackages, common ones include ``types`` and ``fixture` <.> Holds classes for the `so` ("simple object") entity/aggregate, consisting of the entity definition itself (`SimpleObject`) and a corresponding domain services (`SimpleObjects` and `SimpleObjectRepository`). The associated `.layout.xml` and `.png` are optional but provide metadata/resources for rendering (Maven is configured to also treat `src/main/java` as a resource location). -<.> For the `jpa` branch only, uses Spring Data JPA to automatically provide the query implementation. +<.> Uses Spring Data JPA to automatically provide the query implementation. <.> The `fixture` package contains classes to set up the database to an initial state (as described xref:#fixtures[earlier]. One of the classes is a `FixtureScript` (defines _how_ to set up the data) the other is a persona enum (defines _what_ data to set up). @@ -412,7 +396,6 @@ One of the classes is a `FixtureScript` (defines _how_ to set up the data) the o <.> `SimpleModule` is a Spring link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html[@Configuration] which allows the domain services and entities of the module to be located. + This is discussed in more detail below. -<.> For the `jdo` branch only, the `persistence.xml` file is required boilerplate. ==== SimpleModule @@ -495,7 +478,8 @@ Depending on their nature, domain services are used to build up the menu, or are + In the simpleapp starter app, the only domain service is `SimpleObjects`. This appears in the menu, and also acts as a repository for the `SimpleObject` entity. -The `jpa` branch also has the `SimpleObjectRepository` Spring Data service. +It also has the `SimpleObjectRepository` repository interface for which Spring Data provides the query implementations. + * all entities. + @@ -510,7 +494,7 @@ These are classes that extend from the testing applib's `FixtureScript` class, a As already discussed, the `fixture` package provides classes to create sample objects, while the `SimpleModule` provides a fixture script to tear down all data from the module. -=== module-...-simple-test's src/test/java +=== module-jpa-simple-test's src/test/java Under `src/test/java` we have: @@ -587,12 +571,11 @@ public abstract class SimpleModuleIntegTestAbstract In this case, the test inherits from the `CausewayIntegrationTestAbstractWithFixtures` subclass which also adds in support for running fixtures. <.> Specifies the modules that make up Apache Causeway framework itself. -These include core, security set to the bypass implementation (effectively is ignored) and xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] for persistence. Note that no viewers are bootstrapped because the tests are run through Spring's integration testing framework, rather than (say) as Selenium tests. -<.> Disables security checks. +<.> Configures the xref:security:bypass:about.adoc[Bypass] implementation which effectively disables security checks. -<.> Configures JPA as the ORM. +<.> Configures xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] object store as the persistence mechanism. <.> Brings in support for running fixtures. + @@ -676,7 +659,8 @@ It's very simple though: .ApplicationModule.java ---- package domainapp.webapp.application; -... imports omitted ... +//... + @Configuration @Import(SimpleModule.class) // <.> @ComponentScan // <.> @@ -699,7 +683,7 @@ It looks like this: @Configuration @Import({ CausewayModuleCoreRuntimeServices.class, // <.> - CausewayModuleSecurityShiro.class, // <.> + CausewayModuleSecuritySimple.class, // <.> CausewayModuleJpaEclipseLink.class, // <.> CausewayModuleViewerRestfulObjectsViewer.class, // <.> CausewayModuleViewerGraphqlViewer.class, // <.> @@ -724,9 +708,9 @@ public class AppManifest { ---- <.> Mandatory - specifies the core of the Apache Causeway framework -<.> Enables the Shiro security mechanism. +<.> Enables the xref:security:simple:about.adoc[Simple] security mechanism. There are several security implementations, precisely one must be selected -<.> Enables JPA/Eclipselink for persistence. +<.> Enables xref:pjpa:ROOT:about.adoc[JPA/Eclipselink] for persistence <.> Enables the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)] (ie REST API). <.> Enables the xref:gqlv:ROOT:about.adoc[GraphQL API (GraphQL viewer)]. <.> Enables the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] @@ -790,7 +774,6 @@ src/main/resources banner.txt <.> log4j2-spring.xml <.> menubars.layout.xml <.> - shiro.ini <.> ---- <.> By convention, we use `config/application.properties` to hold configuration properties that change between environments (dev, test, prod). @@ -809,16 +792,10 @@ This leverages a feature in Spring Boot's Flyway integration which allows differ <.> The `banner.txt` is shown when bootstrapping. -<.> The `log4j2-spring.xml` configures log4j2 (the logging system used by Apache Causeway) +<.> The `log4j2-spring.xml` configures log4j2 <.> The `menubars.layout.xml` arranges the actions of the domain services into menus. -<.> The `shiro.ini` file configures Shiro security integration (see the `CausewayModuleSecurityShiro` module imported in the `AppManifest`, above). -+ -[TIP] -==== -The xref:security:shiro:about.adoc[Shiro security] integration is much more flexible than simple file-based authentication. -==== To call out some of the files under `static`: @@ -921,10 +898,6 @@ Here's what the setup looks like in IntelliJ IDEA: image::simpleapp/simpleapp-webapp.png[width="600px"] -If using JDO as the ORM (rather than JPA), then the DataNucleus enhancer must be run beforehand. -With IntelliJ this can be done by setting up a different _Run Configuration_ to be executed beforehand: - -image::simpleapp/simpleapp-webapp-before-launch.png[width="600px"] @@ -956,11 +929,12 @@ Otherwise, you can easily run up an instance using Docker: [source,bash] ---- docker run \ - --name sqlserver \ + --platform linux/amd64 \ + --name sqlserver-simpleapp \ -e 'ACCEPT_EULA=Y' \ - -e 'SA_PASSWORD=pa$$w0rd' \ + -e 'SA_PASSWORD=VeryStrongPassword123!' \ -p 1433:1433 \ - -d mcr.microsoft.com/mssql/server:2019-latest + -d mcr.microsoft.com/mssql/server:2022-latest ---- You can then connect: @@ -969,12 +943,12 @@ You can then connect: + [source,bash] ---- -docker exec -it sqlserver \ - /opt/mssql-tools/bin/sqlcmd \ - -S localhost -U sa -P pa$$w0rd +docker exec -it sqlserver-simpleapp \ + /opt/mssql-tools18/bin/sqlcmd \ + -S localhost -U sa -P VeryStrongPassword123! -C ---- -* if on Windows, you might instead prefer to use Microsoft's free GUI client, link:https://docs.microsoft.com/en-us/sql/ssms/download-sql-server-management-studio-ssms?view=sql-server-ver15[SQL Server Management Studio]. +* if on Windows, you might instead prefer to use Microsoft's free GUI client, link:https://learn.microsoft.com/en-us/ssms/install/install[SQL Server Management Studio]. You then need to create a database and login: @@ -1060,6 +1034,6 @@ If you were using Docker to try this out, remember to clean up afterwards: [source,bash] ---- -docker kill sqlserver -docker rm sqlserver +docker kill sqlserver-simpleapp +docker rm sqlserver-simpleapp ----
