= Migrating from M7 to M8

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:


== Programming Model

[cols="2a,3a", options="header"]

|===

| previously
| new

| For _Domain Objects_ we had support for (direct) _Collection_ modification (`addTo`, `removeFrom`).

As this is part of _Restful Object Specification 1.0_, it was implemented for the _RO Viewer_ and also the _WrapperFactory_.

Specifically REST endpoints (removed):
----
DomainObjectResource
  addToSet(...)
  addToList(...)
  removeFromCollection(...)
----
Events (removed)
----
CollectionAddToEvent
CollectionRemoveFromEvent
----
| Has been removed without replacement. (An updated _Restful Object Specification 2.0_ is in preparation.)

It has proven difficulty to define what an "execution" would mean for _Collection_ changes, hence we finally removed that notion.

In some situations it however  makes sense to limit which objects can be *added to* or *removed from* a _Collection_.
Thus, one would make the _Collection_ read only and then define _Actions_ that encapsulate the required business logic.

| `@DomainService.logicalTypeName` deprecated for removal
| use `@Named` or any other semantics supported by Spring
+
Behavioral change: `@DomainService.logicalTypeName` can now be left empty, which is interpreted as _unspecified/indifferent_

| `RecreatableDomainObject` interface removed
| use `ViewModel` interface instead

| `ViewModel.viewModelInit(String memento)` removed
| use a single (String) argument constructor instead; this will allow Java Records to be used as viewmodels (future work)

| `MetamodelEvent` as provided with _metamodel_ moved
| moved to _applib_; we introduced _interface_ `MetamodelListener` for convenience to maybe use instead
[source, java]
.Example
----
@Service
public class SeedService implements MetamodelListener {
/..
    @Override
    public void onMetamodelLoaded() {
        // seed database entities
    }
}
----

| Factory method `Identifier.propertyOrCollectionIdentifier(..)`
| was slit up into `Identifier.propertyIdentifier(..)` and `Identifier.collectionIdentifier(..)`

|===

== Commons

The following changed:
[cols="2a,3a", options="header"]

|===

| previously
| new

| `Result<T>` removed
| replaced by `Try<T>`; also promoting `Either<L, R>` to non-internal,
and introducing `Railway<F, S>`

|===

== Configuration

The following changed:
[cols="2a,3a", options="header"]

|===

| previously
| new

| (non-essential) object meta-data mixins were split out of `IsisModuleApplib`
| need to be explicitly imported via `IsisModuleApplibObjectMetadataMixins`

| default logging subscribers were split out of `IsisModuleApplib`
| need to be explicitly imported via `IsisModuleApplibChangeAndExecutionLoggers`

|===

== Other

=== Placeholder Rendering (UI)

The UI now renders placeholders `(none)` when representing `null` references.
To customize behavior you may want to implement your own `PlaceholderRenderService`.
(See `PlaceholderRenderServiceDefault`, the default implementation.)

=== Bill of Material / Parent POM

Folder moved `/isis-parent` -> `/bom`

[source, xml]
.Bill of Material
----
<!-- renamed
	<groupId>org.apache.isis</groupId>
	<artifactId>isis-parent</artifactId>
-->

<groupId>org.apache.isis</groupId>
<artifactId>isis-bom</artifactId>
----

=== Extensions

[source, xml]
.secman
----
<!-- renamed
	<groupId>org.apache.isis.extensions</groupId>
	<artifactId>isis-extensions-secman-shiro-realm</artifactId>
-->
<!-- instead use ... -->
<artifactId>isis-extensions-secman-delegated-shiro</artifactId>
----

Classes `IsisModuleExtSecmanShiroRealm` and
`AuthenticationStrategyForIsisModuleSecurityRealm`
were moved and renamed. (see shiro.ini)

[source, ini]
.shiro.ini
----
## renamed
#authenticationStrategy=org.apache.isis.extensions.secman.shiro.AuthenticationStrategyForIsisModuleSecurityRealm
#isisModuleSecurityRealm=org.apache.isis.extensions.secman.shiro.IsisModuleExtSecmanShiroRealm
## instead use
authenticationStrategy=org.apache.isis.extensions.secman.delegated.shiro.realm.AuthenticationStrategyForSecMan
isisModuleSecurityRealm=org.apache.isis.extensions.secman.delegated.shiro.realm.IsisModuleExtSecmanShiroRealm
----

=== Restclient

[source, java]
.Restclient Package Names
----
// renamed ...
//import org.apache.isis.extensions.restclient.RestfulClient;
//import org.apache.isis.extensions.restclient.RestfulClientConfig;
import org.apache.isis.viewer.restfulobjects.client.RestfulClient;
import org.apache.isis.viewer.restfulobjects.client.RestfulClientConfig;
----

[source, xml]
.Restclient Artifacts
----
<!-- renamed
	<groupId>org.apache.isis.mappings</groupId>
	<artifactId>isis-mappings-restclient-applib</artifactId>
-->

<groupId>org.apache.isis.viewer</groupId>
<artifactId>isis-viewer-restfulobjects-client</artifactId>
----

[source, java]
.Restclient Usage
----
// DigestResponse is no longer publicly visible, instead returning Try<T>
<T> Try<T> digest(Response response, Class<T> entityType);

// DigestResponse is no longer publicly visible, instead returning Try<Can<T>>
<T> Try<Can<T>> digestList(Response response, Class<T> entityType, GenericType<List<T>> genericType);
----

=== Mappings

[source, xml]
.Mappings
----
<!-- all removed
	<groupId>org.apache.isis.mappings</groupId>
	<artifactId>isis-mappings-...</artifactId>
-->
----

=== Mavendeps

[source, xml]
.integtests
----
<!-- removed
	<groupId>org.apache.isis.mavendeps</groupId>
	<artifactId>isis-mavendeps-integtests</artifactId>
	<type>pom</type>
-->

<!-- instead use directly as required ... -->

<groupId>org.apache.isis.testing</groupId>
<artifactId>isis-testing-integtestsupport-applib</artifactId>

<groupId>org.apache.isis.testing</groupId>
<artifactId>isis-testing-fakedata-applib</artifactId>

<groupId>org.apache.isis.testing</groupId>
<artifactId>isis-testing-fixtures-applib</artifactId>
----

[source, xml]
.unittests
----
<!-- removed
	<groupId>org.apache.isis.mavendeps</groupId>
	<artifactId>isis-mavendeps-unittests</artifactId>
	<type>pom</type>
-->

<!-- instead use directly as required ... -->

<groupId>org.apache.isis.testing</groupId>
<artifactId>isis-testing-unittestsupport-applib</artifactId>

<groupId>org.apache.isis.testing</groupId>
<artifactId>isis-testing-fakedata-applib</artifactId>
----

[source, xml]
.valuetypes
----
<!-- removed
	<groupId>org.apache.isis.valuetypes</groupId>
	<artifactId>isis-valuetypes-prism</artifactId>
-->

<!-- removed
	<groupId>org.apache.isis.valuetypes</groupId>
	<artifactId>isis-valuetypes-resources</artifactId>
-->

<!-- removed
	<groupId>org.apache.isis.valuetypes</groupId>
	<artifactId>isis-valuetypes-prism-wicket</artifactId>
-->

<!-- removed
	<groupId>org.apache.isis.valuetypes</groupId>
	<artifactId>isis-valuetypes-prism-vaadin</artifactId>
-->

<!-- instead use ... -->

<groupId>org.apache.isis.viewer.commons</groupId>
<artifactId>isis-viewer-commons-prism</artifactId>

<!-- moved
	<groupId>org.apache.isis.valuetypes</groupId>
	<artifactId>isis-valuetypes-sse*</artifactId>
-->

<!-- instead use ... -->
<groupId>org.apache.isis.extensions</groupId>
<artifactId>isis-extensions-sse*</artifactId>

IsisModuleValSseApplib renamed to IsisModuleExtSseApplib
IsisModuleValSseMetaModel renamed to IsisModuleExtSseMetaModel
IsisModuleValSseUiWkt renamed to IsisModuleExtSseWicket
----

