From v1.16.x to 2.0.0-M1

Meta annotations

Most of the Apache Isis annotations can now be associated with meta-annotations. Coupled with the fact that DataNucleus 5.x also supports meta annotations, this therefore allows a degree of reuse.

For example, instead of:

@Column(length=30)
@Property(regex=...)
@Getter @Setter
private String name;

public Customer updateName(
    @Parameter(maxLength=30, regex=...)
    String name ) {
    setName(name);
}

we can instead define a @Name annotation:

@Column(length=30)
@Property(regex=...)
@Parameter(maxLength=30, regex=...)
public @interface @Name {}

and then use this annotation:

@Name
@Getter @Setter
private String name;

public Customer updateName(
    @Name
    String name ) {
    setName(name);
}

The full list of Apache Isis annotations that can be used in meta-annotations is shown in the table below.

Table 1. Apache Isis annotations that can be used in meta-annotations
Domain layer UI layer

domain service

domain object

Action

action parameter

property

collection

Updated annotations

Prior to v2.0.0, several annotation attributes were defined as booleans. In order to support meta annotations, these have been replaced by enums which also include a NOT_SPECIFIED value. Other enums have been extended (where necessary) to also have a NOT_SPECIFIED value. In all cases NOT_SPECIFIED is the new default.

Table 2. Updated annotations
Annotation Updated attribute Nature of change

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Default changed from NOWHERE to NOT_SPECIFIED.

Default changed from OBJECT_ONLY to NOT_SPECIFIED.

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Default changed from NO_RESTRICTIONS to NOT_SPECIFIED.

Default changed from NON_IDEMPOTENT to NOT_SPECIFIED.

Default changed from NEVER to NOT_SPECIFIED.

Default changed from AS_BOTH to NOT_SPECIFIED.

Default changed from BELOW to NOT_SPECIFIED.

Default changed from NOWHERE to NOT_SPECIFIED.

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Replaces bounded, taking values of BOUNDED, UNBOUNDED and NOT_SPECIFIED. Defaults to NOT_SPECIFIED.

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Default changed from NEVER to NOT_SPECIFIED.

Default changed from DEFAULT to NOT_SPECIFIED.

Default changed from DEFAULT to NOT_SPECIFIED.

Replaces renderedAsDayBefore, taking values of AS_DAY, AS_DAY_BEFORE or NOT_SPECIFIED. Defaults to NOT_SPECIFIED.

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Default changed from NOWHERE to NOT_SPECIFIED.

Replaces notPersisted, taking values of INCLUDED, EXCLUDED or NOT_SPECIFIED. Defaults to NOT_SPECIFIED.

Default changed from DEFAULT to NOT_SPECIFIED.

Default changed from AS_CONFIGURED to NOT_SPECIFIED.

Default changed from DEFAULT to NOT_SPECIFIED.

Default changed from DEFAULT to NOT_SPECIFIED.

Replaces notPersisted, taking values of AS_DAY, AS_DAY_BEFORE or NOT_SPECIFIED. Defaults to NOT_SPECIFIED.

Replaces unchanging, taking values of REPAINT, NO_REPAINT or NOT_SPECIFIED. Defaults to NOT_SPECIFIED.

Removed annotations/attributes

The following annotations, or attributes of annotations, have been removed

Table 3. Removed annotations/attributes
Annotation Attribute Use instead

@Action

publishingPayloadFactory()

Removed, use the simpler PublisherService SPI instead.

@ActionInteraction

@ActionOrder

@Aggregated

Never implemented internally in Isis 1.x so no replacement.

@Auditable (JDO applib)

@Audited

@AutoComplete

@ActionSemantics

@Bookmarkable

@Bounded

@Bulk

Similarly, the Bulk.InteractionContext domain service is replaced with the ActionInvocationContext domain service.

@Collection

notPersisted

Removed, no replacement.

@CollectionInteraction

@CollectionLayout

render

@Command

@CssClass

@CssClassFa

@Debug

@DescribedAs

@Disabled

@DomainObject

bounded

Deleted (was a boolean attribute), replaced by @Property#bounding

publishingPayloadFactory

Removed, use the simpler PublisherService SPI instead.

@Exploration

@FieldOrder

@Hidden

For actions by either @Action#hidden() or @ActionLayout#hidden(), for properties by either @Property#hidden() or @PropertyLayout#hidden(), for collections by either @Collection#hidden() or @CollectionLayout#hidden().

@Idempotent

@Ignore

@Immutable

@Mandatory

For properties, can also use @Column#allowsNull() Can also use @Nullable for either properties or parameters.

@Mask

Removed, never implemented internally in Isis 1.x so no replacement.

@MaxLength

For properties, can also use @Column#length()

@MemberGroups

.layout.xml file instead.

@MultiLine

@MustSatisfy

@NotPersisted

@Optional

For properties, can also use @Column#allowsNull() Can also use @Nullable for either properties or parameters.

@Named

@NotInServiceMenu

Specify nature of VIEW_CONTRIBUTIONS_ONLY. Alternatively, use a mixin.

@NotContributed

Specify nature of VIEW_MENU_ONLY.

@NotPersistable

Never implemented internally in Isis 1.x so no replacement.

@ObjectType

Alternatively, for domain entities either:

  • the @Discriminator annotation can be specified; the value is used as the object type, or

  • the @PersistenceCapable#schema() can be specified; the value is used as the concatenated with the class name to create a two part object type.

@Parameter

minLength

Never implemented internally in Isis 1.x so no replacement.

Note that the @MinLength annotation is for use with autocomplete supporting methods (specifying the minimum number of characters to enter before an auto-complete search is performed).

@Paged

Either @CollectionLayout#paged() (for parented collections), or @DomainObject#paged() (for standalone collections)

@ParameterLayout

renderedAsDayBefore

Deleted (was a boolean attribute), replaced by @ParameterLayout#renderDay.

@Plural

@PostsAction
InvokedEvent

@PostsCollection
AddedToEvent

@PostsCollection
RemovedFromEvent

@PostsProperty
ChangedEvent

@Property

notPersisted

Removed, replaced with @Property#snapshot()

@PropertyInteraction

@PropertyLayout

renderedAsDayBefore

Deleted (was a boolean attribute), replaced by @PropertyLayout#renderDay.

unchanging

Deleted (was a boolean attribute), replaced by @PropertyLayout#repainting.

@Prototype

@PublishedAction

Removed, use @Action#publishing()

@PublishedObject

@PublishingPayload FactoryForAction

Removed, use the simpler PublisherService SPI instead.

PublishingPayload FactoryForObject

Removed, use the simpler PublisherService SPI instead.

@QueryOnly

@Regex

@Render

Supporting RenderType enum also removed.

@RenderedAs
DayBefore

@Resolve

@SortedBy

@TypeOf

Either @CollectionLayout#typeOf() (for parented collections), or @ActionLayout#typeOf() (for actions returning a standalone collection).

@TypicalLength

Moved types

The following applib types have been moved.

Table 4. Moved types
Description Type(s) From To

Events emitted by WrapperFactory when interactions occur.

ActionUsabilityEvent, PropertyVisibilityEvent, CollectionAccessEvent etc.

o.a.i.applib.
events

o.a.i.applib.
services.wrapper.events

Interface types for mixins

Timestampable HoldsUpdatedAt HoldsUpdatedBy

o.a.i.applib.
services.timestamp

o.a.i.applib.
mixins.timestamp

Dto

o.a.i.applib.
services.dto

o.a.i.applib.
mixins.dto

Lifecycle events, domain events & UI events

  • AbstractDomainEvent
    domain events/subtypes

  • ObjectXxxEvent
    lifecycle events

  • XxxUiEvent
    UI events

o.a.i.applib.services.eventbus

  • o.a.i.applib.
    events.domain

  • o.a.i.applib.
    events.lifecycle

  • o.a.i.applib.
    events.ui

Removed configuration properties

The following configuration properties are no longer recognised.

Table 5. Removed configuration properties
Configuration property Description

isis.persistor.
datanucleus.
PublishingService.
serializedForm

PublishingService has been removed. Use PublisherService instead.

Updated classes

The following classes have been updated.

Table 6. Updated classes
Updated class Method Nature of change

IsisAppModule.
ActionDomainEvent

N-arg constructor

removed; just use the 0-arg ones

IsisAppModule.
CollectionDomainEvent

N-arg constructor

removed; just use the 0-arg ones

IsisAppModule.
PropertyDomainEvent

N-arg constructor

removed; just use the 0-arg ones

FixtureScript

asKeyValueMap(String)

Removed; this shouldn’t have had public visibility.

FixtureScript

execute(…​) executeChild(…​) executeIfNotAlready(…​) run(…​)

All removed or no longer public; use FixtureScript.ExecutionContext's #executeChild(…​) instead.

FixtureScript

lookup(…​)

Removed; use FixtureScript.ExecutionContext#lookup(…​) instead.

FixtureScript.
ExecutionContext

add(…​)

Removed; use addResult(…​) instead.

FixtureScripts

deprecated constructors

Removed

FixtureScripts.
MultipleExecutionStrategy

IGNORE

Removed, use EXECUTE_ONCE_PER_CLASS instead

Removed types

Adapter classes

The following adapter classes have been removed.

Table 7. Removed adapter classes
Removed class Replaced with

AbstractContainedObject

No replacement.

AbstractDomainObject

No replacement.

AbstractFactoryAndRepository

No replacement.

AbstractHomePageDashboardService

No replacement.

Filter classes/interfaces

Also, all classes and interfaces in org.apache.isis.applib.filter have been removed. Instead, the java.util.Predicate<T> interface is used.

For example, RepositoryService#allMatches(…​) method, which allows client-side filtering of results (typically during prototyping), now has the signature:

public interface RepositoryService {
    ...
    <T> List<T> allMatches(
                    final Class<T> ofType,
                    final Predicate<? super T> predicate,
                    long... range);

}

Removed interfaces

The following interfaces have been removed.

Table 8. Removed interfaces
Removed interface Replaced with

Auditable
(JDO applib)

Bounded
(JDO applib)

NotPersistable
(JDO applib)

Never implemented internally in Isis 1.x so no replacement.

ProgramPersistable
(JDO applib)

Never implemented fully in Isis 1.x so no replacement.

AlwaysImmutable
(JDO applib)

Never implemented fully in Isis 1.x so no replacement.

ImmutableOncePersisted
(JDO applib)

Never implemented fully in Isis 1.x so no replacement.

ImmutableUntilPersisted
(JDO applib)

Never implemented fully in Isis 1.x so no replacement.

NeverImmutable
(JDO applib)

Never implemented fully in Isis 1.x so no replacement.

Legacy Modules

TODO: v2 - these mignotes themselves are out of date…​

Deprecated types have been moved into new "legacy" modules. For example, applib types have been moved into org.apache.isis.core:isis-core-applib-legacy module. Generally speaking these types remain in the same package; in some cases they have been renamed.

These modules will be removed for the final release of 2.0.0.

applib-legacy

Deprecated types have been moved into a new org.apache.isis.core:isis-core-applib-legacy module.

The most significant type that has been deprecated is the DomainObjectContainer type, but there are several others also.

Table 9. Legacy types under org.apache.isis.applib
Package Type Use instead

o.a.i.applib

DomainObjectContainer

Use RepositoryService, FactoryService, UserService, MessageService instead etc.

o.a.i.applib.
annotation

Encodable

No replacement

Parseable

No replacement

o.a.i.applib.
fixtures

AbstractFixture

Use FixtureScript instead

AbstractFixtureSusa

Use fixture with injected SudoService

BaseFixture

Derive from FixtureScript

DateFixture

Use TickingClockFixture instead

SwitchUserFixture

Use fixture with injected SudoService instead

o.a.i.applib. switchuser

SwitchUserService

SudoService

SwitchUserServiceAware

No replacement

o.a.i.applib.
layout.component

CollectionLayoutData_legacy

Renamed from CollectionLayoutData, provides trivial utility functions. No replacement.

FieldSetData_legacy

Renamed from FieldSet, provides trivial utility functions. No replacement.

o.a.i.applib.
services.background

BackgroundCommandService2

Use BackgroundCommandService instead

BackgroundService2

Use BackgroundService instead

o.a.i.applib.
services.exceprecog

ExceptionRecognizer
AbstractLegacy

Copy of the 1.16.x version of ExceptionRecognizerAbstract, with the original dependency on guava. Refactor to use the new ExceptionRecognizerAbstract (which uses Java 8 predicates etc. instead)

ExceptionRecognizer
ForTypeLegacy

Copy of the 1.16.x version of ExceptionRecognizerForType, but with the original dependency on guava. Replace with the new ExceptionRecognizerForType which uses Java 8 predicates etc.

o.a.i.applib.
services.memento

MementoService

No replacement. Originally provided as a utility to view models that implemented ViewModel interface (as opposed to the newer approaches of annotating with @ViewModel or as a JAXB DTO class.

Note that the framework-provided implementation, MementoServiceDefault, has been moved out to the corresponding runtime-legacy module.

o.a.i.applib.
services.repository

RepositoryServiceLegacy

Copy of the 1.16.x version of RepositoryService, with the original dependency on guava. Refactor to use the new RepositoryService (which uses Java 8 predicates etc. instead).

Note that the framework-provided implementation, RepositoryServiceLegacyInternalDefault, has been moved out to the corresponding metamodel-legacy module.

o.a.i.applib.
services.urlencoding

UrlEncodingService
UsingBaseEncoding
WithSupportForLargeUrlsAbstract

The UrlEncodingServiceWithCompression (provided as the default implementation by the core framework) can be used in most cases.

o.a.i.applib.
util

ObjectContractsLegacy

Copy of the 1.16.x version of ObjectContracts, which heavily uses reflection. Use ObjectContracts instead. This provides a new API that does not require reflection and instead encourages a different coding style, but does also still support the old API.

o.a.i.applib.
value

Date
DateTime

Use JDK8 LocalDate, LocalDateTime or Joda DateTime or LocalDate or LocalDateTime

Time

Use JDK8 LocalTime or Joda LocalTime

Timestamp

Use java.sql.Timestamp or JDK8 DateTime or Joda DateTime instead

See also transition-1-2 module, below, for further discussion of background services.

integtestsupport-legacy

Table 10. Legacy types under org.apache.isis.applib
Package Type Use instead

o.a.i.core.
integtestsupport

IntegrationTestAbstract

Use IntegrationTestAbstract3 instead

IntegrationTestAbstract2

Use IntegrationTestAbstract3 instead

IsisSystemForTest

Helper class used only by other classes in this module. No replacement.

o.a.i.core.
integtestsupport.
scenarios

ScenarioExecutionForIntegration

Subclass spec "glue" from HeadlessWithBootstrappingAbstract (the common superclass of IntegrationTestAbstract3) instead, and inject services into glue.

unittestupport-legacy

TODO

transition-1-2

TODO

metamodel-legacy

Contains facet factories (which build up the metamodel) for these types moved from applib to applib-legacy:

  • Encodeable and Parseable interfaces

  • Date, DateTime, Time and Timestamp value types

It provides contains an implementation of ProgrammingModelPlugin interface which is used to register these facet factories in a pluggable fashion.

Similarly, it also provides implementations of the ValuePropertyPlugin interface which aggregate the set of value types, used for the swagger UI support.

Finally, it also contains these framework-provided service implementations:

  • DomainObjectContainerDefault (for DomainObjectContainer)

  • RepositoryServiceLegacyInternalDefault (for RepositoryServiceLegacy)

runtime-legacy

TODO

viewer-wicket-ui-legacy

TODO

Other Changes

View model URLs

The default implementation of UrlEncodingService provided by the framework has changed:

  • in 1.16.x the implementation is o.a.i.applib.services.urlencoding.UrlEncodingServiceUsingBaseEncoding

  • in 2.0.0-M1 this is changed to o.a.i.applib.services.urlencoding.UrlEncodingServiceWithCompression

This new implementation increases the state that can be encoded within the URL (approx 8000 characters) by first gzipping the state prior to base64 encoding the characters.

However, this does mean that any persisted URLs for view models will be invalid.

Applib types fully generic

All types in the applib have now been made fully generic

Updated dependencies

Wicket has been upgraded from Wicket 7.9 to Wicket 8.0.

Removed dependencies

The Apache Isis applib (o.a.i.core:isis-core-applib) no longer depends on the google guava library.

Likewise the Apache Isis Unit Test Support module (o.a.i.core:isis-core-unittestsupport) no longer depends on guava either.

Do note however that the core framework does still depend on guava (though the intention is to remove this over time).

New isis-core-commons module

The new org.apache.isis.core:isis-core-commons module provides a set of utility classes that are not API but that are depended upon by the applib.

Because these are not API, they should not be used by application code, even though they will be on the applications classpath.

To help prevent accidental usage:

  • the package is org.apache.isis.core.commons.internal

  • all of the types in this module are prefixed "_".

For example, o.a.i.commons.internal.resources._Resource provides utilities for loading static resources from the classpath.

This module performs many of the responsibilities that were previously provided by the dependency on guava.

This module also defines a number of plugin interface types, discussed in the section below.

Plugins

The framework introduces a plugin architecture whereby variations on the configuration are automatically enabled just by the presence of the Maven module on the classpath.

For example, the framework can be run using either DataNucleus 4 or DataNucleus 5. Including the relevant module will configure the rest of the framework accordingly.

The plugin architecture uses the JDK ServiceLoader API, whereby a Maven module can optionally provide an implementation of a well-known plugin interface type.

The plugin interface types themselves are defined in various of the Maven modules, broadly depending on what consumes them.

Table 11. Plugin types
Defined in Plugin type Used for Implementations

isis-core-commons

o.a.i.core.plugins.
classdiscovery.
ClassDiscoveryPlugin

Obtain a plugin to finding types on the classpath with certain characteristics, eg annotated with certain annotations

Include only one implementation on classpath.

ClassDiscoveryPluginUsingReflections uses the org.reflections open source library (which depends in turn on guava).

o.a.i.core.plugins.
codegen.
ProxyFactoryPlugin

Obtain a plugin acting as a factory to proxy types (as used by the WrapperFactory domain service).

Include only one implementation on classpath,

o.a.i.core.plugins.codegen. ProxyFactoryPluginUsingByteBuddy (using ByteBuddy)

o.a.i.core.plugins.codegen. ProxyFactoryPluginUsingJavassist (using Javassist).

o.a.i.core.plugins.
eventbus.
EventBusPlugin

Obtain a plugin for finding event bus implementations.

This removes the need to explicitly specify the implementation using the isis.services.eventbus.implementation config property; it can be left as simply "auto".

o.a.i.core.plugins.eventbus. EventBusPluginForAxon (using Axon Framework)

org.apache.isis.core.plugins.eventbus. EventBusPluginForGuava (using Guava)

isis-core-metamodel

org.apache.isis.core.
metamodel.progmodel.
ProgrammingModelPlugin

Obtain plugins that can provide implementations of Isis' own FacetFactory SPI (which is used to build up the metamodel).

There can be multiple implementations on the classpath.

org.apache.isis.progmodels. plugins.ProgrammingModelIsisTimePlugin (in metamodel-legacy) contributes facet factories for the applib value types that have been moved to applib-legacy.

org.apache.isis.core.
metamodel.services.
swagger.internal.
ValuePropertyPlugin

Obtain plugins that can provide implementations of Isis' own ValuePropertyFactory SPI (which is used to build up Swagger representations).

There can be multiple implementations on the classpath.

o.a.i.core.metamodel. services.swagger.plugins. IsisTimeValuePropertyPlugin (in metamodel-legacy) contributes factories for the applib value types that have been moved to applib-legacy.

o.a.i.core.
metamodel.
IsisJdoMetamodelPlugin

Decouples the metamodel module from a particular implementation of DataNucleus.

Include only one implementation on classpath,

o.a.i.plugins.jdo.dn4.IsisJdoSupportPlugin4

o.a.i.plugins.jdo.dn5.IsisJdoSupportPlugin5

isis-core-runtime

o.a.i.core.
metamodel.
IsisJdoRuntimePlugin

Decouples the runtime module from a particular implementation of DataNucleus.

Include only one implementation on classpath,

o.a.i.plugins.jdo.dn4.IsisJdoSupportPlugin4

o.a.i.plugins.jdo.dn5.IsisJdoSupportPlugin5

isis-core-viewer-restfulobjects-applib

o.a.i.viewer.
restfulobjects.
applib.client.
UriBuilderPlugin

Plugin to obtain a UriBuilder to create uri templates.

Include only one implementation on classpath,

o.a.i.plugins.
jaxrs.resteasy.IsisResteasy3Plugin

or

o.a.i.plugins.
jaxrs.resteasy.IsisResteasy4Plugin

isis-core-viewer-restfulobjects-server

o.a.i.viewer.
restfulobjects.
server.
IsisJaxrsServerPlugin

Plugin to configure the JAX-RS runtime.

Include only one implementation on classpath.

o.a.i.plugins.
jaxrs.resteasy.IsisResteasy3Plugin

or

o.a.i.plugins.
jaxrs.resteasy.IsisResteasy4Plugin

The two JDO/DataNucleus plugins are not independent of each other, because (as the table above shows) the same class implements both plugin interface types. These plugins allow the framework to run either using DataNucleus 4 (JDO 3.1 API) or using DataNucleus 5 (JDO 3.2 API).

Similarly, the two RestfulObjects plugins are also not independent of each other; again the pattern is for a single class implements both plugin interface types. These plugins support alternate implementations of JAX-RS API. JAX-RS 2.0 (one of the JavaEE 7.0 specifications) is implemented by RestEasy 3 whereas JAX-RS 2.1 is implemented by RestEasy 4 (part of JavaEE 8).

IsisJdoSupport domain service

In 1.16.x the IsisJdoSupport domain service exposed the DataNucleus 4 org.datanucleus.query.typesafe.TypesafeQuery type in one of its signatures. However, in DataNucleus 5 this type was removed and replaced by javax.jdo.JDOQLTypedQuery, reflecting the fact that type-safe queries are now part of JDO 3.2.

Consequently in 2.0.0-M1 this API has been split into three:

  • IsisJdoSupport (defined in isis-core-applib) is independent of JDO APIs

  • IsisJdoSupport_v3_1 (defined in isis-core-plugins-jdo-datanucleus-4) extends IsisJdoSupport with DataNucleus 4/JDO 3.1-specific APIs

  • IsisJdoSupport_v3_2 (defined in isis-core-plugins-jdo-datanucleus-5) extends IsisJdoSupport with JDO 3.2-specific APIs

Swagger UI

Swagger UI is now reinstated as a webjar, so there is no need to have any swagger UI files in the webapp (ISIS-1908).