Migration Notes

To remove boilerplate in your application’s pom.xml, three new maven "aggregator projects have been defined:

The HelloWorld and SimpleApp archetypes both make use of these new aggregators.

The <groupId> and <artifactId> of the Wicket viewer have been made consistent with other artifacts:

For example:

has been renamed to:

Domain services fall into three categories:

As described here, it is possible to override framework services so that the framework uses the replacement implementation. Previously this required explicitly setting either @DomainService#menuOrder() or @DomainServiceLayout#menuOrder().

In 1.15.0, the default value for menuOrder has been set to a value lower than that of the framework-provided implementations, and so will a custom implementation will always take precedence over the framework implementations without having to remember to also set menuOrder.

Of course, your application can still override menuOrder if it wishes. A small change (made in (ISIS-1688) is that if both are set, then the minimum value is used.

The metamodel validator has been extended with several new checks relating to JAXB view models:

... in other words, that the view model can be instantiated.

These checks are enabled by default but can be disabled with a configuration property if required.

ISIS-1613 improves the UI so that the framework does not repaint the entire page after a property edit or after invoking an action that returns the same object (this). The overall effect is a smoother user experience.

However, it also results in "WARN" messages being emitted by Apache Wicket. These are not harmful, but may pollute the log.

To remove them, add the following to logging.properties:

Bootstrapping the application can now be accomplished with less boilerplate, both for the regular webapp and in integration tests.

For more information, see the testing guide and reference guide for classes/methods/schema.

This ticket fixed a bug whereby - in the absence of an explicit @Property(optionality=…​) or @Nullable annotation, a view model’s properties would be defaulted as optional rather than mandatory.

Note also that this bug fix means that numeric properties (eg java.lang.Integer and java.lang.BigDecimal) will default to zero if the view model is instantiated using FactoryService#instantiate(…​), and dates (eg java.util.Date and org.jodatime.LocalDate) will default to the current date. This could cause your application to behave differently.

You should therefore inspect all properties of your view models and ensure that they are annotated as optional if required.

The configuration property isis.reflector.validator.jdoqlVariablesClause was incorrectly named variablesClause. This has now been corrected.

Any applications that used this configuration property should be updated.

In previous versions, if any domain service threw an exception in their initialization method (annotated @PostConstruct) then none of the remaining domain services would be initialized. Even though the failing service would cause an error to be logged during start-up, this could still manifest as the application starting (in a fashion) but then failing in unrelated areas later on.

As of this version, the framework now always calls ensures that all services are initialized, even if one or more of them throw an exception. The first exception encountered is then re-thrown (to preserve similar behaviour as possible to earlier versions).

The various (non-ASF) Isis Addons and Incode Catalog have also been combined into a single "Incode Platform".

While each module can still be consumed individually, the new platform versions consistently (a change in any one module will result in a re-release of all). This should make these modules easier to consume, and easier to maintain/develop.

All the modules remain open source, still licensed under the ASF v2.0 license.

As of this release, none of the groupIds or artifactIds have changed. They will be rationalized/made consistent in a future release; most probably to coincide with v2.0.0 of the framework.

This release defines a number of metamodel validations. These can be enabled or disabled using configuration properties:

The main feature in 1.13.0 is the InteractionContext domain service to represent an action invocation/property edit, with the re-positioning of CommandContext to represent the _intention to invoke an action/edit a property. You can read more about this design in the reference guide on domain services, in the commands and events section.

This refactoring completely overhauls the structure of the XML mementos passed to CommandService (to persist) and to BackgroundCommandService (to invoke persisted commands in the background). If you are using these services then ensure that there are no pending commands at the point at which you cut-over. If you have any code that makes assumptions on the format of the XML, it will also need to be rewritten. Note that the XML which is persisted henceforth is well-defined and any future changes to it will be backward compatible; see schema reference guide. In fact, there are three schema: for commands (cmd.xsd), inteactions (ixn.xsd) and for changes (chg.xsd). These replace the earlier aim.xsd schema (which was an amalgam of cmd.xsd and ixn.xsd).

The reworked CommandService now properly supports property edits in the exact same way as action invocations.

As a side-effect of this work, note also that:

The AuditingService SPI service has been deprecated, instead replaced by the AuditerService.

There can be more than one implementation of this new SPI, and a framework-provided implementation (AuditerServiceLogging) will log to a file. The (non-ASF) Incode Platform's audit module also implements the new SPI.

The PublishingService SPI service and its supporting EventSerializer domain service, have both deprecated, instead replaced by the PublisherService.

There can be more than one implementation of this new SPI, and a framework-provided implementation (PublisherServiceLogging) will log to a file. The (non-ASF) Incode Platform's publishmq module also implements the new SPI.

The new service also supports the notion of published property edits; the new @Property#publishing() annotation attribute can be used to specify. The ` isis.services.publish.properties` configuration property can be used to specify a fallback default for properties where the attribute is not set explicitly.

Conversely, neither the @Action#publishingPayloadFactory() nor the @DomainObject#publishingPayloadFactory() are supported by PublisherService; instead the consumers of the events are expected to callback for any additional information, eg using Resful Objects viewer.

The new configuration property isis.authentication.shiro.autoLogoutIfAlreadyAuthenticated (documented more fully in the security guide) is by default set to false, thereby disabling auto-logout behaviour that is believed to be the root cause of some exceptions thrown by the Restful Objects viewer during a race condition. The previous behaviour can be re-enabled by setting to true.

Apache Isis leverages Apache Wicket's rememberMe support which holds remembered user/passwords in an encrypted cookie.

If a hard-coded and publicly known value were to be used (as was the case prior to 1.13.0), then it would be possible for rememberMe user/password to be intercepted and decrypted, possibly compromising access. The isis.viewer.wicket.rememberMe.encryptionKey configuration property therefore allows a private key to be specified, baked into the application.

If no value is set then (for safety) a random UUID will be used as the encryption key. (The net effect of this fallback behaviour is that 'rememberMe' will work, but only until the webapp is restarted (after which the end-user will have to log in again).

Related, the isis.viewer.wicket.suppressRememberMe configuration property has been replaced by isis.viewer.wicket.rememberMe.suppress (though the old configuration property is still supported).

In previous releases the isis.reflector.facets configuration property could be used to specify a new implementation of the (internal) ProgrammingModel API. This configuration property is no longer supported. See the beyond the basics guide for an alternative broadly equivalent approach.

Apache Isis automatically injects domain services into other domain objects, supporting the @Inject annotation, also injection to set…​() setter methods and finally injection into inject…​() methods. This last method is now no longer supported by default. It can be re-enabled if necessary using the isis.services.injector.injectPrefix configuration property.

It is also possible to disable injection to set…​() methods (using the isis.services.injector.setPrefix configuration property), though this is enabled by default.

Disabling auto-wiring has a positive impact on bootstrap times, as well as standarding Apache Isis' conventions to be more in line with JEE.

The isis.reflector.facets.ignoreDeprecated configuration property indicates whether to continue to honour or to simply ignore any deprecated annotations and other semantics that make up the programming model.

This is disabled by default, in other words deprecated facets continue to be recognized. Be aware that enabling this setting could substantially alter the semantics of your application. To be safe, we recommend that you first run the application using isis.reflector.validator.allowDeprecated set to false; if any deprecated annotations etc. are in use, then the app will fail-fast and refuse to start.

The isis.services.applicationFeatures.init configuration property is used to control whether the ApplicationFeatureRepository domain service lazily or eagerly initializes itself based on the framework’s internal metamodel.

Previously this service eagerly initialized itself, causing the framework to have to traverse the domain object model graph for all types, noticeably increasing the bootstrap time. For 1.13.0 this service now initializes itself lazily. The previous behaviour (of eager initialization) can be re-enabled by setting this property to eager.

There are two sets of changes relating to integration tests.

In the web.xml, the "isis.viewers" context-param is now ignored. Instead the viewer_wicket.properties and viewer_restfulobjects.properties will both be loaded if present (but neither need be present).

The HasTransactionId mixin interface has subtly changed its meaning (and is now somewhat mis-named). Prior to 1.13.0, this identifier was the GUID of the Isis transaction in which the object was created. As of 1.13.0, this identifier actually is for the request/interaction (as per the new InteractionContext service) in which the object was created.

The following are new features so do not impact in themselves impact any migration effort, but you may wish to start taking advantage of once you have upgraded.

The major new feature in 1.12.0 is dynamic XML layouts, providing much enhanced support for custom layouts.

The new Xxx.layout.xml file is optional; without it domain objects will continue to be rendered as before, using metadata from annotations (@DomainObjectLayout, @PropertyLayout, @CollectionLayout, @ActionLayout, @MemberOrder and @MemberGroupLayout), and also from any Xxx.layout.json file that might already exist. There is therefore no requirement to move to the new more flexible XML-based layout.

If you do want to start using the new format, then you will find that 1.12.0 provides a mixin action (available in prototype mode only) called "download XML layout". This will allow you to download the current layout file for the object being rendered. This can then be saved alongside the class' Java source file. Once a Xxx.layout.xml file is present, any existing Xxx.layout.json file will be ignored; any annotations though will continue to be honoured.

If you wish to migrate all your domain objects to use XML layouts, this can be done using the "download layouts (XML)" (on the "Prototyping" menu), as a single zip file. This can then be unzipped into the src/main/java directory.

(As mentioned above), 1.12.0 provides a number of new mixin actions and properties:

These are in addition to the download JDO metadata mixin action (prototype mode) provided in earlier versions of the framework.

The properties are grouped in a "metadata" fieldset, and the mixin actions associated with that fieldset. If the domain object is a view model rather than an entity (that is, has no id or version) then the actions will instead be rendered as top-level actions.

Most of these mixin object members are visible only in prototype mode, though some are visible in production mode and so potentially visible to end-users. If you wish to suppress these members from the view, you can either use security, or alternatively you can write subscribers to veto the visibility of these members by subscribing to their respective domain events.

All @XmlRootElement view models are now implicitly editable. Therefore any view models that should be read-only should have editing attribute disabled using @DomainObject#editing() (or use a subscriber to veto editability).

The DomainObjectContainerdomain service has been deprecated, with its methods moved to a new set of more fine-grained domain services, such as RepositoryService and MessageService.

The DomainObjectContainer service will continue to be supported until Apache Isis v2.0.0, but in the meantime, consider changing existing application code to use these new domain services.

Please note that when migrating from _rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc#_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api[DomainObjectContainer#persist()] to RepositoryService#persist(), no exception will be thrown if the Domain Object is already persisted, so the behavior of RepositoryService#persist() will be the same as that of DomainObjectContainer#persistIfNotAlready().

The self-host profile has been removed from the SimpleApp archetype. Instead, run the application using either the org.apache.isis.WebServer main class, or mvn jetty:run, or build the WAR and deploy to a servlet container such as Tomcat.

The Apache Isis Wicket viewer uses a modal dialog for action parameters. Before this feature was implemented (prior to 1.4.0), action parameters were rendered on their own page. This property was provided to re-enable the old behaviour.

The property has now been removed and this feature removed; actions parameters are always now always shown in a modal dialog.

The new SwaggerService allows Swagger spec files to be generated from the Apache Isis metamodel. These can be downloaded directly through the SwaggerResource (mapped to /restful/swagger/public and /restful/swagger/private) as well as from the Wicket UI through the SwaggerServiceMenu.

In addition, the SimpleApp archetype now bundles Swagger UI, which documents the main features of the REST API and allows it to be explored.

To enable this in your application, first update the web.xml:

There is also an HTML page to load the Swagger UI itself; this resides in src/main/webapp/swagger-ui/index.html. Copy the file from Apache Isis' repo, or from the app generated by the SimpleApp archetype.

The text of the simple app’s about/index.html has also changed (the <li> for the /restful URL has been replaced with a /swagger-ui URL). If you use this file, then update it.

If your application is bootstrapped using an AppManifest (recommended; here) then the default implementation of the SwaggerService will automatically be discovered and registered. However, if you are still using the older isis.properties configuration file to explicitly register services then you will need to add in this service.

The new RoutingService SPI service provides a plugin point to the Wicket viewer so that a different object than that returned from an action invocation can be rendered.

The framework provides a default implementation of this service that will - instead of a void or a null result - render the home page (as per the @HomePage annotation) if there is one. This is therefore a subtle change in the UI. If you wish to retain the original behaviour (to return the "no results" page instead), then you should implement your own no-op implementation of this service:

The Wicket viewer (its labels, buttons, messages etc) can now be internationalized using the TranslationService.

To enable this, new msgIds and corresponding translations must be added to the translations.po file. Full details of these msgIds can be found in i18n section of the "beyond the basics" guide.

If no translations are available, then the fallback is to use the previous mechanism, ie Wicket’s original resource bundles. This feature can therefore be considered as optional.

In earlier releases the Wicket viewer defined its own parent pom.xml for dependency management and its dependencies and to declare the various submodules that make up the viewer. This pom.xml has now been incorporated into the parent pom.xml for the Core framework.

Therefore, in the parent pom.xml of your own domain applications, remove:

One possible issue is that (as per ISIS-830) the EventBusService is now initialized as one of the first domain services; this is to ensure that any object lifecycle events caused by domain services initializing themselves can be posted on the event bus for subscribers. The typical case for such lifecycle events to occur is from domain services that seed reference data; one such example can be found in the (non-ASF) Incode Platform's security module.

In previous releases, the ordering of initialization for the EventBusService was undefined (but would typically be towards the "end" of the list of services. What this meant in practice is that it generally didn’t matter whether (domain service) subscribers were initialized before or after seed services.

Now, though, because the EventBusService is initialized early on, it proactively checks that all subscribers have been registered before any event posts occur (so that no events get missed). If any subscriber attempts to register after at least one event has been posted, then the service will fail fast and the framework will not start. The error looks something like:

To ensure that subscriber domain services are initialized before "seed" domain services, the @DomainServiceLayout#menuOrder() attribute can be used. Normally this attribute is just used to order UI-visible services on the menu bars, but it also is used internally to sequence the internal list of services being initialized.

Alternatively, you can disable this checking within the EventBusService using:

If you do that, be aware that not all subscribers may not receive some events generated by other domain services.

For more details, see the EventBusService man page.

The domain event superclasses now provide no-arg versions; the framework will use new (non-API) setters to initialize.

This means that domain events can be substantially simplified, eg from this:

to just this:

The way that the Isis Maven plugin is configured has changed slightly; check out its documentation for full details.

Apache Isis 1.9.0 updates to DataNucleus 4.0.0, which requires some changes (simplifications) to the Maven configuration.

If you starting a new app then you can start from the SimpleApp archetype; its Maven configuration has been updated.

If you have an existing Apache Isis app that you want to upgrade, then you’ll need to make some changes.

Apache Isis automatically scans for certain classes on the classpath in order to configure itself. Specifically these are:

For the last of these we have tightened up the validation, to ensure that each package specified in the isis.persistor.datanucleus.RegisterEntities.packagePrefix key does indeed include at least one annotated entity. This should include any domain classes for addon modules.

For example, the (non-ASF) Isis addons' todoapp's configuration now reads:

If you fail to do specify all packages things may still work, however DataNucleus will build up its metamodel lazily. This can call issues: we’ve seen malformed SQL being submitted when DN wasn’t aware of subclasses of a superclass, and we’ve also seen deadlocks when running against HSQLDB as it attempts to perform a DDL statement intermixed with DML statements.

Apache Isis 1.9.0 is the first version to support Java 8. You can continue to use Java 7, but if you want to move to Java 8 then there are several small changes to be made.

The ExceptionRecognizerCompositeForJdoObjectStore service (an implementation of the ExceptionRecognizer SPI) recognizes certain expected exceptions thrown by the JDO objectstore (for example, violations of uniqueness) and converts them into meaningful messages for the end-user.

Prior to 1.9.0 this implementation was not annotated with @DomainService and thus needed to be explicitly registered in isis.properties.

In 1.9.0 the service has been annotated with @DomainService meaning that:

If you fail to do this you will get an exception to the effect of duplicate service Ids being registered.

Now that the ExceptionRecognizerCompositeForJdoObjectStore no longer needs to be explicitly registered, you might (very rarely) require the opposite situation, namely to disable the service. As this can’t be done by just removing it from isis.properties, you instead can set a new configuration property isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable:

If you did not register this service directly but instead registered a subclass of this service, then you should refactor your code so that your implementation is in a separate service, eg by subclassing ExceptionRecognizerComposite. You should probably also annotate with @DomainService.

The FixtureScriptsSpecificationProvider SPI service is an alternative to subclassing the FixtureScripts domain service. The logic that would normally be in the subclass moves to the provider service instead, and the framework instantiates a fallback default instance, FixtureScriptsDefault.

This new design is optional; if you continue to provide your own subclass then everything will continue as before. However the new design is more flexible and involves less code.

See user guide for further discussion.

As discussed in SimpleApp archetype and elsewhere, the org.apache.isis.WebServer provides the ability to run your app from an embedded jetty. This is great for prototyping. The class resides in the isis-core-webserver module, which also has the dependency on jetty.

In 1.9.0 we have upgraded the jetty dependency to use Jetty 9.2.0 (org.eclipse.jetty.aggregate:jetty-all:9.2.11.v20150529, to be precise). One consequence of this is that the packaged WAR file will not boot on Tomcat.

One fix is to simply remove the isis-core-webserver module as a dependency of your webapp module, however this will prevent you from using our org.apache.isis.WebServer launcher. That’s not necessarily a bad thing; you could continue to use jetty:run, say. But it might be a change to your development workflow that you don’t want.

Alternatively you can change your webapp’s pom.xml so that when the war is packaged up it excludes the jetty files. To do this, locate the maven-war-plugin module definition (under <build>/<plugins> and add to its <configuration> section:

For future projects the SimpleApp archetype has been updated with this change.

Apache Isis 1.9.0 provides a simplified programmatic way of bootstrapping the application, that also unifies bootstrapping for integration tests.

For now this new bootstrapping mechanism is optional (you don’t have to change your code), but it may become mandatory in future releases. The SimpleApp archetype has been updated to use this new mechanism.

The instructions below assume that your application is structured as per the simpleapp archetype. Adjust accordingly.

The following modules are no longer released as part of Apache Isis core and have moved to Isis Addons (or in one case, back into Apache Isis core).

Minor changes are required to pom.xml files and (in some cases) to isis.properties config file.

In one or two exceptional cases it may be necessary to fix up import statements if there are reference to changed package/class names in code (most likely any dependency on the devutils module or settings module).

As per ISIS-802, the ProfileStore component has been removed. This functionality was not surfaced or available in the Wicket or Restful Objects viewers, so there is no meaningful loss of functionality. However, Maven pom.xml files will require updating:

Specifically, remove any dependencies on org.apache.isis:isis-core-profilestore:

A number of corresponding classes/interfaces have also been removed from the Apache Isis applib:

It is highly unlikely that any existing production code references these classes.