uk.gov.nationalarchives.dp.client.DataProcessor.scala Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of preservica-client-root_3 Show documentation
A client to communicate with the Preservica API
The newest version!
package uk.gov.nationalarchives.dp.client

import cats.MonadError
import cats.implicits.*
import uk.gov.nationalarchives.dp.client.Client.*
import uk.gov.nationalarchives.dp.client.DataProcessor.EventAction
import uk.gov.nationalarchives.dp.client.Entities.*
import uk.gov.nationalarchives.dp.client.EntityClient.*
import uk.gov.nationalarchives.dp.client.EntityClient.EntityType.*
import uk.gov.nationalarchives.dp.client.EntityClient.GenerationType.*

import java.time.ZonedDateTime
import java.util.UUID
import scala.xml.{Elem, MetaData, Node, NodeSeq}

/** A class to process XML responses from Preservica
  * @param me
  *   An implicit MonadError instance
  * @tparam F
  *   The effect type
  */
class DataProcessor[F[_]]()(using me: MonadError[F, Throwable]) {

  extension (ns: NodeSeq)
    def textOfFirstElement(): F[String] = ns.headOption.map(_.text) match {
      case Some(value) => me.pure(value)
      case None        => me.raiseError(PreservicaClientException("Generation URL not found"))
    }

  /** Converts an entity response to an [[Entities.Entity]] case class
    * @param entityRef
    *   The reference of the entity
    * @param entityResponse
    *   The XML response from Preservica
    * @param entityType
    *   The [[EntityClient.EntityType]] of the entity.
    * @return
    *   An [[Entities.Entity]] wrapped in the F effect
    */
  def getEntity(entityRef: UUID, entityResponse: Elem, entityType: EntityType): F[Entity] = {
    (entityResponse \ entityType.toString).headOption
      .map { entity =>
        def optionValue(nodeName: String): Option[String] = (entity \ nodeName).headOption.map(_.text.trim)
        val title = optionValue("Title")
        val description = optionValue("Description")
        val securityTag = optionValue("SecurityTag").flatMap(SecurityTag.fromString)
        val deleted = optionValue("Deleted").isDefined
        val parent = optionValue("Parent").map(UUID.fromString)
        fromType[F](entityType.entityTypeShort, entityRef, title, description, deleted, securityTag, parent)
      }
      .getOrElse(me.raiseError(PreservicaClientException(s"Entity type '$entityType' not found for id $entityRef")))
  }

  /** Retrieves the [[EntityClient.EntityType]] Node from an entity response
    * @param entityRef
    *   The reference of the entity
    * @param entityResponse
    *   The XML response from Preservica
    * @param entityType
    *   The [[EntityClient.EntityType]] of the entity.
    * @return
    *   An [[scala.xml.Node]] found in the entity response (by searching for [[EntityClient.EntityType]]) wrapped in the
    *   F effect
    */
  def getEntityXml(entityRef: UUID, entityResponse: Elem, entityType: EntityType): F[Node] =
    (entityResponse \ entityType.toString).headOption
      .map(me.pure)
      .getOrElse(me.raiseError(PreservicaClientException(s"Entity type '$entityType' not found for id $entityRef")))

  /** Fetches `nodeName` -> `childNodeName` text from `entityResponse`
    * @param entityResponse
    *   The response from the entity
    * @param nodeName
    *   The node name to search
    * @param childNodeName
    *   The child node name to return the text from
    * @return
    *   The text of the child node wrapped in the F effect
    */
  def childNodeFromEntity(entityResponse: Elem, nodeName: String, childNodeName: String): F[String] =
    me.fromOption(
      (entityResponse \ nodeName \ childNodeName.capitalize).headOption.map(_.text),
      PreservicaClientException(s"Either $nodeName or $childNodeName does not exist on entity")
    )

  /** Returns `elementName` -> `ApiId` from the XML response where the `Name` field matches `fileName`
    * @param res
    *   The XML response from Preservica
    * @param elementName
    *   The name of the element
    * @param fileName
    *   The name of the file
    * @return
    *   An optional string with the `ApiId` or `None` if not found.
    */
  def existingApiId(res: Elem, elementName: String, fileName: String): Option[String] = {
    (res \\ elementName).find(n => (n \ "Name").text == fileName).map(n => (n \ "ApiId").text)
  }

  /** Returns the metadata fragment urls from the element
    * @param entityResponseElement
    *   The EntityResponse element to search
    * @return
    *   A `Seq` of `String` wrapped in the F effect with the fragment URLS
    */
  def fragmentUrls(entityResponseElement: Elem): F[Seq[String]] = {
    val fragmentUrls = entityResponseElement \ "AdditionalInformation" \ "Metadata" \ "Fragment"
    me.pure(fragmentUrls.map(_.text))
  }

  /** Returns a list of metadata content
    * @param metadataResponseElements
    *   The MetadataResponse elements that contains the fragments
    * @return
    *   A `Seq` of String representing the metadata XML or an error if none are found
    */
  def fragments(metadataResponseElements: Seq[Elem]): F[Seq[Node]] = {
    val metadataContainerObjects =
      (metadataResponseElements \ "MetadataContainer").toList

    val emptyMetadataContainerObjects = metadataContainerObjects.filter(_.isEmpty)
    if (metadataContainerObjects.isEmpty || emptyMetadataContainerObjects.nonEmpty || metadataContainerObjects.size != metadataResponseElements.size) && metadataResponseElements.nonEmpty
    then
      me.raiseError(
        PreservicaClientException(
          s"Could not be retrieve all 'MetadataContainer' Nodes from:\n${metadataResponseElements.mkString("\n")}"
        )
      )
    else me.pure(metadataContainerObjects)
  }

  /** Gets the text of the first generation element
    * @param contentObjectElement
    *   The Content Object element to search
    * @return
    *   The text of the first generation element wrapped in the F effect
    */
  def generationUrlFromEntity(contentObjectElement: Elem): F[String] =
    (contentObjectElement \ "AdditionalInformation" \ "Generations").textOfFirstElement()

  /** Returns all the text content of every `Generations` -> `Generation` element
    * @param generationsElement
    *   The 'Generations' element containing the generations
    * @return
    *   A `Seq` of `String` with the text content of every `Generations` -> `Generation` element
    */
  def allGenerationUrls(generationsElement: Elem, contentObjectRef: UUID): F[Seq[String]] =
    (generationsElement \ "Generations" \ "Generation").map(_.text) match {
      case Nil =>
        me.raiseError(PreservicaClientException(s"No generations found for entity ref: $contentObjectRef"))
      case generationUrls => me.pure(generationUrls)
    }

  /** Returns whether the the text content of every `Generations` -> `Generation` element
    * @param generationsElement
    *   The 'Generations' element containing the generations
    * @return
    *   A `Seq` of `String` with the text content of every `Generations` -> `Generation` element
    */

  def generationType(generationsElement: Elem, contentObjectRef: UUID): F[GenerationType] =
    (generationsElement \ "Generation").map(_.attributes) match {
      case Nil | List(xml.Null) =>
        me.raiseError(PreservicaClientException(s"No attributes found for entity ref: $contentObjectRef"))
      case (attributesPerGeneration: MetaData) :: _ =>
        val potentialOriginalityStatus = attributesPerGeneration.get("original").map(_.text)

        val potentialGenerationType: F[GenerationType] =
          potentialOriginalityStatus match {
            case Some("true")  => me.pure(Original)
            case Some("false") => me.pure(Derived)
            case _ =>
              me.raiseError(
                PreservicaClientException(
                  s"'original' attribute could not be found on Generation for entity ref: $contentObjectRef"
                )
              )
          }
        potentialGenerationType
    }

  /** Returns all the text content of every `Bitstreams` -> `Bitstream` element
    * @param generationElement
    *   The 'Generation' element containing the bitstreams
    * @return
    *   A `Seq` of `String` with the text content of every `Bitstreams` -> `Bitstream` element
    */
  def allBitstreamUrls(generationElement: Elem): F[Seq[String]] = me.pure {
    (generationElement \ "Bitstreams" \ "Bitstream").map(_.text)
  }

  /** Returns a list of [[Client.BitStreamInfo]] objects
    * @param bitstreamElements
    *   The elements containing the bitstream information
    * @return
    *   A `Seq` of `BitStreamInfo` objects parsed from the XML
    */
  def allBitstreamInfo(
      bitstreamElements: Seq[Elem],
      generationType: GenerationType,
      contentObject: Entity
  ): F[Seq[BitStreamInfo]] =
    me.pure {
      bitstreamElements.map { be =>
        val filename = (be \\ "Bitstream" \\ "Filename").text
        val fileSize = (be \\ "Bitstream" \\ "FileSize").text.toLong
        val bitstreamInfoUrl = (be \\ "AdditionalInformation" \\ "Self").text

        val bitstreamInfoUrlReversed = bitstreamInfoUrl.split("/").reverse
        val generationVersion = bitstreamInfoUrlReversed(2).toInt

        val bitstreamUrl = (be \\ "AdditionalInformation" \\ "Content").text

        val fixities = (be \\ "Bitstream" \\ "Fixities" \\ "Fixity").map { eachFixity =>
          Fixity((eachFixity \ "FixityAlgorithmRef").text, (eachFixity \ "FixityValue").text)
        }.toList

        BitStreamInfo(
          filename,
          fileSize,
          bitstreamUrl,
          fixities,
          generationVersion,
          generationType,
          contentObject.title,
          contentObject.parent
        )
      }
    }

  /** Returns the next page
    * @param elem
    *   The element containing the pagination element
    * @return
    *   The optional next page or None if there are none
    */
  def nextPage(elem: Elem): F[Option[String]] =
    me.pure((elem \ "Paging" \ "Next").headOption.map(_.text))

  /** Parses a list of [[Entities.Entity]] parsed from the XML
    * @param elem
    *   The element to parse
    * @return
    *   A `Seq` of [[Entities.Entity]]
    */
  def getEntities(elem: Elem): F[Seq[Entity]] =
    (elem \ "Entities" \ "Entity").map { e =>
      val entityAttributes = e.attributes

      val ref = UUID.fromString(attrToString(e, "ref"))
      val title = entityAttributes.get("title").map(_.toString)
      val description = entityAttributes.get("description").map(_.toString)
      val entityType = attrToString(e, "type")
      val deleted = attrToString(e, "deleted").nonEmpty
      fromType[F](entityType, ref, title, description, deleted)
    }.sequence

  /** Returns a list of [[Entities.IdentifierResponse]] objects
    * @param elem
    *   The element containing the identifiers
    * @return
    *   A `Seq` of `IdentifierResponse` objects parsed from the XML
    */
  def getIdentifiers(elem: Elem): F[Seq[IdentifierResponse]] = {
    me.pure {
      (elem \ "Identifiers" \ "Identifier")
        .map { i =>
          val id = (i \ "ApiId").text
          val identifierName = (i \ "Type").text
          val identifierValue = (i \ "Value").text
          IdentifierResponse(id, identifierName, identifierValue)
        }
    }
  }

  /** Returns a list of [[NodeSeq]] objects
    * @param elem
    *   The element containing the identifiers
    * @return
    *   A `Seq` of `Identifier` elements parsed from the XML
    */
  def getIdentifiersXml(elem: Elem): F[Seq[Node]] = me.pure(elem \ "Identifiers" \ "Identifier")

  /** Returns a list of [[DataProcessor.EventAction]] objects
    * @param elem
    *   The element containing the event actions
    * @return
    *   A `Seq` of `EventAction` objects parsed from the XML
    */
  def getEventActions(elem: Elem): F[Seq[EventAction]] = {
    me.pure(
      (elem \ "EventActions" \ "EventAction")
        .map { e =>
          val eventRef = UUID.fromString((e \\ "Event" \\ "Ref").text)
          val eventType = (e \\ "Event").flatMap(event => event.attributes("type")).text
          val dateOfEvent = ZonedDateTime.parse((e \ "Date").text)

          EventAction(eventRef, eventType, dateOfEvent)
        }
    )
  }

  /** Gets the child node from a workflow instance response
    * @param workflowInstanceResponse
    *   The workflow instance response
    * @param nodeName
    *   The name of the node to search for
    * @return
    *   The text of the child node provided as an argument.
    */
  def childNodeFromWorkflowInstance(workflowInstanceResponse: Elem, nodeName: String): F[String] =
    me.fromOption(
      (workflowInstanceResponse \ nodeName).headOption.map(_.text),
      PreservicaClientException(s"'$nodeName' does not exist on the workflowInstance response.")
    )

  /** Returns a `Seq` of String objects
    * @param elem
    *   The element containing the representations
    * @param representationType
    *   The (Optional) representation type that you want returned
    * @return
    *   A `Seq` of `String` objects parsed from the XML
    */
  def getUrlsToEntityRepresentations(elem: Elem, representationType: Option[RepresentationType]): F[Seq[String]] =
    me.pure {
      (elem \ "Representations" \ "Representation").collect {
        case rep if representationType.isEmpty || attrToString(rep, "type") == representationType.get.toString =>
          rep.text
      }
    }

  private def attrToString(node: Node, key: String) = node.attributes.get(key).map(_.toString()).getOrElse("")

  /** Returns a `Seq` of String objects
    * @param elem
    *   The element containing the representations
    * @param representationType
    *   The (Optional) representation type that you want returned
    * @return
    *   A `Seq` of `String` objects parsed from the XML
    */
  def getContentObjectsFromRepresentation(
      elem: Elem,
      representationType: RepresentationType,
      ioEntityRef: UUID
  ): F[Seq[Entity]] =
    me.pure {
      (elem \ "Representation" \ "ContentObjects" \ "ContentObject").map { rep =>
        Entity(
          Some(ContentObject),
          UUID.fromString(rep.text),
          None,
          None,
          deleted = false,
          ContentObject.entityPath.some,
          None,
          Some(ioEntityRef)
        )
      }
    }

  /** Returns a `Float`
    * @param elem
    *   The element containing the namespace with the version in it
    * @return
    *   A `Float`, representing the Preservica version, parsed from the XML
    */
  def getPreservicaNamespaceVersion(elem: Elem): F[Float] =
    me.pure {
      val namespaceUrl = elem.namespace
      val version = namespaceUrl.split("/").last
      version.stripPrefix("v").toFloat
    }

  /** Returns a list of [[scala.xml.Node]] XML objects
    *
    * @param elem
    *   The element containing the Entity's links
    * @return
    *   A `Seq` of `Node` containing the links
    */
  def getEntityLinksXml(ref: UUID, elem: Elem): F[Seq[Node]] = me.pure {
    val links = elem \ "Links" \ "Link"
    links.flatMap { link =>
      for {
        linkType <- link.attribute("linkType").flatMap(_.headOption)
        linkDirection <- link.attribute("linkDirection").flatMap(_.headOption)
        refLinks <- link.attribute("ref").flatMap(_.headOption.map(_.toString))
      } yield {
        val entities =
          if linkDirection.text == "To" then
            List(
              {refLinks}
          {ref.toString}
            )
          else
            List(
              {ref.toString}
            {refLinks}
            )

        
          {linkType.text}
          {entities}
        
      }
    }
  }

  /** Returns a Seq containing multiple [[scala.xml.Node]] XML object objects representing an `EventAction`
    *
    * @param eventActionsResponseElement
    *   The element containing the Event actions
    * @return
    *   A `Seq` of Node, representing Event actions
    */
  def getEventActionElements(eventActionsResponseElement: Elem): F[Seq[Node]] =
    me.pure((eventActionsResponseElement \ "EventActions" \ "EventAction"))

  /** Returns a Seq containing one Representation [[scala.xml.Node]] XML object
    *
    * @param representationResponseElement
    *   The element containing the information for the Representation
    * @return
    *   A `Seq` of `Node` containing the links
    */
  def getRepresentationElement(representationResponseElement: Elem): F[Seq[Node]] =
    me.pure((representationResponseElement \ "Representation"))

  /** Returns a Seq containing one Generation [[scala.xml.Node]] XML object
    *
    * @param generationResponseElement
    *   The element containing the information for the Generation
    * @return
    *   A `Seq` of `Node` containing the links
    */
  def getGenerationElement(generationResponseElement: Elem): F[Seq[Node]] =
    me.pure((generationResponseElement \ "Generation"))
}

/** An apply method for the `DataProcessor` class and the `EventAction` case class
  */
object DataProcessor {
  def apply[F[_]]()(implicit me: MonadError[F, Throwable]) = new DataProcessor[F]()

  /** @param eventRef
    *   The reference of the event
    * @param eventType
    *   The type of the event
    * @param dateOfEvent
    *   The date of the event
    */
  case class EventAction(eventRef: UUID, eventType: String, dateOfEvent: ZonedDateTime)
}