Domain Services

The SPI defined by this service is:

In versions prior to v1.12.0, this interface resided in a different package, internal to the Restful Objects viewer, and defined a slightly different signature that used an internal enum:

No default implementations are provided by Apache Isis framework itself.

However, the (non-ASF) Isis addons' todoapp includes a sample implementation to convert its ToDoItem entity into a (JAXB annotated) ToDoItemDto. The source code is:

This service is a companion to the default implementation of the ContentNegotiationService.

The SPI defined by this service is:

If isConfigured() returns false then it is not valid to call send(…​) (and doing so will result in an IllegalStateException being thrown.

The framework provides a default implementation, o.a.i.core.runtime.services.userreg.EmailNotificationServiceDefault that constructs the emails to send.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' default implementation of EmailNotificationService service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

As noted elsewhere, the default implementation of this service uses EmailService. This service has no specific configuration properties but does require that the EmailService has been configured.

Conversely, this service is used by (Isis' default implementation of) UserRegistrationService.

The SPI defined by this service is:

where ErrorDetails provided to the service is:

and Ticket (returned by the service) has the constructor:

The (non-ASF) Isis addons' kitchensink app provides an example implementation:

which is rendered as:

There is no default implementation of this service. To register your own implementation (and assuming that an AppManifest is being used to bootstrap the app), then just ensure that the implementation is on the classpath and the module containing the implementation is returned in AppManifest#getModules().

The SPI defined by this service is:

The categories are:

In essence, if an exception is recognized then it is also categorized. This lets the viewer act accordingly. For example, if an exception is raised from the loading of an individual object, then this is passed by the registered ExceptionRecognizers. If any of these recognize the exception as representing a not-found exception, then an Apache Isis ObjectNotFoundException is raised. Both the viewers interprets this correctly (the Wicket viewer as a suitable error page, the Restful Objects viewer as a 404 status return code).

If the implementation recognizes the exception then it returns a user-friendly message to be rendered (by the viewer) back to the user; otherwise it returns null. There is no need for the implementation to check for exception causes; the casual chain is unwrapped by Apache Isis core and each exception in the chain will also be passed through to the recognizer (from most specific to least). The recognizer implementation can therefore be as fine-grained or as coarse-grained as it wishes.

The framework provides two default implementations:

If you want to recognize and handle additional exceptions (for example to capture error messages specific to the JDBC driver you might be using), then create a fine-grained implementation of ExceptionRecognizer2 for the particular error message (there are some convenience implementations of the interface that you can subclass from if required) and register in isis.properties.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then the default implementations provided by the framework (DomainObjectContainerDefault and ExceptionRecognizerCompositeForJdoObjectStore) will be registered.

In addition, you can register any further exception recognizers in isis.properties:

If the JDO exception recognizers are not required (rather unlikely), then they can be disabled en-masse using the configuration property isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable.

The SPI defined by this service is:

The framework provides a default implementation of this service, namely GridLoaderServiceDefault. This implementation loads the grid from its serialized representation as a .layout.xml file, loaded from the classpath.

For example, the layout for a domain class com.mycompany.myapp.Customer would be loaded from com/mycompany/myapp/Customer.layout.xml.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app), then the default implementation of GridLoaderService is automatically registered and injected, and no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

This service is used by GridService.

The SPI defined by this service is:

The first four methods just delegate to the corresponding methods in GridSystemService, while the last four delegate to the corresponding method in GridSystemService. The service inspects the Grid's concrete class to determine which actual GridSystemService instance to delegate to.

The framework provides a default implementation of this service, namely GridServiceDefault.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app), then the default implementation of GridLoaderService is automatically registered and injected, and no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide). That said, there should be little reason to use a different implementation; if behaviour does need to be changed, it would also be possible to replace the implementation of either the GridLoaderService or the GridSystemService.

This service calls GridLoaderService and GridSystemService.

This service is called by LayoutService, exposed in the UI through LayoutServiceMenu (to download the layout XML as a zip file for all domain objects) and the downloadLayoutXml() mixin (to download the layout XML for a single domain object).

The SPI defined by this service is:

The framework provides GridSystemServiceBS3, an implementation that encodes the bootstrap3 grid system. (The framework also provides Wicket viewer components that are capable of interpreting and rendering this metadata).

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app), then the Bootstrap3 default implementation of GridSystemService is automatically registered and injected, and no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

This service is used by GridService.

The SPI of HintStore is:

The core framework provides a default implementation of this service (org.apache.isis.viewer.wicket.viewer.services.HintStoreUsingWicketSession).

Hints are stored against the Bookmark of a domain object, essentially the identifier of the domain object. For a domain entity this identifier is fixed and unchanging but for a view models the identifier changes each time the view model’s state changes (the identifier is basically a digest of the object’s state). This means that any hints stored against the view model’s bookmark are in effect lost as soon as the view model is modified.

To address this issue the HintStore provides an optional interface that the view model can implement, the intent of which is to expose the "logical" identity of the view model. This interface is:

For example, suppose that there’s a view model that wraps a Customer and its Orders For this the Customer represents the logical identity. This view model might therefore be implemented as follows:

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of HintStore service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The Wicket viewer exposes the "clear hints" mixin action that is for use by end-users of the application to clear any UI hints that have accumulated for a domain object.

The SPI defined by this service is:

This is notionally request-scoped, returning the Locale of the current user; not that of the server. (Note that the implementation is not required to actually be @RequestScoped, however).

Isis' Wicket viewer provides an implementation of this service (LocaleProviderWicket) which leverages Apache Wicket APIs.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app), and that the Wicket viewer is being used, then an implementation of LocaleProvider is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

This service works in conjunction with TranslationService and TranslationsResolver in order to provide i18n support.

The SPI defined by this service is:

The framework provides a default implementation - RoutingServiceDefault - which will always return the original object provided, or the home page if a null or void was provided. It uses the HomePageProviderService.

There can be multiple implementations of RoutingService registered. These are checked in turn (chain of responsibility pattern), ordered according to @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide). The route from the first service that returns true from its canRoute(…​) method will be used.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' default implementation of RoutingService service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

The default implementation of this service uses the HomePageProviderService.

The SPI defined by this service is:

The framework provides an implementation, SessionLoggingService.Stderr that just prints out to standard error. This is not registered by default, but can be easily registered manually using AppManifestAbstract.Builder#withAdditionalServices(…​).

The (non-ASF) Incode Platform's sessionlogger module provides an implementation that logs each session as a JDO entity.

The SPI defined by this service is:

There can be multiple implementations of TableColumnOrderService registered, ordered as per @DomainServiceLayout#menuOrder(). The ordering provided by the first such service that returns a non-null value will be used. If all provided implementations return null, then the framework will fallback to a default implementation.

The framework provides a fallback implementation of this service, namely TableColumnOrderService.Default.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app), then the default implementation of TableColumnOrderService is automatically registered and injected, and no further configuration is required.

The SPI defined by this service is:

If in read mode, then the translations are expected to be present.

If in write mode, then the implementation is saving translation keys, and will always return the untranslated translation.

The Apache Isis framework provides a default implementation (TranslationServicePo) that uses the GNU .pot and .po files for translations. It relies on the LocaleProvider service (to return the Locale of the current user) and also the TranslationsResolver service (to read existing translations).

The framework also provides a supporting TranslationServicePoMenu provides menu items under the "Prototyping" secondary menu for controlling this service and downloading .pot files for translation.

For more details on the implementation, see i18n support.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of TranslationService service (along with the supporting menu service) are automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

If the menu items are not required then these can be suppressed either using security or by implementing a vetoing subscriber.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The TranslationServicePoMenu menu exposes the TranslationServicePo service’s toPot() method so that all translations can be downloaded as a single file.

This service works in conjunction with LocaleProvider and TranslationsResolver in order to provide i18n support.

The SPI defined by this service is:

Isis' Wicket viewer provides an implementation of this service (TranslationsResolverWicket) which leverages Apache Wicket APIs. This searches for translation files in the standard WEB-INF/ directory.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app), _and that the Wicket viewer is being used, then an implementation of TranslationsResolver is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

This service works in conjunction with LocaleProvider and TranslationService in order to provide i18n support.

The SPI defined by the service is:

The framework provides a default implementation (UrlEncodingServiceUsingBaseEncoding) that simply converts the string using base-64 encoding and UTF-8 character set. As already noted, be aware that the maximum length of a URL should not exceed 2083 characters. For large view models, there’s the possibility that this limit could be exceeded; in such cases register an alternative implementation of this service.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The SPI defined by the service is:

If the method returns null or throws an exception then the framework will default to using the current user name.

In the future this API may be expanded; one obvious possibility is to return a profile photo or avatar URL.

There is no default implementation of this service provided by the core Apache Isis framework.

An example implementation can be found in the (non-ASF) Isis addons' todoapp:

The API defined by the service is:

The default implementation is provided by o.a.i.v.ro.rendering.service.acceptheader.AcceptHeaderServiceForRest.

The intended use of this service is where there are multiple concurrent versions of a REST API, for backward compatibility of existing clients. The AcceptHeaderService allows the responsibility for content negotiation (determining which version of the REST API is to be used) to be performed by logic in the domain objects themselves.

The diagram below illustrated this:

The REST request is submitted to a domain service with a nature of VIEW_REST_ONLY (MyRestApi in the diagram). This uses the AcceptHeaderService to obtain the values of the HTTP Accept header. Based on this it delegates to the appropriate underlying domain service (with a nature of DOMAIN so that they are not exposed in the REST API at all).

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' default implementation of AcceptHeaderService class is automatically registered (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The API defined by the service is:

For actions that are void or that return null, Apache Isis will return to the list once executed. But for bulk actions that are non-void, Apache Isis will render the returned object/value from the last object invoked (and simply discards the object/value of all actions except the last).

One idiom is for the domain objects to also use the Scratchpad service to share information, for example to aggregate values. The ActionInvocationContext#isLast() method can then be used to determine if all the information has been gathered, and then do something with it (eg derive variance across a range of values, render a graph etc).

More prosaically, the ActionInvocationContext can be used to ensure that the action behaves appropriately depending on how it has been invoked (on a single object and/or a collection) whether it is called in bulk mode or regular mode. Here’s a snippet of code from the bulk action in the Isis addon example todoapp (not ASF):

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' default implementation of ActionInvocationContext class is automatically registered (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The ActionInvocationContext class also has a couple of static factory methods intended to support unit testing:

The API is:

The default implementation is provided by core (o.a.i.core.runtime.services.background.BackgroundServiceDefault).

Using the service is very straight-forward; wrap the target domain object using BackgroundService#execute(…​) and invoke the method on the object returned by that method.

For example:

This will create a bunch of background commands executing the submitInvoice() action for each of the customers returned from the customer repository.

The action method invoked must be part of the Apache Isis metamodel, which is to say it must be public, accept only scalar arguments, and must not be annotated with @Programmatic or @Ignore. However, it may be annotated with @Action#hidden() or @ActionLayout#hidden() and it will still be invoked.

In fact, when invoked by the background service, no business rules (hidden, disabled, validation) are enforced; the action method must take responsibility for performing appropriate validation and error checking.

For the end-user, executing an action that delegates work off to the BackgroundService raises the problem of how does the user know the work is complete?

One option is for the background jobs to take responsibility to notify the user themselves. In the above example, this would be the submitInvoice() method called upon each customer. One could imagine more complex designs where only the final command executed notifies the user.

However, an alternative is to rely on the fact that the BackgroundService will automatically hint that the Command representing the original interaction (to submitCustomerInvoices() in the example above) should be persisted. This will be available if the related CommandContext and CommandService domain services are configured, and the CommandService supports persistent commands. Note that (non-ASF) Incode Platform's command module does indeed provide such an implementation of CommandService (as well as of the required BackgroundCommandService).

Thus, the original action can run a query to obtain it corresponding Command, and return this to the user. The upshot is that the child Commands created by the BackgroundService will then be associated with Command for the original action.

We could if we wanted write the above example as follows:

The user would be returned a domain object representing their action invocation.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of BackgroundService is automatically registered (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

This service is closely related to the CommandContext and also that service’s supporting CommandService service.

The CommandContext service is responsible for providing a parent Command with which the background Commands can then be associated as children, while the CommandService is responsible for persisting those parent Command`s. The latter is analogous to the way in which the `BackgroundCommandService persists the child background `Command`s.

The implementations of CommandService and BackgroundCommandService go together; typically both parent Command`s and child background `Command`s will be persisted in the same way. The (non-ASF) Incode Platform's command module provides implementations of both (see `CommandService and BackgroundCommandService).

The CommandDtoServiceInternal is used to obtain a memento of the command such that it can be persisted. (In earlier versions, MementoService was used for this purpose).

The BackgroundCommandExecution (in isis-core) is an abstract template class provided by isis-core that defines an abstract hook method to obtain background `Command`s to be executed:

The developer is required to implement this hook method in a subclass.

The last part of the puzzle is to actually run the (appropriate implementation of) BackgroundCommandExecution). This could be run in a batch job overnight, or run continually by, say, the Quartz scheduler or by Apache Camel. This section looks at configuring Quartz.

If using (non-ASF) Incode Platform's command module, then note that this already provides a suitable concrete implementation, namely org.isisaddons.module.command.dom.BackgroundCommandExecutionFromBackgroundCommandServiceJdo. We therefore just need to schedule this to run as a Quartz job.

First, we need to define a Quartz job, for example:

where AbstractIsisQuartzJob is in turn the following boilerplate:

This job can then be configured to run using Quartz' quartz-config.xml file:

The remaining two pieces of configuration are the quartz.properties file:

and the entry in web.xml for the Quartz servlet:

The screencast provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.

The CommandContext request-scoped service defines the following very simple API:

This class (o.a.i.applib.services.CommandContext) is also the default implementation. Under normal circumstances there shouldn’t be any need to replace this implementation with another.

The Command type referenced above is in fact an interface, defined as:

The typical way to indicate that an action should be treated as a command is to annotate it with the @Action#command() annotation.

For example:

The @Action#command() annotation can also be used to specify whether the command should be performed in the background, for example:

When a background command is invoked, the user is returned the command object itself (to provide a handle to the command being invoked).

This requires that an implementation of CommandService that persists the commands (such as the (non-ASF) Incode Platform's command module’s CommandService) is configured. It also requires that a scheduler is configured to execute the background commands, see BackgroundCommandService).

Typically domain objects will have little need to interact with the CommandContext and Command directly; what is more useful is that these are persisted in support of the various use cases identified above.

One case however where a domain object might want to obtain the Command is to determine whether it has been invoked in the foreground, or in the background. It can do this using the getExecutedIn() method:

Although not often needed, this then allows the domain object to access the Command object through the CommandContext service. To expand th above example:

If run in the background, it might then notify the user (eg by email) if all work is done.

This leads us onto a related point, distinguishing the current effective user vs the originating "real" user. When running in the foreground, the current user can be obtained from the UserService, using:

If running in the background, however, then the current user will be the credentials of the background process, for example as run by a Quartz scheduler job.

The domain object can still obtain the original ("effective") user that caused the job to be created, using:

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of CommandContext service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The CommandContext service is very similar in nature to the InteactionContext, in that the Command object accessed through it is very similar to the Interaction object obtained from the InteractionContext. The principle distinction is that while Command represents the intention to invoke an action or edit a property, the Interaction (and contained Executions) represents the actual execution.

Most of the time a Command will be followed directly by its corresponding Interaction. However, if the Command is annotated to run in the background (using @Action#commandExecuteIn(), or is explicitly created through the BackgroundService, then the actual interaction/execution is deferred until some other mechanism invokes the command (eg as described here). The persistence of background commands requires a configured BackgroundCommandService) to actually persist such commands for execution.

Commands - even if executed in the foreground - can also be persisted by way of the CommandService. Implementations of CommandService and BackgroundCommandService are intended to go together, so that child Commands persistent (to be executed in the background) can be associated with their parent Commands (executed in the foreground, with the background Command created explicitly through the BackgroundService).

The public API of the service consists of several related classes:

The Execution class itself is abstract; there are two subclasses, ActionInvocation and PropertyEdit.

Typically domain objects will have little need to interact with the InteractionContext and Interaction directly. The services are used within the framework however, primarily to support the PublisherService SPI, and to emit domain events over the EventBusService.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' default implementation of InteractionContext class is automatically registered (it is annotated with @DomainService) so no further configuration is required.

The framework also takes responsibility for instantiating the Interaction, using the FactoryService.

This service is very similar in nature to CommandContext, in that the Interaction object accessed through it is very similar to the Command object obtained from the CommandContext. The principle distinction is that while Command represents the intention to invoke an action or edit a property, the Interaction (and contained Executions) represents the actual execution.

Most of the time a Command will be followed directly by its corresponding Interaction. However, if the Command is annotated to run in the background (using @Action#commandExecuteIn(), or is explicitly created through the BackgroundService, then the actual interaction/execution is deferred until some other mechanism invokes the command (eg as described here).

The API of MessageService is:

For example:

The core framework provides a default implementation of this service, o.a.i.core.runtime.services.message.MessageServiceDefault.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of MessageService service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The API of SessionManagementService is:

Normally, the framework will automatically start a session and then a transaction before each user interaction (action invocation or property modification), and wil then commit that transaction and close the session after the interaction has completed. If the interaction throws an exception then the transaction is aborted.

The nextSession() method allows a domain object to commit the transaction, close the session, then open a new session and start a new transaction.

The core framework provides a default implementation of this service (o.a.i.core.runtime.services.xactn.SessionManagementServiceDefault).

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of SessionManagementService service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The API of TitleService is:

By way of example, here’s some code based on a system for managing government benefits:

In this example, whatever the title of a Customer, it is reused within the title of that customer’s QualifiedAdult object.

The core framework provides a default implementation of this service (o.a.i.core.metamodel.services.title.TitleServiceDefault).

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of TitleService service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The API of TransactionService2 is:

Here TransactionState is an enum defined as:

The nextTransaction() is also used by the Wicket viewer's support for bulk actions; each action is invoked in its own transaction.

The Transaction object - as obtained by currentTransaction() method, above - is a minimal wrapper around the underlying database transaction. Its API is:

The core framework provides a default implementation of this service, o.a.i.core.metamodel.services.xactn.TransactionServiceDefault.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of TransactionService service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The API provided by the service is:

The service works by returning a "wrapper" around a supplied domain object (a javassist proxy), and it is this wrapper that ensures that the hide/disable/validate rules implies by the Apache Isis programming model are enforced. The wrapper can be interacted with as follows:

Calling any of the above methods may result in a (subclass of) InteractionException if the object disallows it. For example, if a property is annotated with @Hidden then a HiddenException will be thrown. Similarly if an action has a validateXxx() method and the supplied arguments are invalid then an InvalidException will be thrown.

In addition, the following methods may also be called:

An exception will be thrown if any other methods are thrown.

The caller will typically obtain the target object (eg from some repository) and then use the injected WrapperFactory to wrap it before interacting with it.

For example:

The WrapperFactory also provides a listener API to allow other services to listen in on interactions.

The original intent of this API was to enable test transcripts to be captured (in a BDD-like fashion) from integration tests. No such feature has yet been implemented however. Also, the capabilities have by and large been superceded by Apache Isis' support for domain events. We may therefore deprecate this API in the future.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of WrapperFactory service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The SPI of the BackgroundCommandService is:

The API of ActionInvocationMemento in turn is:

The BackgroundCommandExecution (in isis-core) is an abstract template class for headless access, that defines an abstract hook method to obtain background `Command`s to be executed:

The developer is required to implement this hook method in a subclass.

The (non-ASF) Incode Platform's command module provides an implementation (org.isisaddons.module.command.dom.BackgroundCommandServiceJdo) that persists Commands using the JDO/DataNucleus object store. It further provides a number of supporting services:

The module also provides a concrete subclass of BackgroundCommandExecution that knows how to query for persisted (background) `Command`s such that they can be executed by a scheduler.

Background commands can be created either declaratively or imperatively.

The declarative approach involves annotating an action using @Action#command() with @Action#commandExecuteIn=CommandExecuteIn.BACKGROUND.

The imperative approach involves explicitly calling the BackgroundService from within domain object’s action.

The (non-ASF) Incode Platform's command module provides an implementation of this service (BackgroundCommandService), and also provides a number of related domain services (BackgroundCommandServiceJdo, BackgroundCommandJdoRepository and BackgroundCommandServiceJdoContributions). This module also provides service implementations of the CommandService.

Assuming that an AppManifest is being used to bootstrap the app) then this can be activated by updating the pom.xml and updating the AppManifest#getModules() method.

If contributions are not required in the UI, these can be suppressed either using security or by implementing a vetoing subscriber.

As discussed above, this service supports the BackgroundService , persisting `Command`s such that they can be executed in the background.

There is also a tie-up with the CommandContext and its supporting CommandService domain service. The CommandContext service is responsible for providing a parent Command with which the background Command`s can then be associated as children, while the `CommandService is responsible for persisting those parent Command`s (analogous to the way in which the `BackgroundCommandService persists the child background Command`s). The `BackgroundCommandService ensures that these background Command`s are associated with the parent "foreground" `Command.

What that means is that the implementations of CommandService and BackgroundCommandService go together, hence both implemented in the (non-ASF) Incode Platform's command module.).

The screencast below provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.

The CommandService service defines the following very simple API:

The (non-ASF) Incode Platform's command module provides an implementation (org.isisaddons.module.command.dom.CommandServiceJdo) that persists Commands using the JDO/DataNucleus object store. It further provides a number of supporting services:

The typical way to indicate that an action should be reified into a Command is by annotating the action using @Action#command().

The (non-ASF) Incode Platform's command module provides an implementation of this service (CommandService), and also provides a number of related domain services (CommandJdoRepository and CommandServiceJdoContributions). This module also provides service implementations of the BackgroundCommandService.

Assuming that an AppManifest is being used to bootstrap the app) then this can be activated by updating the pom.xml and updating the AppManifest#getModules() method.

If contributions are not required in the UI, these can be suppressed either using security or by implementing a vetoing subscriber.

As discussed above, this service supports the CommandContext, providing the ability for Command objects to be persisted. This is closely related to the BackgroundCommandServicethat allows the BackgroundService to schedule commands for background/asynchronous execution.

The implementations of CommandService and BackgroundCommandService are intended to go together, so that persistent parent `Command`s can be associated with their child background `Command`s.

The services provided by this module combines very well with the AuditingService. The CommandService captures the _cause of an interaction (an action was invoked, a property was edited), while the AuditingService3 captures the effect of that interaction in terms of changed state.

You may also want to configure the PublishingService.

All three of these services collaborate implicitly by way of the HasTransactionId interface.

The SPI defined by HomePageProviderService is:

The default implementation is provided by o.a.i.core.runtime.services.homepage.HomePageProviderServiceDefault.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of HomePageProviderService is automatically registered (it is annotated with @DomainService) so no further configuration is required.

The API defined by ClockService is:

This class (o.a.i.applib.services.clock.ClockService) is also the default implementation. The time provided by this default implementation is based on the system clock.

The default ClockService implementation in fact simply delegates to another class defined in the API, namely the o.a.i.applib.clock.Clock, an abstract singleton class. It is not recommended that your code use the Clock directly, but you should understand how this all works:

The FixtureClock will behave as the system clock, unless its is explicitly set using FixtureClock#setDate(…​) or FixtureClock#setTime(…​) and so forth.

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of ClockService is automatically registered (it is annotated with @DomainService) so no further configuration is required.

If you want to use a different implementation of Clock, eg delegating to NNTP, then do not register directly, but instead subclass from o.a.i.applib.clock.Clock singleton (as described in the section above).

The API of ConfigurationService is:

For example, here’s a fictitious service that might wrap Twitter4J. say:

The core framework provides a default implementation of this service (o.a.i.core.runtime.services.config.ConfigurationServiceDefault).

Assuming that the configuration-and-annotation services installer is configured (implicit if using the AppManifest to bootstrap the app) then Apache Isis' core implementation of ConfigurationService service is automatically registered and injected (it is annotated with @DomainService) so no further configuration is required.

To use an alternative implementation, use @DomainServiceLayout#menuOrder() (as explained in the introduction to this guide).

The ConfigurationServiceMenu exposes the allConfigurationProperties action in the user interface.

The sections below discuss the functions provided by the service, broken out into categories.