refactor(#110): Create interface for Services and replace static methods with instance methods

closes #110

BREAKING CHANGE: 💥 in sct-commons:
  The services which provide static methods are moved from scl to commons package.
  Now  those services implements interfaces, no static methods.
  Expect for PrivateService which is an UtilityClass is renamed to PrivateUtils and moved from scl to util package.

Signed-off-by: Samir Romdhani <[email protected]>

refactor(#110): give PrivateService the new name PrivateUtils and change the package from scl to util.

Changing the name of PrivateService to PrivateUtils and move it from scl to util package , closes #110

refactor(#110): update SclAutomationService

Signed-off-by: Samir Romdhani <[email protected]>

refactor(#110): check review part1

use @requiredargsconstructor, instead of @NoArgsConstructor.
use Camel case for PrivateLinkedToStds

Signed-off-by: Samir Romdhani <[email protected]>

refactor(#110): check review part2 [use mockito properly]

Remove unused test package.
Use latest version of mockito.
Fix related to version 5.4.0

Signed-off-by: Samir Romdhani <[email protected]>

refactor(#110): review part3 [naming] remove prefix 'I' and add suffix 'Editor'

The interfaces are moved from scl to api package.

add package doc

Signed-off-by: Samir Romdhani <[email protected]>

refactor(#110): review part4 [seperate SclService features ]

SclEditor (interface) spec are reduced by adding ReadOnly and Write One

Signed-off-by: Samir Romdhani <[email protected]>

refactor(#110): sonar review

Signed-off-by: Samir Romdhani <[email protected]>

docs(#110): update demo project and quickstart page

Signed-off-by: Samir Romdhani <[email protected]>

Author: samirromdhani

docs/QUICK_START.md

@@ -1,4 +1,4 @@
-<!-- SPDX-FileCopyrightText: 2022 RTE FRANCE -->
+<!-- SPDX-FileCopyrightText: 2022 2023 RTE FRANCE -->
 <!-- -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 # CoMPAS SCT (Substation Configuration Tool)
@@ -17,13 +17,13 @@ First you need to add following dependencies to the pom.xml of your repository.
 <dependency>
     <groupId>org.lfenergy.compas</groupId>
     <artifactId>sct-commons</artifactId>
-    <version>0.1.0</version>
+    <version>0.2.12</version>
 </dependency>
 <!-- SclAutomationService -->
 <dependency>
     <groupId>org.lfenergy.compas</groupId>
     <artifactId>sct-app</artifactId>
-    <version>0.1.0</version>
+    <version>0.2.12</version>
 </dependency>
 ```
 Actually there are 4 packages available:
@@ -37,15 +37,20 @@ Actually there are 4 packages available:
 Now that you have your **compas-sct** dependency set, you can start communicating with Commons SCT services.
 
 **sct-commons** provides a collection of services to help you build SCL files for a range of use cases.
+
 Following services provides needed functions compliant with IEC 61850 :
 
-1. **SclService**
-2. **SubstationService**
+1. **SclEditorService**
+2. **SclElementsProviderService**
+3. **SubstationService**
+4. **ExtRefService**
+5. **HmiService**
 
 Let's start with a simple **SclService** call
 
 ```java
-var scl = SclService.initScl(Optional.empty(), "1.0", "1.0");
+SclEditor sclEditorService = new SclEditorService();
+SCL scl = sclEditorService.initScl(UUID.randomUUID(), "1.0", "1.0");
 marshaller.marshal(scl.getCurrentElem(), System.out);
 ```
 
@@ -78,11 +83,15 @@ Start it by using existing files of type `SSD` and `STD` and
 running the following :
 
 ```java
-// ssd : SSD 
-// std : STD 
+// ssd : SCL object represent an SSD file
+// std : SCL object represent an STD file
+SclEditor sclService = new SclEditorService();
+SubstationEditor substationService = new SubstationService();
 HeaderDTO headerDTO = new HeaderDTO(UUID.randomUUID(), "1.0", "1.0");
-var scl = SclAutomationService.createSCD(ssd, headerDTO, Set.of(std));
-marshaller.marshal(scl.getCurrentElem(), System.out);
+
+SclAutomationService sclAutomationService = new SclAutomationService(sclService, substationService);
+SCL scl = sclAutomationService.createSCD(ssd, headerDTO, List.of(std));
+marshaller.marshal(scl, System.out);
 ```
 When the command completes, it prints XML output representing completed **SCL** file.
 Its structure resembles the following:

docs/examples/example-app/pom.xml

@@ -18,9 +18,9 @@ SPDX-License-Identifier: Apache-2.0
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.source>11</maven.compiler.source>
-    <maven.compiler.target>11</maven.compiler.target>
-    <maven.compiler.release>11</maven.compiler.release>
+    <maven.compiler.source>17</maven.compiler.source>
+    <maven.compiler.target>17</maven.compiler.target>
+    <maven.compiler.release>17</maven.compiler.release>
   </properties>
 
   <distributionManagement>
@@ -44,13 +44,13 @@ SPDX-License-Identifier: Apache-2.0
     <dependency>
       <groupId>org.lfenergy.compas</groupId>
       <artifactId>sct-commons</artifactId>
-      <version>0.1.0</version>
+      <version>0.2.12</version>
     </dependency>
     <!-- SclAutomationService -->
     <dependency>
       <groupId>org.lfenergy.compas</groupId>
       <artifactId>sct-app</artifactId>
-      <version>0.1.0</version>
+      <version>0.2.12</version>
     </dependency>
     <dependency>
       <groupId>org.junit.jupiter</groupId>

docs/examples/example-app/src/main/java/org/lfenergy/compas/sct/examples/SctAppExample.java

@@ -1,32 +1,33 @@
-// SPDX-FileCopyrightText: 2022 RTE FRANCE
+// SPDX-FileCopyrightText: 2022 2023 RTE FRANCE
 //
 // SPDX-License-Identifier: Apache-2.0
 
 package org.lfenergy.compas.sct.examples;
 
 import org.lfenergy.compas.scl2007b4.model.SCL;
-import org.lfenergy.compas.sct.commons.scl.SclRootAdapter;
-import org.lfenergy.compas.sct.commons.scl.SclService;
+import org.lfenergy.compas.sct.commons.SclEditorService;
+import org.lfenergy.compas.sct.commons.api.SclEditor;
 
 import javax.xml.bind.JAXBContext;
 import javax.xml.bind.JAXBException;
 import javax.xml.bind.Marshaller;
-import java.util.Optional;
 import java.util.UUID;
 
 public class SctAppExample {
 
+    private static final SclEditor sclEditor = new SclEditorService();
+
     public static void main( String[] args ) throws JAXBException {
-        initSclWithSclService(Optional.empty(), "1.0", "1.0");
+        initSclWithSclService(UUID.randomUUID(), "1.0", "1.0");
     }
 
-    public static SclRootAdapter initSclWithSclService(Optional<UUID> hId, String hVersion, String hRevision) throws JAXBException {
-        SclRootAdapter scl = SclService.initScl(hId, hVersion, hRevision);
-        marshaller.marshal(scl.getCurrentElem(), System.out);
+    public static SCL initSclWithSclService(UUID hId, String hVersion, String hRevision) throws JAXBException {
+        SCL scl = sclEditor.initScl(hId, hVersion, hRevision);
+        marshaller.marshal(scl, System.out);
         return scl;
     }
 
-    private static Marshaller marshaller;
+    private static final Marshaller marshaller;
     static{
         try {
             JAXBContext context = JAXBContext.newInstance(SCL.class);

docs/examples/example-app/src/test/java/org/lfenergy/compas/sct/examples/SctAppExampleTest.java

@@ -10,38 +10,36 @@
 
 import javax.xml.bind.JAXBException;
 import java.util.List;
-import java.util.Optional;
 import java.util.UUID;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.assertj.core.api.Assertions.assertThat;
 
 
-public class SctAppExampleTest {
+class SctAppExampleTest {
 
     @Test
-    public void initSclWithSclServiceTest() throws JAXBException {
+    void initSclWithSclServiceTest() throws JAXBException {
         // Given : Header attributes
-        Optional<UUID> headerId = Optional.of(UUID.randomUUID());
+        UUID headerId = UUID.randomUUID();
         String headerVersion = SclRootAdapter.VERSION;
         String headerRevision = SclRootAdapter.REVISION;
         // When: Sct Service
-        SclRootAdapter scl = SctAppExample
-                .initSclWithSclService(headerId, headerVersion, headerRevision);
+        SCL scl = SctAppExample.initSclWithSclService(headerId, headerVersion, headerRevision);
         // Then
-        assertNotNull(scl.getCurrentElem().getHeader());
-        assertEquals(headerId.get().toString(), scl.getCurrentElem().getHeader().getId());
-        assertEquals(headerVersion, scl.getCurrentElem().getHeader().getVersion());
-        assertEquals(headerRevision, scl.getCurrentElem().getHeader().getRevision());
-        THeader.History history = scl.getCurrentElem().getHeader().getHistory();
-        List<TSubstation> substations = scl.getCurrentElem().getSubstation();
-        TCommunication communication = scl.getCurrentElem().getCommunication();
-        List<TIED> iedList = scl.getCurrentElem().getIED();
-        TDataTypeTemplates dataTypeTemplates = scl.getCurrentElem().getDataTypeTemplates();
-        assertNull(history);
-        assertEquals(0, substations.size());
-        assertNull(communication);
-        assertEquals(0, iedList.size());
-        assertNull(dataTypeTemplates);
+        assertThat(scl.getHeader()).isNotNull();
+        assertThat(scl.getHeader().getId()).isEqualTo(headerId.toString());
+        assertThat(scl.getHeader().getVersion()).isEqualTo(headerVersion);
+        assertThat(scl.getHeader().getRevision()).isEqualTo(headerRevision);
+        THeader.History history = scl.getHeader().getHistory();
+        List<TSubstation> substations = scl.getSubstation();
+        TCommunication communication = scl.getCommunication();
+        List<TIED> iedList = scl.getIED();
+        TDataTypeTemplates dataTypeTemplates = scl.getDataTypeTemplates();
+        assertThat(history).isNull();
+        assertThat(substations).isEmpty();
+        assertThat(communication).isNull();
+        assertThat(iedList).isEmpty();
+        assertThat(dataTypeTemplates).isNull();
     }
 
 }

pom.xml

@@ -44,6 +44,7 @@
         <logback-classic.version>1.4.5</logback-classic.version>
         <assertj.version>3.22.0</assertj.version>
         <lombok.version>1.18.24</lombok.version>
+        <mockito.version>5.5.0</mockito.version>
         <jackson-databind.version>2.13.4.1</jackson-databind.version>
     </properties>
 
@@ -78,6 +79,18 @@
                 <version>${junit-version}</version>
                 <scope>test</scope>
             </dependency>
+            <dependency>
+                <groupId>org.mockito</groupId>
+                <artifactId>mockito-core</artifactId>
+                <version>${mockito.version}</version>
+                <scope>test</scope>
+            </dependency>
+            <dependency>
+                <groupId>org.mockito</groupId>
+                <artifactId>mockito-junit-jupiter</artifactId>
+                <version>${mockito.version}</version>
+                <scope>test</scope>
+            </dependency>
             <dependency>
                 <groupId>org.lfenergy.compas.core</groupId>
                 <artifactId>scl-extension</artifactId>

sct-app/pom.xml

@@ -58,6 +58,14 @@
             <groupId>org.assertj</groupId>
             <artifactId>assertj-core</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-junit-jupiter</artifactId>
+        </dependency>
     </dependencies>
     <build>
         <plugins>

sct-app/src/main/java/org/lfenergy/compas/sct/app/SclAutomationService.java

@@ -5,13 +5,14 @@
 package org.lfenergy.compas.sct.app;
 
 import lombok.NonNull;
+import lombok.RequiredArgsConstructor;
 import org.lfenergy.compas.scl2007b4.model.SCL;
+import org.lfenergy.compas.sct.commons.api.SclEditor;
+import org.lfenergy.compas.sct.commons.api.SubstationEditor;
 import org.lfenergy.compas.sct.commons.dto.HeaderDTO;
 import org.lfenergy.compas.sct.commons.dto.SubNetworkDTO;
 import org.lfenergy.compas.sct.commons.dto.SubNetworkTypeDTO;
 import org.lfenergy.compas.sct.commons.exception.ScdException;
-import org.lfenergy.compas.sct.commons.scl.SclService;
-import org.lfenergy.compas.sct.commons.scl.SubstationService;
 
 import java.util.*;
 
@@ -24,8 +25,12 @@
  *   <li>{@link SclAutomationService#createSCD(SCL, HeaderDTO, List) Adds all elements under the <b>SCL </b> object from given <b>SSD </b> and <b>STD </b> files}
  *  </ul>
  */
+@RequiredArgsConstructor
 public class SclAutomationService {
 
+    private final SclEditor sclEditor;
+    private final SubstationEditor substationEditor;
+
     /**
      * Possible Subnetwork and ConnectedAP names which should be used in generated SCD in order a have global coherence
      * Configuration based on used framework can be used to externalize this datas
@@ -34,10 +39,6 @@ public class SclAutomationService {
             new SubNetworkTypeDTO("RSPACE_PROCESS_NETWORK", SubNetworkDTO.SubnetworkType.MMS.toString(), List.of("PROCESS_AP", "TOTO_AP_GE")),
             new SubNetworkTypeDTO("RSPACE_ADMIN_NETWORK", SubNetworkDTO.SubnetworkType.IP.toString(), List.of("ADMIN_AP", "TATA_AP_EFFACEC")));
 
-    private SclAutomationService() {
-        throw new UnsupportedOperationException("This is a utility class and cannot be instantiated");
-    }
-
     /**
      * Create an SCD file from specified parameters, it calls all functions defined in the process one by one, every step
      * return an SCD file which will be used by the next step.
@@ -47,15 +48,15 @@ private SclAutomationService() {
      * @return an SCD object
      * @throws ScdException
      */
-    public static SCL createSCD(@NonNull SCL ssd, @NonNull HeaderDTO headerDTO, List<SCL> stds) throws ScdException {
-        SCL scd = SclService.initScl(headerDTO.getId(), headerDTO.getVersion(), headerDTO.getRevision());
+    public SCL createSCD(@NonNull SCL ssd, @NonNull HeaderDTO headerDTO, List<SCL> stds) throws ScdException {
+        SCL scd = sclEditor.initScl(headerDTO.getId(), headerDTO.getVersion(), headerDTO.getRevision());
         if (!headerDTO.getHistoryItems().isEmpty()) {
             HeaderDTO.HistoryItem hItem = headerDTO.getHistoryItems().get(0);
-            SclService.addHistoryItem(scd, hItem.getWho(), hItem.getWhat(), hItem.getWhy());
+            sclEditor.addHistoryItem(scd, hItem.getWho(), hItem.getWhat(), hItem.getWhy());
         }
-        SubstationService.addSubstation(scd, ssd);
-        SclService.importSTDElementsInSCD(scd, stds, SUB_NETWORK_TYPES);
-        SclService.removeAllControlBlocksAndDatasetsAndExtRefSrcBindings(scd);
+        substationEditor.addSubstation(scd, ssd);
+        sclEditor.importSTDElementsInSCD(scd, stds, SUB_NETWORK_TYPES);
+        sclEditor.removeAllControlBlocksAndDatasetsAndExtRefSrcBindings(scd);
         return scd;
     }
 }