java.lang.Object

org.gcube.informationsystem.resourceregistry.pep.PolicyEnforcementPoint

Direct Known Subclasses:: ContextPolicyEnforcementPoint, InstancesPolicyEnforcementPoint, QueryTemplatePolicyEnforcementPoint, SystemPolicyEnforcementPoint, TypePolicyEnforcementPoint

public abstract class PolicyEnforcementPoint extends Object

Base class for all Policy Enforcement Points (PEP) in the resource-registry service.

A PEP is the single coupling point between the HTTP/REST layer and the role-agnostic backend Management classes. Each collection (Contexts, Types, Instances, Queries, …) has exactly one PEP subclass.

State and utilities shared across all PEPs:

getUriInfo() — the JAX-RS UriInfo for the current request, used to read query parameters and build response headers.
isPrivilegedUser() — checks whether the current caller holds a globally-privileged role (IS-Manager or Infrastructure-Manager).

Author:: Luca Frosini (ISTI - CNR)

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static class

PolicyEnforcementPoint.EndpointPolicySpec

Specification for an entire HTTP endpoint's policy.

static class

PolicyEnforcementPoint.QueryParamSpec

Specification for query parameter authorization and validation.

static enum

PolicyEnforcementPoint.TokenScopeRule

Defines rules for binding the Context in the caller's JWT token to the target resource.
Field Summary

Fields

Modifier and Type

Field

Description

static final Set<String>

ALL_ADMIN_ROLES

Set of all administrative roles (both global and subtree).

static final Set<String>

ALL_OPERATIONAL_ROLES

Set of all operational roles in the system.

static final String

CONTEXT_MANAGER

Role constant representing the Context-Manager role.

static final int

DEPTH_DEFAULT

Default value for the depth query parameter (mirrors ContextPath.DEPTH_QUERY_PARAMETER_DEFAULT_READ_VALUE).

static final Set<String>

GLOBAL_PRIVILEGED_ROLES

Set of globally privileged administrative roles.

static final String

INFRASTRUCTURE_MANAGER

Role constant representing the Infrastructure-Manager role.

static final String

IS_ADMIN

Role constant representing the IS-Admin role.

static final String

IS_CONTRIBUTOR

Role constant representing the IS-Contributor role.

static final String

IS_EDITOR

Role constant representing the IS-Editor role.

static final String

IS_MANAGER

Role constant representing the IS-Manager role.

static final String

IS_MEMBER

Role constant representing the IS-Member role.

static final String

LEGACY_ALL_META_QUERY_PARAMETER

Legacy query parameter kept for server-side operational compatibility only.

static final String

LEGACY_INCLUDE_META_QUERY_PARAMETER

Legacy query parameter kept for server-side operational compatibility only.

static final int

LIMIT_DEFAULT

Default value for the limit pagination parameter (mirrors InstancePath.LIMIT_QUERY_PARAMETER_DEFAULT_VALUE).

static final int

LIMIT_MAX

System-enforced maximum value for the limit parameter (anti-DoS cap).

static final int

OFFSET_DEFAULT

Default value for the offset pagination parameter (mirrors InstancePath.OFFSET_QUERY_PARAMETER_DEFAULT_VALUE).

protected jakarta.ws.rs.container.ContainerRequestContext

requestContext

JAX-RS request context for the current request.

static final Set<String>

SUBTREE_ADMIN_ROLES

Set of subtree administrative roles.
Constructor Summary

Constructors

Modifier

Constructor

Description

protected

PolicyEnforcementPoint(jakarta.ws.rs.container.ContainerRequestContext requestContext)

Creates a new PolicyEnforcementPoint instance for the current HTTP request.
Method Summary

Modifier and Type

Method

Description

protected void

addContentWarning(ContentWarning warning)

Adds a structured content warning produced by the Management/backend layer.

protected void

addIgnoredFieldsWarning(IgnoredFieldsWarning warning)

Adds a structured ignored-fields-on-write warning (called internally by PEP subclasses after deserializing a write request body).

protected void

addLink(String rel, String targetUri)

Records an RFC 8288 Link header relation to be emitted on the response, per appendix/08-hateoas-navigation.md.

protected void

addPaginationLinks(PageResult page)

Emits the standard RFC 8288 pagination Link relations for a paginated response, pointing at the current request path with limit/offset substituted.

protected void

addPreferenceApplied(org.gcube.informationsystem.resourceregistry.api.rest.OperationReturn operationReturn)

Records the OperationReturn preference honored for the current request's Operation Envelope response.

protected void

addQueryParameterWarning(QueryParameterWarning warning)

Adds a structured query-parameter warning (called internally by resolve* methods), also recording it on the ContainerRequestContext "warnings" property from which the global WarningResponseFilter emits it as an X-Warning response header.

protected void

addResultScope(org.gcube.informationsystem.resourceregistry.api.rest.ResultScope scope)

Records that the response was affected by the given ResultScope (e.g. a hierarchical lookup succeeded via descendant expansion, or the response was role- or state-filtered).

protected String

buildUri(String... pathSegments)

Builds an absolute target URI by joining the current request's base URI with the given path segments, e.g.

protected void

enforcePolicy(PolicyEnforcementPoint.EndpointPolicySpec policy, UUID targetUuid, UUID parentUuid)

Enforces the endpoint-level and context-level authorization rules specified by the given policy specification, and automatically validates query parameters.

protected void

enforceTargetContextWithinTokenSubtree(UUID targetContextUuid, String operationName)

Enforces that the given target Context is either the caller's token Context itself or one of its descendants (the token Context's subtree is self-inclusive).

List<ServiceWarning>

getAllWarnings()

Returns an aggregated, immutable view of all warnings accumulated during this request: query-parameter warnings first, content warnings second, ignored-fields warnings third.

String

getContentLocation()

Returns the canonical URI recorded for this request's single-instance read, or null if none was recorded (e.g. a List/Query response, or a write handled by the request-path-based fallback in ContentLocationResponseFilter).

List<ContentWarning>

getContentWarnings()

Returns an immutable view of only the content warnings accumulated during this request.

List<IgnoredFieldsWarning>

getIgnoredFieldsWarnings()

Returns an immutable view of only the ignored-fields-on-write warnings accumulated during this request.

List<LinkRelation>

getLinks()

Returns an immutable view of the Link relations accumulated during this request.

org.gcube.informationsystem.resourceregistry.api.rest.OperationReturn

getPreferenceApplied()

Returns the operation-envelope return preference honored during this request, or null if none was recorded.

List<QueryParameterWarning>

getQueryParameterWarnings()

Returns an immutable view of only the query-parameter warnings accumulated during this request.

String

getResolvedContextPath()

Returns the resolved current Context path recorded during this request, or null if none was recorded.

Set<org.gcube.informationsystem.resourceregistry.api.rest.ResultScope>

getResultScopes()

Returns an immutable view of the result scopes accumulated during this request.

jakarta.ws.rs.core.UriInfo

getUriInfo()

Returns the JAX-RS UriInfo for the current request.

protected boolean

hasNonActiveDescendant()

Returns true if at least one descendant of the caller's current Context has an effectiveState other than ACTIVE.

protected boolean

isAdministrativeUser()

Returns true if the current caller holds at least one administrative role (ALL_ADMIN_ROLES: IS-Manager, Infrastructure-Manager, IS-Admin, or Context-Manager).

protected boolean

isPrivilegedUser()

Returns true if the current caller holds at least one globally-privileged role (IS-Manager or Infrastructure-Manager).

protected boolean

isUserAllowed(Set<String> allowedRoles)

Helper method to check if the current user holds at least one of the allowed roles.

protected boolean

resolveAllMeta()

Resolves the allMeta query parameter from the current request.

protected boolean

resolveBoolean(String paramName, boolean defaultValue)

Low-level helper: resolves a boolean query parameter with strict validation.

protected boolean

resolveBypassHierarchyCheck()

Resolves the bypassHierarchyCheck query parameter from the current request (admin add-to-context endpoint only).

protected int

resolveDepth()

Resolves the depth query parameter from the current request.

protected int

resolveDepth(int defaultValue)

Resolves the depth query parameter from the current request, falling back to an explicit caller-supplied default instead of the global DEPTH_DEFAULT.

protected boolean

resolveDryRun()

Resolves the dryRun query parameter from the current request.

protected boolean

resolveHierarchical()

Resolves the hierarchical query parameter from the current request.

protected boolean

resolveIncludeContexts()

Resolves the includeContexts query parameter from the current request.

protected boolean

resolveIncludeMeta()

Resolves the includeMeta query parameter from the current request.

protected int

resolveLimit()

Resolves the limit pagination parameter from the current request.

protected org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy

resolveMetadataPolicy()

Resolves metadata inclusion policy for the current request.

protected int

resolveOffset()

Resolves the offset pagination parameter from the current request.

protected boolean

resolvePolymorphic()

Resolves the polymorphic query parameter from the current request.

protected org.gcube.informationsystem.resourceregistry.api.rest.PropagationMode

resolvePropagationMode()

Resolves the propagationMode query parameter from the current request.

protected boolean

resolveRawResult()

Resolves the rawResult query parameter from the current request (raw-query endpoint only).

protected boolean

resolveSyncExistingHierarchy()

Resolves the syncExistingHierarchy query parameter from the current request.

protected UUID

resolveTokenContextUuid()

Resolves the Context UUID bound to the caller's authorization token.

protected void

setContentLocation(String targetUri)

Records the canonical URI of the single-instance representation this request is about to return, for ContentLocationResponseFilter to emit as the Content-Location response header (RFC 9110 Section 8.7), per 07-api-foundations-and-roles.md.

protected void

setResolvedContextPath(String path)

Records the current path a caller's previousPaths-matched token resolved to, later emitted as the X-Resolved-Context-Path response header.

protected void

validateQueryParameters(Set<String> acceptedParams)

Validates the query parameters of the current request against the given set of accepted parameter names and accumulates an IGNORED warning for any parameter that is not in acceptedParams.

protected void

warnEnrichmentParametersIgnoredByEmitProjection()

Reports that metadataPolicy/includeContexts were requested but had no effect because the query's _emit projection replaced the full instance representation with a flat, projection-only response (Canonical _emit Precedence Rules, appendix/07-json-query-syntax-reference.md).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- IS_MANAGER
  
  public static final String IS_MANAGER
  
  Role constant representing the IS-Manager role.
  See Also:
  
  Constant Field Values
- INFRASTRUCTURE_MANAGER
  
  public static final String INFRASTRUCTURE_MANAGER
  
  Role constant representing the Infrastructure-Manager role.
  See Also:
  
  Constant Field Values
- IS_ADMIN
  
  public static final String IS_ADMIN
  
  Role constant representing the IS-Admin role.
  See Also:
  
  Constant Field Values
- CONTEXT_MANAGER
  
  public static final String CONTEXT_MANAGER
  
  Role constant representing the Context-Manager role.
  See Also:
  
  Constant Field Values
- IS_EDITOR
  
  public static final String IS_EDITOR
  
  Role constant representing the IS-Editor role.
  See Also:
  
  Constant Field Values
- IS_CONTRIBUTOR
  
  public static final String IS_CONTRIBUTOR
  
  Role constant representing the IS-Contributor role.
  See Also:
  
  Constant Field Values
- IS_MEMBER
  
  public static final String IS_MEMBER
  
  Role constant representing the IS-Member role.
  See Also:
  
  Constant Field Values
- GLOBAL_PRIVILEGED_ROLES
  
  public static final Set<String> GLOBAL_PRIVILEGED_ROLES
  
  Set of globally privileged administrative roles.
- SUBTREE_ADMIN_ROLES
  
  public static final Set<String> SUBTREE_ADMIN_ROLES
  
  Set of subtree administrative roles.
- ALL_ADMIN_ROLES
  
  public static final Set<String> ALL_ADMIN_ROLES
  
  Set of all administrative roles (both global and subtree).
- ALL_OPERATIONAL_ROLES
  
  public static final Set<String> ALL_OPERATIONAL_ROLES
  
  Set of all operational roles in the system.
- DEPTH_DEFAULT
  
  public static final int DEPTH_DEFAULT
  
  Default value for the depth query parameter (mirrors ContextPath.DEPTH_QUERY_PARAMETER_DEFAULT_READ_VALUE).
- LIMIT_DEFAULT
  
  public static final int LIMIT_DEFAULT
  
  Default value for the limit pagination parameter (mirrors InstancePath.LIMIT_QUERY_PARAMETER_DEFAULT_VALUE).
  See Also:
  
  Constant Field Values
- LIMIT_MAX
  
  public static final int LIMIT_MAX
  
  System-enforced maximum value for the limit parameter (anti-DoS cap).
  See Also:
  
  Constant Field Values
- OFFSET_DEFAULT
  
  public static final int OFFSET_DEFAULT
  
  Default value for the offset pagination parameter (mirrors InstancePath.OFFSET_QUERY_PARAMETER_DEFAULT_VALUE).
  See Also:
  
  Constant Field Values
- LEGACY_INCLUDE_META_QUERY_PARAMETER
  
  public static final String LEGACY_INCLUDE_META_QUERY_PARAMETER
  
  Legacy query parameter kept for server-side operational compatibility only.
  See Also:
  
  Constant Field Values
- LEGACY_ALL_META_QUERY_PARAMETER
  
  public static final String LEGACY_ALL_META_QUERY_PARAMETER
  
  Legacy query parameter kept for server-side operational compatibility only.
  See Also:
  
  Constant Field Values
- requestContext
  
  protected jakarta.ws.rs.container.ContainerRequestContext requestContext
  
  JAX-RS request context for the current request.
Constructor Details
- PolicyEnforcementPoint
  
  protected PolicyEnforcementPoint(jakarta.ws.rs.container.ContainerRequestContext requestContext)
  
  Creates a new PolicyEnforcementPoint instance for the current HTTP request.
  
  Parameters:
  
  requestContext - the JAX-RS ContainerRequestContext for the current request
Method Details
- getUriInfo
  
  public jakarta.ws.rs.core.UriInfo getUriInfo()
  
  Returns the JAX-RS UriInfo for the current request.
  
  Returns:
  
  the request URI information
- addQueryParameterWarning
  
  protected void addQueryParameterWarning(QueryParameterWarning warning)
  
  Adds a structured query-parameter warning (called internally by resolve* methods), also recording it on the ContainerRequestContext "warnings" property from which the global WarningResponseFilter emits it as an X-Warning response header.
  
  Parameters:
  
  warning - the query-parameter warning to accumulate
- addContentWarning
  
  protected void addContentWarning(ContentWarning warning)
  
  Adds a structured content warning produced by the Management/backend layer. Typically called by the PEP subclass after invoking a Management method, to propagate any backend warnings into the HTTP response.
  
  Parameters:
  
  warning - the content warning to accumulate
- addIgnoredFieldsWarning
  
  protected void addIgnoredFieldsWarning(IgnoredFieldsWarning warning)
  
  Adds a structured ignored-fields-on-write warning (called internally by PEP subclasses after deserializing a write request body).
  
  Parameters:
  
  warning - the ignored-fields warning to accumulate
- getQueryParameterWarnings
  
  public List<QueryParameterWarning> getQueryParameterWarnings()
  
  Returns an immutable view of only the query-parameter warnings accumulated during this request.
  
  Returns:
  
  immutable list of query-parameter warnings
- getContentWarnings
  
  public List<ContentWarning> getContentWarnings()
  
  Returns an immutable view of only the content warnings accumulated during this request.
  
  Returns:
  
  immutable list of content warnings
- getIgnoredFieldsWarnings
  
  public List<IgnoredFieldsWarning> getIgnoredFieldsWarnings()
  
  Returns an immutable view of only the ignored-fields-on-write warnings accumulated during this request.
  
  Returns:
  
  immutable list of ignored-fields warnings
- getAllWarnings
  
  public List<ServiceWarning> getAllWarnings()
  
  Returns an aggregated, immutable view of all warnings accumulated during this request: query-parameter warnings first, content warnings second, ignored-fields warnings third. This accessor is a convenience for tests and callers holding this PEP instance directly; the actual X-Warning response headers are emitted by the global WarningResponseFilter from the same warnings, independently accumulated on the JAX-RS ContainerRequestContext "warnings" property by addQueryParameterWarning(org.gcube.informationsystem.resourceregistry.http.headers.warning.QueryParameterWarning), addContentWarning(org.gcube.informationsystem.resourceregistry.http.headers.warning.ContentWarning), and addIgnoredFieldsWarning(org.gcube.informationsystem.resourceregistry.http.headers.warning.IgnoredFieldsWarning).
  
  Returns:
  
  immutable list of all accumulated warnings
- addResultScope
  
  protected void addResultScope(org.gcube.informationsystem.resourceregistry.api.rest.ResultScope scope)
  
  Records that the response was affected by the given ResultScope (e.g. a hierarchical lookup succeeded via descendant expansion, or the response was role- or state-filtered). The REST layer emits these as a single combined X-Result-Scope response header via ResultScopeResponseFilter.
  
  Parameters:
  
  scope - the result scope to accumulate
- getResultScopes
  
  public Set<org.gcube.informationsystem.resourceregistry.api.rest.ResultScope> getResultScopes()
  
  Returns an immutable view of the result scopes accumulated during this request.
  
  Returns:
  
  immutable set of accumulated result scopes
- addPreferenceApplied
  
  protected void addPreferenceApplied(org.gcube.informationsystem.resourceregistry.api.rest.OperationReturn operationReturn)
  
  Records the OperationReturn preference honored for the current request's Operation Envelope response. The REST layer emits this as the Preference-Applied response header via PreferenceAppliedResponseFilter. Unlike addResultScope(ResultScope), this is a single value, not an accumulated set: exactly one OperationReturn ever applies per request.
  
  Parameters:
  
  operationReturn - the operation-return preference that was honored
- getPreferenceApplied
  
  public org.gcube.informationsystem.resourceregistry.api.rest.OperationReturn getPreferenceApplied()
  
  Returns the operation-envelope return preference honored during this request, or null if none was recorded.
  
  Returns:
  
  the honored operation-return preference, or null
- setResolvedContextPath
  
  protected void setResolvedContextPath(String path)
  
  Records the current path a caller's previousPaths-matched token resolved to, later emitted as the X-Resolved-Context-Path response header.
  
  Parameters:
  
  path - the resolved current Context path
- getResolvedContextPath
  
  public String getResolvedContextPath()
  
  Returns the resolved current Context path recorded during this request, or null if none was recorded.
  
  Returns:
  
  the resolved current Context path, or null
- addLink
  
  protected void addLink(String rel, String targetUri)
  
  Records an RFC 8288 Link header relation to be emitted on the response, per appendix/08-hateoas-navigation.md. The REST layer never builds these headers itself: the response is finalized by LinkResponseFilter, mirroring addResultScope(ResultScope)/addQueryParameterWarning(QueryParameterWarning).
  
  Parameters:
  
  rel - the link relation type (e.g. "parent", "collection", "up")
  
  targetUri - the absolute target URI of the related resource
- addPaginationLinks
  
  protected void addPaginationLinks(PageResult page)
  
  Emits the standard RFC 8288 pagination Link relations for a paginated response, pointing at the current request path with limit/offset substituted.
  Emitted relations: first (always), prev (when offset > 0), next (when page.hasNext()).
  
  Parameters:
  
  page - the paginated page result whose limit/offset/hasNext drive link computation
- buildUri
  
  protected String buildUri(String... pathSegments)
  
  Builds an absolute target URI by joining the current request's base URI with the given path segments, e.g. buildUri("contexts", parentUuid) yields https://host/rest-path/contexts/<uuid>.
  
  Parameters:
  
  pathSegments - the path segments to append to the base URI, in order
  
  Returns:
  
  the absolute URI string, or null if no UriInfo is available
- getLinks
  
  public List<LinkRelation> getLinks()
  
  Returns an immutable view of the Link relations accumulated during this request.
  
  Returns:
  
  immutable list of accumulated Link relations
- setContentLocation
  
  protected void setContentLocation(String targetUri)
  
  Records the canonical URI of the single-instance representation this request is about to return, for ContentLocationResponseFilter to emit as the Content-Location response header (RFC 9110 Section 8.7), per 07-api-foundations-and-roles.md.
  Only single-instance reads call this (Context/Type/Instance/Query Template read()); a List/Query response is a collection, not "the" representation of one URI, so it must never call this. Most callers simply pass their own request path back (the common case: the addressed URI already is the canonical one) - the one exception is ContextPolicyEnforcementPoint.readCurrent(), which delegates to read(UUID) and therefore reports the resolved Context's own UUID-based URI, not the @current alias the client actually requested.
  
  Parameters:
  
  targetUri - the absolute canonical URI of the returned representation
- getContentLocation
  
  public String getContentLocation()
  
  Returns the canonical URI recorded for this request's single-instance read, or null if none was recorded (e.g. a List/Query response, or a write handled by the request-path-based fallback in ContentLocationResponseFilter).
  
  Returns:
  
  the recorded canonical URI, or null
- isPrivilegedUser
  
  protected boolean isPrivilegedUser()
  
  Returns true if the current caller holds at least one globally-privileged role (IS-Manager or Infrastructure-Manager).
  
  Returns:
  
  true if the caller is globally privileged, false otherwise
- isAdministrativeUser
  
  protected boolean isAdministrativeUser()
  
  Returns true if the current caller holds at least one administrative role (ALL_ADMIN_ROLES: IS-Manager, Infrastructure-Manager, IS-Admin, or Context-Manager).
  Broader than isPrivilegedUser() (which only covers the two global roles). These roles already bypass the write-side operational lock on non-ACTIVE descendant Contexts (per 11-api-query-parameters.md's "Admin Overrides" row), so they must also see the unfiltered read view - a role that can write into a subtree it cannot read would be incoherent.
  
  Returns:
  
  true if the caller is administrative, false otherwise
- isUserAllowed
  
  protected boolean isUserAllowed(Set<String> allowedRoles)
  
  Helper method to check if the current user holds at least one of the allowed roles.
  
  Parameters:
  
  allowedRoles - the set of allowed roles to check
  
  Returns:
  
  true if the user has at least one of the roles, false otherwise
- resolveTokenContextUuid
  
  protected UUID resolveTokenContextUuid()
  
  Resolves the Context UUID bound to the caller's authorization token.
  
  Returns:
  
  the token's Context UUID, or null if it cannot be resolved
- hasNonActiveDescendant
  
  protected boolean hasNonActiveDescendant() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
  
  Returns true if at least one descendant of the caller's current Context has an effectiveState other than ACTIVE. Used to decide whether a hierarchical read/query for a non-administrative caller should report ResultScope.STATE_FILTERED: this signals that the filtering mechanism was live for the request, not that a specific response actually excluded a row (the exclusion itself happens transparently at the permission layer, with no per-request signal of its own to check against).
  
  Returns:
  
  true if a non-ACTIVE descendant exists, false otherwise
  
  Throws:
  
  org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the caller's current Context cannot be resolved
- enforceTargetContextWithinTokenSubtree
  
  protected void enforceTargetContextWithinTokenSubtree(UUID targetContextUuid, String operationName)
  
  Enforces that the given target Context is either the caller's token Context itself or one of its descendants (the token Context's subtree is self-inclusive).
  This check is a fail-closed Level 2 (Token Scope Binding) safeguard for endpoints whose target is a Context UUID that must be validated independently of any instance UUID also being enforced by enforcePolicy(EndpointPolicySpec, UUID, UUID) (e.g. Add to Context, whose targetUuid for role/query-parameter enforcement is the instance being shared, not the destination Context).
  
  Parameters:
  
  targetContextUuid - the Context UUID to validate against the token's subtree
  
  operationName - the operation name to include in the rejection message
  
  Throws:
  
  jakarta.ws.rs.ForbiddenException - if the token Context cannot be resolved, or if targetContextUuid lies outside the token Context's subtree
- enforcePolicy
  
  protected void enforcePolicy(PolicyEnforcementPoint.EndpointPolicySpec policy, UUID targetUuid, UUID parentUuid)
  
  Enforces the endpoint-level and context-level authorization rules specified by the given policy specification, and automatically validates query parameters.
  
  Parameters:
  
  policy - the policy specification to enforce
  
  targetUuid - the UUID of the target resource, or null if none
  
  parentUuid - the UUID of the parent resource (for PARENT scope checks), or null if none
  
  Throws:
  
  jakarta.ws.rs.ForbiddenException - if the caller lacks required roles or scope clearance
  
  jakarta.ws.rs.NotAuthorizedException - if the caller lacks parent context authorization
- validateQueryParameters
  
  protected void validateQueryParameters(Set<String> acceptedParams)
  
  Validates the query parameters of the current request against the given set of accepted parameter names and accumulates an IGNORED warning for any parameter that is not in acceptedParams.
  All unrecognised parameters are grouped into a single warning entry so that the caller receives one X-Warning header per validation call rather than one per stray parameter.
  
  This method is a no-op when getUriInfo() is null (e.g. in unit tests that invoke PEP methods directly without a JAX-RS context).
  
  Parameters:
  
  acceptedParams - the set of parameter names that are valid for the calling endpoint; all other parameters will be reported as ignored
- resolveBoolean
  
  protected boolean resolveBoolean(String paramName, boolean defaultValue)
  
  Low-level helper: resolves a boolean query parameter with strict validation.
  Only "true" and "false" (case-insensitive) are accepted as valid. Any other non-null value emits a MODIFIED warning and falls back to defaultValue.
  
  Prefer the parameter-specific methods (resolvePolymorphic(), resolveIncludeMeta(), …) over calling this directly.
  
  Parameters:
  
  paramName - the query parameter name
  
  defaultValue - the value to return when the parameter is absent
  
  Returns:
  
  the resolved boolean value
- resolveLimit
  
  protected int resolveLimit()
  Resolves the limit pagination parameter from the current request.
  
  Absent or null → returns LIMIT_DEFAULT.
  
  -1 or value > LIMIT_MAX → clamped to LIMIT_MAX with a MODIFIED warning ("Clamped to system maximum").
  
  0 or value < -1 → invalid; MODIFIED warning, fallback to LIMIT_DEFAULT.
  
  Non-integer string → MODIFIED warning, fallback to LIMIT_DEFAULT.
  
  [1..LIMIT_MAX] → returned as-is.
  Returns:
  
  the resolved limit, always in [1..LIMIT_MAX]
- resolveOffset
  
  protected int resolveOffset()
  Resolves the offset pagination parameter from the current request.
  
  Absent or null → returns OFFSET_DEFAULT (0).
  
  Valid integer >= 0 → returned as-is.
  
  Negative integer → MODIFIED warning, fallback to OFFSET_DEFAULT.
  
  Non-integer string → MODIFIED warning, fallback to OFFSET_DEFAULT.
  Returns:
  
  the resolved offset, always >= 0
- resolvePolymorphic
  
  protected boolean resolvePolymorphic()
  
  Resolves the polymorphic query parameter from the current request.
  Default: true.
  
  Returns:
  
  the resolved value
- resolveDepth
  
  protected int resolveDepth()
  Resolves the depth query parameter from the current request.
  
  Absent or null → returns DEPTH_DEFAULT.
  
  Valid integer >= -1 → returned as-is.
  
  Integer < -1 → MODIFIED warning, fallback to DEPTH_DEFAULT.
  
  Non-integer string → MODIFIED warning, fallback to DEPTH_DEFAULT.
  Returns:
  
  the resolved depth, always >= -1
- resolveDepth
  
  protected int resolveDepth(int defaultValue)
  
  Resolves the depth query parameter from the current request, falling back to an explicit caller-supplied default instead of the global DEPTH_DEFAULT.
  Used by endpoints whose default differs from DEPTH_DEFAULT (e.g. QUERY /types, which defaults to -1 for polymorphic-equivalent matching, unlike the 0 default of the Read endpoints).
  
  Parameters:
  
  defaultValue - the depth to fall back to when absent or invalid
  
  Returns:
  
  the resolved depth, always >= -1
- resolveHierarchical
  
  protected boolean resolveHierarchical()
  
  Resolves the hierarchical query parameter from the current request.
  Default: false.
  
  Returns:
  
  the resolved value
- resolveSyncExistingHierarchy
  
  protected boolean resolveSyncExistingHierarchy()
  
  Resolves the syncExistingHierarchy query parameter from the current request.
  Default: false. Mutually exclusive with hierarchical=true; the calling endpoint is responsible for enforcing that constraint.
  
  Returns:
  
  the resolved value
- resolvePropagationMode
  
  protected org.gcube.informationsystem.resourceregistry.api.rest.PropagationMode resolvePropagationMode()
  
  Resolves the propagationMode query parameter from the current request.
  Accepted values: the PropagationMode enum constants (shallow, deep, surgical, case-insensitive). Any other string falls back to PropagationMode.DEFAULT with a MODIFIED warning.
  
  Note: authorization checks (e.g. restricting surgical to global administrators) are NOT performed here; they must be enforced by the calling endpoint in the PEP subclass.
  
  Returns:
  
  the resolved PropagationMode, never null
- resolveDryRun
  
  protected boolean resolveDryRun()
  
  Resolves the dryRun query parameter from the current request.
  Default: false.
  
  Returns:
  
  the resolved value
- resolveIncludeMeta
  
  protected boolean resolveIncludeMeta()
  
  Resolves the includeMeta query parameter from the current request.
  Default: false.
  
  Returns:
  
  the resolved value
- resolveAllMeta
  
  protected boolean resolveAllMeta()
  
  Resolves the allMeta query parameter from the current request.
  Default: false. Requires includeMeta=true to have any effect; enforcement is the caller's responsibility.
  
  Returns:
  
  the resolved value
- resolveMetadataPolicy
  
  protected org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy resolveMetadataPolicy()
  Resolves metadata inclusion policy for the current request.
  Canonical parameter is metadataPolicy with accepted values none, root, all. Legacy parameters (includeMeta, allMeta) are accepted only for server-side operational compatibility and mapped to the canonical policy when metadataPolicy is not provided.
  
  Canonical absent + includeMeta=false/absent + allMeta=false/absent -> none
  
  Canonical absent + includeMeta=true + allMeta=false/absent -> root
  
  Canonical absent + includeMeta=true + allMeta=true -> all
  
  Canonical absent + includeMeta=false/absent + allMeta=true -> none (with warning)
  
  When canonical metadataPolicy is present, it has precedence; legacy parameters are ignored (with warning).
  Returns:
  
  resolved MetadataPolicy, never null
- resolveIncludeContexts
  
  protected boolean resolveIncludeContexts()
  
  Resolves the includeContexts query parameter from the current request.
  Default: false.
  
  Returns:
  
  the resolved value
- warnEnrichmentParametersIgnoredByEmitProjection
  
  protected void warnEnrichmentParametersIgnoredByEmitProjection()
  
  Reports that metadataPolicy/includeContexts were requested but had no effect because the query's _emit projection replaced the full instance representation with a flat, projection-only response (Canonical _emit Precedence Rules, appendix/07-json-query-syntax-reference.md). Mirrors rawResult=true's equivalent warning for the admin raw-query endpoint.
  Shared by every query engine that executes an _emit-capable JSON query (direct instance queries and Query Template execution), since the precedence rule is documented as applying uniformly across all of them.
- resolveRawResult
  
  protected boolean resolveRawResult()
  
  Resolves the rawResult query parameter from the current request (raw-query endpoint only).
  Default: false.
  
  Returns:
  
  the resolved value
- resolveBypassHierarchyCheck
  
  protected boolean resolveBypassHierarchyCheck()
  
  Resolves the bypassHierarchyCheck query parameter from the current request (admin add-to-context endpoint only).
  Default: false. Authorization enforcement (IS-M / Infra-M only) is the caller's responsibility.
  
  Returns:
  
  the resolved value

Class PolicyEnforcementPoint

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

IS_MANAGER

INFRASTRUCTURE_MANAGER

IS_ADMIN

CONTEXT_MANAGER

IS_EDITOR

IS_CONTRIBUTOR

IS_MEMBER

GLOBAL_PRIVILEGED_ROLES

SUBTREE_ADMIN_ROLES

ALL_ADMIN_ROLES

ALL_OPERATIONAL_ROLES

DEPTH_DEFAULT

LIMIT_DEFAULT

LIMIT_MAX

OFFSET_DEFAULT

LEGACY_INCLUDE_META_QUERY_PARAMETER

LEGACY_ALL_META_QUERY_PARAMETER

requestContext

Constructor Details

PolicyEnforcementPoint

Method Details

getUriInfo

addQueryParameterWarning

addContentWarning

addIgnoredFieldsWarning

getQueryParameterWarnings

getContentWarnings

getIgnoredFieldsWarnings

getAllWarnings

addResultScope

getResultScopes

addPreferenceApplied

getPreferenceApplied

setResolvedContextPath

getResolvedContextPath

addLink

addPaginationLinks

buildUri

getLinks

setContentLocation

getContentLocation

isPrivilegedUser

isAdministrativeUser

isUserAllowed

resolveTokenContextUuid

hasNonActiveDescendant

enforceTargetContextWithinTokenSubtree

enforcePolicy

validateQueryParameters

resolveBoolean

resolveLimit

resolveOffset

resolvePolymorphic

resolveDepth

resolveDepth

resolveHierarchical

resolveSyncExistingHierarchy

resolvePropagationMode

resolveDryRun

resolveIncludeMeta

resolveAllMeta

resolveMetadataPolicy

resolveIncludeContexts

warnEnrichmentParametersIgnoredByEmitProjection

resolveRawResult

resolveBypassHierarchyCheck