Migration guide v5.0.0

Java 21

powsybl-diagram now only supports Java 21 and higher. Please check that your installed SDK is still compatible.

Network-area diagrams

HVDC line edge type

Starting from this release, in the metadata the type HvdcLineEdge has been replaced by either HvdcLineLccEdge or HvdcLineVscEdge depending on the corresponding converter station type.

Simplifying the SVG

LabelProvider changes

Starting from this release the LabelProvider methods have been refactored as the label provider is called before the graph is fully constructed:

• getEdgeInfo(g, branchEdge, side) has been replaced by getBranchEdgeInfo(branchId, side, branchType)
• getEdgeInfo(g, threeWtEdge) has been replaced by getThreeWindingTransformerEdgeInfo(threeWindingTransformerId, side)
• getEdgeInfo(g, injection) has been replaced by getInjectionEdgeInfo(injectionId)
• getVoltageLevelDescription(VoltageLevelNode n), getVoltageLevelDetails(VoltageLevelNode n) and getBusDescription(BusNode bn) have been renplaced by getVoltageLevelLegend(String voltageLevelId)
• getLabel(Edge e) has been replaced by getBranchLabel(String branchId)
• getArrowPathDIn() is now given by SvgParameters.getArrowPathIn() instead
• getArrowPathDOut() is now given by SvgParameters.getArrowPathOut() instead

SVG structure changes

Starting from this release, the svg structure has changed. Hence, you need to change the CSS rules if you're using some of your own:

• replace .nad-disconnected .nad-edge-path with .nad-disconnected.nad-edge-path
• replace .nad-vlXXXtoYYY.nad-bus-Z with .nad-vlXXXtoYYY .nad-bus-Z
• remove path.nad-arrow-out:not(.nad-state-out .nad-arrow-out) {visibility: hidden}
• remove path.nad-arrow-in:not(.nad-state-in .nad-arrow-in) {visibility: hidden}

As an example, below is a comparison for an edge inside a SVG generated by v4.9.0 / the same edge inside a SVG generated by v5.0.0. Before, both edge polyline and edge infos (arrow, value) were in <g class="nad-branch-edges">:

<g id="25">
    <g id="25.1" class="nad-vl0to30">
        <polyline class="nad-edge-path" points="172.27,-645.72 122.28,-526.91"/>
        <g class="nad-edge-infos" transform="translate(159.67,-615.77)">
            <g class="nad-active">
                <g transform="rotate(-157.18)">
                    <path class="nad-arrow-in" transform="scale(10.00)" d="M-1 -1 H1 L0 1z"/>
                    <path class="nad-arrow-out" transform="scale(10.00)" d="M-1 1 H1 L0 -1z"/>
                </g>
                <text transform="rotate(-67.18)" x="-19.00" style="text-anchor:end">143.2</text>
            </g>
        </g>
    </g>
    <g id="25.2" class="nad-vl0to30">
        <polyline class="nad-edge-path" points="72.29,-408.09 122.28,-526.91"/>
        <g class="nad-edge-infos" transform="translate(84.89,-438.04)">
            <g class="nad-active">
                <g transform="rotate(22.82)">
                    <path class="nad-arrow-in" transform="scale(10.00)" d="M-1 -1 H1 L0 1z"/>
                    <path class="nad-arrow-out" transform="scale(10.00)" d="M-1 1 H1 L0 -1z"/>
                </g>
                <text transform="rotate(-67.18)" x="19.00">-144.5</text>
            </g>
        </g>
    </g>
</g>

After,

1. in <g class="nad-branch-edges">:

<g id="25">
    <polyline class="nad-vl0to30 nad-edge-path" points="172.27,-645.72 122.28,-526.9"/>
    <polyline class="nad-vl0to30 nad-edge-path" points="72.29,-408.09 122.28,-526.91"/>
</g>

2. in <g class="nad-edge-infos">

<g id="16" transform="translate(159.67,-615.77)" class="nad-active">
    <path transform="rotate(-157.18)" class="nad-arrow-in" d="M-10 -10 H10 L0 10z"/>
    <text transform="rotate(-67.18)" x="-19.00" style="text-anchor:end">143.2</text>
</g>
<g id="18" transform="translate(84.89,-438.04)" class="nad-active">
    <path transform="rotate(22.82)" class="nad-arrow-in" d="M-10 -10 H10 L0 10z"/>
    <text transform="rotate(-67.18)" x="19.00">-144.5</text>
</g>

Graph builder changes

All the following breaking changes are only for advanced users of the powsybl-network-area-diagram library, it doesn't affect you if you're using the NetworkAreaDiagram static methods.

• Starting from this release the IdProvider has only one method which takes a String to provide an id, instead of one for Identifiable and one for ThreeWindingTranformer.Leg, and is called several times with the same object as parameter. This is to avoid addding more and more methods giving ids to specific part of the svg (edge infos, text nodes, text edges, ...), knowing that the default and recommended provider is just a counter.
• Starting from this release, if you were constructing the graph based on NetworkGraphBuilder and SvgWriter, you need to adapt your call to their constructors as NetworkGraphBuilder constructor now needs the LabelProvider, whereas SvgWriter does not expect a LabelProvider anymore.
• Starting from this release, if you were constructing the graph based on you own GraphBuilder, you need to adapt your code to following changes:
  • The BranchEdge constructor needs the IdProvider and the (nullable) parameters edgeInfo1, edgeInfo2 and label related to the information displayed on the edge. Similarly the ThreeWtEdge and Injection constructors expect the (nullable) parameter svgEdgeInfo.
  • The VoltageLevelNode constructor needs the IdProvider, a (nullable) legendDiagramId and a list of string for both the legend header and legend footer.
  • The BusNode constructor needs the IdProvider and a (nullable) legend string.