Migration guide v2.7.0

Migrate powsybl-core version to v4.6.0

In this release, powsybl-core version has been updated from version 4.5.1 to 4.6.0. From this release, the base-voltages.yml default file is in powsybl-commons artifact from powsybl-core, instead of in each repository using this configuration class. This allows a unique configuration file across the full powsybl ecosystem. Aside this, no other migration issue should affect you on powsybl-line-diagram. Nonetheless, if you are also using powsybl-core directly, please refer to powsybl-core migration guide to fix any issue due to that migration.

API simplified

Diagram API simplified

In this release, the "Diagram" API has been simplified: classes VoltageLevelDiagram and SubstationDiagram have been removed and replaced by a SingleLineDiagram classes containing only static methods to draw the diagram. For instance, the following example taken from README.md:

ComponentLibrary componentLibrary = new ConvergenceComponentLibrary();
LayoutParameters layoutParameters = new LayoutParameters()
   .setAdaptCellHeightToContent(true)
   .setCssLocation(LayoutParameters.CssLocation.INSERTED_IN_SVG);
VoltageLevelDiagram
   .build(new NetworkGraphBuilder(network), "N", new SmartVoltageLevelLayoutFactory(network), false)
   .writeSvg("",
      new DefaultSVGWriter(componentLibrary, layoutParameters),
      new DefaultDiagramLabelProvider(network, componentLibrary, layoutParameters),
      new TopologicalStyleProvider(network),
      Paths.get("/tmp/n.svg"));

can be replaced by following single line:

SingleLineDiagram.draw(network, "N", "/tmp/n.svg");

This simpler API introduced following changes or new behaviours:

• The parameter useName of diagrams API is now within LayoutParameter. Use LayoutParameter::setUseName to change its value.
• SmartVoltageLevelLayoutFactory is used by default in SingleLineDiagram class.
• TopologicalStyleProvider is used by default in SingleLineDiagram class, hence the class DefaultDiagramStyleProvider has been renamed to BasicStyleProvider.
• The CSS is embedded by default: LayoutParameters::getCssLocation is CssLocation.INSERTED_IN_SVG by default.
• The cell height is adapted to content by default: LayoutParameters::isAdaptCellHeightToContent is true by default.

SVGWriter API simplified

In this release, the SVGWriter interface has been simplified. All methods have been replaced by a single one:

GraphMetadata write(String prefixId, Graph graph, DiagramLabelProvider initProvider, DiagramStyleProvider styleProvider, Writer writer);

If you were using the methods with a Writer this change should be transparent. If you were using the methods with a Path, either use the new SingleLineDiagram API, or create a Writer from your Path.

Layout interfaces merged

Starting from this release, the SubstationLayout, VoltageLevelLayout and ZoneLayoutlayout interfaces have been merged into a single Layout interface.

Replacing ambiguous getters

getNodes

Starting from this release, node keyword is used only for Node class, and not anymore for nodes (meaning vertices) of ZoneGraph and SubstationGraph. Hence the methods SubstationGraph::getNodes and ZoneGraph::getNodes are renamed to Graph::getVoltageLevels and ZoneGraph::getSubstations respectively. A new method has been introduced to access all the nodes corresponding to a graph: Graph::getAllNodesStream.

getGraph

Starting from this release, graph keyword is used only for Graph class, and not anymore for VoltageLevelGraph class (unless when obvious). This way:

• method Node::getGraph has been renamed to Node::getVoltageLevelGraph
• method LBSCluster::getGraph has been renamed to LBSCluster::getVoltageLevelGraph
• method Block::getGraph has been renamed to Block::getVoltageLevelGraph
• method Cell::getGraph has been renamed to Cell::getVoltageLevelGraph

Nonetheless, RawGraphBuilder.VoltageLevelBuilder::getGraph has been kept and RawGraphBuilder.SubstationBuilder::getSsGraph has been replaced by RawGraphBuilder.SubstationBuilder::getGraph, as the substation keyword is already held by the builder class.