You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2023/06/27 07:47:54 UTC
[causeway] branch master updated: CAUSEWAY-3395 : adds docs for setup of audittrail
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git
The following commit(s) were added to refs/heads/master by this push:
new 28c88b79be CAUSEWAY-3395 : adds docs for setup of audittrail
28c88b79be is described below
commit 28c88b79be6e678a9f9383b6ea839e8c899749cd
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Jun 27 08:47:40 2023 +0100
CAUSEWAY-3395 : adds docs for setup of audittrail
---
.../modules/ROOT/partials/modules/progmodel.adoc | 60 +++++++++++
.../core/excel/adoc/modules/excel/pages/about.adoc | 49 +++++++--
.../adoc/modules/audittrail/pages/about.adoc | 113 ++++++++++++++++++++-
3 files changed, 208 insertions(+), 14 deletions(-)
diff --git a/antora/components/userguide/modules/ROOT/partials/modules/progmodel.adoc b/antora/components/userguide/modules/ROOT/partials/modules/progmodel.adoc
index a4910c6e37..fe50bdba97 100644
--- a/antora/components/userguide/modules/ROOT/partials/modules/progmodel.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/modules/progmodel.adoc
@@ -159,3 +159,63 @@ The benefit if you do is much stronger access control to ensure that modules onl
Using the xref:modules.adoc#an-archetypal-module[archetypal module structure] described below will help.
****
+[#appmanifest]
+== AppManifest
+
+There needs to be one top-level module that references all of the modules that make up the application, either directly or indirectly (through transitive dependencies).
+In Apache Causeway we call this module the "app manifest" or `AppManifest`, though this is just a name: it is, ultimately, just another Spring `@Configuration` module.
+
+For example, in the xref:simpleapp.adoc[simpleapp] starter app the `AppManifest` looks like:
+
+[source,java]
+.AppManifest.java
+----
+package domainapp.webapp;
+
+//...
+
+@Configuration
+@Import({
+ CausewayModuleApplibMixins.class,
+ CausewayModuleApplibChangeAndExecutionLoggers.class,
+
+ CausewayModuleCoreRuntimeServices.class,
+ CausewayModulePersistenceJpaEclipselink.class,
+ CausewayModuleViewerRestfulObjectsJaxrsResteasy.class,
+ CausewayModuleViewerWicketApplibMixins.class,
+ CausewayModuleViewerWicketViewer.class,
+
+ CausewayModuleTestingFixturesApplib.class,
+ CausewayModuleTestingH2ConsoleUi.class,
+
+ CausewayModuleExtFlywayImpl.class,
+
+ CausewayModuleExtSecmanPersistenceJpa.class,
+ CausewayModuleExtSecmanEncryptionSpring.class,
+ CausewayModuleExtSessionLogPersistenceJpa.class,
+ CausewayModuleExtAuditTrailPersistenceJpa.class,
+ CausewayModuleExtCommandLogPersistenceJpa.class,
+ CausewayModuleExtExecutionLogPersistenceJpa.class,
+ CausewayModuleExtExecutionOutboxPersistenceJpa.class,
+
+ CausewayModuleExtExcelDownloadWicketUi.class,
+ CausewayModuleExtFullCalendarWicketUi.class,
+ CausewayModuleExtPdfjsWicketUi.class,
+
+ CausewayModuleValAsciidocMetaModel.class,
+ CausewayModuleValAsciidocUiWkt.class,
+
+ ApplicationModule.class,
+ CustomModule.class,
+ QuartzModule.class,
+
+ // discoverable fixtures
+ DomainAppDemo.class
+})
+@PropertySources({
+ @PropertySource(CausewayPresets.DebugDiscovery), // <.>
+})
+public class AppManifest {
+}
+----
+<.> there are a whole set of preset configuration properties that you can enable
diff --git a/extensions/core/excel/adoc/modules/excel/pages/about.adoc b/extensions/core/excel/adoc/modules/excel/pages/about.adoc
index 1945dd6afd..3b7deb7834 100644
--- a/extensions/core/excel/adoc/modules/excel/pages/about.adoc
+++ b/extensions/core/excel/adoc/modules/excel/pages/about.adoc
@@ -16,7 +16,7 @@ In addition, the library provides fixture support, allowing test data to be spec
=== Dependency Management
-Add a section for _Excel_ module's own BOM:
+In your application's top level `pom.xml`, add a dependency for this module's own bill of materials (BOM):
[source,xml,subs="attributes+"]
.pom.xml
@@ -33,13 +33,15 @@ Add a section for _Excel_ module's own BOM:
----
[#dependencies]
-=== Dependencies
+=== Dependencies / Imports
-In the modules of your application that will use the _Excel_ extension, add the following dependency/ies:
+In the modules of your application that will use the _Excel_ extension, add dependency/ies to `pom.xml`, and update the `@Import` of the corresponding xref:userguide::modules.adoc[module]:
-* for xref:export-and-import[export/import], add:
+For xref:export-and-import[export/import]:
+
+* add this dependency:
+
-[source,xml]
+[source,xml,subs="attributes+"]
.pom.xml
----
<dependencies>
@@ -50,9 +52,25 @@ In the modules of your application that will use the _Excel_ extension, add the
</dependencies>
----
-* for xref:fixture-support[fixture support], add:
+* and `@Import` this module:
+
-[source,xml]
+[source,java]
+.MyModule.java
+----
+@Configuration
+@Import({
+ CausewayModuleExtExcelApplib.class,
+ // ...
+})
+public class MyModule { ... }
+----
+
+
+For xref:fixture-support[fixture support]:
+
+* add this dependency:
++
+[source,xml,subs="attributes+"]
.pom.xml
----
<dependencies>
@@ -63,10 +81,23 @@ In the modules of your application that will use the _Excel_ extension, add the
</dependencies>
----
+* and `@Import` this module:
++
+[source,java]
+.MyModule.java
+----
+@Configuration
+@Import({
+ CausewayModuleExtExcelTesting.class,
+ // ...
+})
+public class MyModule { ... }
+----
+
[#export-and-import]
-== Export and Import
+== Usage: Export and Import
Define a view model to act as a DTO.
For example:
@@ -136,7 +167,7 @@ public TransactionImportExportManager importFromExcel(
[#fixture-support]
-== Fixture Support
+== Usage: Fixture Support
The fixture support is provided through `ExcelFixture`, an implementation of `FixtureScript` that is initialized with a spreadsheet and a set of handler classes, one for each sheet.
These handler classes implement `ExcelFixtureRowHandler`
diff --git a/extensions/security/audittrail/adoc/modules/audittrail/pages/about.adoc b/extensions/security/audittrail/adoc/modules/audittrail/pages/about.adoc
index 40eae2da20..1815d4dab1 100644
--- a/extensions/security/audittrail/adoc/modules/audittrail/pages/about.adoc
+++ b/extensions/security/audittrail/adoc/modules/audittrail/pages/about.adoc
@@ -4,21 +4,124 @@
The xref:security:audittrail:about.adoc[] module provides an implementation of the xref:refguide:applib:index/services/publishing/spi/EntityPropertyChangeSubscriber.adoc[EntityPropertyChangeSubscriber], which provides a fine-grained persistent audit trail: each and every change to a entity property is persisted as an individual `AuditTrailEntry` instance.
+This entity has a xref:refguide:applib:index/services/iactn/Interaction.adoc#getInteractionId_[interaction id] which makes it easy to identify all the changes made within a single xref:refguide:applib:index/services/iactn/Interaction.adoc[interaction].
+If the xref:userguide:commandlog:about.adoc[] extension is enabled, then it also means that the audit entries can be correlated back to the command (action invocation or property edit) that gave rise to them.
+The xref:refguide:extensions:index/audittrail/applib/app/AuditTrailMenu.adoc[] provides a set of actions that can be used to query the resultant audit trail.
+See xref:#menubar-layout-xml[menu bar layout] below for the configuration of these.
-The xref:refguide:applib:index/services/iactn/Interaction.adoc#getInteractionId_[interaction id] identifies all the changes made within a single xref:refguide:applib:index/services/iactn/Interaction.adoc[interaction].
+== Setup
-The xref:refguide:extensions:index/audittrail/applib/app/AuditTrailMenu.adoc[] ...
+=== Dependency Management
-// TODO: to complete
+In your application's top level `pom.xml`, add a dependency for this module's own bill of materials (BOM):
-== Setup
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.causeway.extensions</groupId>
+ <artifactId>causeway-extensions-audittrail</artifactId>
+ <version>{page-causewayrel}</version>
+ </dependency>
+ </dependencies>
+</dependencyManagement>
+----
+
+=== Dependencies / Imports
+
+Your application may or may not need to interact with the audit trail directly.
+If it does, then add a dependency/import to the applib module wherever required:
+
+* add this dependency:
++
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<dependencies>
+ <dependency>
+ <groupId>org.apache.causeway.extensions</groupId>
+ <artifactId>causeway-extensions-audittrail-applib</artifactId>
+ </dependency>
+</dependencies>
+----
+
+* and `@Import` this module:
++
+[source,java]
+.MyModule.java
+----
+@Configuration
+@Import({
+ CausewayModuleExtAuditTrailApplib.class,
+ // ...
+})
+public class MyModule { ... }
+----
-// TODO: to complete
+In addition, your app _will_ need to reference the implementation part of the module, usually from your webapp Maven module / top-level xref:userguide::modules.adoc#appmanifest[AppManifest] module.
+The details will depend on the ORM in use.
+* if using xref:pjpa::about.adoc[JPA/EclipseLink]:
+** add this dependency to your webapp's `pom.xml`:
++
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<dependencies>
+ <dependency>
+ <groupId>org.apache.causeway.extensions</groupId>
+ <artifactId>causeway-extensions-audittrail-persistence-jpa</artifactId>
+ </dependency>
+</dependencies>
+----
+
+** and `@Import` this module to your app manifest:
++
+[source,java]
+.MyAppManifest.java
+----
+@Configuration
+@Import({
+ CausewayModuleExtAuditTrailPersistenceJpa.class,
+ // ...
+})
+public class MyAppManifest { ... }
+----
+
+* if using xref:pjdo::about.adoc[]:
+
+** add this dependency to your webapp's `pom.xml`:
++
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<dependencies>
+ <dependency>
+ <groupId>org.apache.causeway.extensions</groupId>
+ <artifactId>causeway-extensions-audittrail-persistence-jdo</artifactId>
+ </dependency>
+</dependencies>
+----
+
+** and `@Import` this module to your app manifest:
++
+[source,java]
+.MyAppManifest.java
+----
+@Configuration
+@Import({
+ CausewayModuleExtAuditTrailPersistenceJdo.class,
+ // ...
+})
+public class MyAppManifest { ... }
+----
+[#menubar-layout-xml]
== menubar.layout.xml
Once configured, the extension provides a number of menu actions.