ApplibCandidatesForRemovalInApacheIsis2

current status

This work is being done in 'master' branch, with progress to date in: https://github.com/apache/isis/blob/master/todo-deprecation-list.txt

in Apache Isis 1.16.0 we'll be updating DataNucleus to 5.1, which requires moving to Java 8. This is probably in itself a good enough reason to rename this to Apache Isis 2.0.0, but also note that one of the DN classes - TypeSafeQuery - is exposed from the Apache Isis applib and in DN 5.1 that class is renamed ... so backward compatibility is broken anyway.

According to semver, we therefore should call this release Apache Isis 2.0.0. Do people agree?

Following on from that, we may as well look to remove stuff that's been deprecated for a while. Below I've listed stuff that has been deprecated, and which I think should be removed. Comments welcome.

Propose:

make AppManifest mandatory
remove support for Xxx.layout.json
remove support for contributed services (use mixins instead)

Propose to remove (isis-core-applib):

            org.apache.isis.applib

                AbstractContainedObject.java - entire class
                AbstractDomainObject.java  - entire class
                AbstractFactoryAndRepository.java  - entire class

                DomainObjectContainer.java  - entire class

                IsisApplibModule.java
                    ActionDomainEvent - the N-arg constructors (just use the 0-arg ones)
                    CollectionDomainEvent - the N arg constructors (just use the 0-arg ones)
                    PropertyDomainEvent  - the N arg constructors (just use the 0-arg ones)

            org.apache.isis.applib.annotation 

                Action.java 
                    publishingPayloadFactory()  - attribute; use the simpler PublisherService SPI instead
                DomainObject.java 
                    publishingPayloadFactory() - attribute, use the simpler PublisherService SPI instead
                PublishedAction.java - entire annotation, use @Action(publishing=...) instead
                PublishedObject.java - entire annotation, use @DomainObject(publishing=...) instead
                PublishingPayloadFactoryForAction.java - entire annotation, replaced with simpler PublisherService SPI
                PublishingPayloadFactoryForObject.java - entire annotation, replaced with simpler PublisherService SPI

                ActionInteraction.java  - entire annotation, use @Action(domainEvent=...)
                CollectionInteraction.java - entire annotation, use @Collection(domainEvent=...)
                PostsActionInvokedEvent.java - entire annotation, use @Action(domainEvent=...) instead
                PostsCollectionAddedToEvent.java - entire annotation, use @Collection(domainEvent=...) instead.
                PostsCollectionRemovedFromEvent.java - entire annotation, use @Collection(domainEvent=...) instead.
                PostsPropertyChangedEvent.java - entire annotation, use @Property(domainEvent=...) instead.
                PropertyInteraction.java - entire annotation, use @Property(domainEvent=...) instead.

                ActionOrder.java - entire annotation, use @MemberOrder instead
                FieldOrder.java - entire annotation, use @MemberOrder instead

                ActionSemantics.java  - entire annotation, use @Action(semantics=...)
                Idempotent.java - entire annotation, use @Action(semantics=...) instead.
                QueryOnly.java - entire annotation, use @Action(semantics=...) instead.

                Aggregated.java - entire annotation, not supported internally
                NotPersistable.java - entire annotation, not supported and does nothing

                AutoComplete.java - entire annotation, use @DomainObject(autoComplete...=...)
                Bookmarkable.java - entire annotation, use @DomainObjectLayout(bookmarking=...)
                Bounded.java - entire annotation, use @DomainObject(bounded=...)

                Bulk.java - entire annotation, use @Action(invokeOn=...)
                Bulk.InteractionContext - entire service, use ActionInvocationContext service instead
                InvokedOn.java - entire enum, along with @Bulk annotation.

                CollectionLayout.java
                    render() - use @CollectionLayout(defaultView=...) instead
                Render.java - entire annotation, use @CollectionLayout(defaultView=...) instead
                RenderType.java - supporting enum for @Render annotation
                Resolve.java - entire annotation, use @CollectionLayout(defaultView=...) instead

                Audited.java - entire annotation, use @DomainObject(audited=...)

                Command.java - entire annotation, use @Action(command=...) instead
                CommandExecuteIn.java - entire annotation, use @Action(commandExecuteIn=...) instead
                CommandPersistence.java - entire annotation, use @Action(commandPersistence=...) instead

                CssClass.java - entire annotation, use @XxxLayout(cssClass=...) instead, where Xxx is Property, Collection, Action, Parameter, DomainObject, ViewModel
                CssClassFa.java - entire annotation, use @XxxLayout(cssClass=...) instead, where Xxx is Property, Collection, Action, Parameter, DomainObject, ViewModel

                Debug.java - entire annotation, use @Action#(restrictTo=...) instead
                Exploration.java - entire annotation, use @Action(restrictTo=....) instead
                Prototype.java  - entire annotation, use @Action(restrictTo=....) instead

                DescribedAs.java - entire annotation, use @XxxLayout(describedAs=...) instead

                Disabled.java - entire annotation, use @Property(editingDisabledReason=...) instead
                Hidden.java - entire annotation, use @Property(hidden=...), @Collection(hidden=...), @Action(hidden=...)

                Ignore.java - entire annotation, use @Programmatic instead.
                Immutable.java - entire annotation, use @DomainObject(editing=...) instead

                Mandatory.java - entire annotation, use @Property(optionality=...) and @Parameter(optionality=...), or @javax.annotations.Nullable
                Optional.java - entire annotation, use @Property(optionality=...) and @Parameter(optionality=...), or @javax.annotations.Nullable

                Mask.java - entire annotation, not supported by either Wicket viewer or RO viewer
                MaxLength.java - entire annotation, use @Property(maxLength=...) and @Parameter(maxLength=...)

                MemberGroups.java - entire annotation, use @MemberGroupLayout instead

                MultiLine.java - entire annotation, use @PropertyLayout(multiLine=...) and @ParameterLayout(multiLine=...) instead.
                MustSatisfy.java - entire annotation, use @Property(mustSatisfy=....) or @Parameter(mustSatisfy=...) instead
                Named.java - entire annotation, use @XxxLayout(named=...) instead, where Xxx is Property, Collection, Action, Parameter, DomainObject, ViewModel
                Plural.java - entire annotation, use @DomainObjectLayout(plural=...) instead
                RegEx.java - entire annotation, use @Property(regexPatternFlags=...) or @Parameter(regexPatternFlags=...) instead
                RenderedAsDayBefore.java - entire annotation, use @PropertyLayout(renderedAsDayBefore=...) and @ParameterLayout(renderedAsDayBefore=...)
                SortedBy.java - entire annotation, use @CollectionLayout(sortedBy=...) instead
                TypeOf.java - entire annotation, use @Collection(typeOf=...) or @Action(typeOf=...) instead.
                TypicalLength.java - entire annotation, use @PropertyLayout(typicalLength=...) instead.

                NotContributed.java - entire annotation, use @DomainService(nature=...) or mixins instead.
                NotInServiceMenu.java - entire annotation, use @DomainService(nature=...) or mixins instead.
 
                NotPersisted.java - entire annotation, use @Property(notPersisted=...) instead

                ObjectType.java - entire annotation, use @DomainObject(objectType=...) or @javax.jdo.annotations.Discriminator instead.
                Paged.java - entire annotation, use @DomainObjectLayout(paged=...) or @CollectionLayout(paged=...) instead.

                Parameter.java 
                    minLength() attribute; not supported.  For autocomplete, use @MinLength annotation.

                When.java - entire enum, no replacement (believe is unused within the framwork)

            org.apache.isis.applib.clock 
                Clock.java - 
                    getTimeAsCalendar()  (1 usage found)
                    getTimeAsDate()  (1 usage found)

            org.apache.isis.applib.events - entire package.  These event classes supported only by WrapperFactory; 
                                            redundant as @Xxx(domainEvent=...) on member achieves much the same effect using event bus
            org.apache.isis.applib.filter  - entire package of Filter classes; use guava Predicate instead.

            org.apache.isis.applib.fixturescripts 
                FixtureScript.java  - various methods to simplify API
                    add(...) - use addResult(...) instead
                    asKeyValueMap(String) - removed; this shouldn't have had public visibility.
                    execute(...) and executeChild(...) - use ExecutionContext#executeChild(FixtureScript, String, FixtureScript)} instead
                    executeIfNotAlready(FixtureScript) - removed; this shouldn't have had public visibility.
                    lookup(String, Class<T>) - use ExecutionContext#lookup(...) instead
                FixtureScripts.java - remove deprecated methods;
                                      framework provides an implementation of this service, and use FixtureScriptsSpecificatoinProvider to configure instead.

            org.apache.isis.applib.marker - remove these marker interaces (tend to use annotations in preference)
                ImmutableOncePersisted.java  
                ImmutableUntilPersisted.java 
                NeverImmutable.java 
                NonPersistable.java 
                ProgramPersistable.java 
            org.apache.isis.applib.services.actinvoc
                ActionInvocationContext.java -remove unused constructors

            org.apache.isis.applib.services.audit  (2 usages found)
                AuditingService3.java - remove entire service, use AuditerService instead
            org.apache.isis.applib.services.background  (10 usages found)
                ActionInvocationMemento.java - remove entire class, use InteractionDto and CommandDto are used internally instead
                BackgroundCommandService.java - remove methods using AIM, instead keep those using CommandDto (in BackgroundCommandService2)
                BackgroundService.java 
                    asActionInvocationMemento(Method, Object, Object[]) - remove this internal API, no longer called by framework

            org.apache.isis.applib.services.bookmark  (8 usages found)
                BookmarkService.java - deprecated methods, have overloads in BookmarkService2 subtype [suggest we retain these for now]
            org.apache.isis.applib.services.classdiscovery  
                ClassDiscoveryService.java , push down into ClassDiscoveryService2

            org.apache.isis.applib.services.command 
                Command2.java  - methods for working with interaction events (remove with those event types)
                    flushActionInteractionEvents()
                    peekActionInteractionEvent() 
                    popActionInteractionEvent()  
                    pushActionInteractionEvent(ActionInteractionEvent<?>) 

            org.apache.isis.applib.services.command.spi 
                CommandService.java 
                    startTransaction(Command, UUID) - no longer required to do anything, so remove

            org.apache.isis.applib.services.eventbus 
                AbstractInteractionEvent.java - remove
                ActionInteractionEvent.java - remove
                ActionInvokedEvent.java - remove
                CollectionAddedToEvent.java - remove
                CollectionInteractionEvent.java - remove
                CollectionRemovedFromEvent.java  - remove
                PropertyChangedEvent.java - remove
                PropertyInteractionEvent.java - remove
            org.apache.isis.applib.services.memento  (19 usages found)
                MementoService.java - remove entire service (previously to support view models, but now @ViewModel and JAXB)

            org.apache.isis.applib.services.metamodel 
                MetaModelService2.java - push down to subtype, retain overloads for now

            org.apache.isis.applib.services.publish - remove classes pertaining to original PublishingService (payload factories etc).
                EventMetadata.java - remove class
                EventPayload.java - remove class
                EventPayloadForActionInvocation.java - remove class
                EventPayloadForObjectChanged.java - remove class
                PublishedEventStateType.java - remove class
                PublishingService.java - remove domain service interface
                StatusMessageMessageType.java - remove class

            org.apache.isis.applib.services.settings
                SettingTypes.java - remove, used only by 3rd party code (incode platform settings module)

            org.apache.isis.applib.services.wrapper
                WrapperObject.java 
                    save() and wrapped() - remove to avoid name clashes, use __isis_Xxx() methods instead

            org.apache.isis.applib.snapshot 
                Snapshottable.java - remove ?  [suggest we retain the Snapshot service for now]

 
            org.apache.isis.applib.value  
                DateTime.java 
                    longValue() - use #millisSinceEpoch()
                Time.java 
                    longValue() - use #millisSinceEpoch()

            org.apache.isis.core.objectstore.jdo.applib.annotations - remove package entirely 
                Auditable.java - use @DomainObject(audited=...) instead.
            org.apache.isis.objectstore.jdo.applib 
                Auditable.java - use @DomainObject(audited=...) instead.
            org.apache.isis.objectstore.jdo.applib.service
                DomainChangeJdoAbstract.java - move to incode platform
                JdoColumnLength.java - remove class (all constants defined in other classes)
                                     - https://github.com/apache/isis/blob/rel/isis-1.15.1/core/applib/src/main/java/org/apache/isis/objectstore/jdo/applib/service/JdoColumnLength.java
                Util.java - remove
            org.apache.isis.objectstore.jdo.applib.service.support 
                IsisJdoSupport.java - replaced by org.apache.isis.applib.services.jdosupport.IsisJdoSupport

Notes:

sometimes there are multiple versions of a type, eg BookmarkService2 and BookmarkService, where BookmarkService2 extends BookmarkService. In these cases, suggest pull up the methods from the subtype(s) into the supertype, and then delete those subtypes... ie we end up with a new expanded version of BookmarkService.

To retain:

Below is the code currently deprecated in the applib, but I propose to retain even in 2.0.0 (on the grounds that a replacement for them is not fully designed):

            org.apache.isis.applib.adapters  - custom value type support


            org.apache.isis.applib.annotation 

                Encodable.java - entire annotation, part of custom value types support
                Parseable.java - entire annotation, part of custom value types support

                MemberGroupLayout.java - entire annotation, use Xxx.layout.xml instead  [move to retained, per comments at bottom: see [1] ]

            org.apache.isis.applib.fixtures  - "legacy" fixture support package ... by and large can use FixtureScripts (though not sure if there's feature parity in all cases)
                AbstractFixture.java 
                AbstractFixtureSusa.java 
                BaseFixture.java 
                CompositeFixture.java 
                DateFixture.java 
                LogonFixture.java 
            org.apache.isis.applib.fixtures.switchuser 
                SwitchUserService.java 
                SwitchUserServiceAware.java 

            org.apache.isis.applib.services.command 
                Command.java  - methods that pertain to the execution of the command and its completion (for that, use Interaction) [suggest we retain for now]
                    getCompletedAt()
                    getException()
                    getResult()
                    getStartedAt()
                    next(String)
                    setCompletedAt(Timestamp)
                    setStartedAt(Timestamp)
                Command3.java  - metods for working with domain events (equiv functionality in Interaction)  [suggest we retain for now]
                    flushActionDomainEvents()
                    peekActionDomainEvent()  
                    popActionDomainEvent() 
                    pushActionDomainEvent(ActionDomainEvent<?>)  (

Also for 2.0.0, new features/deprecations:

automatically wrap domain services (perhaps behind a config property)
automatically infer \@Programmatic for all \@DomainService(nature=DOMAIN)
deprecate use of guava predicates, but don't remove (too big a change, weren't deprecated previously)
deprecate FixtureScripts service with view to removing from applib ... the framework provides an implementation by default
get rid of automatic initialization of fields (perhaps behind a config property)
deprecate the Apache Isis' DateTime classes for removal in the future) ... and probably all of the custom value types, subclasses of Magnitude

Comments:

1 Kevin: Removing Layout annotations and relying only on xxx.layout.xml: Personally, I prefer not to have rely on "out of band" (i.e. not in source code) resources. I understand the power of the *.layout.xml resource, but is there an overhead in maintaining them when the sources (i.e. property names) change? However, I am not using this in code, so I will defer to those who are!