Package org.gcube.informationsystem.resourceregistry.instances

Class InstancesPolicyEnforcementPoint

java.lang.Object

org.gcube.informationsystem.resourceregistry.pep.PolicyEnforcementPoint

org.gcube.informationsystem.resourceregistry.instances.InstancesPolicyEnforcementPoint

public class InstancesPolicyEnforcementPoint
extends PolicyEnforcementPoint

Policy Enforcement Point (PEP) for the Instances collection.

Enforces role-based endpoint access control, executes declarative validation of query parameters, and delegates JSON query executions to the underlying InstancesJsonQueryExecutor.

Author:

Luca Frosini (ISTI - CNR)

Nested Class Summary

Nested classes/interfaces inherited from class org.gcube.informationsystem.resourceregistry.pep.PolicyEnforcementPoint

PolicyEnforcementPoint.EndpointPolicySpec, PolicyEnforcementPoint.QueryParamSpec, PolicyEnforcementPoint.TokenScopeRule

Field Summary

Fields inherited from class org.gcube.informationsystem.resourceregistry.pep.PolicyEnforcementPoint

ALL_ADMIN_ROLES, ALL_OPERATIONAL_ROLES, CONTEXT_MANAGER, DEPTH_DEFAULT, GLOBAL_PRIVILEGED_ROLES, INFRASTRUCTURE_MANAGER, IS_ADMIN, IS_CONTRIBUTOR, IS_EDITOR, IS_MANAGER, IS_MEMBER, LEGACY_ALL_META_QUERY_PARAMETER, LEGACY_INCLUDE_META_QUERY_PARAMETER, LIMIT_DEFAULT, LIMIT_MAX, OFFSET_DEFAULT, requestContext, SUBTREE_ADMIN_ROLES

Constructor Summary

Constructors

Constructor	Description
InstancesPolicyEnforcementPoint(jakarta.ws.rs.container.ContainerRequestContext requestContext)	Creates a new InstancesPolicyEnforcementPoint instance associated with the current JAX-RS request context.

Method Summary

Modifier and Type	Method	Description
String	addToContext(String type, String instanceId, String newContextId)	Adds an existing instance to another context under authorized constraints.
String	addToContext(String type, String instanceId, String newContextId, org.gcube.informationsystem.resourceregistry.api.rest.PropagationMode defaultPropagationMode)	Adds an existing instance to another context under authorized constraints.
String	adminAddToContext(String type, String instanceId, String newContextId)	Adds an existing instance to another Context on behalf of a globally-privileged administrator, under the Admin Add to Context contract.
String	adminRawQuery(String query)	Executes an arbitrary read-only raw query directly against the backend database, on behalf of a globally-privileged administrator.
String	adminRemoveFromContext(String type, String instanceId)	Removes an existing instance from the current Context on behalf of a globally-privileged administrator, under the Admin Remove from Context contract.
String	create(String type, String json)	Creates a new instance of the specified type, non-idempotently.
org.gcube.informationsystem.resourceregistry.api.rest.OperationReturn	getOperationReturn()	Returns the operation-envelope return shape applied to the current request.
PageResult	list(String type)	Lists instances of the specified type under authorized constraints.
String	listContexts(String type, String instanceId)	Lists the visible Context memberships of the specified exact instance.
String	mergeUpdate(String type, String instanceId, String json)	Applies a merge update to an existing instance of the specified type and UUID under authorized constraints.
PageResult	query(String jsonQuery)	Executes a JSON query on the instances collection under authorized constraints.
String	read(String type, String instanceId)	Reads a single instance with the specified type and UUID under authorized constraints.
String	remove(String type, String instanceId)	Removes an existing instance from the current context under authorized constraints.
String	removeFromContext(String type, String instanceId, String contextId, org.gcube.informationsystem.resourceregistry.api.rest.PropagationMode defaultPropagationMode)	Removes an existing instance from the specified context under authorized constraints.
org.gcube.informationsystem.resourceregistry.api.rest.OperationReturn	resolveOperationReturn()	Resolves the requested operation envelope return preference from the current request context.
InstanceCreationResult	updateOrCreate(String type, String instanceId, String json)	Creates or updates an instance with the specified UUID under authorized constraints.

Methods inherited from class org.gcube.informationsystem.resourceregistry.pep.PolicyEnforcementPoint

addContentWarning, addIgnoredFieldsWarning, addLink, addPaginationLinks, addPreferenceApplied, addQueryParameterWarning, addResultScope, buildUri, enforcePolicy, enforceTargetContextWithinTokenSubtree, getAllWarnings, getContentLocation, getContentWarnings, getIgnoredFieldsWarnings, getLinks, getPreferenceApplied, getQueryParameterWarnings, getResolvedContextPath, getResultScopes, getUriInfo, hasNonActiveDescendant, isAdministrativeUser, isPrivilegedUser, isUserAllowed, resolveAllMeta, resolveBoolean, resolveBypassHierarchyCheck, resolveDepth, resolveDepth, resolveDryRun, resolveHierarchical, resolveIncludeContexts, resolveIncludeMeta, resolveLimit, resolveMetadataPolicy, resolveOffset, resolvePolymorphic, resolvePropagationMode, resolveRawResult, resolveSyncExistingHierarchy, resolveTokenContextUuid, setContentLocation, validateQueryParameters, warnEnrichmentParametersIgnoredByEmitProjection

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

InstancesPolicyEnforcementPoint

public InstancesPolicyEnforcementPoint(jakarta.ws.rs.container.ContainerRequestContext requestContext)

Creates a new InstancesPolicyEnforcementPoint instance associated with the current JAX-RS request context.

Parameters:

requestContext - the JAX-RS container request context

Method Details

getOperationReturn

public org.gcube.informationsystem.resourceregistry.api.rest.OperationReturn getOperationReturn()

Returns the operation-envelope return shape applied to the current request.

Returns:

the applied operation-envelope return shape

resolveOperationReturn

public org.gcube.informationsystem.resourceregistry.api.rest.OperationReturn resolveOperationReturn()

Resolves the requested operation envelope return preference from the current request context.

Returns:

the resolved operation envelope return preference

read

public String read(String type,
 String instanceId)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a single instance with the specified type and UUID under authorized constraints.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

Returns:

the serialized JSON representation of the retrieved instance

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the lookup fails or the caller lacks visibility

query

public PageResult query(String jsonQuery)
                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Executes a JSON query on the instances collection under authorized constraints.

Parameters:

jsonQuery - the JSON query payload string

Returns:

a paginated page of matching instances

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the query syntax or structure is invalid

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or processing failure

adminRawQuery

public String adminRawQuery(String query)
                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Executes an arbitrary read-only raw query directly against the backend database, on behalf of a globally-privileged administrator.

Strictly a manual diagnostic tool: never invoke this programmatically, and never surface it via any client library. The persistence engine backing this method is expected to change (see the PostgreSQL migration roadmap), so no compatibility guarantee is offered for the raw query surface or its syntax.

Parameters:

query - the backend-native query text to execute

Returns:

JSON array string of query results, in raw backend format or Information System model format depending on the resolved rawResult parameter

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the query is invalid or contains disallowed mutations

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or processing failure

list

public PageResult list(String type)
                throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Lists instances of the specified type under authorized constraints.

Parameters:

type - the case-sensitive concrete or abstract instance Type name

Returns:

a paginated page of retrieved instances

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or read failure

create

public String create(String type,
 String json)
              throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new instance of the specified type, non-idempotently. Unlike updateOrCreate(String, String, String), a client-supplied `id` — root or nested — is optional: present, it is honored and validated against the usual UUID-reuse guard; absent, a fresh UUID is always server-generated.

Parameters:

type - the concrete type name of the instance

json - the serialized JSON representation of the new instance

Returns:

the serialized JSON representation of the created instance

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the creation fails or the caller lacks privileges

updateOrCreate

public InstanceCreationResult updateOrCreate(String type,
 String instanceId,
 String json)
                                      throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates or updates an instance with the specified UUID under authorized constraints.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

json - the serialized JSON representation of the instance

Returns:

the serialized representation and atomic create/update outcome

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the upsert fails or the caller lacks privileges

mergeUpdate

public String mergeUpdate(String type,
 String instanceId,
 String json)
                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Applies a merge update to an existing instance of the specified type and UUID under authorized constraints.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

json - the serialized JSON representation of the merge update payload

Returns:

the serialized JSON representation of the merge-updated instance

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the merge update fails or the caller lacks privileges

remove

public String remove(String type,
 String instanceId)
              throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an existing instance from the current context under authorized constraints.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

Returns:

the serialized JSON representation of the removed instance

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the removal fails or the caller lacks privileges

removeFromContext

public String removeFromContext(String type,
 String instanceId,
 String contextId,
 org.gcube.informationsystem.resourceregistry.api.rest.PropagationMode defaultPropagationMode)
                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an existing instance from the specified context under authorized constraints.

This method is intended for deprecated compatibility endpoints whose target Context is still encoded in the legacy URI.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

contextId - the unique identifier of the target context

defaultPropagationMode - the propagation mode to apply when no query parameter is supplied

Returns:

the serialized operation envelope

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the removal fails or the caller lacks privileges

adminRemoveFromContext

public String adminRemoveFromContext(String type,
 String instanceId)
                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an existing instance from the current Context on behalf of a globally-privileged administrator, under the Admin Remove from Context contract.

When hierarchical=true, the removal is atomically applied to the caller's token Context and every one of its descendants in a single transaction. If the caller's token is for the Root Context, this effectively annihilates the instance from every Context it belongs to.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

Returns:

the serialized operation envelope

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the removal fails or the caller lacks privileges

addToContext

public String addToContext(String type,
 String instanceId,
 String newContextId)
                    throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an existing instance to another context under authorized constraints.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

newContextId - the unique identifier of the target context

Returns:

the serialized affected-instance operation envelope

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the addition fails or the caller lacks privileges

addToContext

public String addToContext(String type,
 String instanceId,
 String newContextId,
 org.gcube.informationsystem.resourceregistry.api.rest.PropagationMode defaultPropagationMode)
                    throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an existing instance to another context under authorized constraints.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

newContextId - the unique identifier of the target context

defaultPropagationMode - the propagation mode to apply when no query parameter is supplied

Returns:

the serialized affected-instance operation envelope

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the addition fails or the caller lacks privileges

adminAddToContext

public String adminAddToContext(String type,
 String instanceId,
 String newContextId)
                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an existing instance to another Context on behalf of a globally-privileged administrator, under the Admin Add to Context contract.

Unlike the standard addToContext(String, String, String), this method allows propagationMode=surgical and honours bypassHierarchyCheck: when true, the destination Context is not required to lie within the caller's token-Context subtree. When false (default), the exact same subtree-containment check enforced on the standard endpoint still applies.

When hierarchical=true, the addition is atomically applied to the destination Context and every one of its descendants in a single transaction.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

newContextId - the unique identifier of the target context

Returns:

the serialized affected-instance operation envelope

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the addition fails or the caller lacks privileges

listContexts

public String listContexts(String type,
 String instanceId)
                    throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Lists the visible Context memberships of the specified exact instance.

Parameters:

type - the concrete type name of the instance

instanceId - the unique identifier of the instance

Returns:

JSON object string mapping Context UUIDs to paths

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the lookup fails or the caller lacks privileges