Bug/met 6053 dereference cache does not work properly (#679)

* MET-6053: Rework the dereference service unit tests.

* MET-6053: Rework the dereference service.

* MET-6053: Add support in again for caching (was removed in previous commit).

* MET-6053: Some code improvements.

* MET-6053: records replacing pairs.

* MET-6053: records replacing model classes.

metis-dereference/metis-dereference-common/src/main/java/eu/europeana/metis/dereference/ProcessedEntity.java

@@ -7,6 +7,7 @@
 import dev.morphia.annotations.Index;
 import dev.morphia.annotations.IndexOptions;
 import dev.morphia.annotations.Indexes;
+import eu.europeana.enrichment.api.external.DereferenceResultStatus;
 import eu.europeana.metis.mongo.utils.ObjectIdSerializer;
 import jakarta.xml.bind.annotation.XmlElement;
 import jakarta.xml.bind.annotation.XmlRootElement;
@@ -27,12 +28,12 @@ public class ProcessedEntity {
   private ObjectId id;
 
   /**
-   * The resourceId (URI) of the resource
+   * The resourceId (URI) of the resource.
    **/
   private String resourceId;
 
   /**
-   * A xml representation of the mapped resource in one of the contextual resources
+   * A xml representation of the contextual resource (transformed from the original entity).
    **/
   private String xml;
 
@@ -41,6 +42,11 @@ public class ProcessedEntity {
    **/
   private String vocabularyId;
 
+  /**
+   * The status of the dereference operation.
+   */
+  private DereferenceResultStatus resultStatus;
+
   @XmlElement
   public ObjectId getId() {
     return id;
@@ -76,4 +82,13 @@ public String getVocabularyId() {
   public void setVocabularyId(String vocabularyId) {
     this.vocabularyId = vocabularyId;
   }
+
+  @XmlElement
+  public DereferenceResultStatus getResultStatus() {
+    return resultStatus;
+  }
+
+  public void setResultStatus(DereferenceResultStatus resultStatus) {
+    this.resultStatus = resultStatus;
+  }
 }

metis-dereference/metis-dereference-service/src/main/java/eu/europeana/metis/dereference/service/DereferenceService.java

@@ -3,17 +3,27 @@
 import eu.europeana.metis.dereference.DereferenceResult;
 
 /**
- * Dereferencing service Created by ymamakis on 2/11/16.
+ * Implementations of this interface are able to dereference resource IDs. If the resource's
+ * vocabulary specifies a positive iteration count, this method also repeatedly retrieves the
+ * 'broader' resources and returns those as well.
  */
 public interface DereferenceService {
 
   /**
-   * Dereference a URI
+   * <p>
+   * This method dereferences a resource. If the resource's vocabulary specifies a positive
+   * iteration count, this method also repeatedly retrieves the 'broader' resources and returns
+   * those as well.
+   * </p>
+   * <p>
+   * A resource may have references to its 'broader' resources. these resources form a directed
+   * graph and the iteration count is the distance from the requested resource. This method performs
+   * a breadth-first search through this graph to retrieve all resources within a certain distance
+   * from the requested resource. The distance depends on the vocabulary of the main resource.
+   * </p>
    *
-   * @param resourceId The resource ID (URI) to dereference
-   * @return Dereferenceresult contains of the dereferenced entity (or multiple in case of parent entities). List is not null, but
-   * could be empty and the dereference result status of enrichment. If an exception occurs the status is not set, it should be
-   * captured by the callee.
+   * @param resourceId The resource to dereference.
+   * @return An object containing the dereferenced resources and the result status of the process.
    */
   DereferenceResult dereference(String resourceId);
 }