feat: add support for the format parameter

search-service/src/main/kotlin/com/egm/stellio/search/authorization/web/EntityAccessControlHandler.kt

@@ -105,7 +105,7 @@ class EntityAccessControlHandler(
 
         val compactedEntities = compactEntities(entities, contexts)
 
-        val ngsiLdDataRepresentation = parseRepresentations(queryParams, mediaType)
+        val ngsiLdDataRepresentation = parseRepresentations(queryParams, mediaType).bind()
         buildQueryResponse(
             compactedEntities.toFinalRepresentation(ngsiLdDataRepresentation),
             count,
@@ -150,7 +150,7 @@ class EntityAccessControlHandler(
 
         val compactedEntities = compactEntities(entities, contexts)
 
-        val ngsiLdDataRepresentation = parseRepresentations(params, mediaType)
+        val ngsiLdDataRepresentation = parseRepresentations(params, mediaType).bind()
         buildQueryResponse(
             compactedEntities.toFinalRepresentation(ngsiLdDataRepresentation),
             count,
@@ -196,7 +196,7 @@ class EntityAccessControlHandler(
 
         val compactedEntities = compactEntities(entities, contexts)
 
-        val ngsiLdDataRepresentation = parseRepresentations(params, mediaType)
+        val ngsiLdDataRepresentation = parseRepresentations(params, mediaType).bind()
         buildQueryResponse(
             compactedEntities.toFinalRepresentation(ngsiLdDataRepresentation),
             count,

search-service/src/main/kotlin/com/egm/stellio/search/entity/web/EntityHandler.kt

@@ -194,11 +194,11 @@ class EntityHandler(
         @RequestHeader httpHeaders: HttpHeaders,
         @AllowedParameters(
             implemented = [
-                QP.OPTIONS, QP.COUNT, QP.OFFSET, QP.LIMIT, QP.ID, QP.TYPE, QP.ID_PATTERN, QP.ATTRS, QP.Q,
+                QP.OPTIONS, QP.FORMAT, QP.COUNT, QP.OFFSET, QP.LIMIT, QP.ID, QP.TYPE, QP.ID_PATTERN, QP.ATTRS, QP.Q,
                 QP.GEOMETRY, QP.GEOREL, QP.COORDINATES, QP.GEOPROPERTY, QP.GEOMETRY_PROPERTY,
                 QP.LANG, QP.SCOPEQ, QP.CONTAINED_BY, QP.JOIN, QP.JOIN_LEVEL, QP.DATASET_ID,
             ],
-            notImplemented = [QP.FORMAT, QP.PICK, QP.OMIT, QP.EXPAND_VALUES, QP.CSF, QP.ENTITY_MAP, QP.LOCAL, QP.VIA]
+            notImplemented = [QP.PICK, QP.OMIT, QP.EXPAND_VALUES, QP.CSF, QP.ENTITY_MAP, QP.LOCAL, QP.VIA]
         )
         @RequestParam queryParams: MultiValueMap<String, String>
     ): ResponseEntity<*> = either {
@@ -264,7 +264,7 @@ class EntityHandler(
             mergedEntities ?: emptyList()
         }
 
-        val ngsiLdDataRepresentation = parseRepresentations(queryParams, mediaType)
+        val ngsiLdDataRepresentation = parseRepresentations(queryParams, mediaType).bind()
         buildQueryResponse(
             mergedEntities.toFinalRepresentation(ngsiLdDataRepresentation),
             maxCount,
@@ -288,10 +288,10 @@ class EntityHandler(
         @PathVariable entityId: URI,
         @AllowedParameters(
             implemented = [
-                QP.OPTIONS, QP.TYPE, QP.ATTRS, QP.GEOMETRY_PROPERTY,
+                QP.OPTIONS, QP.FORMAT, QP.TYPE, QP.ATTRS, QP.GEOMETRY_PROPERTY,
                 QP.LANG, QP.CONTAINED_BY, QP.JOIN, QP.JOIN_LEVEL, QP.DATASET_ID,
             ],
-            notImplemented = [QP.FORMAT, QP.PICK, QP.OMIT, QP.ENTITY_MAP, QP.LOCAL, QP.VIA]
+            notImplemented = [QP.PICK, QP.OMIT, QP.ENTITY_MAP, QP.LOCAL, QP.VIA]
         )
         @RequestParam queryParams: MultiValueMap<String, String>
     ): ResponseEntity<*> = either {
@@ -358,7 +358,7 @@ class EntityHandler(
         val mergedEntityWithLinkedEntities =
             linkedEntityService.processLinkedEntities(mergedEntity, entitiesQuery, sub.getOrNull()).bind()
 
-        val ngsiLdDataRepresentation = parseRepresentations(queryParams, mediaType)
+        val ngsiLdDataRepresentation = parseRepresentations(queryParams, mediaType).bind()
         prepareGetSuccessResponseHeaders(mediaType, contexts)
             .let {
                 val body = if (mergedEntityWithLinkedEntities.size == 1)

search-service/src/main/kotlin/com/egm/stellio/search/entity/web/EntityOperationHandler.kt

@@ -281,7 +281,7 @@ class EntityOperationHandler(
 
         val compactedEntities = compactEntities(filteredEntities, contexts)
 
-        val ngsiLdDataRepresentation = parseRepresentations(queryParams, mediaType)
+        val ngsiLdDataRepresentation = parseRepresentations(queryParams, mediaType).bind()
             .copy(languageFilter = query.lang)
 
         buildQueryResponse(

search-service/src/main/kotlin/com/egm/stellio/search/scope/ScopeService.kt

@@ -24,6 +24,7 @@ import com.egm.stellio.search.entity.model.SucceededAttributeOperationResult
 import com.egm.stellio.search.temporal.model.AttributeInstance.TemporalProperty
 import com.egm.stellio.search.temporal.model.TemporalEntitiesQuery
 import com.egm.stellio.search.temporal.model.TemporalQuery
+import com.egm.stellio.search.temporal.util.TemporalRepresentation
 import com.egm.stellio.search.temporal.util.WHOLE_TIME_RANGE_DURATION
 import com.egm.stellio.search.temporal.util.composeAggregationSelectClause
 import com.egm.stellio.shared.model.APIException
@@ -136,7 +137,7 @@ class ScopeService(
 
         if (temporalEntitiesQuery.isAggregatedWithDefinedDuration())
             sqlQueryBuilder.append(" GROUP BY entity_id, start")
-        else if (temporalEntitiesQuery.withAggregatedValues)
+        else if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES)
             sqlQueryBuilder.append(" GROUP BY entity_id")
         if (temporalQuery.hasLastN())
             // in order to get first or last instances, need to order by time
@@ -161,7 +162,7 @@ class ScopeService(
         temporalEntitiesQuery: TemporalEntitiesQuery,
         origin: ZonedDateTime?
     ): String = when {
-        temporalEntitiesQuery.withAggregatedValues -> {
+        temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES -> {
             val temporalQuery = temporalEntitiesQuery.temporalQuery
             val aggrPeriodDuration = temporalQuery.aggrPeriodDuration
             val allAggregates = temporalQuery.aggrMethods?.composeAggregationSelectClause(AttributeValueType.ARRAY)
@@ -215,7 +216,7 @@ class ScopeService(
         row: Map<String, Any>,
         temporalEntitiesQuery: TemporalEntitiesQuery
     ): ScopeInstanceResult =
-        if (temporalEntitiesQuery.withAggregatedValues) {
+        if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES) {
             val startDateTime = toZonedDateTime(row["start"])
             val endDateTime =
                 if (!temporalEntitiesQuery.isAggregatedWithDefinedDuration())
@@ -231,7 +232,7 @@ class ScopeService(
                 entityId = toUri(row["entity_id"]),
                 values = values
             )
-        } else if (temporalEntitiesQuery.withTemporalValues) {
+        } else if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.TEMPORAL_VALUES) {
             SimplifiedScopeInstanceResult(
                 entityId = toUri(row["entity_id"]),
                 scopes = toList(row["value"]),

search-service/src/main/kotlin/com/egm/stellio/search/scope/TemporalScopeBuilder.kt

@@ -3,6 +3,7 @@ package com.egm.stellio.search.scope
 import com.egm.stellio.search.entity.model.Entity
 import com.egm.stellio.search.temporal.model.TemporalEntitiesQuery
 import com.egm.stellio.search.temporal.model.TemporalQuery
+import com.egm.stellio.search.temporal.util.TemporalRepresentation
 import com.egm.stellio.shared.util.JsonLdUtils.JSONLD_LIST
 import com.egm.stellio.shared.util.JsonLdUtils.JSONLD_TYPE
 import com.egm.stellio.shared.util.JsonLdUtils.JSONLD_VALUE
@@ -27,12 +28,12 @@ object TemporalScopeBuilder {
         // if no history but entity has a scope, add an empty scope list (no history in the given time range)
         else if (scopeInstances.isEmpty())
             mapOf(NGSILD_SCOPE_PROPERTY to emptyList<String>())
-        else if (temporalEntitiesQuery.withAggregatedValues)
+        else if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES)
             buildScopeAggregatedRepresentation(
                 scopeInstances,
                 temporalEntitiesQuery.temporalQuery.aggrMethods!!
             )
-        else if (temporalEntitiesQuery.withTemporalValues)
+        else if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.TEMPORAL_VALUES)
             buildScopeSimplifiedRepresentation(scopeInstances)
         else
             buildScopeFullRepresentation(scopeInstances)

search-service/src/main/kotlin/com/egm/stellio/search/temporal/model/TemporalEntitiesQuery.kt

@@ -3,19 +3,19 @@ package com.egm.stellio.search.temporal.model
 import com.egm.stellio.search.entity.model.EntitiesQuery
 import com.egm.stellio.search.entity.model.EntitiesQueryFromGet
 import com.egm.stellio.search.entity.model.EntitiesQueryFromPost
+import com.egm.stellio.search.temporal.util.TemporalRepresentation
 import java.time.Duration
 import java.time.Period
 import java.time.temporal.TemporalAmount
 
 sealed class TemporalEntitiesQuery(
     open val entitiesQuery: EntitiesQuery,
     open val temporalQuery: TemporalQuery,
-    open val withTemporalValues: Boolean,
-    open val withAudit: Boolean,
-    open val withAggregatedValues: Boolean
+    open val temporalRepresentation: TemporalRepresentation,
+    open val withAudit: Boolean
 ) {
     fun isAggregatedWithDefinedDuration(): Boolean =
-        withAggregatedValues &&
+        temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES &&
             temporalQuery.aggrPeriodDuration != null &&
             temporalQuery.aggrPeriodDuration != "PT0S"
 
@@ -36,15 +36,13 @@ sealed class TemporalEntitiesQuery(
 data class TemporalEntitiesQueryFromGet(
     override val entitiesQuery: EntitiesQueryFromGet,
     override val temporalQuery: TemporalQuery,
-    override val withTemporalValues: Boolean,
-    override val withAudit: Boolean,
-    override val withAggregatedValues: Boolean
-) : TemporalEntitiesQuery(entitiesQuery, temporalQuery, withTemporalValues, withAudit, withAggregatedValues)
+    override val temporalRepresentation: TemporalRepresentation,
+    override val withAudit: Boolean
+) : TemporalEntitiesQuery(entitiesQuery, temporalQuery, temporalRepresentation, withAudit)
 
 data class TemporalEntitiesQueryFromPost(
     override val entitiesQuery: EntitiesQueryFromPost,
     override val temporalQuery: TemporalQuery,
-    override val withTemporalValues: Boolean,
-    override val withAudit: Boolean,
-    override val withAggregatedValues: Boolean
-) : TemporalEntitiesQuery(entitiesQuery, temporalQuery, withTemporalValues, withAudit, withAggregatedValues)
+    override val temporalRepresentation: TemporalRepresentation,
+    override val withAudit: Boolean
+) : TemporalEntitiesQuery(entitiesQuery, temporalQuery, temporalRepresentation, withAudit)

search-service/src/main/kotlin/com/egm/stellio/search/temporal/service/AttributeInstanceService.kt

@@ -28,6 +28,7 @@ import com.egm.stellio.search.temporal.model.SimplifiedAttributeInstanceResult
 import com.egm.stellio.search.temporal.model.TemporalEntitiesQuery
 import com.egm.stellio.search.temporal.model.TemporalQuery
 import com.egm.stellio.search.temporal.model.TemporalQuery.Timerel
+import com.egm.stellio.search.temporal.util.TemporalRepresentation
 import com.egm.stellio.search.temporal.util.WHOLE_TIME_RANGE_DURATION
 import com.egm.stellio.search.temporal.util.composeAggregationSelectClause
 import com.egm.stellio.shared.model.APIException
@@ -174,7 +175,7 @@ class AttributeInstanceService(
 
         sqlQueryBuilder.append(composeSearchSelectStatement(temporalQuery, attributes, origin))
 
-        if (!temporalEntitiesQuery.withTemporalValues && !temporalEntitiesQuery.withAggregatedValues)
+        if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.NORMALIZED)
             sqlQueryBuilder.append(", payload")
 
         if (temporalQuery.timeproperty == OBSERVED_AT)
@@ -204,7 +205,7 @@ class AttributeInstanceService(
 
         if (temporalEntitiesQuery.isAggregatedWithDefinedDuration())
             sqlQueryBuilder.append(" GROUP BY temporal_entity_attribute, start")
-        else if (temporalEntitiesQuery.withAggregatedValues)
+        else if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES)
             sqlQueryBuilder.append(" GROUP BY temporal_entity_attribute")
 
         if (temporalQuery.hasLastN())
@@ -319,7 +320,7 @@ class AttributeInstanceService(
         row: Map<String, Any>,
         temporalEntitiesQuery: TemporalEntitiesQuery
     ): AttributeInstanceResult =
-        if (temporalEntitiesQuery.withAggregatedValues) {
+        if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES) {
             val startDateTime = toZonedDateTime(row["start"])
             val endDateTime =
                 if (!temporalEntitiesQuery.isAggregatedWithDefinedDuration())
@@ -335,7 +336,7 @@ class AttributeInstanceService(
                 attributeUuid = toUuid(row["temporal_entity_attribute"]),
                 values = values
             )
-        } else if (temporalEntitiesQuery.withTemporalValues)
+        } else if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.TEMPORAL_VALUES)
             SimplifiedAttributeInstanceResult(
                 attributeUuid = toUuid(row["temporal_entity_attribute"]),
                 // the type of the value of a property may have changed in the history (e.g., from number to string)

search-service/src/main/kotlin/com/egm/stellio/search/temporal/service/TemporalPaginationService.kt

@@ -5,6 +5,7 @@ import com.egm.stellio.search.temporal.model.AttributeInstanceResult
 import com.egm.stellio.search.temporal.model.TemporalEntitiesQuery
 import com.egm.stellio.search.temporal.model.TemporalQuery
 import com.egm.stellio.search.temporal.util.AttributesWithInstances
+import com.egm.stellio.search.temporal.util.TemporalRepresentation
 import java.time.ZonedDateTime
 
 typealias Range = Pair<ZonedDateTime, ZonedDateTime>
@@ -47,12 +48,13 @@ object TemporalPaginationService {
         val temporalQuery = query.temporalQuery
 
         val attributesTimeRanges = attributeInstancesWhoReachedLimit.map {
-            it.first().getComparableTime() to if (query.withAggregatedValues) {
-                val lastInstance = it.last() as AggregatedAttributeInstanceResult
-                lastInstance.values.first().endDateTime
-            } else {
-                it.last().getComparableTime()
-            }
+            it.first().getComparableTime() to
+                if (query.temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES) {
+                    val lastInstance = it.last() as AggregatedAttributeInstanceResult
+                    lastInstance.values.first().endDateTime
+                } else {
+                    it.last().getComparableTime()
+                }
         }
 
         if (temporalQuery.hasLastN()) {

search-service/src/main/kotlin/com/egm/stellio/search/temporal/service/TemporalQueryService.kt

@@ -17,6 +17,7 @@ import com.egm.stellio.search.temporal.model.TemporalEntitiesQuery
 import com.egm.stellio.search.temporal.service.TemporalPaginationService.getPaginatedAttributeWithInstancesAndRange
 import com.egm.stellio.search.temporal.util.AttributesWithInstances
 import com.egm.stellio.search.temporal.util.TemporalEntityBuilder
+import com.egm.stellio.search.temporal.util.TemporalRepresentation
 import com.egm.stellio.search.temporal.web.Range
 import com.egm.stellio.shared.model.APIException
 import com.egm.stellio.shared.model.ExpandedEntity
@@ -93,8 +94,8 @@ class TemporalQueryService(
         // - timeAt if it is provided
         // - the oldest value if not (timeAt is optional if querying a temporal entity by id)
 
-        return if (!temporalEntitiesQuery.withAggregatedValues)
-            null
+        if (!(temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES))
+            return null
         else if (temporalQuery.timeAt != null)
             temporalQuery.timeAt
         else {
@@ -198,7 +199,7 @@ class TemporalQueryService(
                 // when retrieved from DB, values of geo-properties are encoded in WKT and won't be automatically
                 // transformed during compaction as it is not done for temporal values, so it is done now
                 if (it.key == Attribute.AttributeValueType.GEOMETRY &&
-                    temporalEntitiesQuery.withTemporalValues
+                    temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.TEMPORAL_VALUES
                 ) {
                     it.value.map { attributeInstanceResult ->
                         attributeInstanceResult as SimplifiedAttributeInstanceResult

search-service/src/main/kotlin/com/egm/stellio/search/temporal/util/TemporalEntityBuilder.kt

@@ -68,10 +68,10 @@ object TemporalEntityBuilder {
         attributeAndResultsMap: AttributesWithInstances,
         temporalEntitiesQuery: TemporalEntitiesQuery,
     ): Map<String, Any> =
-        if (temporalEntitiesQuery.withTemporalValues) {
+        if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.TEMPORAL_VALUES) {
             val attributes = buildAttributesSimplifiedRepresentation(attributeAndResultsMap)
             mergeSimplifiedTemporalAttributesOnAttributeName(attributes)
-        } else if (temporalEntitiesQuery.withAggregatedValues) {
+        } else if (temporalEntitiesQuery.temporalRepresentation == TemporalRepresentation.AGGREGATED_VALUES) {
             val attributes = buildAttributesAggregatedRepresentation(
                 attributeAndResultsMap,
                 temporalEntitiesQuery.temporalQuery.aggrMethods!!