Merge branch 'main' into pf_fix_missing_curmg

# Conflicts:
#	powerfactory/powerfactory-dgs/src/test/resources/BOMTest.dgs

Author: geofjamg

action-ial/action-ial-simulator/src/test/java/com/powsybl/action/ial/simulator/tools/SecurityAnalysisResultBuilderTest.java

@@ -34,11 +34,27 @@ private Contingency createContingency() {
     }
 
     private List<LimitViolation> createPreContingencyViolations() {
-        return Collections.singletonList(new LimitViolation("line1", LimitViolationType.CURRENT, "IST", Integer.MAX_VALUE, 0.0, 100f, 101, TwoSides.ONE));
+        return Collections.singletonList(LimitViolation.builder()
+            .subject("line1")
+            .type(LimitViolationType.CURRENT)
+            .limitName("IST")
+            .limit(0.0)
+            .reduction(100f)
+            .value(101)
+            .side(TwoSides.ONE)
+            .build());
     }
 
     private List<LimitViolation> createPostContingencyViolations() {
-        return Collections.singletonList(new LimitViolation("line2", LimitViolationType.CURRENT, "IST", Integer.MAX_VALUE, 0.0, 100f, 110, TwoSides.ONE));
+        return Collections.singletonList(LimitViolation.builder()
+            .subject("line2")
+            .type(LimitViolationType.CURRENT)
+            .limitName("IST")
+            .limit(0.0)
+            .reduction(100f)
+            .value(110)
+            .side(TwoSides.ONE)
+            .build());
     }
 
     private void testLimitViolation(LimitViolationsResult result, boolean convergent, List<String> equipmentsId, List<String> actionsId) {

contingency/contingency-api/src/main/java/com/powsybl/contingency/violations/LimitViolation.java

@@ -60,6 +60,7 @@ public class LimitViolation extends AbstractExtendable<LimitViolation> {
      * @param limitReduction     The limit reduction factor used for violation detection.
      * @param value              The actual value of the physical value which triggered the detection of a violation.
      * @param side               The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
+     * @param voltageLocation    Detailed information about the location of the violation.
      */
     public LimitViolation(String subjectId, @Nullable String subjectName, String operationalLimitsGroupId, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration,
                           double limit, double limitReduction, double value, @Nullable ThreeSides side, @Nullable ViolationLocation voltageLocation) {
@@ -90,7 +91,9 @@ public LimitViolation(String subjectId, @Nullable String subjectName, String ope
      * @param limitReduction     The limit reduction factor used for violation detection.
      * @param value              The actual value of the physical value which triggered the detection of a violation.
      * @param side               The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
+     * @deprecated use {@link LimitViolationBuilder} or {@link LimitViolation#LimitViolation(String, String, String, LimitViolationType, String, int, double, double, double, ThreeSides, ViolationLocation)}
      */
+    @Deprecated(since = "7.3.0", forRemoval = true)
     public LimitViolation(String subjectId, @Nullable String subjectName, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration,
                           double limit, double limitReduction, double value, @Nullable ThreeSides side, @Nullable ViolationLocation voltageLocation) {
         this(subjectId, subjectName, "", limitType, limitName, acceptableDuration, limit, limitReduction, value, side, voltageLocation);
@@ -110,7 +113,9 @@ public LimitViolation(String subjectId, @Nullable String subjectName, LimitViola
      * @param limitReduction     The limit reduction factor used for violation detection.
      * @param value              The actual value of the physical value which triggered the detection of a violation.
      * @param side               The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
+     * @deprecated use {@link LimitViolationBuilder} or {@link LimitViolation#LimitViolation(String, String, String, LimitViolationType, String, int, double, double, double, ThreeSides, ViolationLocation)}
      */
+    @Deprecated(since = "7.3.0", forRemoval = true)
     public LimitViolation(String subjectId, @Nullable String subjectName, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration,
                           double limit, double limitReduction, double value, @Nullable ThreeSides side) {
         this(subjectId, subjectName, limitType, limitName, acceptableDuration, limit, limitReduction, value, side, null);
@@ -129,7 +134,9 @@ public LimitViolation(String subjectId, @Nullable String subjectName, LimitViola
      * @param limit              The value of the limit which has been violated.
      * @param limitReduction     The limit reduction factor used for violation detection.
      * @param value              The actual value of the physical value which triggered the detection of a violation.
+     * @deprecated use {@link LimitViolationBuilder} or {@link LimitViolation#LimitViolation(String, String, String, LimitViolationType, String, int, double, double, double, ThreeSides, ViolationLocation)}
      */
+    @Deprecated(since = "7.3.0", forRemoval = true)
     public LimitViolation(String subjectId, @Nullable String subjectName, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration,
                           double limit, double limitReduction, double value) {
         this(subjectId, subjectName, limitType, limitName, acceptableDuration, limit, limitReduction, value, (ThreeSides) null);
@@ -150,7 +157,9 @@ public LimitViolation(String subjectId, @Nullable String subjectName, LimitViola
      * @param limitReduction     The limit reduction factor used for violation detection.
      * @param value              The actual value of the physical value which triggered the detection of a violation.
      * @param side               The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
+     * @deprecated use {@link LimitViolationBuilder} or {@link LimitViolation#LimitViolation(String, String, String, LimitViolationType, String, int, double, double, double, ThreeSides, ViolationLocation)}
      */
+    @Deprecated(since = "7.3.0", forRemoval = true)
     public LimitViolation(String subjectId, @Nullable String subjectName, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration,
                           double limit, double limitReduction, double value, TwoSides side) {
         this(subjectId, subjectName, limitType, limitName, acceptableDuration, limit, limitReduction, value, Objects.requireNonNull(side).toThreeSides());
@@ -169,7 +178,9 @@ public LimitViolation(String subjectId, @Nullable String subjectName, LimitViola
      * @param limitReduction     The limit reduction factor used for violation detection.
      * @param value              The actual value of the physical value which triggered the detection of a violation.
      * @param side               The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
+     * @deprecated use {@link LimitViolationBuilder} or {@link LimitViolation#LimitViolation(String, String, String, LimitViolationType, String, int, double, double, double, ThreeSides, ViolationLocation)}
      */
+    @Deprecated(since = "7.3.0", forRemoval = true)
     public LimitViolation(String subjectId, LimitViolationType limitType, String limitName, int acceptableDuration,
                           double limit, double limitReduction, double value, TwoSides side) {
         this(subjectId, null, limitType, limitName, acceptableDuration, limit, limitReduction, value, Objects.requireNonNull(side).toThreeSides());
@@ -187,7 +198,9 @@ public LimitViolation(String subjectId, LimitViolationType limitType, String lim
      * @param limit              The value of the limit which has been violated.
      * @param limitReduction     The limit reduction factor used for violation detection.
      * @param value              The actual value of the physical value which triggered the detection of a violation.
+     * @deprecated use {@link LimitViolationBuilder} or {@link LimitViolation#LimitViolation(String, String, String, LimitViolationType, String, int, double, double, double, ThreeSides, ViolationLocation)}
      */
+    @Deprecated(since = "7.3.0", forRemoval = true)
     public LimitViolation(String subjectId, LimitViolationType limitType, String limitName, int acceptableDuration,
                           double limit, double limitReduction, double value) {
         this(subjectId, null, limitType, limitName, acceptableDuration, limit, limitReduction, value, (ThreeSides) null);
@@ -206,7 +219,7 @@ public LimitViolation(String subjectId, LimitViolationType limitType, String lim
      * @param voltageLocation    Detailed information about the location of the violation.
      */
     public LimitViolation(String subjectId, LimitViolationType limitType, double limit, double limitReduction, double value, ViolationLocation voltageLocation) {
-        this(subjectId, null, limitType, null, Integer.MAX_VALUE, limit, limitReduction, value, null, voltageLocation);
+        this(subjectId, null, null, limitType, null, Integer.MAX_VALUE, limit, limitReduction, value, null, voltageLocation);
     }
 
     /**
@@ -220,7 +233,9 @@ public LimitViolation(String subjectId, LimitViolationType limitType, double lim
      * @param limit          The value of the limit which has been violated.
      * @param limitReduction The limit reduction factor used for violation detection.
      * @param value          The actual value of the physical value which triggered the detection of a violation.
+     * @deprecated use {@link LimitViolationBuilder} or {@link LimitViolation#LimitViolation(String, String, String, LimitViolationType, String, int, double, double, double, ThreeSides, ViolationLocation)}
      */
+    @Deprecated(since = "7.3.0", forRemoval = true)
     public LimitViolation(String subjectId, String subjectName, LimitViolationType limitType, double limit, double limitReduction, double value) {
         this(subjectId, subjectName, limitType, null, Integer.MAX_VALUE, limit, limitReduction, value, null, null);
     }
@@ -237,7 +252,9 @@ public LimitViolation(String subjectId, String subjectName, LimitViolationType l
      * @param limitReduction The limit reduction factor used for violation detection.
      * @param value          The actual value of the physical value which triggered the detection of a violation.
      * @param voltageLocation    Detailed information about the location of the violation.
+     * @deprecated use {@link LimitViolationBuilder} or {@link LimitViolation#LimitViolation(String, String, String, LimitViolationType, String, int, double, double, double, ThreeSides, ViolationLocation)}
      */
+    @Deprecated(since = "7.3.0", forRemoval = true)
     public LimitViolation(String subjectId, String subjectName, LimitViolationType limitType, double limit, double limitReduction, double value, ViolationLocation voltageLocation) {
         this(subjectId, subjectName, limitType, null, Integer.MAX_VALUE, limit, limitReduction, value, null, voltageLocation);
     }
@@ -252,11 +269,17 @@ public LimitViolation(String subjectId, String subjectName, LimitViolationType l
      * @param limit          The value of the limit which has been violated.
      * @param limitReduction The limit reduction factor used for violation detection.
      * @param value          The actual value of the physical value which triggered the detection of a violation.
+     * @deprecated use {@link LimitViolationBuilder} or {@link LimitViolation#LimitViolation(String, String, String, LimitViolationType, String, int, double, double, double, ThreeSides, ViolationLocation)}
      */
+    @Deprecated(since = "7.3.0", forRemoval = true)
     public LimitViolation(String subjectId, LimitViolationType limitType, double limit, double limitReduction, double value) {
         this(subjectId, null, limitType, null, Integer.MAX_VALUE, limit, limitReduction, value, null, null);
     }
 
+    public static LimitViolationBuilder builder() {
+        return new LimitViolationBuilder();
+    }
+
     /**
      * The identifier of the network equipment on which the violation occurred.
      *

contingency/contingency-api/src/main/java/com/powsybl/contingency/violations/LimitViolationBuilder.java

@@ -7,6 +7,7 @@
  */
 package com.powsybl.contingency.violations;
 
+import com.powsybl.iidm.network.OperationalLimitsGroup;
 import com.powsybl.iidm.network.ThreeSides;
 import com.powsybl.iidm.network.TwoSides;
 
@@ -27,84 +28,159 @@ public class LimitViolationBuilder {
     private LimitViolationType type;
     private Double limit;
     private String limitName;
-    private Integer duration;
+    private Integer duration = Integer.MAX_VALUE;
     private double reduction = 1.0;
     private Double value;
     private ThreeSides side;
     private ViolationLocation violationLocation;
 
+    /**
+     * @param type The type of limit which has been violated.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder type(LimitViolationType type) {
         this.type = requireNonNull(type);
         return this;
     }
 
+    /**
+     * @param subjectId The identifier of the network equipment on which the violation occurred.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder subject(String subjectId) {
         this.subjectId = requireNonNull(subjectId);
         return this;
     }
 
+    /**
+     * @param subjectName An optional name of the network equipment on which the violation occurred.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder subjectName(String subjectName) {
         this.subjectName = subjectName;
         return this;
     }
 
+    /**
+     * @param id The {@link OperationalLimitsGroup} due to which this violation occurred.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder operationalLimitsGroupId(String id) {
         this.operationalLimitsGroupId = id;
         return this;
     }
 
+    /**
+     * @param location Detailed information about the location of the violation.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder violationLocation(ViolationLocation location) {
         this.violationLocation = location;
         return this;
     }
 
+    /**
+     * @param name An optional name for the limit which has been violated.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder limitName(String name) {
         this.limitName = name;
         return this;
     }
 
+    /**
+     * @param duration The acceptable duration, in seconds, associated to the violation value.
+     *                 Default is {@link Integer#MAX_VALUE}.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder duration(int duration) {
         this.duration = duration;
         return this;
     }
 
+    /**
+     * @param duration The acceptable duration, in <code>unit</code> of time, associated to the violation value.
+     * @param unit the time unit to be used.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder duration(int duration, TimeUnit unit) {
         this.duration = (int) unit.toSeconds(duration);
         return this;
     }
 
+    /**
+     * @param limit The value of the limit which has been violated.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder limit(double limit) {
         this.limit = limit;
         return this;
     }
 
+    /**
+     * @param value The actual value of the physical value which triggered the detection of a violation.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder value(double value) {
         this.value = value;
         return this;
     }
 
+    /**
+     * @param reduction The limit reduction factor used for violation detection.
+     *                  Default is 1.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder reduction(double reduction) {
         this.reduction = reduction;
         return this;
     }
 
+    /**
+     * @param side The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder side(ThreeSides side) {
         this.side = requireNonNull(side);
         return this;
     }
 
+    /**
+     * @param side side The side of the equipment where the violation occurred. May be {@code null} for non-branch, non-three windings transformer equipments.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder side(TwoSides side) {
         return side(requireNonNull(side).toThreeSides());
     }
 
+    /**
+     * Sets the side as {@link ThreeSides#ONE}.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder side1() {
         return side(TwoSides.ONE);
     }
 
+    /**
+     * Sets the side as {@link ThreeSides#TWO}.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder side2() {
         return side(TwoSides.TWO);
     }
 
+    /**
+     * Sets the side as {@link ThreeSides#THREE}.
+     * @return this {@link LimitViolationBuilder}
+     */
+    public LimitViolationBuilder side3() {
+        return side(ThreeSides.THREE);
+    }
+
+    /**
+     * Sets the violation type as {@link LimitViolationType#CURRENT}.
+     * @return this {@link LimitViolationBuilder}
+     */
     public LimitViolationBuilder current() {
         return type(LimitViolationType.CURRENT);
     }