Operational limits group

iidm/iidm-api/src/main/java/com/powsybl/iidm/network/Branch.java

@@ -7,7 +7,6 @@
 package com.powsybl.iidm.network;
 
 import java.util.Collection;
-import java.util.Collections;
 import java.util.Optional;
 
 /**
@@ -116,52 +115,260 @@ public interface Branch<I extends Branch<I>> extends Identifiable<I> {
 
     TwoSides getSide(Terminal terminal);
 
-    default Collection<OperationalLimits> getOperationalLimits1() {
-        return getCurrentLimits1()
-                .map(l -> Collections.singletonList((OperationalLimits) l))
-                .orElseGet(Collections::emptyList);
-    }
+    /**
+     * Get the collection of the defined {@link OperationalLimitsGroup} on side 1.
+     * @return the {@link OperationalLimitsGroup} s on side 1.
+     */
+    Collection<OperationalLimitsGroup> getOperationalLimitsGroups1();
+
+    /**
+     * Get the {@link OperationalLimitsGroup} corresponding to an ID on side 1.
+     * @return the {@link OperationalLimitsGroup} of the given ID on side 1 if any, an empty {@link Optional} otherwise.
+     */
+    Optional<String> getSelectedOperationalLimitsGroupId1();
+
+    /**
+     * Get the {@link OperationalLimitsGroup} corresponding to an ID on side 1.
+     * @return the {@link OperationalLimitsGroup} of the given ID on side 1 if any, an empty {@link Optional} otherwise.
+     */
+    Optional<OperationalLimitsGroup> getOperationalLimitsGroup1(String id);
+
+    /**
+     * Get the selected {@link OperationalLimitsGroup} on side 1.
+     * @return the selected {@link OperationalLimitsGroup} on side 1 if any, an empty {@link Optional} otherwise.
+     */
+    Optional<OperationalLimitsGroup> getSelectedOperationalLimitsGroup1();
+
+    /**
+     * <p>Create a new {@link OperationalLimitsGroup} on side 1 with the given ID.</p>
+     * <p>If a group of the given ID already exists, it is replaced silently.</p>
+     * @return the newly created group {@link OperationalLimitsGroup}.
+     */
+    OperationalLimitsGroup newOperationalLimitsGroup1(String id);
+
+    /**
+     * <p>Set the {@link OperationalLimitsGroup} corresponding to the given ID as as the selected one on side 1.</p>
+     * <p>Throw a {@link com.powsybl.commons.PowsyblException} if the ID doesn't correspond to any existing group.</p>
+     * <p>Throw an {@link NullPointerException} if the ID is <code>null</code>.
+     * To reset the selected group, use {@link #cancelSelectedOperationalLimitsGroup1}.</p>
+     * @param id an ID of {@link OperationalLimitsGroup}
+     */
+    void setSelectedOperationalLimitsGroup1(String id);
+
+    /**
+     * <p>Remove the {@link OperationalLimitsGroup} corresponding to the given ID on side 1.</p>
+     * <p>Throw an {@link NullPointerException} if the ID is <code>null</code>.
+     * @param id an ID of {@link OperationalLimitsGroup}
+     */
+    void removeOperationalLimitsGroup1(String id);
+
+    /**
+     * <p>Cancel the selected {@link OperationalLimitsGroup} on side 1.</p>
+     * <p>After calling this method, no {@link OperationalLimitsGroup} is selected on side 1.</p>
+     */
+    void cancelSelectedOperationalLimitsGroup1();
 
-    Optional<CurrentLimits> getCurrentLimits1();
+    /**
+     * Get the {@link CurrentLimits} of the selected {@link OperationalLimitsGroup} on side 1.
+     * @return {@link CurrentLimits} of the selected {@link OperationalLimitsGroup} on side 1 if any, <code>null</code> otherwise.
+     */
+    default Optional<CurrentLimits> getCurrentLimits1() {
+        return getSelectedOperationalLimitsGroup1().flatMap(OperationalLimitsGroup::getCurrentLimits);
+    }
 
-    CurrentLimits getNullableCurrentLimits1();
+    /**
+     * Get the {@link CurrentLimits} of the selected {@link OperationalLimitsGroup} on side 1.
+     * @return {@link CurrentLimits} of the selected {@link OperationalLimitsGroup} on side 1 if any, <code>null</code> otherwise.
+     */
+    default CurrentLimits getNullableCurrentLimits1() {
+        return getCurrentLimits1().orElse(null);
+    }
 
-    Optional<ActivePowerLimits> getActivePowerLimits1();
+    /**
+     * Get the {@link ActivePowerLimits} of the selected {@link OperationalLimitsGroup} on side 1.
+     * @return {@link ActivePowerLimits} of the selected {@link OperationalLimitsGroup} on side 1 if any, an empty {@link Optional} otherwise.
+     */
+    default Optional<ActivePowerLimits> getActivePowerLimits1() {
+        return getSelectedOperationalLimitsGroup1().flatMap(OperationalLimitsGroup::getActivePowerLimits);
+    }
 
-    ActivePowerLimits getNullableActivePowerLimits1();
+    /**
+     * Get the {@link ActivePowerLimits} of the selected {@link OperationalLimitsGroup} on side 1.
+     * @return {@link ActivePowerLimits} of the selected {@link OperationalLimitsGroup} on side 1 if any, <code>null</code> otherwise.
+     */
+    default ActivePowerLimits getNullableActivePowerLimits1() {
+        return getActivePowerLimits1().orElse(null);
+    }
 
-    Optional<ApparentPowerLimits> getApparentPowerLimits1();
+    /**
+     * Get the {@link ApparentPowerLimits} of the selected {@link OperationalLimitsGroup} on side 1.
+     * @return {@link ApparentPowerLimits} of the selected {@link OperationalLimitsGroup} on side 1 if any, an empty {@link Optional} otherwise.
+     */
+    default Optional<ApparentPowerLimits> getApparentPowerLimits1() {
+        return getSelectedOperationalLimitsGroup1().flatMap(OperationalLimitsGroup::getApparentPowerLimits);
+    }
 
-    ApparentPowerLimits getNullableApparentPowerLimits1();
+    /**
+     * Get the {@link ApparentPowerLimits} of the selected {@link OperationalLimitsGroup} on side 1.
+     * @return {@link ApparentPowerLimits} of the selected {@link OperationalLimitsGroup} on side 1 if any, <code>null</code> otherwise.
+     */
+    default ApparentPowerLimits getNullableApparentPowerLimits1() {
+        return getApparentPowerLimits1().orElse(null);
+    }
 
+    /**
+     * <p>Create an adder to add a new {@link CurrentLimits} in the selected {@link OperationalLimitsGroup} on side 1.</p>
+     * <p>If there's no selected group, the adder will also create a new group with the default name and set it as selected.
+     * This operation is performed when the limits are created via {@link CurrentLimitsAdder#add()}, only if the limits to add
+     * are valid.</p>
+     * @return an adder allowing to create a new {@link CurrentLimits} in the selected {@link OperationalLimitsGroup} on side 1.
+     */
     CurrentLimitsAdder newCurrentLimits1();
 
+    /**
+     * <p>Create an adder to add a new {@link ActivePowerLimits} in the selected {@link OperationalLimitsGroup} on side 1.</p>
+     * <p>If there's no selected group, the adder will also create a new group with the default name and set it as selected.
+     * This operation is performed when the limits are created via {@link CurrentLimitsAdder#add()}, only if the limits to add
+     * are valid.</p>
+     * @return an adder allowing to create a new {@link ActivePowerLimits} in the selected {@link OperationalLimitsGroup} on side 1.
+     */
     ActivePowerLimitsAdder newActivePowerLimits1();
 
+    /**
+     * <p>Create an adder to add a new {@link ApparentPowerLimits} in the selected {@link OperationalLimitsGroup} on side 1.</p>
+     * <p>If there's no selected group, the adder will also create a new group with the default name and set it as selected.
+     * This operation is performed when the limits are created via {@link CurrentLimitsAdder#add()}, only if the limits to add
+     * are valid.</p>
+     * @return an adder allowing to create a new {@link ApparentPowerLimits} in the selected {@link OperationalLimitsGroup} on side 1.
+     */
     ApparentPowerLimitsAdder newApparentPowerLimits1();
 
-    default Collection<OperationalLimits> getOperationalLimits2() {
-        return getCurrentLimits2()
-                .map(l -> Collections.singletonList((OperationalLimits) l))
-                .orElseGet(Collections::emptyList);
-    }
+    /**
+     * Get the collection of the defined {@link OperationalLimitsGroup} on side 2.
+     * @return the {@link OperationalLimitsGroup} s on side 2.
+     */
+    Collection<OperationalLimitsGroup> getOperationalLimitsGroups2();
+
+    /**
+     * Get the {@link OperationalLimitsGroup} corresponding to an ID on side 2.
+     * @return the {@link OperationalLimitsGroup} of the given ID on side 2 if any, an empty {@link Optional} otherwise.
+     */
+    Optional<String> getSelectedOperationalLimitsGroupId2();
+
+    /**
+     * Get the {@link OperationalLimitsGroup} corresponding to an ID on side 2.
+     * @return the {@link OperationalLimitsGroup} of the given ID on side 2 if any, an empty {@link Optional} otherwise.
+     */
+    Optional<OperationalLimitsGroup> getOperationalLimitsGroup2(String id);
+
+    /**
+     * Get the selected {@link OperationalLimitsGroup} on side 2.
+     * @return the selected {@link OperationalLimitsGroup} on side 2 if any, an empty {@link Optional} otherwise.
+     */
+    Optional<OperationalLimitsGroup> getSelectedOperationalLimitsGroup2();
+
+    /**
+     * <p>Create a new {@link OperationalLimitsGroup} on side 2 with the given ID.</p>
+     * <p>If a group of the given ID already exists, it is replaced silently.</p>
+     * @return the newly created group {@link OperationalLimitsGroup}.
+     */
+    OperationalLimitsGroup newOperationalLimitsGroup2(String id);
+
+    /**
+     * <p>Set the {@link OperationalLimitsGroup} corresponding to the given ID as as the selected one on side 2.</p>
+     * <p>Throw a {@link com.powsybl.commons.PowsyblException} if the ID doesn't correspond to any existing group.</p>
+     * <p>Throw an {@link NullPointerException} if the ID is <code>null</code>.
+     * To reset the selected group, use {@link #cancelSelectedOperationalLimitsGroup2}.</p>
+     * @param id an ID of {@link OperationalLimitsGroup}
+     */
+    void setSelectedOperationalLimitsGroup2(String id);
+
+    /**
+     * <p>Remove the {@link OperationalLimitsGroup} corresponding to the given ID on side 2.</p>
+     * <p>Throw an {@link NullPointerException} if the ID is <code>null</code>.
+     * @param id an ID of {@link OperationalLimitsGroup}
+     */
+    void removeOperationalLimitsGroup2(String id);
+
+    /**
+     * <p>Cancel the selected {@link OperationalLimitsGroup} on side 2.</p>
+     * <p>After calling this method, no {@link OperationalLimitsGroup} is selected on side 2.</p>
+     */
+    void cancelSelectedOperationalLimitsGroup2();
 
-    Optional<CurrentLimits> getCurrentLimits2();
+    /**
+     * Get the {@link CurrentLimits} of the selected {@link OperationalLimitsGroup} on side 2.
+     * @return {@link CurrentLimits} of the selected {@link OperationalLimitsGroup} on side 2 if any, <code>null</code> otherwise.
+     */
+    default Optional<CurrentLimits> getCurrentLimits2() {
+        return getSelectedOperationalLimitsGroup2().flatMap(OperationalLimitsGroup::getCurrentLimits);
+    }
 
-    CurrentLimits getNullableCurrentLimits2();
+    /**
+     * Get the {@link CurrentLimits} of the selected {@link OperationalLimitsGroup} on side 2.
+     * @return {@link CurrentLimits} of the selected {@link OperationalLimitsGroup} on side 2 if any, <code>null</code> otherwise.
+     */
+    default CurrentLimits getNullableCurrentLimits2() {
+        return getCurrentLimits2().orElse(null);
+    }
 
-    Optional<ActivePowerLimits> getActivePowerLimits2();
+    /**
+     * Get the {@link ActivePowerLimits} of the selected {@link OperationalLimitsGroup} on side 2.
+     * @return {@link ActivePowerLimits} of the selected {@link OperationalLimitsGroup} on side 2 if any, an empty {@link Optional} otherwise.
+     */
+    default Optional<ActivePowerLimits> getActivePowerLimits2() {
+        return getSelectedOperationalLimitsGroup2().flatMap(OperationalLimitsGroup::getActivePowerLimits);
+    }
 
-    ActivePowerLimits getNullableActivePowerLimits2();
+    /**
+     * Get the {@link ActivePowerLimits} of the selected {@link OperationalLimitsGroup} on side 2.
+     * @return {@link ActivePowerLimits} of the selected {@link OperationalLimitsGroup} on side 2 if any, <code>null</code> otherwise.
+     */
+    default ActivePowerLimits getNullableActivePowerLimits2() {
+        return getActivePowerLimits2().orElse(null);
+    }
 
-    Optional<ApparentPowerLimits> getApparentPowerLimits2();
+    /**
+     * Get the {@link ApparentPowerLimits} of the selected {@link OperationalLimitsGroup} on side 2.
+     * @return {@link ApparentPowerLimits} of the selected {@link OperationalLimitsGroup} on side 2 if any, an empty {@link Optional} otherwise.
+     */
+    default Optional<ApparentPowerLimits> getApparentPowerLimits2() {
+        return getSelectedOperationalLimitsGroup2().flatMap(OperationalLimitsGroup::getApparentPowerLimits);
+    }
 
-    ApparentPowerLimits getNullableApparentPowerLimits2();
+    /**
+     * Get the {@link ApparentPowerLimits} of the selected {@link OperationalLimitsGroup} on side 2.
+     * @return {@link ApparentPowerLimits} of the selected {@link OperationalLimitsGroup} on side 2 if any, <code>null</code> otherwise.
+     */
+    default ApparentPowerLimits getNullableApparentPowerLimits2() {
+        return getApparentPowerLimits2().orElse(null);
+    }
 
+    /**
+     * <p>Create an adder to add a new {@link CurrentLimits} in the selected {@link OperationalLimitsGroup} on side 2.</p>
+     * <p>If there's no selected group, the adder will also create a new group with the default name and set it as selected.
+     * This operation is performed when the limits are created via {@link CurrentLimitsAdder#add()}, only if the limits to add
+     * are valid.</p>
+     * @return an adder allowing to create a new {@link CurrentLimits} in the selected {@link OperationalLimitsGroup} on side 2.
+     */
     CurrentLimitsAdder newCurrentLimits2();
 
+    /**
+     * <p>Create an adder to add a new {@link ActivePowerLimits} in the selected {@link OperationalLimitsGroup} on side 2.</p>
+     * <p>If there's no selected group, the adder will also create a new group with the default name and set it as selected.
+     * This operation is performed when the limits are created via {@link CurrentLimitsAdder#add()}, only if the limits to add
+     * are valid.</p>
+     * @return an adder allowing to create a new {@link ActivePowerLimits} in the selected {@link OperationalLimitsGroup} on side 2.
+     */
     ActivePowerLimitsAdder newActivePowerLimits2();
 
+    /**
+     * <p>Create an adder to add a new {@link ApparentPowerLimits} in the selected {@link OperationalLimitsGroup} on side 2.</p>
+     * <p>If there's no selected group, the adder will also create a new group with the default name and set it as selected.
+     * This operation is performed when the limits are created via {@link CurrentLimitsAdder#add()}, only if the limits to add
+     * are valid.</p>
+     * @return an adder allowing to create a new {@link ApparentPowerLimits} in the selected {@link OperationalLimitsGroup} on side 2.
+     */
     ApparentPowerLimitsAdder newApparentPowerLimits2();
 
     default Optional<CurrentLimits> getCurrentLimits(TwoSides side) {