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.
      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