Skip to content

Migration guide v6.5.0

Jump to bottom
Olivier Perrin edited this page Oct 11, 2024 · 18 revisions

Breaking Change Breaking changes for all users

DataSources

New DataSources interfaces

Two types of DataSources based on files now exists:

  • DirectoryDataSource (inherited by GzDirectoryDataSource, Bzip2DirectoryDataSource, ZstdDirectoryDataSource, XZDirectoryDataSource): considers files in a directory
  • AbstractArchiveDataSource (only ZipArchiveDataSource for now but a TarArchiveDataSource could be added later): considers files in an archive.

Therefore, multiple classes have changed, please update your code if you used them directly:

Old classes New classes
Bzip2FileDataSource Bzip2DirectoryDataSource
FileDataSource DirectoryDataSource
GzFileDataSource GzDirectoryDataSource
XZFileDataSource XZDirectoryDataSource
ZipFileDataSource ZipArchiveDataSource
ZstdFileDataSource ZstdDirectoryDataSource

Note: Their constructors are not the same so you will have to adapt your code to the new ones, depending on which DataSource you use.

Adding data extension

Some datasource constructors have changed or have been deleted. Change accordingly:

Old constructor New constructor
Bzip2DirectoryDataSource(Path directory, String baseName, DataSourceObserver observer) or Bzip2DirectoryDataSource(Path directory, String baseName) Bzip2DirectoryDataSource(Path directory, String baseName, String dataExtension, DataSourceObserver observer)
GzDirectoryDataSource(Path directory, String baseName, DataSourceObserver observer) or GzDirectoryDataSource(Path directory, String baseName) GzDirectoryDataSource(Path directory, String baseName, String dataExtension, DataSourceObserver observer)
XZDirectoryDataSource(Path directory, String baseName, DataSourceObserver observer) or XZDirectoryDataSource(Path directory, String baseName) XZDirectoryDataSource(Path directory, String baseName, String dataExtension, DataSourceObserver observer)
ZstdDirectoryDataSource(Path directory, String baseName, DataSourceObserver observer) or ZstdDirectoryDataSource(Path directory, String baseName) ZstdDirectoryDataSource(Path directory, String baseName, String dataExtension, DataSourceObserver observer)
XZDirectoryDataSource(Path directory, String baseName, DataSourceObserver observer) or XzDirectoryDataSource(Path directory, String baseName) XzDirectoryDataSource(Path directory, String baseName, String dataExtension, DataSourceObserver observer)
ZipArchiveDataSource(Path directory, String zipFileName, String baseName, DataSourceObserver observer) ZipArchiveDataSource(Path directory, String zipFileName, String baseName, String dataExtension, DataSourceObserver observer)
ZipArchiveDataSource(Path directory, String zipFileName, String baseName) ZipArchiveDataSource(Path directory, String zipFileName, String baseName, String dataExtension)

"Double" extensions (.iidm.xml, .iidm.json, .iidm.bin) are not anymore considered by the importers. If you used them, please use those instead:

Old double extension Extension to use
.iidm.xml .xiidm
.iidm.json .jiidm
.iidm.bin .biidm

Previously, when providing a filename to a datasource method (exists, newOutputStream, etc.), the datasource compression format extension was always added to the filename. Now it is added to the filename only if the filename doesn't have one already.

CgmesOnDataSource

The following methods of CgmesOnDataSource now throw an IOException:

  • public boolean exists()
  • public boolean existsCim14()

If you call them, you should catch or propagate this exception. To keep the same behavior as before, you can catch this exception and propagate it in a new UncheckedIOException.

CGMES

Clear metadata models supersedes

If you had define a custom CgmesMetadataModel implementation, you need to define a new method: CgmesMetadataModelImpl clearSupersedes().

Network Modifications dry run

Classes extending AbstractNetworkModification now have to implement a new method getName returning the name of the network modification.

Eurostag example network fix

In Eurostag example network, NVH1_XNODE2 dangling line id has been renamed to NHV1_XNODE2.

AbstractToolTest::assertCommand refactor

The two following AbstractToolTest methods have been removed:assertCommand and assertCommandMatchTextOrRegex. Please use instead :

  • for string equality with the command output: assertCommandSuccessful / assertCommandError
  • for string contained in the command output : assertCommandSuccessfulMatch / assertCommandErrorMatch
  • for regex : assertCommandSuccessfulRegex/assertCommandErrorRegex If both standard and error outputs were checked, please use the method assertCommandResult.

ReportNode serialization

When using an ObjectMapper to read a ReportNode, you should not specify the implementation anymore but the interface; for instance:

new ObjectMapper().readValue(inputStream), ReportNodeImpl.class);

becomes

new ObjectMapper().readValue(inputStream), ReportNode.class);

In addition:

  • RootContext has been renamed to TreeContext as while writing the javadoc the tree was always mentioned instead of the root.
  • RootContext.getTimestamp() was moved in TypedValue and now takes a DateTimeFormatter as parameter.

Dynamic simulation OutputVariables

Output variables are replacing the curves in the API starting from this release. Therefore, the following renaming has occurred:

  • Curve renamed to OutputVariable; a curve becomes an OutputVariable with a CURVE OutputType.
  • CurveGroovyExtension renamed to OutputVariableGroovyExtension
  • CurveSupplier renamed to OutputVariablesSupplier
  • GroovyCurvesSupplier renamed to GroovyOutputVariablesSupplier

Moreover, some new methods have been added in the API, which you need to implement in your own dynamic simulation implementation.

  • in DynamicSimulationResult interface: Map<String, Double> getFinalStateValues()
  • in OutputVariable interface:
    • String getModelId()
    • String getVariableName()
    • OutputType getOutputType()

Platform config values for parameters

Providers

  • LoadFlowProvider and ShortCircuitProvider: The method getSpecificParameters(PlatformConfig platformConfig) has been added to enable providers to retrieve parameters with any overrides specified in the platform configuration.
  • Custom Module Configuration: The getModuleConfig(PlatformConfig platformConfig) method must be implemented by all LoadFlowProvider and ShortCircuitProvider implementations to use getSpecificParameters(PlatformConfig platformConfig). This method retrieves configuration details for the specific provider module from the PlatformConfig, allowing for customized behavior based on platform settings.

Importers and Exporters

  • Importers and Exporters (classes annotated with @AutoService(Importer.class) or @AutoService(Exporter.class)) now account for configuration when retrieving parameters with getParameters(). This ensures that parameters account for any platform-specific configuration settings.

For instance:

    @Override
    public List<Parameter> getParameters() {
        return STATIC_PARAMETERS;
    }

should be replaced by:

    @Override
    public List<Parameter> getParameters() {
        return ConfiguredParameter.load(STATIC_PARAMETERS, getFormat(), defaultValueConfig);
    }

If you don't have a defaultValueConfig in your class, you can use ParameterDefaultValueConfig.INSTANCE.

Only if you migrate from v6.5.0-RC1

Stable ids/nodes in ViolationLocation

Only for migrating from 6.5.0-RC1:

  • To retrieve data from a ViolationLocation, you now have to check it's type and cast it in the corresponding implementation.
  • The getBusId() method from BusBreakerViolationLocation is replaced by a getBusIds() method returning the list of the ids of the configured buses instead of the sole id of the merged bus (which is not stable).
  • The getBusbarIds() method from NodeBreakerViolationLocation is replaced by a getNodes() method returning the list of the nodes where the violation was detected. If needed, it is possible to retrieve the list of all concerned busbar sections using the following code:
NodeBreakerViolationLocation vloc = (NodeBreakerViolationLocation) violationLocation;
VoltageLevel vl = network.getVoltageLevel(vloc.getVoltageLevelId());
List<String> busbarSectionIds = vloc.getNodes().stream()
        .map(node -> vl.getNodeBreakerView().getTerminal(node))
        .filter(Objects::nonNull)
        .map(Terminal::getConnectable)
        .filter(t -> t.getType() == IdentifiableType.BUSBAR_SECTION)
        .map(Identifiable::getId)
        .toList();

Custom IIDM Impl Notice for custom IIDM implementations maintainers

Tap changer neutral position

This is not really a breaking change, but a TCK test was added and so, the maintainers of a custom IIDM implementation must make sure that the neutralPosition of the TapChanger is correctly updated when using a stepsReplacer on the TapChanger or this new test will fail.

Setter for temporary limits

Custom IIDM implementation maintainers should implement:

  • LoadingLimits.setTemporaryLimitValue(int acceptableDuration, double temporaryLimitValue)

Flatten network

Custom IIDM implementation maintainers should add the following method in their Network implementations:

  • Network.flatten().
Clone this wiki locally