> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration notes 5.9

# Migrate to 5.9

Java 8 is no longer supported. ActivePivot 5.9 is compatible with Java 11.

### ActivePivot

#### New Copper API

Shipped as an experimental feature in ActivePivot 5.8.3, the [new Copper API](copper/copper_intro) is officially replacing the one
released with ActivePivot 5.7.0, which is now abandoned.

##### Shift measure creation

The Copper shift measure creation methods have changed: `CopperMeasure#at([...])` methods have been changed to a unified `CopperMeasure#shift(CopperLevelsAt...)` method.
Find more information in our [user guide](copper/copper_measures#shift-measures) for updated examples.

##### Parent Value

The method `Copper.parentValue(measure, hierarchy)` has been changed to `measure.parentValueOn(hierarchy)`.

##### Setting the designated type of measure

To improve clarity, the method `CopperMeasure#cast([...])` has been renamed to `CopperMeasure#withType([...])`.

##### Level and hierarchy representation

`LevelCoordinate` has been renamed and is now `LevelIdentifier`.
`HierarchyCoordinate` has been renamed and is now `HierarchyIdentifier`.

##### Test jar

The Copper test utils that were previously packaged in a `test-jar` have been moved to their own module:

> ```xml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>  <groupId>com.activeviam.activepivot</groupId>
>  <artifactId>activepivot-copper-test</artifactId>
> ```

#### Spring Configuration Changes

##### Schema configuration

`ActivePivotConfig` now requires an `IActivePivotManagerDescriptionConfig`.
`IDatastoreDescriptionConfig` was merged into `IActivePivotManagerDescriptionConfig` and
`IParameterAwareDatastoreDescriptionConfig` was renamed `IParameterAwareActivePivotManagerDescriptionConfig`.

In `IActivePivotManagerDescriptionConfig` you must now implement `userManagerDescription()`
(respectively named `userSchemaDescription()`) instead of `managerDescription()` (respectively `schemaDescription()`).

The way the description post-processors are applied has been changed. You are impacted if you explicitly build the Datastore or
the ActivePivotManager in your project instead of using `DatastoreConfig` and `ActivePivotConfig`.
In this case, define an `IActivePivotManagerDescriptionConfig` and give the results of the `managerDescription()` and `schemaDescription()` default methods to the builders.

`IActivePivotConfig.activePivotManagerDescription()` was removed and replaced by `IActivePivotManagerDescriptionConfig.managerDescription()`.

##### CORS configuration

The CORS configuration now relies on Spring standards. Instead of our own `ICorsFilterConfig` that created a
`SpringCorsFilter`, we moved to Spring `CorsConfigurationSource`. As internal components require a knowledge of the
CORS configuration before we can define the actual CorsConfigurationSource, a new interface `ICorsConfig
` has been introduced, detailing the information of a standard CORS configuration. This is used in internal services to create REST and WS
services compatible with the configuration. This is used in the sandbox project to create the final CORS configuration.

`ICorsConfig` only requires you to define the list of allowed origins. The other methods provide the accepted and exposed headers the authorized methods.
Those have default implementations compatible with the ActivePivot stack.

`SpringCorsFilter` has been deleted. Thanks to `CorsConfigurationSource`, Spring automatically creates the filter.

##### Miscellaneous

`ActivePivotServicesConfig` removes an internal attribute, creating an unused dependency to `IDatastoreConfig`.
If needed, you can restore this dependency by extending the configuration class and restoring the attribute.

`I18nConfig` was renamed `AI18nConfig`. Many of the static methods have changed to instance methods to allow
easier extensions and refinements.

#### Aggregation Procedures

##### Interface

The interface was slightly changed to support more features in Copper (`getDatastorePrefetch` and `createContext`).
This change should be transparent for procedures extending `AAnalysisAggregationProcedure`.

##### Additional validation checks

To offer support for Aggregation Procedures depending on other Procedures, ActivePivot uses the property
`IAnalysisAggregationProcedureDescription#getUnderlyingLevels()` to identify the dependencies between Procedures.
This drives a change to the API, preventing Procedures to define their own handled levels in the list of underlying levels.

This constraint is enforced by the validation procedure of the description. Configurations may need to be updated. Particularly,
in 5.8, you always had to define a handled hierarchy from builders. You can now avoid this with the method
`withoutHierarchies()`.

#### Option to disable the Epoch level

The epoch level of the epoch dimension can now be enabled or disabled.
The epoch dimension is still enabled by default. The epoch level is now disabled by default. To enable it,
use `IEpochDimensionDescription.setEpochLevelEnabled(boolean)` or `IEpochDimensionBuilder.withEpochLevel`.

The `IEpochDimensionBuilder.withBranchesLevel` method was renamed `IEpochDimensionBuilder.withBranchLevel`.
The methods in `IEpochDimensionDescription` were also renamed from `*epochsLevel*` and `*branchesLevel*`
(e.g. `getEpochsLevelComparator` or `getBranchesLevelFormatter`) to `*epochLevel*` and `*branchLevel*`
(e.g. `getEpochLevelComparator` and `getBranchLevelFormatter`).

Distributed Cube **no longer supports** the epoch level

#### New default aggregation functions

Aggregation functions that maintain a history state, like AVG, MIN, or MAX are memory intensive. Thus, for the MIN and MAX
aggregation functions, the new default behavior is **append-only**. This means that disaggregation is not supported for these
two functions. For disaggregation support, please use `MIN_HISTORY` and `MAX_HISTORY` aggregation functions
(e.g. `value.MIN_HISTORY` or `value.MAX_HISTORY`).

#### Default Distributed Message Size Limits

Previous ActivePivot versions had a maximum default distributed message size of 1GB for every message type. This limit has been
reduced. The default maximum size is:

* 64MB for `IInitialDiscoveryMessage` messages
* 4MB for `ITransactionCommittedMessage` messages
* 4MB for `ScopedAggregatesRetrievalResultTransporter` answers wrapped in `BroadcastResult` messages
* 32MB for `DrillthroughMessageWithHeadersAnswers` answers wrapped in `BroadcastResult` messages
* 2MB for any other message types

You can still override these values using the property `NETTY_MAX_SIZE_PROPERTY` of the `ActiveViamProperty`.
In addition to the older configuration method using class names, it is possible to configure the message default size limit using the constants (enum)
defined in `NettyStreamUtils#MessageType` as follows:

* `INITIAL_DISCOVERY_MESSAGE` for initial discovery messages
* `ITRANSACTION_COMMITTED_MESSAGE` for transaction commit message
* `SCOPEDAGGREGATES_RETRIEVAL_TRANSPORTER` for single Gaq query result messages
* `DRILLTHROUGH_HEADER` for drillthrough header query result messages
* `DRILLTHROUGH_MESSAGE_WITH_HEADERS_ANSWER` for drillthrough query result messages
* `GLOBAL_MESSAGE` for global configuration

For instance, the following statement used in prior versions:

```diff theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
- -Dqfs.distribution.netty.message.maxSize=com.quartetfs.biz.pivot.cellset.impl.ScopedAggregatesRetrievalResultTransporter=42m,com.qfs.messenger.message.IInitialDiscoveryMessage=200m
```

becomes:

```diff theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
+ -Dactiveviam.distribution.nettyMessageMaxSize=com.quartetfs.biz.pivot.cellset.impl.ScopedAggregatesRetrievalResultTransporter=42m,com.activeviam.messenger.message.IInitialDiscoveryMessage=200m
or
+ -Dactiveviam.distribution.nettyMessageMaxSize=singleGaqResult=42m,initialDiscovery=200m
```

#### Miscellaneous

* `ALocationShiftPostProcessor#handleNoUnderlyingMeasure` is renamed into `ALocationShiftPostProcessor#handleNoUnderlyingMeasure` to fix the typo - missing "g".

### REST and WS APIs

With the introduction of a new REST call to export query plans and another REST endpoint to forward client traces to a tracing server,
the version of ActivePivot REST API has changed from *v4* to *v5*.
With the addition of the metadata to the WS updates of the Content Service entries, the WS API has changed from *v4*
to *v5*.

As components of the REST and WS API versions remain synchronized, these changes result in the following URL changes:

| Before              | After               |
| ------------------- | ------------------- |
| pivot/rest/v4/...   | pivot/rest/v5/...   |
| pivot/ws/v4/...     | pivot/ws/v5/...     |
| content/rest/v4/... | content/rest/v5/... |
| content/ws/v4/...   | content/ws/v5/...   |

Impacted REST services:

* ActivePivot services for queries, context configurations, etc
* Datastore service for queries and updates
* Content Service
* Tracing Service

#### CSV Source

The CSV Source can now accept incomplete lines (where the number of columns is smaller than the
expected number of attributes of a record). You can set this in `CSVParserConfiguration`'s full constructor, or through
its `setAcceptIncompleteLines(boolean)`. It can finally be set through `ParserContext#setAcceptIncompleteLines(boolean)`
method. This sets this property on its underlying `CSVParserConfiguration`.

You can also sample the input files to work on a small portion of the input files. The sampling policy
is passed as an argument of type `ICsvParserConfigPolicy` to the constructor of `CSVParserConfiguration`, or using
the method `CSVParserConfiguration#setParserPolicy(ICsvParserConfigPolicy)`.\
The Core Product ships basic policies to load the first lines of one or more files, or load a limited number of files.
Those are available in `ICsvParserConfigPolicy` static methods.

#### Parquet Source

The Parquet Source benefited from the same sampling policies as the CSV Source. They implement `IParquetReaderPolicy`,
that are passed in the constructor of `ParquetParser`. Like the CSV Source, basic policies are available in
`IParquetReaderPolicy` to load a limited number of lines or files.

#### Other changes

* `LogWriteException` is now a runtime exception. This exception is still thrown when an error occurs during the
  writing of the Transaction Log.
* One of the signatures of `ITransactionManager.performInTransaction` was removed.