Migration guide v2.5.0

Remove deprecated cim1 modules

The modules cim1-converter and cim1-model were deleted in this version. In order to import CIM14 files, now use the CGMES converter with the modules cgmes-conversion and cgmes-model. They handle the modeling and conversion of CIM14 and CIM16 files.

Remove generics from the ContingenciesProviderFactory interface

The create methods in ContingenciesProviderFactory interface do not return generic types anymore. It can be an issue if the generic type is explicit in the method call:

class MyContingenciesProviderImpl implements ContingenciesProvider {
  ... // code
}

public void myMethod() {
  ContingenciesProviderFactory factory = ... // creation of an instance of ContingenciesProviderFactory

  // error in this version
  MyContingenciesProviderImpl myContingenciesProviderImpl = factory.<MyContingenciesProviderImpl>create(); 
}

As a workaround, you can either try to cast as your wanted type if possible:

class MyContingenciesProviderImpl implements ContingenciesProvider {
  ... // code
}

public void myMethod() {
  ContingenciesProviderFactory factory = ... // creation of an instance of ContingenciesProviderFactory

  // no error if this is indeed a MyContingenciesProviderImpl instance
  MyContingenciesProviderImpl myContingenciesProviderImpl = (MyContingenciesProviderImpl) factory.create(); 
}

or explicitly create an implementation of ContingenciesProviderFactory whose create method returns MyContingenciesProviderImpl:

class MyContingenciesProviderImpl implements ContingenciesProvider {
  ... // code
}

class MyContingenciesProviderFactoryImpl implements ContingenciesProviderFactory {
  @Override
  public MyContingenciesProviderImpl create() {
      ... // code creating and returning an instance of MyContingenciesProviderImpl
  }
  ... // code
}

public void myMethod() {
  MyContingenciesProviderFactoryImpl factory = ... // creation of an instance of MyContingenciesProviderFactoryImpl

  // no error
  MyContingenciesProviderImpl myContingenciesProviderImpl = factory.create(); 
}

Remove deprecated newShunt, getShunts and getShuntStream methods

The methods getShunts and getShuntStream of the Bus interface and the methods newShunt, getShunts and getShuntStream of the VoltageLevel interface are now deleted. Respectively use:

• bus.getShuntCompensators() instead of bus.getShunts()
• bus.getShuntCompensatorStream() instead of bus.getShuntStream()
• voltageLevel.newShuntCompensator() instead of voltageLevel.newShunt()
• voltageLevel.getShuntCompensators() instead of voltageLevel.getShunts()
• voltageLevel.getShuntCompensatorStream() instead of voltageLevel.getShuntStream()

Exception thrown if format is not supported

Before this version, the Networks.loadNetwork() returns null if no compatible importer is found in the class path. A NullPointerException might be thrown if the developer forgot to check if the Network was null.

From this version, a PowsyblException is thrown.

In the following example, the test is not needed anymore.

Network network = Importers.loadNetwork(caseFile, context.getShortTimeExecutionComputationManager(), importConfig, inputParams);
if (network == null) {
    throw new PowsyblException("Case '" + caseFile + "' not found");
}

Countries are optional

For fictitious substations (XNodes, tutorials, fictitious networks...), we had to set the country of substations to an arbitrary value. From this version, the country is an optional. We chose to break the Substation API to avoid returning an arbitrary value (valid country or null value) and generate side effects in the existing codes. The existing code is responsible to deal with optional countries.

The following code:

Country country = substation.getCountry();

can be replaced by one of the following lines:

// If null values are allowed
Country country1 = substation.getCountry().orElse(null);

// If null values are not allowed
Country country = substation.getCountry().orElseThrow(() -> new RuntimeException());

Matrix API has changed

Several methods of the Matrix interface have been deprecated and will be removed in a next version. You can change your code to use the new API, and avoid compilation issue. Respectively use:

• matrix.getRowCount() instead of matrix.getM()
• matrix.getColumnCount() instead of matrix.getN()
• matrix.get() instead of matrix.getValue()
• matrix.set() instead of matrix.setValue()
• matrix.add() instead of matrix.addValue()

Security analysis API has changed

The LimitViolationDetector implementations have been moved to the new com.powsybl.security.detectors package. The existing classes have been deprecated and will be removed in a next version.

The DistributedSecurityAnalysis and ExternalSecurityAnalysis have been deprecated and will be removed in a next version. Respectively use DistributedSecurityAnalysisExecution and ForwardedSecurityAnalysisExecution instead. The SecurityAnalysisExecutionInput and SecurityAnalysisExecution classes have been created to clearly separate the inputs from the execution mode of the security analysis.

We also add the SecurityAnalysisExecutionHandlers utility class to create the SecurityAnalysisExecution instance in distributed or forwarded mode.

check methods in module loadflow-validation are not static anymore

In this version, check methods in loadflow-validation are not static anymore. For example, instead of:

FlowsValidation.checkFlows(network, config, writer);

use:

FlowsValidation.INSTANCE.checkFlows(network, config, writer);

The java classes affected by this change are:

• BusesValidation
• FlowsValidation
• GeneratorsValidation
• ShuntCompensatorsValidation
• StaticVarCompensatorsValidation
• Transformers3WValidation
• TransformersValidation