Package org.gcube.informationsystem.resourceregistry.rest

Class QueryTemplateManager

java.lang.Object
org.gcube.informationsystem.resourceregistry.rest.BaseRest
org.gcube.informationsystem.resourceregistry.rest.QueryTemplateManager
@Path("query-templates") public class QueryTemplateManager extends BaseRest
Author:
Luca Frosini (ISTI - CNR)

  • Field Details

  • Constructor Details

    • QueryTemplateManager

      public QueryTemplateManager()

  • Method Details

    • all

      @GET @Consumes({"text/plain","application/json;charset=UTF-8"}) @Produces("application/json;charset=UTF-8") public String all() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves all query templates from the Resource Registry. REST Endpoint: GET /query-templates Request Examples:
      • Basic query: GET /query-templates
      • With pagination: GET /query-templates?limit=20&offset=40
      • With metadata: GET /query-templates?includeMeta=true
      • Combined parameters: GET /query-templates?limit=15&offset=30&includeMeta=true.
      Query Parameters: limit (optional):
      • Maximum number of query templates to return in a single response
      • Default value: 10
      • Example: ?limit=50 (returns at most 50 query templates).
      offset (optional):
      • Number of query templates to skip from the beginning of the result set
      • Default value: 0 (starts from the first query template)
      • Example: ?offset=100 (skips the first 100 query templates).
      includeMeta (optional):
      • Whether to include metadata in the response query templates
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)
      • Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      Authorization Requirements: IS-Manager:
      • Full access to all query templates
      • Can access query templates across all contexts
      • Receives complete, unfiltered metadata including all administrative fields.
      Infrastructure-Manager:
      • Full access to all query templates
      • Can access query templates across all contexts
      • Receives complete, unfiltered metadata including all administrative fields.
      Other Users:
      • Basic access with metadata filtering
      • Receive metadata with sensitive information filtered when includeMeta=true.
      Response Codes:
      • 200 OK: Query templates successfully retrieved
      • 400 Bad Request: Invalid query parameters (e.g., invalid limit/offset values)
      • 403 Forbidden: Insufficient permissions to access query templates.
      Response Format:
      • Returns a JSON array containing the requested query templates
      • Each query template includes its name, description, template definition, template variables, and metadata (if requested)
      • Empty array is returned if no query templates exist in the accessible contexts.
      Example Metadata (filtered for non-admin users): ``json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Returns:
      JSON array containing the requested query templates with their properties and metadata (if requested)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If query templates cannot be retrieved
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template retrieval

    • updateCreate

      @PUT @Path("{query-template-name}") @Consumes({"text/plain","application/json;charset=UTF-8"}) @Produces("application/json;charset=UTF-8") public String updateCreate(@PathParam("query-template-name") String queryTemplateName, String json) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates a new query template or updates an existing query template with the specified name in the Resource Registry. REST Endpoint: PUT /query-templates/{query-template-name} Request Examples:
      • Basic create/update: PUT /query-templates/GetAllEServiceWithState
      • With metadata in response: PUT /query-templates/GetAllEServiceWithState?includeMeta=true.
      Path Parameters:
      • query-template-name: The name of the query template to create or update (e.g., "GetAllEServiceWithState")
      • Important: This name must exactly match the "name" field in the JSON body, otherwise a 400 Bad Request error will be returned.
      Request Body:
      • JSON representation of the query template to create or update
      • The "name" field in the JSON must match the query-template-name path parameter.

      The template field contains a JSON query following the Query by Example (QBE) paradigm, first introduced by Moshé M. Zloof for relational databases (AFIPS National Computer Conference, 1975). This approach allows users to specify queries by providing example structures of the data they want to retrieve.

      Similar implementations exist in modern database systems. For example, MongoDB uses query documents that are query predicates - expressions that return a boolean indicating whether a document matches the specified query.

      The JSON query can include template variables (prefixed with $) that will be replaced with actual values when the query template is executed. Each variable must be declared in the templateVariables field with:
      • name: The variable name (e.g., "$state")
      • description: A description of the variable's purpose
      • defaultValue: The default value used for query validation during template creation/update.
      Example Request Body: ``json { "name" : "GetAllEServiceWithState", "description" : "The following query return all the EService having the state provided as parameters, e.g. down, ready. The content of the request to run this query template will be something like {\"$state\": "ready"}", "template": { "type": "EService", "consistsOf": [{ "type": "ConsistsOf", "target": { "type": "StateFacet", "value": "$state" } }] }, "templateVariables" = { "$state" : { "name": "$state", "description": "The state of the EService, e.g. down, ready.", "defaultValue": "ready" } } } ` <strong>Query Parameters:</strong> <strong>includeMeta</strong> (optional): <ul> <li>Whether to include metadata in the response query template</li> <li>Default value: false (basic information only)</li> <li>Values: true|false</li> <li>Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)</li> <li><strong>Restriction:</strong> IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.</li> </ul> <strong>Authorization Requirements:</strong> <strong>IS-Manager:</strong> <ul> <li>Full access to create/update any query template</li> <li>Can create/update query templates across all contexts</li> <li>Receives complete, unfiltered metadata including all administrative fields in the response.</li> </ul> <strong>Infrastructure-Manager:</strong> <ul> <li>Full access to create/update any query template</li> <li>Can create/update query templates across all contexts</li> <li>Receives complete, unfiltered metadata including all administrative fields in the response.</li> </ul> <strong>Other Users:</strong> <ul> <li>Limited create/update permissions based on context access</li> <li>Receive metadata with sensitive information filtered when includeMeta=true.</li> </ul> <strong>Operation Behavior:</strong> <ul> <li><strong>Create</strong>: If the query template with the specified name does not exist, creates a new query template</li> <li><strong>Update</strong>: If the query template with the specified name exists, updates the existing query template</li> <li><strong>Name Validation</strong>: The path parameter <strong>query-template-name</strong> must exactly match the "name" field in the JSON body</li> <li><strong>Query Validation</strong>: The template query is automatically tested during creation/update</li> <li><strong>Parameter Declaration</strong>: Every parameter used in the query (prefixed with $) must have a corresponding declaration in templateVariables</li> <li><strong>Default Value Substitution</strong>: During validation, parameters are replaced with their default values before executing the query</li> <li><strong>Valid Default Values</strong>: Default values must be valid for the query execution - the query must be able to run on the system</li> <li><strong>Result Independence</strong>: The query doesn't need to return results during validation (empty results are acceptable), but it must execute without errors</li> <li>The operation is idempotent and atomic.</li> </ul> <strong>Response Codes:</strong> <ul> <li><strong>200 OK</strong>: Query template successfully updated (existing template modified)</li> <li><strong>201 Created</strong>: Query template successfully created (new template)</li> <li><strong>400 Bad Request</strong>: Invalid request body, malformed JSON, or path parameter name does not match JSON name field</li> <li><strong>403 Forbidden</strong>: Insufficient permissions to create/update the query template.</li> </ul> <strong>Response Format:</strong> <ul> <li>Returns a JSON object containing the created or updated query template</li> <li>Includes name, description, template definition, template variables, and metadata (if requested).</li> </ul> <strong>Example Metadata (filtered for non-admin users):</strong> `json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Parameters:
      queryTemplateName - The name of the query template to create or update (must match the "name" field in the JSON body)
      json - JSON representation of the query template to create or update
      Returns:
      JSON object containing the created or updated query template with its properties and metadata (if requested)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - If the query template definition is invalid
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template creation or update

    • read

      @GET @Path("{query-template-name}") @Produces("application/json;charset=UTF-8") public String read(@PathParam("query-template-name") String queryTemplateName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves a specific query template by its name from the Resource Registry. REST Endpoint: GET /query-templates/{query-template-name} Request Examples:
      • Basic query: GET /query-templates/GetAllEServiceWithState
      • With metadata: GET /query-templates/GetAllEServiceWithState?includeMeta=true.
      Path Parameters:
      • query-template-name: The name of the query template to retrieve (e.g., "GetAllEServiceWithState").
      Query Parameters: includeMeta (optional):
      • Whether to include metadata in the response query template
      • Default value: false (basic information only)
      • Values: true|false
      • Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)
      • Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      Authorization Requirements: IS-Manager:
      • Full access to retrieve any query template
      • Can access query templates across all contexts
      • Receives complete, unfiltered metadata including all administrative fields.
      Infrastructure-Manager:
      • Full access to retrieve any query template
      • Can access query templates across all contexts
      • Receives complete, unfiltered metadata including all administrative fields.
      Other Users:
      • Basic access with metadata filtering
      • Receive metadata with sensitive information filtered when includeMeta=true.
      Response Codes:
      • 200 OK: Query template successfully retrieved
      • 404 Not Found: Query template with the specified name does not exist
      • 403 Forbidden: Insufficient permissions to access the query template.
      Response Format:
      • Returns a JSON object containing the requested query template
      • Includes name, description, template definition, template variables, and metadata (if requested).
      Example Metadata (filtered for non-admin users): ``json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Parameters:
      queryTemplateName - The name of the query template to retrieve
      Returns:
      JSON object containing the requested query template with its properties and metadata (if requested)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template retrieval

    • run

      @POST @Path("{query-template-name}") @Produces("application/json;charset=UTF-8") public String run(@PathParam("query-template-name") String queryTemplateName, String params) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a query template with the specified name and parameters in the Resource Registry. REST Endpoint: POST /query-templates/{query-template-name} Request Examples:
      • Basic execution: POST /query-templates/GetAllEServiceWithState
      • With polymorphic disabled: POST /query-templates/GetAllEServiceWithState?polymorphic=false
      • With metadata: POST /query-templates/GetAllEServiceWithState?includeMeta=true
      • Hierarchical (admin only): POST /query-templates/GetAllEServiceWithState?hierarchical=true
      • Full metadata context: POST /query-templates/GetAllEServiceWithState?includeMeta=true&allMeta=true
      • With context information: POST /query-templates/GetAllEServiceWithState?includeContexts=true.
      Path Parameters:
      • query-template-name: The name of the query template to execute (e.g., "GetAllEServiceWithState").
      Request Body:
      • JSON object containing parameter values to substitute in the query template
      • Parameters not provided in the body will use their default values from the template definition
      • Parameter names must match those defined in the template's templateVariables section.
      Example Request Body for GetAllEServiceWithState: ``json { "$state" : "down" } ` <strong>Query Parameters:</strong> <strong>polymorphic</strong> (optional): <ul> <li>Whether the query should consider instances polymorphically (include subtypes)</li> <li>Default value: true (includes all subtypes)</li> <li>Values: true|false</li> <li>Example: ?polymorphic=false (exact type match only, may slow down the query)</li> <li>When false, only instances of the exact types defined in the query are returned</li> <li>When true, instances of derived types are also included.</li> </ul> <strong>includeMeta</strong> (optional): <ul> <li>Whether to include metadata in the response instances</li> <li>Default value: false (basic information only)</li> <li>Values: true|false</li> <li>Example: ?includeMeta=true (includes metadata with appropriate filtering based on user role)</li> <li><strong>Effect</strong>: Only applies when query returns complete instances of defined types</li> <li><strong>No Effect</strong>: When query uses _emit to return individual fields instead of complete instances</li> <li><strong>Restriction:</strong> IS-Manager and Infrastructure-Manager see complete metadata; other users see filtered metadata with sensitive fields obfuscated.</li> </ul> <strong>allMeta</strong> (optional): <ul> <li>Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.)</li> <li>Must be used in conjunction with includeMeta=true</li> <li>Default value: false (metadata only for main instances, more human-readable)</li> <li>Values: true|false</li> <li>Example: ?includeMeta=true&allMeta=true (includes metadata for all nested elements)</li> <li><strong>Effect</strong>: Only applies when query returns complete instances of defined types</li> <li><strong>No Effect</strong>: When query uses _emit to return individual fields instead of complete instances.</li> </ul> <strong>hierarchical</strong> (optional, admin-only): <ul> <li>Whether to execute the query across child contexts of the current context</li> <li>Default value: false (current context only)</li> <li>Values: true|false</li> <li><strong>Restriction:</strong> Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles (Context-Manager must be of the current context derived from the authorization token)</li> <li>Example: ?hierarchical=true (executes query in current and child contexts)</li> <li>Current context is determined from the authorization token.</li> </ul> <strong>includeContexts</strong> (optional): <ul> <li>Whether to include the list of contexts where each returned instance is available</li> <li>Default value: false (context information not included)</li> <li>Values: true|false</li> <li>Example: ?includeContexts=true (shows context availability for each instance)</li> <li><strong>Effect</strong>: Only applies when query returns complete instances of defined types</li> <li><strong>No Effect</strong>: When query uses _emit to return individual fields instead of complete instances</li> <li><strong>Note:</strong> A Resource is present in all contexts that form the union of contexts of all its Facets.</li> </ul> <strong>Authorization Requirements:</strong> <strong>IS-Manager:</strong> <ul> <li>Full access to execute any query template</li> <li>Can use hierarchical querying across all contexts</li> <li>Receives complete, unfiltered metadata including all administrative fields.</li> </ul> <strong>Infrastructure-Manager:</strong> <ul> <li>Full access to execute any query template</li> <li>Can use hierarchical querying across all contexts</li> <li>Receives complete, unfiltered metadata including all administrative fields.</li> </ul> <strong>Context-Manager:</strong> <ul> <li>Can execute query templates with hierarchical querying within their managed context hierarchy</li> <li>Must be Context-Manager of the current context (derived from the authorization token)</li> <li>Receives complete, unfiltered metadata including all administrative fields.</li> </ul> <strong>Other Users:</strong> <ul> <li>Can execute query templates in the current context only</li> <li>Cannot use hierarchical querying (hierarchical parameter ignored)</li> <li>Receive metadata with sensitive information filtered when includeMeta=true.</li> </ul> <strong>Operation Behavior:</strong> <ul> <li><strong>Parameter Substitution</strong>: Parameters in the template query (prefixed with $) are replaced with values from the request body</li> <li><strong>Default Values</strong>: Parameters not provided in the request body use their default values from the template definition</li> <li><strong>Query Execution</strong>: The resulting query is executed against the Resource Registry</li> <li><strong>Response Type</strong>: Can return complete instances or individual fields (when using _emit in the query)</li> <li><strong>Metadata Effect</strong>: includeMeta, allMeta, and includeContexts only affect queries returning complete instances, not _emit queries</li> <li><strong>Polymorphic Behavior</strong>: When disabled (polymorphic=false), may impact query performance but ensures exact type matching</li> <li><strong>No Pagination</strong>: Pagination is not currently supported for query template execution</li> </ul> <strong>Response Codes:</strong> <ul> <li><strong>200 OK</strong>: Query template successfully executed</li> <li><strong>400 Bad Request</strong>: Invalid query parameters or malformed parameter values</li> <li><strong>404 Not Found</strong>: Query template with the specified name does not exist</li> <li><strong>403 Forbidden</strong>: Insufficient permissions to execute the query template.</li> </ul> <strong>Response Format:</strong> <ul> <li>Returns query results based on the template definition</li> <li>For complete instances: JSON array containing instances with properties, relations, and metadata (if requested)</li> <li>For _emit queries: JSON array containing individual field values as specified in the query</li> <li>Response structure depends on the query template and parameter values provided.</li> </ul> <strong>Example Metadata (filtered for non-admin users, only for complete instances):</strong> `json "metadata": { "type": "Metadata", "creationTime": "2025-03-18 17:13:40.952 +0100", "createdBy": "HIDDEN_FOR_PRIVACY", "lastUpdateBy": "HIDDEN_FOR_PRIVACY", "lastUpdateTime": "2025-03-19 16:21:16.805 +0100" } ``
      Parameters:
      queryTemplateName - The name of the query template to execute
      params - JSON object containing parameter values for template substitution
      Returns:
      JSON array containing query results based on the template definition and parameters
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - If the query execution fails due to invalid parameters or query structure
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template execution

    • delete

      @DELETE @Consumes({"text/plain","application/json;charset=UTF-8"}) @Path("{query-template-name}") public jakarta.ws.rs.core.Response delete(@PathParam("query-template-name") String queryTemplateName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Deletes a query template with the specified name from the Resource Registry. REST Endpoint: DELETE /query-templates/{query-template-name} IMPORTANT: This is an irreversible operation that permanently removes the query template from the system. Request Examples:
      • Delete query template: DELETE /query-templates/GetAllEServiceWithState.
      Path Parameters:
      • query-template-name: The name of the query template to delete (e.g., "GetAllEServiceWithState").
      Query Parameters:
      • This endpoint does not accept any query parameters
      • No filtering or metadata options are available for delete operations.
      Authorization Requirements: IS-Manager:
      • Full access to delete any query template
      • Can delete query templates across all contexts.
      Infrastructure-Manager:
      • Full access to delete any query template
      • Can delete query templates across all contexts.
      Other Users:
      • Basic access to delete query templates
      • Same deletion permissions as administrative users.
      Operation Behavior:
      • Permanent Deletion: The query template is permanently removed from the system
      • Irreversible Operation: This operation cannot be undone
      • Template Unavailability: Once deleted, the query template name becomes available for reuse
      • Atomicity: The operation is atomic - either the template is completely deleted or the operation fails.
      Response Codes:
      • 204 No Content: Query template successfully deleted
      • 404 Not Found: Query template with the specified name does not exist
      • 403 Forbidden: Insufficient permissions to delete the query template.
      Response Format:
      • Content-Type: N/A (no response body)
      • Body: Empty (204 No Content response)
      • No response body is returned upon successful deletion
      • The query template is permanently removed from the system.
      Parameters:
      queryTemplateName - The name of the query template to delete
      Returns:
      HTTP 204 No Content response upon successful deletion
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template deletion