This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch ISIS-3271 in repository https://gitbox.apache.org/repos/asf/isis.git
commit 4a1497e826de8f331d145a33235a779240e27a9c Author: Dan Haywood <[email protected]> AuthorDate: Thu Nov 3 17:51:12 2022 +0000 ISIS-3255: updates docs; also adds config property for execution outbox. --- .../core/config/CausewayConfiguration.java | 205 +++++++++++---------- .../adoc/modules/commandlog/pages/about.adoc | 31 ++-- .../core/excel/adoc/modules/excel/pages/about.adoc | 78 +++++++- .../extensions/excel/testing/ExcelFixture.java | 109 +++++------ .../extensions/excel/testing/ExcelFixture2.java | 85 ++++----- .../adoc/modules/executionlog/pages/about.adoc | 81 ++++---- .../adoc/modules/executionoutbox/images/outbox.png | Bin 0 -> 22127 bytes .../adoc/modules/executionoutbox/pages/about.adoc | 202 +++++++++++++++++++- .../applib/dom/ExecutionOutboxEntryRepository.java | 4 +- .../CausewayModuleExtExecutionRestClient.java | 3 + .../restclient/api/OutboxClient.java | 3 + .../restclient/integtests/RestEndpointService.java | 2 - .../modules/executionrepublisher/pages/about.adoc | 22 +++ .../flyway/adoc/modules/flyway/pages/about.adoc | 48 ++++- .../quartz/adoc/modules/quartz/pages/about.adoc | 36 +++- .../adoc/modules/secman/pages/setting-up.adoc | 6 +- .../adoc/modules/archtestsupport/pages/about.adoc | 2 +- .../adoc/modules/fakedata/pages/about.adoc | 2 +- .../pages/fixture-scripts/maven-configuration.adoc | 2 +- .../adoc/modules/h2console/pages/about.adoc | 2 +- .../adoc/modules/hsqldbmgr/pages/about.adoc | 2 +- .../adoc/modules/integtestsupport/pages/about.adoc | 2 +- .../adoc/modules/specsupport/pages/about.adoc | 2 +- .../adoc/modules/unittestsupport/pages/about.adoc | 2 +- 24 files changed, 644 insertions(+), 287 deletions(-) diff --git a/core/config/src/main/java/org/apache/causeway/core/config/CausewayConfiguration.java b/core/config/src/main/java/org/apache/causeway/core/config/CausewayConfiguration.java index a0ce43610e..caf986e5e0 100644 --- a/core/config/src/main/java/org/apache/causeway/core/config/CausewayConfiguration.java +++ b/core/config/src/main/java/org/apache/causeway/core/config/CausewayConfiguration.java @@ -42,10 +42,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; import javax.activation.DataSource; import javax.inject.Named; -import javax.validation.Constraint; -import javax.validation.ConstraintValidator; -import javax.validation.ConstraintValidatorContext; -import javax.validation.Payload; +import javax.validation.*; +import javax.validation.constraints.Max; +import javax.validation.constraints.Min; import javax.validation.constraints.NotEmpty; import javax.validation.constraints.NotNull; @@ -2863,9 +2862,105 @@ public class CausewayConfiguration { } private final Extensions extensions = new Extensions(); + @Valid @Data public static class Extensions { + private final CommandLog commandLog = new CommandLog(); + @Data + public static class CommandLog { + + public enum PublishPolicy { + ALWAYS, + ONLY_IF_SYSTEM_CHANGED, + ; + public boolean isAlways() { return this == ALWAYS; } + public boolean isOnlyIfSystemChanged() { return this == ONLY_IF_SYSTEM_CHANGED; } + + } + /** + * Whether commands should be published always, or only if a change in the system's state has been detected. + * + * <p> + * In general, the default of {@link PublishPolicy#ALWAYS} should be used, <i>unless</i> the + * <i>Audit Trail</i> extension is also in use, which is able to advise on whether the systems state has + * changed. + * </p> + * + * <p> + * Put another way, if this policy is set to {@link PublishPolicy#ONLY_IF_SYSTEM_CHANGED} but the + * <i>Audit Trail</i> extension is <i>not</i> enabled, then nothing will be logged. + * </p> + */ + @Getter @Setter + private PublishPolicy publishPolicy = PublishPolicy.ALWAYS; + + } + + private final CommandReplay commandReplay = new CommandReplay(); + @Data + public static class CommandReplay { + + private final PrimaryAccess primaryAccess = new PrimaryAccess(); + @Data + public static class PrimaryAccess { + @javax.validation.constraints.Pattern(regexp="^http[s]?://[^:]+?(:\\d+)?.*([^/]+/)$") + private Optional<String> baseUrlRestful = Optional.empty(); + private Optional<String> user = Optional.empty(); + private Optional<String> password = Optional.empty(); + @javax.validation.constraints.Pattern(regexp="^http[s]?://[^:]+?(:\\d+)?.*([^/]+/)$") + private Optional<String> baseUrlWicket = Optional.empty(); + } + + private final SecondaryAccess secondaryAccess = new SecondaryAccess(); + @Data + public static class SecondaryAccess { + @javax.validation.constraints.Pattern(regexp="^http[s]?://[^:]+?(:\\d+)?.*([^/]+/)$") + private Optional<String> baseUrlWicket = Optional.empty(); + } + + private Integer batchSize = 10; + + private final QuartzSession quartzSession = new QuartzSession(); + @Data + public static class QuartzSession { + /** + * The user that runs the replay session secondary. + */ + private String user = "causewayModuleExtCommandReplaySecondaryUser"; + private List<String> roles = listOf("causewayModuleExtCommandReplaySecondaryRole"); + } + + private final QuartzReplicateAndReplayJob quartzReplicateAndReplayJob = new QuartzReplicateAndReplayJob(); + @Data + public static class QuartzReplicateAndReplayJob { + /** + * Number of milliseconds before starting the job. + */ + private long startDelay = 15000; + /** + * Number of milliseconds before running again. + */ + private long repeatInterval = 10000; + } + + private final Analyser analyser = new Analyser(); + @Data + public static class Analyser { + private final Result result = new Result(); + @Data + public static class Result { + private boolean enabled = true; + } + private final Exception exception = new Exception(); + @Data + public static class Exception { + private boolean enabled = true; + } + + } + } + private final Cors cors = new Cors(); @Data public static class Cors { @@ -2975,103 +3070,21 @@ public class CausewayConfiguration { } - private final Quartz quartz = new Quartz(); - @Data - public static class Quartz { - } - - private final CommandLog commandLog = new CommandLog(); - @Data - public static class CommandLog { - - public enum PublishPolicy { - ALWAYS, - ONLY_IF_SYSTEM_CHANGED, - ; - public boolean isAlways() { return this == ALWAYS; } - public boolean isOnlyIfSystemChanged() { return this == ONLY_IF_SYSTEM_CHANGED; } - - } - /** - * Whether commands should be published always, or only if a change in the system's state has been detected. - * - * <p> - * In general, the default of {@link PublishPolicy#ALWAYS} should be used, <i>unless</i> the - * <i>Audit Trail</i> extension is also in use, which is able to advise on whether the systems state has - * changed. - * </p> - * - * <p> - * Put another way, if this policy is set to {@link PublishPolicy#ONLY_IF_SYSTEM_CHANGED} but the - * <i>Audit Trail</i> extension is <i>not</i> enabled, then nothing will be logged. - * </p> - */ - @Getter @Setter - private PublishPolicy publishPolicy = PublishPolicy.ALWAYS; - - } - - private final CommandReplay commandReplay = new CommandReplay(); + private final ExecutionOutbox executionOutbox = new ExecutionOutbox(); + @Valid @Data - public static class CommandReplay { - - private final PrimaryAccess primaryAccess = new PrimaryAccess(); - @Data - public static class PrimaryAccess { - @javax.validation.constraints.Pattern(regexp="^http[s]?://[^:]+?(:\\d+)?.*([^/]+/)$") - private Optional<String> baseUrlRestful = Optional.empty(); - private Optional<String> user = Optional.empty(); - private Optional<String> password = Optional.empty(); - @javax.validation.constraints.Pattern(regexp="^http[s]?://[^:]+?(:\\d+)?.*([^/]+/)$") - private Optional<String> baseUrlWicket = Optional.empty(); - } - - private final SecondaryAccess secondaryAccess = new SecondaryAccess(); - @Data - public static class SecondaryAccess { - @javax.validation.constraints.Pattern(regexp="^http[s]?://[^:]+?(:\\d+)?.*([^/]+/)$") - private Optional<String> baseUrlWicket = Optional.empty(); - } - - private Integer batchSize = 10; + public static class ExecutionOutbox { - private final QuartzSession quartzSession = new QuartzSession(); - @Data - public static class QuartzSession { - /** - * The user that runs the replay session secondary. - */ - private String user = "causewayModuleExtCommandReplaySecondaryUser"; - private List<String> roles = listOf("causewayModuleExtCommandReplaySecondaryRole"); - } - - private final QuartzReplicateAndReplayJob quartzReplicateAndReplayJob = new QuartzReplicateAndReplayJob(); + private final RestApi restApi = new RestApi(); + @Valid @Data - public static class QuartzReplicateAndReplayJob { - /** - * Number of milliseconds before starting the job. - */ - private long startDelay = 15000; + public static class RestApi { /** - * Number of milliseconds before running again. + * The maximum number of interactions that will be returned when the REST API is polled. */ - private long repeatInterval = 10000; - } - - private final Analyser analyser = new Analyser(); - @Data - public static class Analyser { - private final Result result = new Result(); - @Data - public static class Result { - private boolean enabled = true; - } - private final Exception exception = new Exception(); - @Data - public static class Exception { - private boolean enabled = true; - } - + @Min(value = 1) + @Max(value = 1000) + private int maxPending = 100; } } diff --git a/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc b/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc index a151e2ecf0..e364186a9e 100644 --- a/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc +++ b/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc @@ -7,7 +7,7 @@ The _Command Log_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[] SPI that persists xref:refguide:applib:index/services/command/Command.adoc[Command]s using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store. One use case is to combine with the xref:security:audittrail:about.adoc[] extension. -The _commandlog_ module logs the action invocations or property edits that the end-user makes, while the _audit trail_ logs the resultant changes in state to domain objects. +The _Command Log_ module logs the action invocations or property edits that the end-user makes, while the _audit trail_ logs the resultant changes in state to domain objects. The two logs are correlated using the xref:refguide:applib:index/services/iactn/Interaction.adoc#getInteractionId_[interactionId] of the owning xref:refguide:applib:index/services/iactn/Interaction.adoc[interaction]. Another use case is to support (persisted) background commands, whereby actions are not invoked immediately but instead persisted and invoked by a background thread; this is described in the xref:#background-commands[background commands] section below. @@ -18,9 +18,9 @@ Sometimes the xref:executionlog:about.adoc[] extension is also configured with o == Setup -include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+2] +=== Dependency Management -In addition, add a section for _Command Log_'s own BOM: +Add a section for the _Command Log_ module's own BOM: [source,xml,subs="attributes+"] .pom.xml @@ -61,7 +61,6 @@ In the webapp module of your application, add the following dependency: In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the CommandLog modules. -You will also need to import the fixture module; SecMan uses fixture scripts to seed its entities: [source,java] .AppManifest.java @@ -78,6 +77,7 @@ public class AppManifest { <.> specify either `CausewayModuleExtCommandLogPersistenceJdo` or `CausewayModuleExtCommandLogPersistenceJpa`, as required +If using xref:security:secman:about.adoc[], you will also need to import the xref:testing:fixtures:about.adoc[Fixture] module; SecMan uses fixture scripts to seed its entities. [#configure-properties] === Configuration Properties @@ -93,7 +93,7 @@ causeway: auto-create-schemas: causewayExtCommandLog ---- -Optionally, modify the configuration properties for CommandLog itself: +Optionally, modify the configuration properties for the _Command Log_ module itself: [source,yaml] .application.yml @@ -137,22 +137,21 @@ To get you started, the following fragment adds all of the actions to an "Activi </mb3:secondary> ---- -[#security-roles] -=== Security Roles +[#secman-security-roles] +=== SecMan Security Roles -TODO - v2 +If xref:security:secman:about.adoc[] extension is configured, then permissions must be granted to access the menu actions. +This can be done by granting the role set up by the xref:refguide:extensions:index/secman/applib/role/seed/CausewayExtCommandLogRoleAndPermissions.adoc[] seed fixture script (see its `ROLE_NAME` constant). - -[#background-commands] == User Interface The extension provides a number of menu actions and contributions. The menu actions are as listed in xref:menubar-layout-xml[], above. They allow the administrator to query the persisted commands. -Typically access to these actions would be restricted, see xref:security-roles[security roles] above. +Typically access to these actions would be restricted, see xref:secman-security-roles[security roles] above. The extension also provides these mixins: @@ -170,7 +169,9 @@ Most notably, this is xref:security:secman:about.adoc[] extension's xref:refguid It is also supported by xref:security:sessionlog:about.adoc * xref:refguide:extensions:index/commandlog/applib/contributions/HasInteractionId_commandLogEntry.adoc[] - ++ +This contributes the `commandLogEntry` property to any object implementing xref:refguide:applib:index/mixins/system/HasInteractionId.adoc[] interface. +Typically these are the entities persisted by the xref:executionlog:about.adoc[] or xref:security:audittrail:about.adoc[] extensions, making it easy to traverse between these logs. [#background-commands] @@ -224,7 +225,7 @@ This is a Spring `@Service` and so can be obtained through injection. === Executing Actions using the Quartz scheduler Once a command has been persisted as a `CommandLogEntry`, we require some other process to actually execute the command. -The _commandlog_ module includes the `RunBackgroundCommandsJob`, a https://www.quartz-scheduler.org/[Quartz] job that does exactly this. +The _Command Log_ module includes the `RunBackgroundCommandsJob`, a https://www.quartz-scheduler.org/[Quartz] job that does exactly this. Each time it is called it will query for any background commands that have not been started, and will execute each (using the xref:refguide:applib:index/services/command/CommandExecutorService.adoc[CommandExecutorService]). The job is marked as non re-entrant, so it doesn't matter how often it is called; we recommend a 10 second delay usually works fine. @@ -267,8 +268,8 @@ public class AppManifest { ==== Disabling Quartz -The _commandlog_ module automatically references the https://www.quartz-scheduler.org/[Quartz] library. -If you don't want to use this functionality and want to exclude quartz, then add an explicit dependency on the _commandlog_ applib but exclude the quartz dependency within it: +The _Command Log_ module automatically references the https://www.quartz-scheduler.org/[Quartz] library. +If you don't want to use this functionality and want to exclude quartz, then add an explicit dependency on the _Command Log_ applib but exclude the quartz dependency within it: [source,xml] .pom.xml diff --git a/extensions/core/excel/adoc/modules/excel/pages/about.adoc b/extensions/core/excel/adoc/modules/excel/pages/about.adoc index a3702932b1..4802b4d433 100644 --- a/extensions/core/excel/adoc/modules/excel/pages/about.adoc +++ b/extensions/core/excel/adoc/modules/excel/pages/about.adoc @@ -1,14 +1,82 @@ -= Excel Library += Excel :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 Excel Library provides the ability to read from Excel spreadsheets, which can be useful for certain use cases, eg bulk import of data. +The _Excel_ module provides the ability to read from Excel spreadsheets, which can be useful for certain use cases, eg bulk import of data. Each row of a spreadsheet can be mapped to a domain object, usually a view model. -The view model can validate itself and then apply +The view model can validate itself and then be applied. -The library also provides the opposite use case, converting a collection of domain objects into an Excel spreadsheet. +The module also supports the opposite use case, converting a collection of domain objects into an Excel spreadsheet. In addition, the library provides fixture support, allowing test data to be specified in a spreadsheet. -WARNING: TODO: v2 - to write up... + +== Setup + +=== Dependency Management + +Add a section for _Excel_ module's own BOM: + +[source,xml,subs="attributes+"] +.pom.xml +---- +<dependencyManagement> + <dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-excel</artifactId> + <scope>import</scope> + <type>pom</type> + <version>{page-causewayrel}</version> + </dependency> + </dependencies> +</dependencyManagement> +---- + +[#dependencies] +=== Dependencies + +In the modules of your application that will use the _Excel_ extension, add the following dependency/ies: + +* for xref:export-and-import[export/import], add: ++ +[source,xml] +.pom.xml +---- +<dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-excel-applib</artifactId> + </dependency> +</dependencies> +---- + +* for xref:fixture-support[fixture support], add: ++ +[source,xml] +.pom.xml +---- +<dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-excel-testing</artifactId> + </dependency> +</dependencies> +---- + + + +[#export-and-import] +== Export and Import + +TODO - v2 + +[#fixture-support] +== Fixture Support + +TODO - v2 + +== See also + +* xref:testing:fixtures:about.adoc[] (in the xref:testing::about.adoc[Testing Guide]). diff --git a/extensions/core/excel/testing/src/main/java/org/apache/causeway/extensions/excel/testing/ExcelFixture.java b/extensions/core/excel/testing/src/main/java/org/apache/causeway/extensions/excel/testing/ExcelFixture.java index bf95b85ae7..5ee17946ce 100644 --- a/extensions/core/excel/testing/src/main/java/org/apache/causeway/extensions/excel/testing/ExcelFixture.java +++ b/extensions/core/excel/testing/src/main/java/org/apache/causeway/extensions/excel/testing/ExcelFixture.java @@ -18,12 +18,13 @@ */ package org.apache.causeway.extensions.excel.testing; +import lombok.Getter; +import lombok.Setter; +import lombok.val; + +import java.io.InputStream; import java.net.URL; -import java.util.Arrays; -import java.util.Collections; -import java.util.List; -import java.util.Map; -import java.util.Optional; +import java.util.*; import javax.inject.Inject; import javax.inject.Named; @@ -31,7 +32,6 @@ import javax.inject.Named; import org.apache.causeway.applib.annotation.DomainObject; import org.apache.causeway.applib.annotation.Programmatic; import org.apache.causeway.applib.annotation.PropertyLayout; -import org.apache.causeway.applib.services.inject.ServiceInjector; import org.apache.causeway.applib.services.metamodel.BeanSort; import org.apache.causeway.applib.services.repository.RepositoryService; import org.apache.causeway.applib.value.Blob; @@ -45,28 +45,26 @@ import org.apache.causeway.extensions.excel.applib.CausewayModuleExtExcelApplib; import org.apache.causeway.extensions.excel.applib.ExcelService; import org.apache.causeway.testing.fixtures.applib.fixturescripts.FixtureResultList; import org.apache.causeway.testing.fixtures.applib.fixturescripts.FixtureScript; - -import lombok.Getter; -import lombok.Setter; -import lombok.val; +import org.apache.causeway.testing.fixtures.applib.fixturescripts.FixtureScriptWithExecutionStrategy; +import org.apache.causeway.testing.fixtures.applib.fixturescripts.FixtureScripts; /** - * This class should be executed using - * {@link org.apache.causeway.testing.fixtures.applib.fixturescripts.FixtureScripts.MultipleExecutionStrategy#EXECUTE_ONCE_BY_VALUE} - * (it has value semantics). * * @since 2.0 {@index} */ @Named(ExcelFixture.LOGICAL_TYPE_NAME) @DomainObject -public class ExcelFixture extends FixtureScript { +public class ExcelFixture extends FixtureScript implements FixtureScriptWithExecutionStrategy { public final static String LOGICAL_TYPE_NAME = CausewayModuleExtExcelApplib.NAMESPACE + ".ExcelFixture"; + private final List<Class<?>> classes; + + @Inject SpecificationLoader specLoader; @Inject ExcelService excelService; + @Inject RepositoryService repositoryService; - private final List<Class<?>> classes; public ExcelFixture(final URL excelResource, final Class<?>... classes) { this(excelResource, Arrays.asList(classes)); @@ -104,6 +102,7 @@ public class ExcelFixture extends FixtureScript { this.classes = classes; } + /** * Input, optional: defines the name of the resource, used as a suffix to override {@link #getQualifiedName()} * (disambiguate items when added to {@link FixtureResultList} if multiple instances of {@link ExcelFixture} are @@ -113,6 +112,13 @@ public class ExcelFixture extends FixtureScript { @PropertyLayout(sequence = "1.1") private String excelResourceName; + @Programmatic + @Override + public String getQualifiedName() { + return super.getQualifiedName() + (getExcelResourceName() != null ? "-" + getExcelResourceName() : ""); + } + + /** * Input, mandatory ... the Excel spreadsheet to read. */ @@ -120,29 +126,28 @@ public class ExcelFixture extends FixtureScript { @PropertyLayout(sequence = "1.2") private URL excelResource; + /** * Input, mandatory ... the Excel spreadsheet to read. */ @Getter @Setter private Blob blob; + /** - * Output: the objects created by this fixture, for a specific persistable/row handler class. + * Output: all the objects created by this fixture. */ @Getter - private final Map<Class<?>, List<Object>> objectsByClass = _Maps.newHashMap(); + private final List objects = _Lists.newArrayList(); /** - * Output: all the objects created by this fixture. + * Output: the objects created by this fixture, for a specific persistable/row handler class. */ @Getter - private final List objects = _Lists.newArrayList(); + private final Map<Class<?>, List<Object>> objectsByClass = _Maps.newHashMap(); + + - @Programmatic - @Override - public String getQualifiedName() { - return super.getQualifiedName() + (getExcelResourceName() != null ? "-" + getExcelResourceName() : ""); - } @Override protected void execute(final ExecutionContext ec) { @@ -165,28 +170,6 @@ public class ExcelFixture extends FixtureScript { } } } - //region > bytes - private byte[] bytes; - - private byte[] getBytes() { - if (bytes == null) { - if (blob != null){ - bytes = blob.getBytes(); - } else { - bytes = readBytes(); - } - } - return bytes; - } - - private byte[] readBytes() { - try(val is = getExcelResource().openStream()) { - return _Bytes.of(is); - } catch (Exception e) { - throw new IllegalArgumentException("Could not read from resource: " + excelResource); - } - } - //endregion private List<Object> create( final Object rowObj, @@ -215,7 +198,32 @@ public class ExcelFixture extends FixtureScript { this.objects.addAll(createdObjects); } - //region > hashCode, equals + + + private byte[] bytes; + private byte[] getBytes() { + if (bytes == null) { + if (blob != null){ + bytes = blob.getBytes(); + } else { + bytes = readBytes(); + } + } + return bytes; + } + + private byte[] readBytes() { + try(final InputStream is = getExcelResource().openStream()) { + return _Bytes.of(is); + } catch (Exception e) { + throw new IllegalArgumentException("Could not read from resource: " + getExcelResource()); + } + } + + @Override + public FixtureScripts.MultipleExecutionStrategy getMultipleExecutionStrategy() { + return FixtureScripts.MultipleExecutionStrategy.EXECUTE_ONCE_BY_VALUE; + } @Override public boolean equals(final Object o) { @@ -235,13 +243,6 @@ public class ExcelFixture extends FixtureScript { return Arrays.hashCode(getBytes()); } - //endregion - @javax.inject.Inject - private RepositoryService repositoryService; -// @javax.inject.Inject -// private BookmarkService bookmarkService; - @javax.inject.Inject - private ServiceInjector serviceInjector; } diff --git a/extensions/core/excel/testing/src/main/java/org/apache/causeway/extensions/excel/testing/ExcelFixture2.java b/extensions/core/excel/testing/src/main/java/org/apache/causeway/extensions/excel/testing/ExcelFixture2.java index e473b534e5..4ed8ac8a26 100644 --- a/extensions/core/excel/testing/src/main/java/org/apache/causeway/extensions/excel/testing/ExcelFixture2.java +++ b/extensions/core/excel/testing/src/main/java/org/apache/causeway/extensions/excel/testing/ExcelFixture2.java @@ -35,23 +35,27 @@ import org.apache.causeway.extensions.excel.applib.CausewayModuleExtExcelApplib; import org.apache.causeway.extensions.excel.applib.ExcelService; import org.apache.causeway.extensions.excel.applib.WorksheetSpec; import org.apache.causeway.testing.fixtures.applib.fixturescripts.FixtureScript; +import org.apache.causeway.testing.fixtures.applib.fixturescripts.FixtureScriptWithExecutionStrategy; +import org.apache.causeway.testing.fixtures.applib.fixturescripts.FixtureScripts; import lombok.Getter; import lombok.Setter; /** - * This class should be executed using - * {@link org.apache.causeway.testing.fixtures.applib.fixturescripts.FixtureScripts.MultipleExecutionStrategy#EXECUTE_ONCE_BY_VALUE} - * (it has value semantics). * * @since 2.0 {@index} */ @Named(ExcelFixture2.LOGICAL_TYPE_NAME) @DomainObject -public class ExcelFixture2 extends FixtureScript { +public class ExcelFixture2 extends FixtureScript implements FixtureScriptWithExecutionStrategy { public final static String LOGICAL_TYPE_NAME = CausewayModuleExtExcelApplib.NAMESPACE + ".ExcelFixture2"; + + @Inject FactoryService factoryService; + @Inject ExcelService excelService; + + /** * Input, optional: defines the name of the resource. */ @@ -85,6 +89,32 @@ public class ExcelFixture2 extends FixtureScript { private WorksheetSpec.Sequencer sequencer; + protected <T> WorksheetSpec.RowFactory<T> rowFactoryFor( + final Class<T> rowClass, + final ExecutionContext ec) { + + return new WorksheetSpec.RowFactory<T>() { + @Override + public T create() { + final T importLine = + factoryService.getOrCreate(rowClass); + // allow the line to interact with the calling fixture + if(importLine instanceof FixtureAwareRowHandler<?>) { + final FixtureAwareRowHandler<?> farh = (FixtureAwareRowHandler<?>) importLine; + farh.setExecutionContext(ec); + farh.setExcelFixture2(ExcelFixture2.this); + } + return importLine; + } + + @Override + public Class<?> getCls() { + return rowClass; + } + }; + } + + /** * Output... a list of list of objects (each representing a row of a sheet) */ @@ -101,12 +131,10 @@ public class ExcelFixture2 extends FixtureScript { } this.lists = excelService.fromExcel(blob, matcher, sequencer); - } - //region > bytes - private byte[] bytes; + private byte[] bytes; private byte[] getBytes() { if (bytes == null) { if (blob != null){ @@ -126,34 +154,11 @@ public class ExcelFixture2 extends FixtureScript { } } - //endregion - - - protected <T> WorksheetSpec.RowFactory<T> rowFactoryFor( - final Class<T> rowClass, - final ExecutionContext ec) { - - return new WorksheetSpec.RowFactory<T>() { - @Override - public T create() { - final T importLine = - factoryService.getOrCreate(rowClass); - // allow the line to interact with the calling fixture - if(importLine instanceof FixtureAwareRowHandler<?>) { - final FixtureAwareRowHandler<?> farh = (FixtureAwareRowHandler<?>) importLine; - farh.setExecutionContext(ec); - farh.setExcelFixture2(ExcelFixture2.this); - } - return importLine; - } - @Override - public Class<?> getCls() { - return rowClass; - } - }; + @Override + public FixtureScripts.MultipleExecutionStrategy getMultipleExecutionStrategy() { + return FixtureScripts.MultipleExecutionStrategy.EXECUTE_ONCE_BY_VALUE; } - //region > hashCode, equals @Override public boolean equals(final Object o) { @@ -173,19 +178,5 @@ public class ExcelFixture2 extends FixtureScript { return Arrays.hashCode(getBytes()); } - //endregion - -// @javax.inject.Inject -// private RepositoryService repositoryService; -// @javax.inject.Inject -// private BookmarkService bookmarkService; -// @javax.inject.Inject -// private ServiceRegistry serviceRegistry; - - @Inject - FactoryService factoryService; - - @Inject - ExcelService excelService; } diff --git a/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc b/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc index 4b9eb5cc94..bbab00cc76 100644 --- a/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc +++ b/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc @@ -4,11 +4,11 @@ :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 _Execution Log_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store. +The _Execution Log_ extension provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store. One use case is to combine with the xref:security:audittrail:about.adoc[] extension. -The _commandlog_ module logs the action invocations or property edits that the end-user makes, while the _audit trail_ logs the resultant changes in state to domain objects. +The _Command Log_ module logs the action invocations or property edits that the end-user makes, while the _audit trail_ logs the resultant changes in state to domain objects. The two logs are correlated using the xref:refguide:applib:index/services/iactn/Interaction.adoc#getInteractionId_[interactionId] of the owning xref:refguide:applib:index/services/iactn/Interaction.adoc[interaction]. Sometimes the xref:commandlog:about.adoc[] extension is also configured with or instead of this extension; see the xref:#notes[notes] below to compare and contrast. @@ -16,9 +16,9 @@ Sometimes the xref:commandlog:about.adoc[] extension is also configured with or == Setup -include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+2] +=== Dependency Management -In addition, add a section for secman's own BOM: +Add a section for _Execution Log_'s own BOM: [source,xml,subs="attributes+"] .pom.xml @@ -56,9 +56,8 @@ In the webapp module of your application, add the following dependency: [[_update-appmanifest]] === Update AppManifest +In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the _ExecutionLog_ modules. -In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the CommandLog modules. -You will also need to import the fixture module; SecMan uses fixture scripts to seed its entities: [source,java] .AppManifest.java @@ -66,15 +65,16 @@ You will also need to import the fixture module; SecMan uses fixture scripts to @Configuration @Import({ ... - CausewayModuleExtCommandLogPersistenceXxx.class, // <.> + CausewayModuleExtExecutionLogPersistenceXxx.class, // <.> ... }) public class AppManifest { } ---- -<.> specify either `CausewayModuleExtCommandLogPersistenceJdo` or `CausewayModuleExtCommandLogPersistenceJpa`, as required +<.> specify either `CausewayModuleExtExecutionLogPersistenceJdo` or `CausewayModuleExtExecutionLogPersistenceJpa`, as required +If using xref:security:secman:about.adoc[], you will also need to import the xref:testing:fixtures:about.adoc[Fixture] module; SecMan uses fixture scripts to seed its entities. [#configure-properties] === Configuration Properties @@ -93,7 +93,8 @@ causeway: This extension currently does not though define any configuration properties of its own. -== menubar.layout.xml +[#menubar-layout-xml] +=== menubar.layout.xml Once configured, the extension provides a number of menu actions. You can use `menubars.layout.xml` to arrange these as you see fit. @@ -106,45 +107,55 @@ To get you started, the following fragment adds all of the actions to an "Activi ... <mb3:menu> <mb3:named>Activity</mb3:named> - <mb3:section> - <mb3:named>Sessions</mb3:named> - <mb3:serviceAction id="activeSessions" objectType="isis.ext.sessionLog.SessionLogMenu"/> - <mb3:serviceAction id="findSessions" objectType="isis.ext.sessionLog.SessionLogMenu"/> - </mb3:section> - <mb3:section> - <mb3:named>Commands</mb3:named> - <mb3:serviceAction id="activeCommands" objectType="isis.ext.commandLog.CommandLogMenu"/> - <mb3:serviceAction id="findMostRecent" objectType="isis.ext.commandLog.CommandLogMenu"/> - <mb3:serviceAction id="findCommands" objectType="isis.ext.commandLog.CommandLogMenu"/> - <mb3:serviceAction id="findAll" objectType="isis.ext.commandLog.CommandLogMenu"/> - </mb3:section> + ... <mb3:section> <mb3:named>Execution Log</mb3:named> <mb3:serviceAction id="findMostRecent" objectType="isis.ext.executionLog.ExecutionLogMenu"/> <mb3:serviceAction id="findExecutions" objectType="isis.ext.executionLog.ExecutionLogMenu"/> <mb3:serviceAction id="findAll" objectType="isis.ext.executionLog.ExecutionLogMenu"/> </mb3:section> - <mb3:section> - <mb3:named>Audit Trail</mb3:named> - <mb3:serviceAction id="findMostRecent" objectType="isis.ext.auditTrail.AuditTrailMenu"/> - <mb3:serviceAction id="findAuditEntries" objectType="isis.ext.auditTrail.AuditTrailMenu"/> - <mb3:serviceAction id="findAll" objectType="isis.ext.auditTrail.AuditTrailMenu"/> - </mb3:section> - <mb3:section> - <mb3:named>Execution Outbox</mb3:named> - <mb3:serviceAction id="findOldest" objectType="isis.ext.executionOutbox.ExecutionOutboxMenu"/> - <mb3:serviceAction id="findAll" objectType="isis.ext.executionOutbox.ExecutionOutboxMenu"/> - </mb3:section> + ... </mb3:menu> </mb3:secondary> ---- -== Security Roles +[#secman-security-roles] +=== SecMan Security Roles + +If xref:security:secman:about.adoc[] extension is configured, then permissions must be granted to access the menu actions. + +This can be done by granting the role set up by the xref:refguide:extensions:index/secman/applib/role/seed/CausewayExtExecutionLogRoleAndPermissions.adoc[] seed fixture script (see its `ROLE_NAME` constant). + + +== User Interface + +The extension provides a number of menu actions and contributions. + +The menu actions are as listed in xref:menubar-layout-xml[], above. +They allow the administrator to query the persisted commands. +Typically access to these actions would be restricted, see xref:secman-security-roles[security roles] above. + +The extension also provides these mixins: + +* xref:refguide:extensions:index/executionlog/applib/contributions/Object_recentExecutions.adoc[] ++ +This contributes a `recentExecutions` collection to each and every domain object. ++ +This can be explicit positioned through the domain class' own xref:userguide:fun:ui.adoc#object-layout[layout file], but this is generally not necessary: it will slot into the tab group in the layout file indicated for unreferenced collections using `<tabGroup unreferencedCollections="true">`. + +* xref:refguide:extensions:index/executionlog/applib/contributions/HasUsername_recentExecutionsByUser.adoc[] ++ +This contributes the `recentExecutionsByUser` collection to any domain object that implements the xref:refguide:applib:index/mixins/security/HasUsername.adoc[] interface. ++ +Most notably, this is xref:security:secman:about.adoc[] extension's xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[] entity that represents a logged-on user. +It is also supported by xref:security:sessionlog:about.adoc -TODO - v2 +* xref:refguide:extensions:index/executionlog/applib/contributions/HasInteractionId_executionLogEntries.adoc[] ++ +This contributes the `executionLogEntries` property to any object implementing xref:refguide:applib:index/mixins/system/HasInteractionId.adoc[] interface. +Typically these are the entities persisted by the xref:commandlog:about.adoc[] or xref:security:audittrail:about.adoc[] extensions, making it easy to traverse between these logs. -== Contributions diff --git a/extensions/core/executionoutbox/adoc/modules/executionoutbox/images/outbox.png b/extensions/core/executionoutbox/adoc/modules/executionoutbox/images/outbox.png new file mode 100644 index 0000000000..b7bf388257 Binary files /dev/null and b/extensions/core/executionoutbox/adoc/modules/executionoutbox/images/outbox.png differ diff --git a/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc b/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc index 17bdd9f080..3c86613e9a 100644 --- a/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc +++ b/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc @@ -4,20 +4,105 @@ :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 _executionoutbox_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s into an "outbox" (using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store). +The _Execution Outbox_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s into an "outbox" (using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store). The purpose of the "outbox" is to act as a temporary store of executions to be propogated to other "downstream" systems. The module also provides a REST API, a rest client and DTOs to represent the payloads between these two services. The client polls the outbox through the REST API (for example every 15 seconds), and uses it to download any new executions. Once processed (eg published to a message bus), the client then uses the same REST API to delete the executions. +The usage REST client is described xref:outbox-rest-client[below]. + +== Setup + +=== Dependency Management + +Add a section for _Execution Outbox_'s own BOM: +[source,xml,subs="attributes+"] +.pom.xml +---- +<dependencyManagement> + <dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-executionoutbox</artifactId> + <scope>import</scope> + <type>pom</type> + <version>{page-causewayrel}</version> + </dependency> + </dependencies> +</dependencyManagement> +---- + +[#dependencies] +=== Dependencies -WARNING: TODO: v2 - to write up... +In the webapp module of your application, add the following dependency: +[source,xml] +.pom.xml +---- +<dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-executionoutbox-persistence-XXX</artifactId> <!--.--> + </dependency> +</dependencies> +---- +<.> specify either `causeway-extensions-executionoutbox-persistence-jpa` or `causeway-extensions-executionoutbox-persistence-jdo`, as required + +[[_update-appmanifest]] +=== Update AppManifest + +In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the _ExecutionOutbox_ modules. + + +[source,java] +.AppManifest.java +---- +@Configuration +@Import({ + ... + CausewayModuleExtExecutionOutboxPersistenceXxx.class, // <.> + ... +}) +public class AppManifest { +} +---- -== menubar.layout.xml +<.> specify either `CausewayModuleExtExecutionOutboxPersistenceJdo` or `CausewayModuleExtExecutionOutboxPersistenceJpa`, as required + +If using xref:security:secman:about.adoc[], you will also need to import the xref:testing:fixtures:about.adoc[Fixture] module; SecMan uses fixture scripts to seed its entities. + +[#configure-properties] +=== Configuration Properties + +Add the database schema used by the _Execution Outbox_ entities to the configuration file: + +[source,yaml] +.application.yml +---- +causeway: + persistence: + schema: + auto-create-schemas: causewayExtExecutionOutbox +---- + +Optionally, modify the configuration properties for the _Execution Outbox_ module itself: + +[source,yaml] +.application.yml +---- +causeway: + extensions: + execution-outbox: + rest-api: + max-pending: 100 +---- + + +[#menubar-layout-xml] +=== menubar.layout.xml Once configured, the extension provides a number of menu actions. You can use `menubars.layout.xml` to arrange these as you see fit. @@ -40,3 +125,110 @@ To get you started, the following fragment adds all of the actions to an "Activi </mb3:menu> </mb3:secondary> ---- + +[#secman-security-roles] +=== SecMan Security Roles + +If xref:security:secman:about.adoc[] extension is configured, then permissions must be granted to access the menu actions. + +This can be done by granting the role set up by the xref:refguide:extensions:index/secman/applib/role/seed/CausewayExtExecutionOutboxRoleAndPermissions.adoc[] seed fixture script (see its `ROLE_NAME` constant). + + +== User Interface + +The extension provides a number of menu actions, as listed in xref:menubar-layout-xml[], above. +They allow the administrator to query the persisted commands. +Typically access to these actions would be restricted, see xref:secman-security-roles[security roles] above. + + +[#outbox-rest-client] +== Outbox REST Client + +Once an execution has been persisted into the outbox, it will stay there until it has been processed and removed by another process. +Typically that other process will be a microservice that forwards on the message to an event bus. + +This is shown below. + +.processing messages from the outbox +image::outbox.png[width=600px] + +The module provides a REST service, along with a rest client, xref:refguide:extensions:index/executionlog/restclient/api/OutboxClient.adoc[OutboxClient]. +The `OutboxClient` is used by the _message processor_ shown in the above diagram. + + +=== Prerequisites + +To setup the message processor: + +* in `dependencyManagement` section, add an entry for _Execution Outbox_'s own BOM: ++ +[source,xml] +.pom.xml +---- +<dependencyManagement> + <dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-executionoutbox</artifactId> + <scope>import</scope> + <type>pom</type> + <version>{page-causewayrel}</version> + </dependency> + </dependencies> +</dependencyManagement> +---- + +* In the `dependencies` section, add the following dependency: ++ +[source,xml] +.pom.xml +---- +<dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-executionoutbox-restclient</artifactId> + </dependency> +</dependencies> +---- + + +=== Usage + +To instantiate the `OutboxClient`, specify the URL, user and password. +The URL will be something like: `http://localhost:8080/restful/`, where the last part is the default path obtainable from the `resteasy.jaxrs.defaultPath` configuration property of the Causeway app. + +The `OutboxClient` API consists of three methods: + +* to retrieve any pending interactions: ++ +[source,java] +---- +List<InteractionDto> pending = outboxClient.pending(); +---- + +* to delete a single interaction: ++ +[source,java] +---- +val first = pending.get(0); +val interactionId = first.getInteractionId(); +val sequence = first.getExecution().getSequence(); + +outboxClient.delete(interactionId, sequence); +---- + +* to delete many interactions: ++ +[source,java] +---- +outboxClient.deleteMany(pending); +---- + +The maximum number of interactions that will be returned is configurable, see xref:configure-properties[above]. + + +== See also + +* xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[] SPI +* xref:executionlog:about.adoc[] extension + diff --git a/extensions/core/executionoutbox/applib/src/main/java/org/apache/causeway/extensions/executionoutbox/applib/dom/ExecutionOutboxEntryRepository.java b/extensions/core/executionoutbox/applib/src/main/java/org/apache/causeway/extensions/executionoutbox/applib/dom/ExecutionOutboxEntryRepository.java index 845665039f..6ea82c026e 100644 --- a/extensions/core/executionoutbox/applib/src/main/java/org/apache/causeway/extensions/executionoutbox/applib/dom/ExecutionOutboxEntryRepository.java +++ b/extensions/core/executionoutbox/applib/src/main/java/org/apache/causeway/extensions/executionoutbox/applib/dom/ExecutionOutboxEntryRepository.java @@ -34,6 +34,7 @@ import org.apache.causeway.applib.services.factory.FactoryService; import org.apache.causeway.applib.services.iactn.Execution; import org.apache.causeway.applib.services.repository.RepositoryService; import org.apache.causeway.applib.util.schema.InteractionDtoUtils; +import org.apache.causeway.core.config.CausewayConfiguration; import org.apache.causeway.core.config.environment.CausewaySystemEnvironment; import org.apache.causeway.extensions.executionoutbox.applib.CausewayModuleExtExecutionOutboxApplib; import org.apache.causeway.schema.ixn.v2.InteractionDto; @@ -65,6 +66,7 @@ public abstract class ExecutionOutboxEntryRepository<E extends ExecutionOutboxEn @Inject Provider<RepositoryService> repositoryServiceProvider; @Inject FactoryService factoryService; @Inject CausewaySystemEnvironment causewaySystemEnvironment; + @Inject CausewayConfiguration causewayConfiguration; protected ExecutionOutboxEntryRepository(Class<E> executionOutboxEntryClass) { this.executionOutboxEntryClass = executionOutboxEntryClass; @@ -102,7 +104,7 @@ public abstract class ExecutionOutboxEntryRepository<E extends ExecutionOutboxEn public List<E> findOldest() { return repositoryService().allMatches( Query.named(executionOutboxEntryClass, ExecutionOutboxEntry.Nq.FIND_OLDEST) - .withLimit(100)); + .withLimit(causewayConfiguration.getExtensions().getExecutionOutbox().getRestApi().getMaxPending())); } public ExecutionOutboxEntry upsert( diff --git a/extensions/core/executionoutbox/restclient/src/main/java/org/apache/causeway/extensions/executionoutbox/restclient/CausewayModuleExtExecutionRestClient.java b/extensions/core/executionoutbox/restclient/src/main/java/org/apache/causeway/extensions/executionoutbox/restclient/CausewayModuleExtExecutionRestClient.java index eb8c5eb7e8..977156ba63 100644 --- a/extensions/core/executionoutbox/restclient/src/main/java/org/apache/causeway/extensions/executionoutbox/restclient/CausewayModuleExtExecutionRestClient.java +++ b/extensions/core/executionoutbox/restclient/src/main/java/org/apache/causeway/extensions/executionoutbox/restclient/CausewayModuleExtExecutionRestClient.java @@ -23,6 +23,9 @@ import org.springframework.context.annotation.Import; import org.apache.causeway.schema.CausewayModuleSchema; +/** + * @since 2.x {@index} + */ @Configuration @Import({ CausewayModuleSchema.class, diff --git a/extensions/core/executionoutbox/restclient/src/main/java/org/apache/causeway/extensions/executionoutbox/restclient/api/OutboxClient.java b/extensions/core/executionoutbox/restclient/src/main/java/org/apache/causeway/extensions/executionoutbox/restclient/api/OutboxClient.java index 2ede5c3094..899641a951 100644 --- a/extensions/core/executionoutbox/restclient/src/main/java/org/apache/causeway/extensions/executionoutbox/restclient/api/OutboxClient.java +++ b/extensions/core/executionoutbox/restclient/src/main/java/org/apache/causeway/extensions/executionoutbox/restclient/api/OutboxClient.java @@ -44,6 +44,9 @@ import lombok.Setter; import lombok.val; import lombok.extern.slf4j.Slf4j; +/** + * @since 2.x {@index} + */ @Slf4j public class OutboxClient { diff --git a/extensions/core/executionoutbox/restclient/src/test/java/org/apache/causeway/extensions/executionoutbox/restclient/integtests/RestEndpointService.java b/extensions/core/executionoutbox/restclient/src/test/java/org/apache/causeway/extensions/executionoutbox/restclient/integtests/RestEndpointService.java index d7cd783ad6..5c71ebf9a5 100644 --- a/extensions/core/executionoutbox/restclient/src/test/java/org/apache/causeway/extensions/executionoutbox/restclient/integtests/RestEndpointService.java +++ b/extensions/core/executionoutbox/restclient/src/test/java/org/apache/causeway/extensions/executionoutbox/restclient/integtests/RestEndpointService.java @@ -39,10 +39,8 @@ import lombok.extern.log4j.Log4j2; @RequiredArgsConstructor(onConstructor_ = {@Inject}) public class RestEndpointService { - private final Environment environment; private final RestEasyConfiguration restEasyConfiguration; private final WebAppContextPath webAppContextPath; - private final InteractionService interactionService; public OutboxClient newClient(int port, String username, String password) { diff --git a/extensions/core/executionrepublisher/adoc/modules/executionrepublisher/pages/about.adoc b/extensions/core/executionrepublisher/adoc/modules/executionrepublisher/pages/about.adoc index ddf0d4aca1..d3d0946971 100644 --- a/extensions/core/executionrepublisher/adoc/modules/executionrepublisher/pages/about.adoc +++ b/extensions/core/executionrepublisher/adoc/modules/executionrepublisher/pages/about.adoc @@ -8,3 +8,25 @@ The _executionrepublisher_ module contributes an action to allow logged executions (as per the xref:userguide:executionlog:about.adoc[] module) to be republished to the outbox (as per the xref:userguide:executionoutbox:about.adoc[] modul). WARNING: TODO: v2 - to write up... + +== Setup + +=== Dependency Management + +Add a section for _Execution Republisher_'s own BOM: + +[source,xml,subs="attributes+"] +.pom.xml +---- +<dependencyManagement> + <dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-executionrepublisher</artifactId> + <scope>import</scope> + <type>pom</type> + <version>{page-causewayrel}</version> + </dependency> + </dependencies> +</dependencyManagement> +---- diff --git a/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc b/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc index 3f366863df..976c8b368f 100644 --- a/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc +++ b/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc @@ -2,20 +2,49 @@ :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 [...] -This module provides a very thin layer to use Spring Boot's integration with https://flywaydb.org[Flyway] +The _Flyway_ extension module provides a very thin layer to use Spring Boot's integration with https://flywaydb.org[Flyway] -== Configuration +== Setup -Add the following dependency: +=== Dependency Management + +Add a section for _Flyway_'s own BOM: + +[source,xml,subs="attributes+"] +.pom.xml +---- +<dependencyManagement> + <dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-flyway</artifactId> + <scope>import</scope> + <type>pom</type> + <version>{page-causewayrel}</version> + </dependency> + </dependencies> +</dependencyManagement> +---- + +[#dependencies] +=== Dependencies + +In the webapp module of your application, add the following dependency: [source,xml] +.pom.xml ---- -<dependency> - <groupId>org.apache.causeway.extensions</groupId> - <artifactId>causeway-extensions-flyway-impl</artifactId> -</dependency> +<dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-flyway-impl</artifactId> + </dependency> +</dependencies> ---- +[[_update-appmanifest]] +=== Update AppManifest + Also add the following module to your `AppManifest`: [source,java] @@ -30,6 +59,9 @@ public static class AppManifest { } ---- +[#configure-properties] +=== Configuration Properties + Configure Flyway connection parameters: [source,properties] @@ -80,6 +112,6 @@ The xref:docs:starters:simpleapp.adoc[simpleapp starter app] also provides an ex -== Reference +== See also * https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto-execute-flyway-database-migrations-on-startup[Spring Boot docs] for Flyway integration diff --git a/extensions/core/quartz/adoc/modules/quartz/pages/about.adoc b/extensions/core/quartz/adoc/modules/quartz/pages/about.adoc index cde63a13a1..6d9cb8037d 100644 --- a/extensions/core/quartz/adoc/modules/quartz/pages/about.adoc +++ b/extensions/core/quartz/adoc/modules/quartz/pages/about.adoc @@ -2,6 +2,12 @@ :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 [...] +[CAUTION] +==== +TODO - v2 I think this module may no longer be necessary; Spring Boot can inject into jobs just fine. +Moving to incubator, pending possible deletion. +==== + Quartz is (according to their link:https://www.quartz-scheduler.org/[website]) a richly featured, open source job scheduling library that can be integrated within virtually any Java application. We can configure Quartz to run ``Job``s using xref:userguide:btb:headless-access.adoc[headless access], for numerous use cases, most commonly involving the polling of work to be performed in the background. @@ -18,7 +24,7 @@ This extension supports the use case where there is a requirement to pass state == Simple use case -The simple use case (that _doesn't_ require a dependeny on this extension) is demonstrated in the xref:docs:starters:simpleapp.adoc[SimpleApp] starter app. +The simple use case (that _doesn't_ require a dependency on this extension) is demonstrated in the xref:docs:starters:simpleapp.adoc[SimpleApp] starter app. * add the dependency (eg to the webapp module): + @@ -53,7 +59,7 @@ The simple use case (that _doesn't_ require a dependeny on this extension) is de @Slf4j public class SampleJob implements Job { - private final InteractionService interactionService; // <1> + private final InteractionService interactionService; // <.> private final TransactionalProcessor transactionalProcessor; // <1> @Override @@ -62,7 +68,7 @@ public class SampleJob implements Job { } } ---- -<1> for xref:userguide:btb:headless-access.adoc[headless access] to the domain object model. +<.> for xref:userguide:btb:headless-access.adoc[headless access] to the domain object model. * Set up beans to act as the trigger factory and a job factory: + @@ -104,11 +110,28 @@ public class QuartzModule { == More complex use cases -This extension supports a couple of slightly more advanced use cases. +This _Quartz_ module is intended to support a couple of slightly more advanced use cases. If either are used: -* update the `pom.xml` dependencies: +* add an entry to the `pom.xml` `dependencyManagement` section: ++ +[source,xml] +---- +<dependencyManagement> + <dependencies> + <dependency> + <groupId>org.apache.causeway.extensions</groupId> + <artifactId>causeway-extensions-quartz</artifactId> + <scope>import</scope> + <type>pom</type> + <version>{page-causewayrel}</version> + </dependency> + </dependencies> +</dependencyManagement> +---- + +* add the following dependency: + [source,xml] ---- @@ -144,9 +167,6 @@ To support this use case, this extension provides the xref:refguide:extensions:i === Injecting domain services into jobs -CAUTION: TODO - it's possible this boilerplate may be unnecessary? -xref:docs:starters:simpleapp.adoc[SimpleApp]'s job seems to be injected into without this extra rigamorole. - If we want to inject domain services into the Quartz `Job`, then we should define a number of additional beans. These instantiate xref:refguide:extensions:index/quartz/spring/AutowiringSpringBeanJobFactory.adoc[] as the job factory: diff --git a/extensions/security/secman/adoc/modules/secman/pages/setting-up.adoc b/extensions/security/secman/adoc/modules/secman/pages/setting-up.adoc index d55c5c419f..b34d4ae7be 100644 --- a/extensions/security/secman/adoc/modules/secman/pages/setting-up.adoc +++ b/extensions/security/secman/adoc/modules/secman/pages/setting-up.adoc @@ -3,9 +3,9 @@ :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 [...] :page-partial: -This section describes how to setup and configure SecMan for use in your Apache Causeway application, for both authentication (`Authenticator` SPI) and authorization (`Authorizor` SPI). +This section describes how to setup and configure _SecMan_ for use in your Apache Causeway application, for both authentication (`Authenticator` SPI) and authorization (`Authorizor` SPI). -It is also possible to use SecMan in conjunction with the framework's xref:security:shiro:about.adoc[integration with Shiro], where Shiro takes primary responsibility for authentication, while still using Secman for authorization. +It is also possible to use _SecMan_ in conjunction with the framework's xref:security:shiro:about.adoc[integration with Shiro], where Shiro takes primary responsibility for authentication, while still using Secman for authorization. This mode allows a separate authentication mechanism such as LDAP to be used. For more details, see xref:setting-up-with-shiro.adoc[setting up with Shiro]. @@ -13,7 +13,7 @@ For more details, see xref:setting-up-with-shiro.adoc[setting up with Shiro]. include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+1] -In addition, add a section for secman's own BOM: +In addition, add an entry for _SecMan_'s own BOM: [source,xml,subs="attributes+"] .pom.xml diff --git a/testing/archtestsupport/adoc/modules/archtestsupport/pages/about.adoc b/testing/archtestsupport/adoc/modules/archtestsupport/pages/about.adoc index 5895e5ad3c..ce7df0b335 100644 --- a/testing/archtestsupport/adoc/modules/archtestsupport/pages/about.adoc +++ b/testing/archtestsupport/adoc/modules/archtestsupport/pages/about.adoc @@ -10,7 +10,7 @@ Apache Causeway provides a library of link:https://www.archunit.org/[ArchUnit] t include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+2] -In addition, add a section for the BOM of all the testing support libraries: +In addition, add an entry for the BOM of all the testing support libraries: [source,xml,subs="attributes+"] .pom.xml diff --git a/testing/fakedata/adoc/modules/fakedata/pages/about.adoc b/testing/fakedata/adoc/modules/fakedata/pages/about.adoc index a8757f3f95..0339155eec 100644 --- a/testing/fakedata/adoc/modules/fakedata/pages/about.adoc +++ b/testing/fakedata/adoc/modules/fakedata/pages/about.adoc @@ -28,7 +28,7 @@ We recommend using fake data in both unit and integration tests as a best practi include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+2] -In addition, add a section for the BOM of all the testing support libraries: +In addition, add an entry for the BOM of all the testing support libraries: [source,xml,subs="attributes+"] .pom.xml diff --git a/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/maven-configuration.adoc b/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/maven-configuration.adoc index d2545ebf85..62bcec239f 100644 --- a/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/maven-configuration.adoc +++ b/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/maven-configuration.adoc @@ -4,7 +4,7 @@ include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+1] -In addition, add a section for the BOM of all the testing support libraries: +In addition, add an entry for the BOM of all the testing support libraries: [source,xml,subs="attributes+"] .pom.xml diff --git a/testing/h2console/adoc/modules/h2console/pages/about.adoc b/testing/h2console/adoc/modules/h2console/pages/about.adoc index f2655a41be..c600db020c 100644 --- a/testing/h2console/adoc/modules/h2console/pages/about.adoc +++ b/testing/h2console/adoc/modules/h2console/pages/about.adoc @@ -13,7 +13,7 @@ The menu appears under the "Prototyping" menu. include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+2] -In addition, add a section for the BOM of all the testing support libraries: +In addition, add an entry for the BOM of all the testing support libraries: [source,xml,subs="attributes+"] .pom.xml diff --git a/testing/hsqldbmgr/adoc/modules/hsqldbmgr/pages/about.adoc b/testing/hsqldbmgr/adoc/modules/hsqldbmgr/pages/about.adoc index 12a0b9f5c7..22d8e22d2b 100644 --- a/testing/hsqldbmgr/adoc/modules/hsqldbmgr/pages/about.adoc +++ b/testing/hsqldbmgr/adoc/modules/hsqldbmgr/pages/about.adoc @@ -15,7 +15,7 @@ NOTE: the HSQLDB Manager is a Swing application, so this can only be used in a l include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+2] -In addition, add a section for the BOM of all the testing support libraries: +In addition, add an entry for the BOM of all the testing support libraries: [source,xml,subs="attributes+"] .pom.xml diff --git a/testing/integtestsupport/adoc/modules/integtestsupport/pages/about.adoc b/testing/integtestsupport/adoc/modules/integtestsupport/pages/about.adoc index 22f9b03645..da7acc30c9 100644 --- a/testing/integtestsupport/adoc/modules/integtestsupport/pages/about.adoc +++ b/testing/integtestsupport/adoc/modules/integtestsupport/pages/about.adoc @@ -17,7 +17,7 @@ To explain further, let's walk through of the xref:docs:starters:simpleapp.adoc[ include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+2] -In addition, add a section for the BOM of all the testing support libraries: +In addition, add an entry for the BOM of all the testing support libraries: [source,xml,subs="attributes+"] .pom.xml diff --git a/testing/specsupport/adoc/modules/specsupport/pages/about.adoc b/testing/specsupport/adoc/modules/specsupport/pages/about.adoc index 7c641a2da1..408b2995d7 100644 --- a/testing/specsupport/adoc/modules/specsupport/pages/about.adoc +++ b/testing/specsupport/adoc/modules/specsupport/pages/about.adoc @@ -37,7 +37,7 @@ For example, if you have a step definition that maps to "given an uncompleted to include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+2] -In addition, add a section for the BOM of all the testing support libraries: +In addition, add an entry for the BOM of all the testing support libraries: [source,xml,subs="attributes+"] .pom.xml diff --git a/testing/unittestsupport/adoc/modules/unittestsupport/pages/about.adoc b/testing/unittestsupport/adoc/modules/unittestsupport/pages/about.adoc index cb1b9aed82..43f08d3438 100644 --- a/testing/unittestsupport/adoc/modules/unittestsupport/pages/about.adoc +++ b/testing/unittestsupport/adoc/modules/unittestsupport/pages/about.adoc @@ -9,7 +9,7 @@ Apache Causeway provides a number of helpers to help unit test your domain objec include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+2] -In addition, add a section for the BOM of all the testing support libraries: +In addition, add an entry for the BOM of all the testing support libraries: [source,xml,subs="attributes+"] .pom.xml
