Package org.gcube.informationsystem.resourceregistry.publisher

Class ResourceRegistryPublisherImpl

java.lang.Object

org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

org.gcube.informationsystem.resourceregistry.publisher.ResourceRegistryPublisherImpl

All Implemented Interfaces:

org.gcube.informationsystem.resourceregistry.api.request.RequestInfo, ResourceRegistryPublisher

public class ResourceRegistryPublisherImpl
extends org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo
implements ResourceRegistryPublisher

Implementation of the ResourceRegistryPublisher interface. Provides concrete implementation for all Resource Registry operations including CRUD operations for Resources, Facets, and Relations, as well as context management functionality.

Author:

Luca Frosini (ISTI - CNR)

Field Summary

Fields

Modifier and Type	Field	Description
protected final String	address	The base address of the Resource Registry service
protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache	contextCache	Cache for context information to improve performance
protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCacheRenewal	contextCacheRenewal	Context cache renewal strategy for refreshing cached context information
protected Map<String,String>	headers	HTTP headers to be included in requests

Fields inherited from class org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

allMeta, hierarchicalMode, includeContexts, includeMeta, limit, offset

Fields inherited from interface org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

DEFAULT_LIMIT, DEFAULT_OFFSET, UNBOUNDED_LIMIT

Constructor Summary

Constructors

Constructor	Description
ResourceRegistryPublisherImpl(String address)	Creates a new ResourceRegistryPublisherImpl instance with a shared context cache.
ResourceRegistryPublisherImpl(String address, boolean sharedContextCache)	Creates a new ResourceRegistryPublisherImpl instance.

Method Summary

Modifier and Type	Method	Description
<F extends org.gcube.informationsystem.model.reference.entities.Facet> List<org.gcube.informationsystem.model.reference.ERElement>	addFacetToContext(F facet, UUID contextUUID, Boolean dryRun)	Adds a Facet instance to a specific context using a provided Facet object.
List<org.gcube.informationsystem.model.reference.ERElement>	addFacetToContext(String facetType, UUID facetUUID, UUID contextUUID, Boolean dryRun)	Adds a Facet instance to a specific context using type name and UUID.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> List<org.gcube.informationsystem.model.reference.ERElement>	addFacetToCurrentContext(F facet, Boolean dryRun)	Adds a Facet instance to the current context using a provided Facet object.
List<org.gcube.informationsystem.model.reference.ERElement>	addFacetToCurrentContext(String facetType, UUID facetUUID, Boolean dryRun)	Adds a Facet instance to the current context using type name and UUID.
void	addHeader(String name, boolean value)	Adds a custom HTTP header to be included in requests.
void	addHeader(String name, String value)	Adds a custom HTTP header to be included in requests.
List<org.gcube.informationsystem.model.reference.ERElement>	addResourceToContext(String resourceType, UUID resourceUUID, UUID contextUUID, Boolean dryRun)	Adds a Resource instance to a specific context.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> List<org.gcube.informationsystem.model.reference.ERElement>	addResourceToContext(R resource, UUID contextUUID, Boolean dryRun)	Adds a Resource instance to a specific context using a provided Resource object.
List<org.gcube.informationsystem.model.reference.ERElement>	addResourceToCurrentContext(String resourceType, UUID resourceUUID, Boolean dryRun)	Adds a Resource instance to the current context.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> List<org.gcube.informationsystem.model.reference.ERElement>	addResourceToCurrentContext(R resource, Boolean dryRun)	Adds a Resource instance to the current context using a provided Resource object.
List<org.gcube.informationsystem.model.reference.ERElement>	addToContext(String type, UUID instanceUUID, UUID contextUUID, Boolean dryRun)	Adds an Information System element instance to a specific context.
List<org.gcube.informationsystem.model.reference.ERElement>	addToContext(org.gcube.informationsystem.model.reference.ERElement er, UUID contextUUID, Boolean dryRun)	Adds an Information System element instance to a specific context using a provided instance object.
List<org.gcube.informationsystem.model.reference.ERElement>	addToCurrentContext(String type, UUID instanceUUID, Boolean dryRun)	Adds an Information System element instance to the current context.
List<org.gcube.informationsystem.model.reference.ERElement>	addToCurrentContext(org.gcube.informationsystem.model.reference.ERElement er, Boolean dryRun)	Adds an Information System element instance to the current context using a provided instance object.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> ERElem	create(ERElem er)	Creates a new instance of an Information System element in the Resource Registry.
String	create(String json)	Creates a new instance of an Information System element from JSON representation.
protected String	create(String type, String json, UUID uuid)	Creates a new instance of the specified type in the Resource Registry.
<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Facet>> C	createConsistsOf(C consistsOf)	Creates a new ConsistsOf relation instance in the Resource Registry.
String	createConsistsOf(String consistsOf)	Creates a new ConsistsOf relation instance from JSON representation.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> F	createFacet(F facet)	Creates a new Facet instance in the Resource Registry.
String	createFacet(String facet)	Creates a new Facet instance from JSON representation.
<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Resource>> I	createIsRelatedTo(I isRelatedTo)	Creates a new IsRelatedTo relation instance in the Resource Registry.
String	createIsRelatedTo(String isRelatedTo)	Creates a new IsRelatedTo relation instance from JSON representation.
String	createResource(String resource)	Creates a new Resource instance from JSON representation.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> R	createResource(R resource)	Creates a new Resource instance in the Resource Registry.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> boolean	delete(ERElem er)	Deletes an Information System element instance from the Resource Registry.
boolean	delete(String type, UUID uuid)	Deletes an Information System element instance from the Resource Registry using type name and UUID.
<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Facet>> boolean	deleteConsistsOf(C consistsOf)	Deletes a ConsistsOf relation instance from the Resource Registry.
boolean	deleteConsistsOf(String consistsOfType, UUID uuid)	Deletes a ConsistsOf relation instance from the Resource Registry using type name and UUID.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> boolean	deleteFacet(F facet)	Deletes a Facet instance from the Resource Registry.
boolean	deleteFacet(String facetType, UUID uuid)	Deletes a Facet instance from the Resource Registry using type name and UUID.
<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Resource>> boolean	deleteIsRelatedTo(I isRelatedTo)	Deletes an IsRelatedTo relation instance from the Resource Registry.
boolean	deleteIsRelatedTo(String isRelatedToType, UUID uuid)	Deletes an IsRelatedTo relation instance from the Resource Registry by its type and UUID.
boolean	deleteResource(String resourceType, UUID uuid)	Deletes a Resource instance from the Resource Registry using type name and UUID.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> boolean	deleteResource(R resource)	Deletes a Resource instance from the Resource Registry.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> boolean	exist(ERElem er)	Checks if an Information System element instance exists in the Resource Registry.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> boolean	exist(Class<ERElem> clazz, UUID uuid)	Checks if an Information System element instance exists in the Resource Registry using class and UUID.
boolean	exist(String type, UUID uuid)	Checks if an Information System element instance exists in the Resource Registry using type name and UUID.
List<org.gcube.informationsystem.contexts.reference.entities.Context>	getAllContextFromServer()	It reads all the contexts from server.
protected List<org.gcube.informationsystem.contexts.reference.entities.Context>	getAllContextFromServer(boolean includeMeta, Integer offset, Integer limit)	Retrieves all contexts from the Resource Registry server.
List<org.gcube.informationsystem.contexts.reference.entities.Context>	getAllContexts()	Retrieves all available contexts using internal cache.
org.gcube.informationsystem.contexts.reference.entities.Context	getContext(UUID uuid)	Retrieves a specific context by its UUID using internal cache.
org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache	getContextCache()	Gets the context cache used for context-related operations.
protected org.gcube.informationsystem.contexts.reference.entities.Context	getContextFromServer(String uuid)	Retrieves a specific context from the Resource Registry server.
org.gcube.informationsystem.contexts.reference.entities.Context	getContextFromServer(UUID uuid)	It reads the context from server.
org.gcube.informationsystem.contexts.reference.entities.Context	getCurrentContext()	Retrieves the current context associated with the publisher's authorization token using internal cache.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> Map<UUID,String>	getElementContexts(ERElem er)	Retrieves the list of contexts where a specific Information System element is present in the Resource Registry.
Map<UUID,String>	getElementContexts(String type, UUID instanceUUID)	Retrieves the list of contexts where a specific Information System element is present in the Resource Registry.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> Map<UUID,String>	getFacetContexts(F facet)	Retrieves the list of contexts where a specific Facet is present in the Resource Registry.
Map<UUID,String>	getFacetContexts(String facetType, UUID facetUUID)	Retrieves the list of contexts where a specific Facet is present in the Resource Registry.
protected org.gcube.common.gxhttp.request.GXHTTPStringRequest	getGXHTTPStringRequest()	Creates and configures a new HTTP request with authorization headers and custom headers.
Map<UUID,String>	getResourceContexts(String resourceType, UUID resourceUUID)	Retrieves the list of contexts where a specific Resource is present in the Resource Registry.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> Map<UUID,String>	getResourceContexts(R resource)	Retrieves the list of contexts where a specific Resource is present in the Resource Registry.
protected <ERElem extends org.gcube.informationsystem.model.reference.ERElement> String	internalCreate(ERElem er)	Internal method to create an Information System element.
boolean	isHierarchicalMode()
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> List<ERElem>	list(Class<ERElem> clazz, Boolean polymorphic)	Retrieves all instances of the specified type from the Resource Registry.
String	list(String type, Boolean polymorphic)	Retrieves all instances of the specified type from the Resource Registry as JSON string.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> ERElem	read(ERElem er)	Reads an existing instance from the Resource Registry using a provided instance object.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> ERElem	read(Class<ERElem> clazz, UUID uuid)	Reads an existing instance from the Resource Registry by its type class and UUID.
String	read(String type, UUID uuid)	Reads an existing instance from the Resource Registry by its type name and UUID.
<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Facet>> C	readConsistsOf(C consistsOf)	Reads a ConsistsOf relation instance from the Resource Registry using a provided instance object.
String	readConsistsOf(String consistsOfType, UUID uuid)	Reads a ConsistsOf relation instance from the Resource Registry by its type and UUID.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> F	readFacet(F facet)	Reads a Facet instance from the Resource Registry using a provided instance object.
String	readFacet(String facetType, UUID uuid)	Reads a Facet instance from the Resource Registry by its type and UUID.
<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Resource>> I	readIsRelatedTo(I isRelatedTo)	Reads an IsRelatedTo relation instance from the Resource Registry by its UUID.
String	readIsRelatedTo(String isRelatedToType, UUID uuid)	Reads an IsRelatedTo relation instance from the Resource Registry by its type and UUID.
String	readResource(String resourceType, UUID uuid)	Reads a Resource instance from the Resource Registry by its type and UUID.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> R	readResource(R resource)	Reads a Resource instance from the Resource Registry using a provided instance object.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> List<org.gcube.informationsystem.model.reference.ERElement>	removeFacetFromContext(F facet, UUID contextUUID, Boolean dryRun)	Removes a Facet instance from a specific context using a provided Facet object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFacetFromContext(String facetType, UUID facetUUID, UUID contextUUID, Boolean dryRun)	Removes a Facet instance from a specific context.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> List<org.gcube.informationsystem.model.reference.ERElement>	removeFacetFromCurrentContext(F facet, Boolean dryRun)	Removes a Facet instance from the current context using a provided Facet object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFacetFromCurrentContext(String facetType, UUID facetUUID, Boolean dryRun)	Removes a Facet instance from the current context.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFromContext(String type, UUID instanceUUID, UUID contextUUID, Boolean dryRun)	Removes an Information System element instance from a specific context.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFromContext(org.gcube.informationsystem.model.reference.ERElement er, UUID contextUUID, Boolean dryRun)	Removes an Information System element instance from a specific context using a provided instance object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFromCurrentContext(String type, UUID instanceUUID, Boolean dryRun)	Removes an ERElement instance from the current context.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFromCurrentContext(org.gcube.informationsystem.model.reference.ERElement er, Boolean dryRun)	Removes an ERElement instance from the current context using a provided ERElement object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeResourceFromContext(String resourceType, UUID resourceUUID, UUID contextUUID, Boolean dryRun)	Removes a Resource instance from a specific context.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> List<org.gcube.informationsystem.model.reference.ERElement>	removeResourceFromContext(R resource, UUID contextUUID, Boolean dryRun)	Removes a Resource instance from a specific context using a provided Resource object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeResourceFromCurrentContext(String resourceType, UUID resourceUUID, Boolean dryRun)	Removes a Resource instance from the current context.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> List<org.gcube.informationsystem.model.reference.ERElement>	removeResourceFromCurrentContext(R resource, Boolean dryRun)	Removes a Resource instance from the current context using a provided Resource object.
void	setHierarchicalMode(boolean hierarchicalMode)
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> ERElem	update(ERElem er)	Updates an existing instance in the Resource Registry using the instance object.
String	update(String json)	Updates an existing instance in the Resource Registry using JSON representation.
String	update(String type, String json)	Updates an existing instance in the Resource Registry using type name and JSON representation.
String	update(String type, String json, UUID uuid)	Updates an existing instance in the Resource Registry using type name, JSON representation, and explicit UUID.
<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Facet>> C	updateConsistsOf(C consistsOf)	Updates an existing ConsistsOf relation instance in the Resource Registry.
String	updateConsistsOf(String consistsOf)	Updates an existing ConsistsOf relation instance in the Resource Registry using JSON representation.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> F	updateFacet(F facet)	Updates an existing Facet instance in the Resource Registry.
String	updateFacet(String facet)	Updates an existing Facet instance in the Resource Registry using JSON representation.
<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Resource>> I	updateIsRelatedTo(I isRelatedTo)	Updates an existing IsRelatedTo relation instance in the Resource Registry.
String	updateIsRelatedTo(String isRelatedTo)	Updates an existing IsRelatedTo relation instance from JSON representation.
String	updateResource(String resource)	Updates an existing Resource instance in the Resource Registry using JSON representation.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> R	updateResource(R resource)	Updates an existing Resource instance in the Resource Registry.

Methods inherited from class org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

allMeta, getLimit, getOffset, includeContexts, includeMeta, setAllMeta, setIncludeContexts, setIncludeMeta, setLimit, setOffset

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

allMeta, getLimit, getOffset, includeContexts, includeMeta, setAllMeta, setIncludeContexts, setIncludeMeta, setLimit, setOffset

Field Details

address

protected final String address

The base address of the Resource Registry service

headers

protected Map<String,String> headers

HTTP headers to be included in requests

contextCache

protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache contextCache

Cache for context information to improve performance

contextCacheRenewal

protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCacheRenewal contextCacheRenewal

Context cache renewal strategy for refreshing cached context information

Constructor Details

ResourceRegistryPublisherImpl

public ResourceRegistryPublisherImpl(String address)

Creates a new ResourceRegistryPublisherImpl instance with a shared context cache.

Parameters:

address - The base address of the Resource Registry service

ResourceRegistryPublisherImpl

public ResourceRegistryPublisherImpl(String address,
 boolean sharedContextCache)

Creates a new ResourceRegistryPublisherImpl instance.

Parameters:

address - The base address of the Resource Registry service

sharedContextCache - Whether to use a shared context cache instance or create a new one

Method Details

isHierarchicalMode

public boolean isHierarchicalMode()

Specified by:

isHierarchicalMode in interface org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

Overrides:

isHierarchicalMode in class org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

setHierarchicalMode

public void setHierarchicalMode(boolean hierarchicalMode)

Specified by:

setHierarchicalMode in interface org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

Overrides:

setHierarchicalMode in class org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

addHeader

public void addHeader(String name,
 String value)

Adds a custom HTTP header to be included in requests.

Specified by:

addHeader in interface ResourceRegistryPublisher

Parameters:

name - Header name

value - Header value

addHeader

public void addHeader(String name,
 boolean value)

Adds a custom HTTP header to be included in requests.

Specified by:

addHeader in interface ResourceRegistryPublisher

Parameters:

name - Header name

value - boolean value

getGXHTTPStringRequest

protected org.gcube.common.gxhttp.request.GXHTTPStringRequest getGXHTTPStringRequest()

Creates and configures a new HTTP request with authorization headers and custom headers.

Returns:

A configured GXHTTPStringRequest instance ready for use

getAllContextFromServer

public List<org.gcube.informationsystem.contexts.reference.entities.Context> getAllContextFromServer()
                                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

It reads all the contexts from server. The cache used for contexts is bypassed and not updated.

Returns:

All Contexts read from server

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there is an error communicating with the server

getAllContextFromServer

protected List<org.gcube.informationsystem.contexts.reference.entities.Context> getAllContextFromServer(boolean includeMeta,
 Integer offset,
 Integer limit)
                                                                                                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves all contexts from the Resource Registry server.

Parameters:

includeMeta - Whether to include metadata in the response

offset - The offset for pagination

limit - The limit for pagination

Returns:

List of all contexts from the server

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the operation

getAllContexts

public List<org.gcube.informationsystem.contexts.reference.entities.Context> getAllContexts()
                                                                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves all available contexts using internal cache. Cache Behavior:

• Uses internal context cache - does NOT bypass cache like server-direct methods
• First call may trigger server request to populate cache
• Subsequent calls return cached data for improved performance
• Cache is automatically maintained and refreshed as needed.

Query Parameters NOT Applicable:

• Standard query parameters like includeMeta, limit, offset, hierarchical are NOT applicable to cached methods
• Cache behavior is controlled internally for optimal performance
• For direct server access with full query control, use the implementation's FromServer methods.

Authorization Requirements:

• Available to all authenticated users
• Returns contexts accessible based on user authorization level
• Context list is filtered according to user permissions.

Context Content:

• Includes all contexts where the user has any level of access
• Context details include basic information (name, UUID, parent relationships)
• Metadata inclusion depends on cache configuration and user role.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get all contexts from cache
 List<Context> contexts = publisher.getAllContexts();
 
 // Iterate through available contexts
 for (Context context : contexts) {
     System.out.println("Context: " + context.getName() + " (" + context.getUuid() + ")");
 }
 

Specified by:

getAllContexts in interface ResourceRegistryPublisher

Returns:

List of all contexts accessible to the current user (from cache)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If fails to retrieve contexts from cache or server

getContextCache

public org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache getContextCache()

Gets the context cache used for context-related operations. Cache Behavior:

• Provides access to the internal context cache used by all context methods
• Cache improves performance by avoiding repeated server requests
• Automatically manages cache updates and invalidation
• Used internally by getAllContexts(), getContext(), and getCurrentContext() methods.

Authorization Requirements:

• Available to all authenticated users
• Cache content is filtered based on user authorization level.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Access context cache for advanced operations
 ContextCache cache = publisher.getContextCache();
 
 // Force cache refresh if needed
 cache.refresh();
 

Specified by:

getContextCache in interface ResourceRegistryPublisher

Returns:

The context cache instance

getContextFromServer

public org.gcube.informationsystem.contexts.reference.entities.Context getContextFromServer(UUID uuid)
                                                                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

It reads the context from server. The cache used for contexts is bypassed and not updated.

Parameters:

uuid - the UUID of the context to read

Returns:

the Contexts read from server

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if there is an error communicating with the server

getContextFromServer

protected org.gcube.informationsystem.contexts.reference.entities.Context getContextFromServer(String uuid)
                                                                                        throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves a specific context from the Resource Registry server.

Parameters:

uuid - The UUID of the context to retrieve

Returns:

The context with the specified UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the context with the specified UUID is not found

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the operation

getContext

public org.gcube.informationsystem.contexts.reference.entities.Context getContext(UUID uuid)
                                                                           throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves a specific context by its UUID using internal cache. Cache Behavior:

• Uses internal context cache - does NOT bypass cache like server-direct methods
• First call may trigger cache population from server if needed
• Subsequent calls use cached data for improved performance
• Cache is automatically maintained and refreshed as needed.

Query Parameters NOT Applicable:

• Standard query parameters like includeMeta, hierarchical are NOT applicable to cached methods
• Metadata inclusion depends on cache configuration and user role
• For direct server access with full query control, use the implementation's FromServer methods.

Authorization Requirements:

• Available to all authenticated users
• Returns context only if accessible based on user authorization level
• Context details are filtered according to user permissions and role.

Context Content:

• Includes basic context information (name, UUID, parent relationships)
• Metadata inclusion depends on user role: IS-Manager/Infrastructure-Manager see complete metadata, others see filtered metadata
• Sensitive information (createdBy, lastUpdatedBy) may be obfuscated for non-administrative users.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get context from cache
 UUID contextUUID = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 Context context = publisher.getContext(contextUUID);
 
 System.out.println("Context name: " + context.getName());
 System.out.println("Context UUID: " + context.getUuid());
 System.out.println("Parent context: " + context.getParent());
 

Specified by:

getContext in interface ResourceRegistryPublisher

Parameters:

uuid - The UUID of the context to retrieve

Returns:

The context with the specified UUID (from cache)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the context is not found or not accessible

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

getCurrentContext

public org.gcube.informationsystem.contexts.reference.entities.Context getCurrentContext()
                                                                                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the current context associated with the publisher's authorization token using internal cache. Cache Behavior:

• Uses internal context cache - does NOT bypass cache like server-direct methods
• Current context is determined from the authorization token/secret
• First call may trigger cache population from server if needed
• Subsequent calls use cached data for improved performance.

Query Parameters NOT Applicable:

• Standard query parameters like includeMeta, hierarchical are NOT applicable to cached methods
• Metadata inclusion depends on cache configuration and user role
• For direct server access with full query control, use the implementation's FromServer methods.

Authorization Requirements:

• Available to all authenticated users
• Returns the context associated with the current authorization token
• Context details are filtered according to user permissions and role.

Context Resolution:

• Current context is extracted from the authorization token/secret
• Token must contain valid context information
• Context must be accessible to the user associated with the token.

Context Content:

• Includes basic context information (name, UUID, parent relationships)
• Metadata inclusion depends on user role: IS-Manager/Infrastructure-Manager see complete metadata, others see filtered metadata
• Sensitive information (createdBy, lastUpdatedBy) may be obfuscated for non-administrative users.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get current context from cache
 Context currentContext = publisher.getCurrentContext();
 
 System.out.println("Current context name: " + currentContext.getName());
 System.out.println("Current context UUID: " + currentContext.getUuid());
 System.out.println("Current context parent: " + currentContext.getParent());
 

Specified by:

getCurrentContext in interface ResourceRegistryPublisher

Returns:

The current context associated with the authorization token (from cache)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

list

public <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
List<ERElem> list(Class<ERElem> clazz,
 Boolean polymorphic)
           throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves all instances of the specified type from the Resource Registry. Corresponding REST API: GET /instances/{type-name}[?polymorphic={true|false}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Returns all instances of the specified class that are accessible in the current context
• Supports polymorphic queries to include instances of subtypes
• Results are filtered based on user authorization and context access.

Query Parameters: polymorphic (automatically set from method parameter):

• Whether to include instances of subtypes in the response
• Default: true (includes all subtypes)
• Values: true (includes all subtypes) | false (exact type only)
• Query parameter: InstancePath.POLYMORPHIC_QUERY_PARAMETER.

limit (configurable via client configuration):

• Maximum number of instances to return in a single response
• Default value: server configuration dependent
• Usage: client.setLimit(50)
• Example: Set to 50 to get at most 50 instances per request
• Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
• Query parameter: InstancePath.LIMIT_QUERY_PARAMETER.

offset (configurable via client configuration):

• Number of instances to skip from the beginning of the result set
• Default value: 0
• Usage: client.setOffset(10)
• Example: Set to 10 to skip the first 10 contexts (useful for pagination)
• Query parameter: InstancePath.OFFSET_QUERY_PARAMETER.

includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

HTTP Response Codes:

• 200 OK: Instances successfully retrieved
• 400 Bad Request: Invalid type name or query parameters
• 403 Forbidden: Insufficient permissions to list instances or access hierarchical data
• 404 Not Found: Specified type does not exist in the model
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• Type name is automatically derived from the provided class using TypeUtility.getTypeName(Class)
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes).

Context Access:

• The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• IS-Manager: Full access to list any instances with hierarchical querying across all contexts; receives complete, unfiltered metadata
• Infrastructure-Manager: Full access to list any instances with hierarchical querying across all contexts; receives complete, unfiltered metadata
• Context-Manager: Full access to list instances within managed contexts with hierarchical querying; receives complete, unfiltered metadata
• All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get all EService instances including subtypes
 List<EService> services = publisher.list(EService.class, true);
 
 // Get only exact ContactFacet instances (no subtypes)
 List<ContactFacet> contacts = publisher.list(ContactFacet.class, false);
 

Implementation Details: Type Resolution:

• Uses TypeUtility.getTypeName(Class) to derive the type name from the class
• Delegates to list(String, Boolean) for the actual REST API call
• Unmarshals the JSON response back to typed objects using ElementMapper.unmarshalList(String).

Request Configuration:

• Builds request to GET /instances/{type-name} endpoint
• Automatically includes offset and limit parameters from base configuration
• Sets polymorphic query parameter based on the provided boolean value
• Uses application/json content type for the response.

Response Processing:

• Receives JSON array from server
• Unmarshals JSON to List of typed objects using ElementMapper
• Returns strongly-typed list for type-safe usage.

Error Handling:

• ResourceRegistryExceptions propagated directly from server
• JSON marshalling/unmarshalling errors are wrapped in RuntimeException;.

Specified by:

list in interface ResourceRegistryPublisher

Type Parameters:

ERElem - The specific type of Information System element to retrieve

Parameters:

clazz - The class representing the type of instances to retrieve

polymorphic - Whether to include instances of subtypes (true) or only exact type instances (false)

Returns:

List of instances of the specified type accessible in the current context

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval or if the type is invalid

list

public String list(String type,
 Boolean polymorphic)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves all instances of the specified type from the Resource Registry as JSON string. Corresponding REST API: GET /instances/{type-name}[?polymorphic={true|false}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Returns all instances of the specified type that are accessible in the current context
• Supports polymorphic queries to include instances of subtypes
• Results are filtered based on user authorization and context access
• Returns the response as a JSON array string.

Query Parameters: polymorphic (automatically set from method parameter):

• Whether to include instances of subtypes in the response
• Default: true (includes all subtypes)
• Values: true (includes all subtypes) | false (exact type only)
• Query parameter: InstancePath.POLYMORPHIC_QUERY_PARAMETER.

limit (configurable via client configuration):

• Maximum number of instances to return in a single response
• Default value: server configuration dependent
• Usage: client.setLimit(50)
• Example: Set to 50 to get at most 50 instances per request
• Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
• Query parameter: InstancePath.LIMIT_QUERY_PARAMETER.

offset (configurable via client configuration):

• Number of instances to skip from the beginning of the result set
• Default value: 0
• Usage: client.setOffset(10)
• Example: Set to 10 to skip the first 10 contexts (useful for pagination)
• Query parameter: InstancePath.OFFSET_QUERY_PARAMETER.

includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
• Type names are case-sensitive and must match exactly the class names defined in the Information System model.

Context Access:

• The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to list instances.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get all EService instances as JSON
 String servicesJson = publisher.list("EService", true);
 
 // Get only exact ContactFacet instances as JSON
 String contactsJson = publisher.list("ContactFacet", false);
 

Implementation Details: REST API Call:

• Makes HTTP GET request to /instances/{type-name} endpoint
• Sets Accept header to application/json for JSON response
• Includes type name as path parameter.

Query Parameters:

• Automatically includes offset and limit from base configuration (if set)
• Adds polymorphic parameter based on the provided boolean value
• Additional query parameters from base class configuration are included.

Response Handling:

• Returns raw JSON string response from server
• Response contains JSON array of instances matching the criteria
• Server filters results based on current context and user authorization.

HTTP Configuration:

• Uses GXHTTPStringRequest for HTTP communication
• Includes authorization headers automatically via base request configuration
• Response processed via HTTPUtility.getResponse(Class, HttpURLConnection) for proper error handling.

Error Handling:

• ResourceRegistryExceptions propagated directly from server
• Other exceptions wrapped in RuntimeException
• HTTP errors converted to appropriate Resource Registry exceptions.

Specified by:

list in interface ResourceRegistryPublisher

Parameters:

type - The name of the Information System type whose instances to retrieve

polymorphic - Whether to include instances of subtypes (true) or only exact type instances (false)

Returns:

JSON array string containing the instances of the specified type accessible in the current context

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval or if the type is invalid

create

protected String create(String type,
 String json,
 UUID uuid)
                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new instance of the specified type in the Resource Registry.

Parameters:

type - The type of the instance to create

json - The JSON representation of the instance

uuid - The UUID for the new instance

Returns:

The JSON representation of the created instance

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the instance violates schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - If an instance with the same UUID already exists

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during creation

internalCreate

protected <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
String internalCreate(ERElem er)
               throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Internal method to create an Information System element. Handles UUID generation if not present and marshals the element to JSON.

Type Parameters:

ERElem - The type of Information System element

Parameters:

er - The element to create

Returns:

The JSON representation of the created element

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the element violates schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - If an element with the same UUID already exists

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during creation

create

public <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
ERElem create(ERElem er)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new instance of an Information System element in the Resource Registry. Corresponding REST API: POST /instances/{type-name} Operation Behavior:

• Creates a new entity (Resource, Facet) or relation (ConsistsOf, IsRelatedTo) instance
• The instance is automatically associated with the current context
• Validates the instance against the Information System model schema
• Generates a new UUID for the instance if not already set
• Returns the created instance with server-generated metadata.

HTTP Response Codes:

• 201 Created: Instance successfully created
• 400 Bad Request: Invalid instance data or schema validation failure
• 409 Conflict: Instance with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• Type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes).

Schema Validation:

• All properties and relationships are validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced
• Relation targets must exist and be accessible in compatible contexts.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create instances.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new EService resource
 EService service = new EService();
 ...
 EService createdService = publisher.create(service);
 
 // Create a new ContactFacet
 ContactFacet contact = new ContactFacet();
 ....
 ContactFacet createdContact = publisher.create(contact);
 

Implementation Details: UUID Generation:

• If the instance doesn't have a UUID set, generates a new valid UUID using UUIDManager
• Sets the generated UUID on the instance before marshalling to JSON.

Marshalling Process:

• Uses ElementMapper.marshal(Element) to convert the instance to JSON representation
• Type name is extracted from the instance using TypeUtility.getTypeName(Class) method
• Delegates to the internal create(String, String, UUID) method for the actual REST call.

REST API Implementation:

• Makes HTTP PUT request to /instances/{type-name}/{uuid} endpoint
• Sets Accept and Content-Type headers to application/json with UTF-8 charset
• Includes query parameters for metadata and context information based on client configuration.

Response Processing:

• Receives JSON response from server containing the created instance with metadata
• Unmarshals the JSON response back to the original object type using ElementMapper
• Returns the typed instance with server-generated properties (e.g., creation timestamp, metadata).

Error Handling:

• ResourceRegistryExceptions from server are propagated directly
• JSON marshalling/unmarshalling errors are wrapped in RuntimeException
• HTTP communication errors are handled by the underlying HTTP utility.

Query Parameters Included:

• includeContexts: Whether to include context information in the response
• includeMeta: Whether to include metadata in the response
• allMeta: Whether to include metadata for all nested instances.

Specified by:

create in interface ResourceRegistryPublisher

Type Parameters:

ERElem - The specific type of Information System element to create

Parameters:

er - The instance to create in the Resource Registry

Returns:

The created instance with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the instance violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - If an instance with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance creation

create

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

Creates a new instance of an Information System element from JSON representation. Corresponding REST API: POST /instances/{type-name} Operation Behavior:

• Creates a new entity (Resource, Facet) or relation (ConsistsOf, IsRelatedTo) instance from JSON
• The instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the instance if not already set
• Returns the created instance as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: Instance successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: Instance with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying the Information System type
• Must conform to the Information System model JSON schema
• All required properties for the specified type must be present
• Nested objects and relations must be properly formatted.

Schema Validation:

• JSON structure is validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced
• Relation targets must exist and be accessible in compatible contexts.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create instances.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new EService from JSON
 String serviceJson = "...";
 String createdServiceJson = publisher.create(serviceJson);
 
 // Create a new ContactFacet from JSON
 String contactJson = "...";
 String createdContactJson = publisher.create(contactJson);
 

Implementation Details: JSON Processing:

• Uses Jackson ObjectMapper to parse the input JSON string into a JsonNode
• Extracts the type name from the JSON using TypeUtility.getTypeName(JsonNode)
• Retrieves or generates UUID using UUIDUtility.getUUID(JsonNode).

UUID Handling:

• If no UUID is present in the JSON, generates a new valid UUID using UUIDManager
• Adds the generated UUID to the JSON structure
• Serializes the updated JSON back to string format for the REST call.

Type Resolution:

• Type name must be present in the JSON as @class property
• Uses TypeUtility to extract the type name from the JSON structure
• Type name is used as path parameter in the REST API call.

REST API Implementation:

• Makes HTTP PUT request to /instances/{type-name}/{uuid} endpoint
• Sets Accept and Content-Type headers to application/json with UTF-8 charset
• Sends the JSON string as request body
• Includes query parameters for metadata and context information.

Response Handling:

• Returns the raw JSON string response from the server
• Response contains the created instance with server-generated metadata and properties
• No unmarshalling is performed, allowing callers to handle JSON as needed.

Error Handling:

• ResourceRegistryExceptions from server are propagated directly
• JSON parsing errors are wrapped in RuntimeException
• Missing @class property or invalid JSON structure cause exceptions.

Query Parameters Included:

• includeContexts: Whether to include context information in the response
• includeMeta: Whether to include metadata in the response
• allMeta: Whether to include metadata for all nested instances.

Specified by:

create in interface ResourceRegistryPublisher

Parameters:

json - JSON representation of the instance to create

Returns:

JSON representation of the created instance with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - If an instance with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance creation or JSON parsing

exist

public <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
boolean exist(ERElem er)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Checks if an Information System element instance exists in the Resource Registry. Corresponding REST API: HEAD /instances/{type-name}/{uuid}[?hierarchical={true|false}] Operation Behavior:

• Verifies the existence of the specified instance using its UUID and type
• The type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• Does not return the instance data, only confirms existence
• Checks accessibility within the current context and user authorization.

HTTP Response Codes:

• 200 OK: Instance exists and is accessible in the current context
• 404 Not Found: Instance does not exist or is not accessible
• 403 Forbidden: Instance exists but user lacks authorization to access it
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes).

Context Access:

• The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to check existence.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Check if an EService instance exists
 EService eService = new EService();
 eService.setID(someUUID);
 boolean exists = publisher.exist(eService);
 
 // Check if a ContactFacet instance exists
 ContactFacet contact = new ContactFacet();
 contact.setID(anotherUUID);
 boolean contactExists = publisher.exist(contact);
 

Implementation Details: Type and UUID Extraction:

• Extracts the type name from the instance using Element.getTypeName()
• Retrieves the UUID from the instance using IdentifiableElement.getID()
• Delegates to exist(String, UUID) for the actual implementation.

Validation:

• The instance must have a valid UUID set, otherwise the check will fail
• The instance's type must be a valid Information System model type.

Specified by:

exist in interface ResourceRegistryPublisher

Type Parameters:

ERElem - The specific type of Information System element to check

Parameters:

er - The instance to check for existence (must have a valid UUID)

Returns:

true if the instance exists and is accessible in the current context, false if not found

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 403)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

exist

public <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
boolean exist(Class<ERElem> clazz,
 UUID uuid)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Checks if an Information System element instance exists in the Resource Registry using class and UUID. Corresponding REST API: HEAD /instances/{type-name}/{uuid}[?hierarchical={true|false}] Operation Behavior:

• Verifies the existence of the specified instance using its UUID and class type
• The type name is automatically derived from the provided class using TypeUtility.getTypeName(Class)
• Does not return the instance data, only confirms existence
• Checks accessibility within the current context and user authorization.

HTTP Response Codes:

• 200 OK: Instance exists and is accessible in the current context
• 404 Not Found: Instance does not exist or is not accessible
• 403 Forbidden: Instance exists but user lacks authorization to access it
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The type name is automatically derived from the provided class using TypeUtility.getTypeName(clazz)
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes).

Context Access:

• The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to check existence.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Check if an EService instance exists by class and UUID
 UUID serviceUUID = UUID.fromString("...");
 boolean exists = publisher.exist(EService.class, serviceUUID);
 
 // Check if a ContactFacet instance exists by class and UUID
 UUID contactUUID = UUID.fromString("...");
 boolean contactExists = publisher.exist(ContactFacet.class, contactUUID);
 

Implementation Details: Type Resolution:

• Derives the type name from the provided class using TypeUtility.getTypeName(Class)
• Ensures type-safe operation by resolving the exact type name from the class
• Delegates to exist(String, UUID) for the actual implementation.

Class Validation:

• The class must be a valid Information System model type
• Type name resolution is performed using the TypeUtility for consistency.

Specified by:

exist in interface ResourceRegistryPublisher

Type Parameters:

ERElem - The specific type of Information System element to check

Parameters:

clazz - The class representing the type of instance to check

uuid - The UUID of the instance to check for existence

Returns:

true if the instance exists and is accessible in the current context, false if not found

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 403)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

exist

public boolean exist(String type,
 UUID uuid)
              throws org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Checks if an Information System element instance exists in the Resource Registry using type name and UUID. Corresponding REST API: HEAD /instances/{type-name}/{uuid}[?hierarchical={true|false}] Operation Behavior:

• Verifies the existence of the specified instance using its UUID and type name
• Does not return the instance data, only confirms existence
• Checks accessibility within the current context and user authorization
• Most direct method when type name is already known.

HTTP Response Codes:

• 200 OK: Instance exists and is accessible in the current context
• 404 Not Found: Instance does not exist or is not accessible
• 403 Forbidden: Instance exists but user lacks authorization to access it
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• Type name must be a valid Information System model type
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
• Type name is case-sensitive and must match exactly.

Context Access:

• The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to check existence.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Check if an EService instance exists by type name and UUID
 UUID serviceUUID = UUID.fromString("...");
 boolean exists = publisher.exist("EService", serviceUUID);
 
 // Check if a ContactFacet instance exists by type name and UUID
 UUID contactUUID = UUID.fromString("...");
 boolean contactExists = publisher.exist("ContactFacet", contactUUID);
 

Implementation Details: Request Configuration:

• Makes HTTP HEAD request to the instances endpoint
• Includes hierarchical mode parameter if enabled via client configuration.

Response Handling:

• Successful response indicates the instance exists and is accessible
• NotFoundException is caught and converted to false return value
• Other exceptions are propagated according to the interface contract.

Authentication:

• Uses automatic authorization headers via the base request configuration
• User permissions are validated server-side.

Logging:

• Logs info-level message when starting the existence check
• Logs debug-level message when instance is confirmed to exist
• Uses type and UUID in log messages for traceability.

Specified by:

exist in interface ResourceRegistryPublisher

Parameters:

type - The name of the Information System type to check

uuid - The UUID of the instance to check for existence

Returns:

true if the instance exists and is accessible in the current context, false if not found

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 403)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

read

public <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
ERElem read(ERElem er)
     throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads an existing instance from the Resource Registry using a provided instance object. Corresponding REST API: GET /instances/{type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing instance (Entity or Relation) by extracting type and UUID from the provided instance
• The instance must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete instance with all properties and metadata
• The type is automatically determined from the provided instance object.

HTTP Response Codes:

• 200 OK: Instance successfully retrieved
• 404 Not Found: No instance found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks read permissions for the instance or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header.

Context Access:

• The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to read instances.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource
 EService eService = new EService();
 eService.setHeader(new Header(uuid));
 EService readEService = publisher.read(eService);
 

Implementation Details: Type and UUID Extraction:

• Extracts the type name from the instance using Element.getTypeName()
• Retrieves the UUID from the instance using IdentifiableElement.getID()
• Delegates to read(String, UUID) for the actual REST API call.

Response Processing:

• Receives JSON response from the delegated method
• Unmarshals the JSON back to the original object type using ElementMapper.unmarshal(Class, String)
• Performs type casting to return the strongly-typed instance
• Returns the complete instance with all properties and server metadata.

Type Safety:

• Uses @SuppressWarnings("unchecked") for the type casting from ERElement to ResourceRegistryPublisherImpl
• Type safety is ensured by the fact that the JSON contains the same type as the input instance
• The returned object will be of the same type as the provided instance.

Error Handling:

• ResourceRegistryExceptions from the delegated method are propagated directly
• JSON unmarshalling errors are wrapped in RuntimeException
• Server-side errors (404, 403, etc.) are handled by the underlying read(String, UUID) method.

Specified by:

read in interface ResourceRegistryPublisher

Type Parameters:

ERElem - The specific type of Entity or Relation to read

Parameters:

er - Instance object containing at least the UUID in the header

Returns:

The complete instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If no instance is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

read

public <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
ERElem read(Class<ERElem> clazz,
 UUID uuid)
     throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads an existing instance from the Resource Registry by its type class and UUID. Corresponding REST API: GET /instances/{type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing instance (Entity or Relation) by its type class and unique identifier
• The instance must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete instance with all properties and metadata
• Type validation ensures the UUID corresponds to an instance of the specified class.

HTTP Response Codes:

• 200 OK: Instance successfully retrieved
• 404 Not Found: No instance found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the instance or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The type name is automatically derived from the provided class using TypeUtility.getTypeName(Class)
• The class must be a valid Information System model type.

Context Access:

• The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to read instances.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource by class and UUID
 UUID serviceUuid = UUID.fromString("...");
 EService service = publisher.read(EService.class, serviceUuid);
 

Implementation Details: Type Resolution:

• Derives the type name from the provided class using TypeUtility.getTypeName(Class)
• Ensures type-safe operation by resolving the exact type name from the class
• Delegates to read(String, UUID) for the actual REST API call.

Response Processing:

• Receives JSON response from the delegated method
• Unmarshals the JSON to the specified class type using ElementMapper.unmarshal(Class, String)
• Performs type casting to return the strongly-typed instance
• Returns the complete instance with all properties and server metadata.

Type Safety:

• Uses @SuppressWarnings("unchecked") for the type casting from ERElement to ResourceRegistryPublisherImpl
• Type safety is ensured by using the class parameter for type resolution
• The returned object will be of exactly the specified class type.

Class Validation:

• The class must be a valid Information System model type
• Type name resolution is performed using the TypeUtility for consistency with other methods.

Error Handling:

• ResourceRegistryExceptions from the delegated method are propagated directly
• JSON unmarshalling errors are wrapped in RuntimeException.

Specified by:

read in interface ResourceRegistryPublisher

Type Parameters:

ERElem - The specific type of Entity or Relation to read

Parameters:

clazz - The class of the Entity or Relation type to read

uuid - The unique identifier of the instance to read

Returns:

The complete instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If no instance is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

read

public String read(String type,
 UUID uuid)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads an existing instance from the Resource Registry by its type name and UUID. Corresponding REST API: GET /instances/{type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing instance (Entity or Relation) by its type name and unique identifier
• The instance must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete instance as JSON with all properties and metadata
• Type validation ensures the UUID corresponds to an instance of the specified type.

HTTP Response Codes:

• 200 OK: Instance successfully retrieved
• 404 Not Found: No instance found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the instance or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The specified type must be a valid Information System model type name
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to an instance of exactly the specified type (no polymorphic matching).

Context Access:

• The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to read instances.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource by type and UUID
 UUID serviceUuid = UUID.fromString("...");
 String serviceJson = publisher.read("EService", serviceUuid);
 

Implementation Details: REST API Call:

• Makes HTTP GET request to /instances/{type-name}/{uuid} endpoint
• Sets Accept header to application/json with UTF-8 charset for JSON response
• Includes type name and UUID as path parameters.

Request Configuration:

• Uses GXHTTPStringRequest for HTTP communication
• Includes authorization headers automatically via base request configuration
• Automatically includes additional query parameters from client configuration:
• hierarchicalMode: Whether to search in parent contexts
• includeContexts: Whether to include context information in response
• includeMeta: Whether to include metadata in response
• allMeta: Whether to include metadata for all nested instances.

Query Parameters:

• Additional query parameters are included
• Parameters are based on the current client configuration state
• Supports hierarchical context navigation when enabled.

Response Handling:

• Returns raw JSON string response from server
• Response contains complete instance with all properties and metadata
• Server filters results based on current context and user authorization
• Response processed via HTTPUtility.getResponse(Class, HttpURLConnection) for proper error handling.

Logging:

• Logs trace-level message when starting the read operation with type and UUID
• Logs debug-level message with the complete JSON response when successful
• Uses structured logging for better traceability and debugging.

Error Handling:

• ResourceRegistryExceptions propagated directly from server
• Other exceptions wrapped in RuntimeException.

Specified by:

read in interface ResourceRegistryPublisher

Parameters:

type - The exact type name of the Entity or Relation to read

uuid - The unique identifier of the instance to read

Returns:

JSON representation of the complete instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If no instance is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

update

public <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
ERElem update(ERElem er)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing instance in the Resource Registry using the instance object. REST Endpoint: PUT /instances/{type-name}/{instance-uuid} Request Examples:

• Basic update: EService myService = publisher.update(existingService);
• With metadata in response: publisher.includeMeta(true); EService myService = publisher.update(existingService);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); EService myService = publisher.update(existingService);
• With context information: publisher.includeContexts(true); EService myService = publisher.update(existingService);.

Update Behavior:

• Updates an existing instance with the same UUID as the provided instance
• The instance must already exist in the Resource Registry
• Only modifiable properties are updated; metadata fields are automatically managed
• The instance UUID cannot be changed during update operations.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header.

Schema Validation:

• All properties and relationships are validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced.

Context Access:

• The instance must be accessible in the current context.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Instance successfully updated
• 400 Bad Request: Invalid request body, malformed instance data, or schema validation failed
• 404 Not Found: The instance does not exist
• 403 Forbidden: Insufficient permissions to update the instance.

Response Format:

• Returns the updated instance object with its properties and relations
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are updated according to the current configuration.

Implementation Details: Instance Validation:

• The instance must have a valid UUID set, as updates require identification of the existing instance
• The instance's type must match an existing instance in the Resource Registry.

Marshalling Process:

• Uses ElementMapper.marshal(Element) to convert the instance to JSON representation
• Type name is extracted from the instance using TypeUtility.getTypeName(Class) method
• UUID is extracted from the instance using IdentifiableElement.getID() method
• Delegates to the internal update(String, String, UUID) method for the actual REST call.

REST API Implementation:

• Makes HTTP PUT request to /instances/{type-name}/{uuid} endpoint
• Sets Accept and Content-Type headers to application/json with UTF-8 charset
• Includes query parameters for metadata and context information based on client configuration.

Response Processing:

• Receives JSON response from server containing the updated instance with metadata
• Unmarshals the JSON response back to the original object type using ElementMapper
• Returns the typed instance with server-updated properties (e.g., modification timestamp, metadata).

Error Handling:

• ResourceRegistryExceptions from server are propagated directly
• JSON marshalling/unmarshalling errors are wrapped in RuntimeException
• HTTP communication errors are handled by the underlying HTTP utility.

Query Parameters Included:

• includeContexts: Whether to include context information in the response
• includeMeta: Whether to include metadata in the response
• allMeta: Whether to include metadata for all nested instances.

Specified by:

update in interface ResourceRegistryPublisher

Type Parameters:

ERElem - The generic type extending ERElement (Entity or Relation)

Parameters:

er - The instance object to update with new values

Returns:

The updated instance object with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated instance violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance update

update

public String update(String json)
              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing instance in the Resource Registry using JSON representation. REST Endpoint: PUT /instances/{type-name}/{instance-uuid} Request Examples:

• Basic update: String result = publisher.update(jsonString);
• With metadata in response: publisher.includeMeta(true); String result = publisher.update(jsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String result = publisher.update(jsonString);
• With context information: publisher.includeContexts(true); String result = publisher.update(jsonString);.

Update Behavior:

• Updates an existing instance using JSON representation
• The JSON must contain the UUID of the instance to update
• The instance type is automatically detected from the JSON content
• The instance must already exist in the Resource Registry
• Only modifiable properties are updated; metadata fields are automatically managed.

JSON Format Requirements:

• Valid JSON representation of an Information System instance
• Must include the "id" field with the UUID of the instance to update
• Must include the "type" field to identify the instance type
• Must conform to the schema of the specified type.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The instance type is automatically detected from the JSON content
• The JSON must contain the UUID of the instance to update.

Schema Validation:

• JSON structure is validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced.

Context Access:

• The instance must be accessible in the current context.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Instance successfully updated
• 400 Bad Request: Invalid JSON format, missing required fields, or schema validation failed
• 404 Not Found: The instance does not exist
• 403 Forbidden: Insufficient permissions to update the instance.

Response Format:

• Returns a JSON string containing the updated instance
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are updated according to the current configuration.

Implementation Details: JSON Processing:

• Uses Jackson ObjectMapper to parse the input JSON string into a JsonNode
• Extracts the type name from the JSON using TypeUtility.getTypeName(JsonNode)
• The JSON must contain the @class property indicating the instance type.

UUID Validation:

• The JSON must contain a valid UUID for the instance to be updated
• UUID is used to identify the existing instance in the Resource Registry
• Delegates to update(String type, String json) for further processing.

Type Resolution:

• Type name must be present in the JSON as @class property
• Uses TypeUtility to extract the type name from the JSON structure
• Type name is used as path parameter in the REST API call.

Processing Flow:

• Extracts type name from JSON structure
• Delegates to update(String, String) method which handles UUID extraction and REST call
• Returns the raw JSON string response from the server.

Error Handling:

• ResourceRegistryExceptions from server are propagated directly
• JSON parsing errors are wrapped in RuntimeException
• Missing @class property or invalid JSON structure cause exceptions.

Specified by:

update in interface ResourceRegistryPublisher

Parameters:

json - JSON representation of the instance to update

Returns:

JSON string containing the updated instance with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated instance violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance update

update

public String update(String type,
 String json)
              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing instance in the Resource Registry using type name and JSON representation. REST Endpoint: PUT /instances/{type-name}/{instance-uuid} Request Examples:

• Basic update: String result = publisher.update("EService", jsonString);
• With metadata in response: publisher.includeMeta(true); String result = publisher.update("EService", jsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String result = publisher.update("EService", jsonString);
• With context information: publisher.includeContexts(true); String result = publisher.update("EService", jsonString);.

Update Behavior:

• Updates an existing instance using explicit type name and JSON representation
• The JSON must contain the UUID of the instance to update
• The provided type name must match the actual instance type
• The instance must already exist in the Resource Registry
• Only modifiable properties are updated; metadata fields are automatically managed.

JSON Format Requirements:

• Valid JSON representation of an Information System instance
• Must include the "id" field with the UUID of the instance to update
• May include the "type" field, but the explicitly provided type parameter takes precedence
• Must conform to the schema of the specified type.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The provided type name must match the actual instance type
• The JSON must contain the UUID of the instance to update.

Schema Validation:

• JSON structure is validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced.

Context Access:

• The instance must be accessible in the current context.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Instance successfully updated
• 400 Bad Request: Invalid JSON format, type mismatch, missing required fields, or schema validation failed
• 404 Not Found: The instance or specified type does not exist
• 403 Forbidden: Insufficient permissions to update the instance.

Response Format:

• Returns a JSON string containing the updated instance
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are updated according to the current configuration.

Implementation Details: UUID Extraction:

• Uses UUIDUtility.getUUID(String) to extract the UUID from the JSON
• The JSON must contain a valid UUID field for instance identification
• Delegates to update(String, String, UUID) for the actual REST call.

JSON Validation:

• The JSON must be well-formed and contain all required fields for the update
• Type parameter ensures type-safe operation by providing explicit type information
• UUID must match an existing instance in the Resource Registry.

Processing Flow:

• Extracts UUID from the provided JSON
• Delegates to the final update method with type, JSON, and UUID parameters
• Returns the raw JSON response from the server.

Error Handling:

• ResourceRegistryExceptions from server are propagated directly
• JSON parsing errors are wrapped in RuntimeException
• Missing or invalid UUID in JSON causes exceptions.

Specified by:

update in interface ResourceRegistryPublisher

Parameters:

type - The name of the Information System type (e.g., "EService", "ContactFacet")

json - JSON representation of the instance to update

Returns:

JSON string containing the updated instance with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated instance violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance to update or the specified type does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance update

update

public String update(String type,
 String json,
 UUID uuid)
              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing instance in the Resource Registry using type name, JSON representation, and explicit UUID. REST Endpoint: PUT /instances/{type-name}/{instance-uuid} Request Examples:

• Basic update: String result = publisher.update("EService", jsonString, instanceUuid);
• With metadata in response: publisher.includeMeta(true); String result = publisher.update("EService", jsonString, instanceUuid);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String result = publisher.update("EService", jsonString, instanceUuid);
• With context information: publisher.includeContexts(true); String result = publisher.update("EService", jsonString, instanceUuid);.

Update Behavior:

• Updates an existing instance using explicit type name, JSON representation, and UUID
• The explicitly provided UUID takes precedence over any UUID in the JSON content
• The provided type name must match the actual instance type
• The instance must already exist in the Resource Registry
• Only modifiable properties are updated; metadata fields are automatically managed
• This method provides the most explicit control over instance identification.

JSON Format Requirements:

• Valid JSON representation of an Information System instance
• The "id" field in JSON is ignored if present; the uuid parameter is used instead
• May include the "type" field, but the explicitly provided type parameter takes precedence
• Must conform to the schema of the specified type.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The explicitly provided UUID takes precedence over any UUID in the JSON content
• The provided type name must match the actual instance type.

Schema Validation:

• JSON structure is validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced.

Context Access:

• The instance must be accessible in the current context.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Instance successfully updated
• 400 Bad Request: Invalid JSON format, type mismatch, invalid UUID, or schema validation failed
• 404 Not Found: The instance with the specified UUID or the specified type does not exist
• 403 Forbidden: Insufficient permissions to update the instance.

Response Format:

• Returns a JSON string containing the updated instance
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are updated according to the current configuration.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Implementation Details: REST API Implementation:

• Makes HTTP PUT request to /instances/{type-name}/{uuid} endpoint
• Sets Accept and Content-Type headers to application/json with UTF-8 charset
• Includes type name and UUID as path parameters
• Sends the JSON string as request body.

Request Configuration:

• Uses GXHTTPStringRequest for HTTP communication
• Includes authorization headers automatically via base request configuration
• Automatically includes additional query parameters from client configuration:
• includeContexts: Whether to include context information in response
• includeMeta: Whether to include metadata in response
• allMeta: Whether to include metadata for all nested instances.

Update Semantics:

• Performs a complete replacement of the existing instance with the provided JSON
• The UUID must match an existing instance in the current context
• All relationships and references are preserved unless explicitly modified in the JSON.

Response Handling:

• Returns raw JSON string response from server
• Response contains the updated instance with all properties and server metadata
• Server updates modification timestamps and other metadata automatically
• Response processed via HTTPUtility.getResponse(Class, HttpURLConnection) for proper error handling.

Logging:

• Logs trace-level message when starting the update operation with type and JSON
• Logs trace-level message with the UUID when the update is successful
• Uses structured logging for better traceability and debugging.

Error Handling:

• ResourceRegistryExceptions propagated directly from server
• HTTP 404 errors converted to NotFoundException if instance doesn't exist
• HTTP 403 errors and context accessibility issues converted to appropriate exceptions
• Other exceptions wrapped in RuntimeException.

Specified by:

update in interface ResourceRegistryPublisher

Parameters:

type - The name of the Information System type (e.g., "EService", "ContactFacet")

json - JSON representation of the instance to update (UUID in JSON is ignored)

uuid - The unique identifier of the instance to update

Returns:

JSON string containing the updated instance with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated instance violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance with the specified UUID or the specified type does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance update

delete

public <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
boolean delete(ERElem er)
        throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes an Information System element instance from the Resource Registry. Corresponding REST API: DELETE /instances/{type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified instance from the Resource Registry
• The type and UUID are automatically extracted from the provided element object
• The instance must exist and be accessible in the current context
• Supports both Resource and Facet types and their specializations
• This is a destructive operation that cannot be undone
• Related elements may also be deleted based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Instance successfully deleted
• 404 Not Found: Instance does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the instance
• 409 Conflict: Instance cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type name is automatically derived from the provided element object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the element's header
• Supports all ERElement types: Resources, Facets, ConsistsOf relations, and IsRelatedTo relations.

Context Access:

• The instance must be accessible in the current context.

Deletion Propagation Rules:

• Resources: When a Resource is deleted, all its associated Facets (via ConsistsOf relations) may also be deleted if they become orphaned and the delete propagation constraint is propagate
• Facets: When a Facet is deleted, the parent Resources that reference it may also be affected based on schema constraints
• Relations: When a relation is deleted, the connected elements remain but the relationship is removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the instance will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Facet that is required by an existing Resource; • Deleting a Resource that has mandatory relationships that would be violated; • Operations that would make related elements incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the instance exists.

IS-Manager:

• Can delete any instance in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any instance in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete instances only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete instances only in contexts where they have appropriate permissions
• Operations are limited to instances they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an EService instance
 EService service = publisher.read(EService.class, serviceUUID);
 boolean deleted = publisher.delete(service);
 
 // Delete a ContactFacet instance
 ContactFacet contact = publisher.read(ContactFacet.class, contactUUID);
 boolean contactDeleted = publisher.delete(contact);
 

Implementation Details: Instance Identification:

• Extracts the type name from the instance using Element.getTypeName()
• Retrieves the UUID from the instance using IdentifiableElement.getID()
• Delegates to delete(String, UUID) for the actual REST API call.

Type and UUID Validation:

• The instance must have a valid UUID set for identification of the target instance
• The instance's type must match an existing instance in the Resource Registry
• Both type and UUID are required for the deletion operation.

Cascading Effects:

• For Resources: Deletion automatically removes all associated ConsistsOf relations
• For Facets: Deletion is only allowed if no ConsistsOf relations reference the Facet
• For Relations: Deletion removes the relation without affecting source or target instances.

Error Handling:

• ResourceRegistryExceptions from server are propagated directly
• Missing UUID or invalid instance structure cause exceptions
• Referential integrity violations result in appropriate server exceptions.

Specified by:

delete in interface ResourceRegistryPublisher

Type Parameters:

ERElem - The specific type of Information System element to delete

Parameters:

er - The instance to delete (must contain a valid UUID in the header)

Returns:

true if the instance was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the instance would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

delete

public boolean delete(String type,
 UUID uuid)
               throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes an Information System element instance from the Resource Registry using type name and UUID. Corresponding REST API: DELETE /instances/{type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified instance from the Resource Registry
• The instance is identified by its type name and UUID
• The instance must exist and be accessible in the current context
• Supports both Resource and Facet types and their specializations
• This is a destructive operation that cannot be undone
• Related elements may also be deleted based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Instance successfully deleted
• 404 Not Found: Instance does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the instance
• 409 Conflict: Instance cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type parameter must be a valid ERElement type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all ERElement types: Resources (e.g., EService, HostingNode), Facets (e.g., StateFacet, ContactFacet), ConsistsOf relations, and IsRelatedTo relations
• The UUID must be a valid UUID that identifies an existing instance.

Context Access:

• The instance must be accessible in the current context.

Deletion Propagation Rules:

• Resources: When a Resource is deleted, all its associated Facets (via ConsistsOf relations) may also be deleted if they become orphaned and the delete propagation constraint is propagate
• Facets: When a Facet is deleted, the parent Resources that reference it may also be affected based on schema constraints
• Relations: When a relation is deleted, the connected elements remain but the relationship is removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the instance will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Facet that is required by an existing Resource; • Deleting a Resource that has mandatory relationships that would be violated; • Operations that would make related elements incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the instance exists.

IS-Manager:

• Can delete any instance in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any instance in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete instances only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete instances only in contexts where they have appropriate permissions
• Operations are limited to instances they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an EService instance by type and UUID
 UUID serviceUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 boolean deleted = publisher.delete("EService", serviceUUID);
 
 // Delete a ContactFacet instance by type and UUID
 UUID contactUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 boolean contactDeleted = publisher.delete("ContactFacet", contactUUID);
 

Implementation Details: REST API Call:

• Makes HTTP DELETE request to /instances/{type-name}/{uuid} endpoint
• Sets Accept header to application/json for consistent communication
• Includes type name and UUID as path parameters.

Request Configuration:

• Uses GXHTTPStringRequest for HTTP communication
• Includes authorization headers automatically via base request configuration
• No query parameters required for basic deletion operation
• No request body is sent with DELETE requests.

Deletion Semantics:

• Performs permanent removal of the instance from the Resource Registry
• The instance must exist in the current context to be deleted
• Referential integrity constraints are enforced by the server
• Cascading deletion rules apply based on the instance type (Resource, Facet, or Relation).

Cascading Behavior:

• Resources: All associated ConsistsOf relations are automatically deleted
• Facets: Deletion fails if any ConsistsOf relations reference the Facet
• Relations: Only the relation itself is deleted, source and target instances remain.

Response Handling:

• Server response is processed but content is not returned to caller
• Always returns true when deletion is successful
• Exceptions are thrown for error conditions rather than returning false
• Response processed via HTTPUtility.getResponse(Class, HttpURLConnection) for proper error handling.

Logging:

• Logs trace-level message when starting the delete operation with type and UUID
• Logs info-level message indicating successful or failed deletion
• Uses structured logging for better traceability and debugging.

Error Handling:

• ResourceRegistryExceptions propagated directly from server
• HTTP 404 errors converted to NotFoundException if instance doesn't exist
• HTTP 403 errors for insufficient permissions or context restrictions
• Referential integrity violations result in SchemaViolationException
• Other exceptions wrapped in RuntimeException.

Specified by:

delete in interface ResourceRegistryPublisher

Parameters:

type - The exact type name of the ERElement to delete

uuid - The UUID of the instance to delete

Returns:

true if the instance was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the instance would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

createFacet

public <F extends org.gcube.informationsystem.model.reference.entities.Facet>
F createFacet(F facet)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new Facet instance in the Resource Registry. Corresponding REST API: POST /instances/{facet-type-name} Operation Behavior:

• Creates a new Facet entity in the Information System
• Facets represent specific aspects or properties that can be attached to Resources via ConsistsOf relations
• The instance is automatically associated with the current context
• Validates the facet against the Information System model schema
• Generates a new UUID for the facet if not already set
• Returns the created facet with server-generated metadata.

HTTP Response Codes:

• 201 Created: Facet successfully created
• 400 Bad Request: Invalid facet data or schema validation failure
• 409 Conflict: Facet with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The facet type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Supports all Facet subtypes defined in the Information System model.

Schema Validation:

• All facet properties are validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced
• Facet-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new ContactFacet
 ContactFacet contact = new ContactFacet();
 ...
 ContactFacet createdContact = publisher.createFacet(contact);
 
 // Create a new SoftwareFacet
 SoftwareFacet software = new SoftwareFacet();
 ...
 SoftwareFacet createdSoftware = publisher.createFacet(software);
 

This method is a type-safe wrapper that delegates to create(ERElem) for implementation details.

Specified by:

createFacet in interface ResourceRegistryPublisher

Type Parameters:

F - The specific type of Facet to create

Parameters:

facet - The Facet instance to create in the Resource Registry

Returns:

The created Facet with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the facet violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAlreadyPresentException - If a facet with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during facet creation

createFacet

public String createFacet(String facet)
                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new Facet instance from JSON representation. Corresponding REST API: POST /instances/{facet-type-name} Operation Behavior:

• Creates a new Facet entity from JSON representation
• Facets represent specific aspects or properties that can be attached to Resources via ConsistsOf relations
• The instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the facet if not already set
• Returns the created facet as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: Facet successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: Facet with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying a Facet type
• Must conform to the Information System model JSON schema for Facets
• All required properties for the specified facet type must be present
• Facet-specific properties must be properly formatted.

Schema Validation:

• JSON structure is validated against the Information System model
• Required facet properties must be present and valid
• Property types and constraints are enforced
• Facet-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new ContactFacet from JSON
 String contactJson = "...";
 String createdContactJson = publisher.createFacet(contactJson);
 
 // Create a new SoftwareFacet from JSON
 String softwareJson = "...";
 String createdSoftwareJson = publisher.createFacet(softwareJson);
 

This method is a type-safe wrapper that delegates to create(String) for implementation details.

Specified by:

createFacet in interface ResourceRegistryPublisher

Parameters:

facet - JSON representation of the Facet to create

Returns:

JSON representation of the created Facet with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAlreadyPresentException - If a facet with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during facet creation or JSON parsing

readFacet

public <F extends org.gcube.informationsystem.model.reference.entities.Facet>
F readFacet(F facet)
     throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a Facet instance from the Resource Registry using a provided instance object. Corresponding REST API: GET /instances/{facet-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing Facet by extracting type and UUID from the provided instance
• The Facet must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete Facet instance with all properties and metadata
• The type is automatically determined from the provided instance object.

HTTP Response Codes:

• 200 OK: Facet successfully retrieved
• 404 Not Found: No Facet found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks read permissions for the Facet or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include Facets from child contexts of the current context
• Values: true (includes child contexts) | false (current context only)
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER.

Input Processing:

• The Facet type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header
• The returned object will be of the same Facet type as the provided instance.

Context Access:

• The Facet must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to read Facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read a ContactFacet
 ContactFacet contactFacet = new ContactFacet();
 contactFacet.setHeader(new Header(uuid));
 ContactFacet readContactFacet = publisher.readFacet(contactFacet);
 

This method is a type-safe wrapper that delegates to read(ERElem) for implementation details.

Specified by:

readFacet in interface ResourceRegistryPublisher

Type Parameters:

F - The specific type of Facet to read

Parameters:

facet - Instance object containing at least the UUID in the header

Returns:

The complete Facet instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If no Facet is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAvailableInAnotherContextException - If the Facet exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Facet retrieval

readFacet

public String readFacet(String facetType,
 UUID uuid)
                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a Facet instance from the Resource Registry by its type and UUID. Corresponding REST API: GET /instances/{facet-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing Facet by its type name and unique identifier
• The Facet must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete Facet instance as JSON with all properties and metadata
• Type validation ensures the UUID corresponds to a Facet of the specified type.

HTTP Response Codes:

• 200 OK: Facet successfully retrieved
• 404 Not Found: No Facet found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the Facet or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The specified type must be a valid Facet type in the Information System model
• Supports all Facet types and their subtypes as defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a Facet of exactly the specified type (no polymorphic matching). *

Context Access:

• The Facet must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to read Facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read a ContactFacet by type and UUID
 UUID facetUuid = UUID.fromString("...");
 String contactJson = publisher.readFacet("ContactFacet", facetUuid);
 

This method is a type-safe wrapper that delegates to read(String, UUID) for implementation details.

Specified by:

readFacet in interface ResourceRegistryPublisher

Parameters:

facetType - The exact type name of the Facet to read

uuid - The unique identifier of the Facet to read

Returns:

JSON representation of the complete Facet instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If no Facet is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAvailableInAnotherContextException - If the Facet exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Facet retrieval

updateFacet

public <F extends org.gcube.informationsystem.model.reference.entities.Facet>
F updateFacet(F facet)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing Facet instance in the Resource Registry. REST Endpoint: PUT /instances/{facet-type-name}/{facet-uuid} Request Examples:

• Basic update: ContactFacet updatedFacet = publisher.updateFacet(facetToUpdate);
• With metadata in response: publisher.includeMeta(true); ContactFacet updatedFacet = publisher.updateFacet(facetToUpdate);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); ContactFacet updatedFacet = publisher.updateFacet(facetToUpdate);
• With context information: publisher.includeContexts(true); ContactFacet updatedFacet = publisher.updateFacet(facetToUpdate);.

Update Behavior:

• Updates an existing Facet with new property values from the provided instance
• The Facet must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• The Facet UUID cannot be changed during update operations
• Associated Resources are automatically revalidated after Facet update
• The update affects all Resources that include this Facet via ConsistsOf relations.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response Facet
• Default value: false (basic information only)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for Facets in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Facet successfully updated
• 400 Bad Request: Invalid Facet data or schema validation failed
• 404 Not Found: The Facet does not exist
• 403 Forbidden: Insufficient permissions to update the Facet.

Response Format:

• Returns the updated Facet object with its properties
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All properties are updated according to the current configuration.

This method is a type-safe wrapper that delegates to update(ERElem) for implementation details.

Specified by:

updateFacet in interface ResourceRegistryPublisher

Type Parameters:

F - The specific type of Facet to update

Parameters:

facet - The Facet instance with updated values (must contain valid UUID)

Returns:

The updated Facet object with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated Facet violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Facet update

updateFacet

public String updateFacet(String facet)
                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing Facet instance in the Resource Registry using JSON representation. REST Endpoint: PUT /instances/{facet-type-name}/{facet-uuid} Request Examples:

• Basic update: String updatedFacet = publisher.updateFacet(facetJsonString);
• With metadata in response: publisher.includeMeta(true); String updatedFacet = publisher.updateFacet(facetJsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String updatedFacet = publisher.updateFacet(facetJsonString);
• With context information: publisher.includeContexts(true); String updatedFacet = publisher.updateFacet(facetJsonString);.

Update Behavior:

• Updates an existing Facet using JSON representation
• The JSON must contain the UUID of the Facet to update
• The Facet type is automatically detected from the JSON content
• The Facet must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• Associated Resources are automatically revalidated after Facet update
• The update affects all Resources that include this Facet via ConsistsOf relations.

JSON Format Requirements:

• Valid JSON representation of a Facet instance
• Must include the "id" field with the UUID of the Facet to update
• Must include the "@class" field to identify the Facet type
• Must conform to the schema of the specified Facet type.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response Facet
• Default value: false (basic information only)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for Facets in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Facet successfully updated
• 400 Bad Request: Invalid JSON format, missing required fields, or schema validation failed
• 404 Not Found: The Facet does not exist
• 403 Forbidden: Insufficient permissions to update the Facet.

Response Format:

• Returns a JSON string containing the updated Facet
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All properties are updated according to the current configuration.

This method is a type-safe wrapper that delegates to update(String) for implementation details.

Specified by:

updateFacet in interface ResourceRegistryPublisher

Parameters:

facet - JSON representation of the Facet to update

Returns:

JSON string containing the updated Facet with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated Facet violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Facet update

deleteFacet

public <F extends org.gcube.informationsystem.model.reference.entities.Facet>
boolean deleteFacet(F facet)
             throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a Facet instance from the Resource Registry. Corresponding REST API: DELETE /instances/{facet-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified Facet instance from the Resource Registry
• The type and UUID are automatically extracted from the provided Facet object
• The Facet must exist and be accessible in the current context
• This is a destructive operation that cannot be undone
• Parent Resources that reference this Facet may also be affected based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Facet successfully deleted
• 404 Not Found: Facet does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the Facet
• 409 Conflict: Facet cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type name is automatically derived from the provided Facet object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Facet's header
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet).

Deletion Propagation Rules:

• Facets: When a Facet is deleted, parent Resources that reference it via ConsistsOf relations may also be affected
• Parent Resources: If the deleted Facet was required for a Resource's schema compliance, the Resource may become invalid or be automatically removed
• ConsistsOf Relations: All ConsistsOf relations connecting Resources to this Facet are automatically removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each Resource type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the Facet will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Facet that is required by an existing Resource; • Deleting Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that would make parent Resources incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the Facet exists.

IS-Manager:

• Can delete any Facet in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any Facet in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete Facets only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete Facets only in contexts where they have appropriate permissions
• Operations are limited to Facets they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete a ContactFacet instance
 ContactFacet contact = publisher.readFacet(ContactFacet.class, contactUUID);
 boolean deleted = publisher.deleteFacet(contact);
 
 // Delete a StateFacet instance
 StateFacet state = publisher.readFacet(StateFacet.class, stateUUID);
 boolean stateDeleted = publisher.deleteFacet(state);
 

This method is a type-safe wrapper that delegates to delete(ERElem) for implementation details.

Specified by:

deleteFacet in interface ResourceRegistryPublisher

Type Parameters:

F - The specific type of Facet to delete

Parameters:

facet - The Facet instance to delete (must contain a valid UUID in the header)

Returns:

true if the Facet was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the Facet would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

deleteFacet

public boolean deleteFacet(String facetType,
 UUID uuid)
                    throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a Facet instance from the Resource Registry using type name and UUID. Corresponding REST API: DELETE /instances/{facet-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified Facet instance from the Resource Registry
• The Facet is identified by its type name and UUID
• The Facet must exist and be accessible in the current context
• This is a destructive operation that cannot be undone
• Parent Resources that reference this Facet may also be affected based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Facet successfully deleted
• 404 Not Found: Facet does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the Facet
• 409 Conflict: Facet cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The facetType parameter must be a valid Facet type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet, SoftwareFacet)
• The UUID must be a valid UUID that identifies an existing Facet instance.

Deletion Propagation Rules:

• Facets: When a Facet is deleted, parent Resources that reference it via ConsistsOf relations may also be affected
• Parent Resources: If the deleted Facet was required for a Resource's schema compliance, the Resource may become invalid or be automatically removed
• ConsistsOf Relations: All ConsistsOf relations connecting Resources to this Facet are automatically removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each Resource type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the Facet will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Facet that is required by an existing Resource; • Deleting Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that would make parent Resources incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the Facet exists.

IS-Manager:

• Can delete any Facet in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any Facet in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete Facets only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete Facets only in contexts where they have appropriate permissions
• Operations are limited to Facets they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete a ContactFacet by type and UUID
 UUID contactUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 boolean deleted = publisher.deleteFacet("ContactFacet", contactUUID);
 
 // Delete a StateFacet by type and UUID
 UUID stateUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 boolean stateDeleted = publisher.deleteFacet("StateFacet", stateUUID);
 

This method is a type-safe wrapper that delegates to delete(String, UUID) for implementation details.

Specified by:

deleteFacet in interface ResourceRegistryPublisher

Parameters:

facetType - The exact type name of the Facet to delete

uuid - The UUID of the Facet instance to delete

Returns:

true if the Facet was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the Facet would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

createResource

public <R extends org.gcube.informationsystem.model.reference.entities.Resource>
R createResource(R resource)
          throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new Resource instance in the Resource Registry. Corresponding REST API: POST /instances/{resource-type-name} Operation Behavior:

• Creates a new Resource entity in the Information System
• Resources represent the main entities that can have Facets attached via ConsistsOf relations and can be connected to other Resources via IsRelatedTo relations
• The instance is automatically associated with the current context
• Validates the resource against the Information System model schema
• Generates a new UUID for the resource if not already set
• Returns the created resource with server-generated metadata.

HTTP Response Codes:

• 201 Created: Resource successfully created
• 400 Bad Request: Invalid resource data or schema validation failure
• 409 Conflict: Resource with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The resource type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Supports all Resource subtypes defined in the Information System model.

Schema Validation:

• All resource properties are validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced
• Resource-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create resources.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new EService resource
 EService service = new EService();
 ...
 EService createdService = publisher.createResource(service);
 
 // Create a new HostingNode resource
 HostingNode node = new HostingNode();
 ...
 HostingNode createdNode = publisher.createResource(node);
 

This method is a type-safe wrapper that delegates to create(ERElem) for implementation details.

Specified by:

createResource in interface ResourceRegistryPublisher

Type Parameters:

R - The specific type of Resource to create

Parameters:

resource - The Resource instance to create in the Resource Registry

Returns:

The created Resource with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the resource violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAlreadyPresentException - If a resource with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during resource creation

createResource

public String createResource(String resource)
                      throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new Resource instance from JSON representation. Corresponding REST API: POST /instances/{resource-type-name} Operation Behavior:

• Creates a new Resource entity from JSON representation
• Resources represent the main entities that can have Facets attached via ConsistsOf relations and can be connected to other Resources via IsRelatedTo relations
• The instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the resource if not already set
• Returns the created resource as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: Resource successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: Resource with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying a Resource type
• Must conform to the Information System model JSON schema for Resources
• All required properties for the specified resource type must be present
• Resource-specific properties must be properly formatted.

Schema Validation:

• JSON structure is validated against the Information System model
• Required resource properties must be present and valid
• Property types and constraints are enforced
• Resource-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create resources.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new EService from JSON
 String serviceJson = "...";
 String createdServiceJson = publisher.createResource(serviceJson);
 
 // Create a new HostingNode from JSON
 String nodeJson = "...";
 String createdNodeJson = publisher.createResource(nodeJson);
 

This method is a type-safe wrapper that delegates to create(String) for implementation details.

Specified by:

createResource in interface ResourceRegistryPublisher

Parameters:

resource - JSON representation of the Resource to create

Returns:

JSON representation of the created Resource with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAlreadyPresentException - If a resource with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during resource creation or JSON parsing

readResource

public <R extends org.gcube.informationsystem.model.reference.entities.Resource>
R readResource(R resource)
        throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a Resource instance from the Resource Registry using a provided instance object. Corresponding REST API: GET /instances/{resource-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing Resource by extracting type and UUID from the provided instance
• The Resource must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete Resource instance with all properties, ConsistsOf relations, and metadata
• The type is automatically determined from the provided instance object.

HTTP Response Codes:

• 200 OK: Resource successfully retrieved
• 404 Not Found: No Resource found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks read permissions for the Resource or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The Resource type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header
• The returned object will be of the same Resource type as the provided instance.

Context Access:

• The Resource must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to read resources.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource
 EService eService = new EService();
 eService.setHeader(new Header(uuid));
 EService readEService = publisher.readResource(eService);
 

This method is a type-safe wrapper that delegates to read(ERElem) for implementation details.

Specified by:

readResource in interface ResourceRegistryPublisher

Type Parameters:

R - The specific type of Resource to read

Parameters:

resource - Instance object containing at least the UUID in the header

Returns:

The complete Resource instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If no Resource is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAvailableInAnotherContextException - If the Resource exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Resource retrieval

readResource

public String readResource(String resourceType,
 UUID uuid)
                    throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a Resource instance from the Resource Registry by its type and UUID. Corresponding REST API: GET /instances/{resource-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing Resource by its type name and unique identifier
• The Resource must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete Resource instance as JSON with all properties, ConsistsOf relations, and metadata
• Type validation ensures the UUID corresponds to a Resource of the specified type.

HTTP Response Codes:

• 200 OK: Resource successfully retrieved
• 404 Not Found: No Resource found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the Resource or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The specified type must be a valid Resource type in the Information System model
• Supports Resource subtypes defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a Resource of exactly the specified type (no polymorphic matching).

Context Access:

• The Resource must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Authorization Requirements:

• All users must have a valid token and read permissions for the specific context where they want to read resources.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource by type and UUID
 UUID resourceUuid = UUID.fromString("...");
 String serviceJson = publisher.readResource("EService", resourceUuid);
 

This method is a type-safe wrapper that delegates to read(String, UUID) for implementation details.

Specified by:

readResource in interface ResourceRegistryPublisher

Parameters:

resourceType - The exact type name of the Resource to read

uuid - The unique identifier of the Resource to read

Returns:

JSON representation of the complete Resource instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If no Resource is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAvailableInAnotherContextException - If the Resource exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Resource retrieval

updateResource

public <R extends org.gcube.informationsystem.model.reference.entities.Resource>
R updateResource(R resource)
          throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing Resource instance in the Resource Registry. REST Endpoint: PUT /instances/{resource-type-name}/{resource-uuid} Request Examples:

• Basic update: EService updatedResource = publisher.updateResource(resourceToUpdate);
• With metadata in response: publisher.includeMeta(true); EService updatedResource = publisher.updateResource(resourceToUpdate);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); EService updatedResource = publisher.updateResource(resourceToUpdate);
• With context information: publisher.includeContexts(true); EService updatedResource = publisher.updateResource(resourceToUpdate);.

Update Behavior:

• Updates an existing Resource with new property values from the provided instance
• The Resource must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• The Resource UUID cannot be changed during update operations
• Associated Facets via ConsistsOf relations are preserved unless explicitly modified
• Existing ConsistsOf relations and their target Facets remain unchanged unless modified through separate operations.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response Resource
• Default value: false (basic information only)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for Resources in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Resource successfully updated
• 400 Bad Request: Invalid Resource data or schema validation failed
• 404 Not Found: The Resource does not exist
• 403 Forbidden: Insufficient permissions to update the Resource.

Response Format:

• Returns the updated Resource object with its properties and relations
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are included according to the current configuration.

This method is a type-safe wrapper that delegates to update(ERElem) for implementation details.

Specified by:

updateResource in interface ResourceRegistryPublisher

Type Parameters:

R - The specific type of Resource to update

Parameters:

resource - The Resource instance with updated values (must contain valid UUID)

Returns:

The updated Resource object with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated Resource violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Resource update

updateResource

public String updateResource(String resource)
                      throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing Resource instance in the Resource Registry using JSON representation. REST Endpoint: PUT /instances/{resource-type-name}/{resource-uuid} Request Examples:

• Basic update: String updatedResource = publisher.updateResource(resourceJsonString);
• With metadata in response: publisher.includeMeta(true); String updatedResource = publisher.updateResource(resourceJsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String updatedResource = publisher.updateResource(resourceJsonString);
• With context information: publisher.includeContexts(true); String updatedResource = publisher.updateResource(resourceJsonString);.

Update Behavior:

• Updates an existing Resource using JSON representation
• The JSON must contain the UUID of the Resource to update
• The Resource type is automatically detected from the JSON content
• The Resource must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• Associated Facets via ConsistsOf relations are preserved unless explicitly modified
• Existing ConsistsOf relations and their target Facets remain unchanged unless modified through separate operations.

JSON Format Requirements:

• Valid JSON representation of a Resource instance
• Must include the "id" field with the UUID of the Resource to update
• Must include the "@class" field to identify the Resource type
• Must conform to the schema of the specified Resource type
• ConsistsOf relations should be included if they need to be updated.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response Resource
• Default value: false (basic information only)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for Resources in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Resource successfully updated
• 400 Bad Request: Invalid JSON format, missing required fields, or schema validation failed
• 404 Not Found: The Resource does not exist
• 403 Forbidden: Insufficient permissions to update the Resource.

Response Format:

• Returns a JSON string containing the updated Resource
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are included according to the current configuration.

This method is a type-safe wrapper that delegates to update(String) for implementation details.

Specified by:

updateResource in interface ResourceRegistryPublisher

Parameters:

resource - JSON representation of the Resource to update

Returns:

JSON string containing the updated Resource with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated Resource violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Resource update

deleteResource

public <R extends org.gcube.informationsystem.model.reference.entities.Resource>
boolean deleteResource(R resource)
                throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a Resource instance from the Resource Registry. Corresponding REST API: DELETE /instances/{resource-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified Resource instance from the Resource Registry
• The type and UUID are automatically extracted from the provided Resource object
• The Resource must exist and be accessible in the current context
• This is a destructive operation that cannot be undone
• Associated Facets and ConsistsOf relations may also be deleted based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Resource successfully deleted
• 404 Not Found: Resource does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the Resource
• 409 Conflict: Resource cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type name is automatically derived from the provided Resource object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Resource's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software, Dataset).

Deletion Propagation Rules:

• Resources: When a Resource is deleted, all its associated Facets (via ConsistsOf relations) may also be deleted if they become orphaned and the delete propagation constraint is propagate
• Associated Facets: Facets connected to the Resource via ConsistsOf relations are automatically removed if no other Resources reference them
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are automatically removed
• IsRelatedTo Relations: IsRelatedTo relations where this Resource is source or target are automatically removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each Resource type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the Resource will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Resource that is required by other Resources via IsRelatedTo relations; • Deleting Resources that violate cardinality constraints (min occurrences) defined in the schema; • Operations that would make related Resources incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the Resource exists.

IS-Manager:

• Can delete any Resource in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any Resource in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete Resources only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete Resources only in contexts where they have appropriate permissions
• Operations are limited to Resources they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an EService instance
 EService service = publisher.readResource(EService.class, serviceUUID);
 boolean deleted = publisher.deleteResource(service);
 
 // Delete a HostingNode instance
 HostingNode host = publisher.readResource(HostingNode.class, hostUUID);
 boolean hostDeleted = publisher.deleteResource(host);
 

This method is a type-safe wrapper that delegates to delete(ERElem) for implementation details.

Specified by:

deleteResource in interface ResourceRegistryPublisher

Type Parameters:

R - The specific type of Resource to delete

Parameters:

resource - The Resource instance to delete (must contain a valid UUID in the header)

Returns:

true if the Resource was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

deleteResource

public boolean deleteResource(String resourceType,
 UUID uuid)
                       throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a Resource instance from the Resource Registry using type name and UUID. Corresponding REST API: DELETE /instances/{resource-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified Resource instance from the Resource Registry
• The Resource is identified by its type name and UUID
• The Resource must exist and be accessible in the current context
• This is a destructive operation that cannot be undone
• Associated Facets and ConsistsOf relations may also be deleted based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Resource successfully deleted
• 404 Not Found: Resource does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the Resource
• 409 Conflict: Resource cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The resourceType parameter must be a valid Resource type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software, Dataset, VirtualMachine)
• The UUID must be a valid UUID that identifies an existing Resource instance.

Deletion Propagation Rules:

• Resources: When a Resource is deleted, all its associated Facets (via ConsistsOf relations) may also be deleted if they become orphaned and the delete propagation constraint is propagate
• Associated Facets: Facets connected to the Resource via ConsistsOf relations are automatically removed if no other Resources reference them
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are automatically removed
• IsRelatedTo Relations: IsRelatedTo relations where this Resource is source or target are automatically removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each Resource type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the Resource will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Resource that is required by other Resources via IsRelatedTo relations; • Deleting Resources that violate cardinality constraints (min occurrences) defined in the schema; • Operations that would make related Resources incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the Resource exists.

IS-Manager:

• Can delete any Resource in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any Resource in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete Resources only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete Resources only in contexts where they have appropriate permissions
• Operations are limited to Resources they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an EService by type and UUID
 UUID serviceUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 boolean deleted = publisher.deleteResource("EService", serviceUUID);
 
 // Delete a HostingNode by type and UUID
 UUID hostUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 boolean hostDeleted = publisher.deleteResource("HostingNode", hostUUID);
 

This method is a type-safe wrapper that delegates to delete(String, UUID) for implementation details.

Specified by:

deleteResource in interface ResourceRegistryPublisher

Parameters:

resourceType - The exact type name of the Resource to delete

uuid - The UUID of the Resource instance to delete

Returns:

true if the Resource was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

createConsistsOf

public <C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Facet>>
C createConsistsOf(C consistsOf)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new ConsistsOf relation instance in the Resource Registry. Corresponding REST API: POST /instances/{consistsof-type-name} Operation Behavior:

• Creates a new ConsistsOf relation between a Resource and a Facet
• ConsistsOf relations represent the composition relationship where a Resource consists of one or more Facets
• The relation instance is automatically associated with the current context
• Validates the relation against the Information System model schema
• Generates a new UUID for the relation if not already set
• Returns the created relation with server-generated metadata.

HTTP Response Codes:

• 201 Created: ConsistsOf relation successfully created
• 400 Bad Request: Invalid relation data or schema validation failure
• 409 Conflict: ConsistsOf relation with the same UUID already exists
• 404 Not Found: Source Resource or target Facet does not exist
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The relation type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Supports ConsistsOf types and subtypes defined in the Information System model

Schema Validation:

• All relation properties are validated against the Information System model
• Source and target entities must exist and be accessible in compatible contexts
• Relation constraints and cardinality rules are enforced
• ConsistsOf-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• User must have write permissions in the current context
• Both source Resource and target Facet must be available in the current context.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a ConsistsOf relation between an EService and ContactFacet
 IsIdentifiedBy<EService, ContactFacet> identifiedBy = new IsIdentifiedBy<>();
 identifiedBy.setSource(eservice);
 identifiedBy.setTarget(contact);
 ...
 IsIdentifiedBy<EService, ContactFacet> createdRelation = publisher.createConsistsOf(identifiedBy);
 

This method is a type-safe wrapper that delegates to create(ERElem) for implementation details.

Specified by:

createConsistsOf in interface ResourceRegistryPublisher

Type Parameters:

C - The specific type of ConsistsOf relation to create

Parameters:

consistsOf - The ConsistsOf relation instance to create in the Resource Registry

Returns:

The created ConsistsOf relation with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the relation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAlreadyPresentException - If a relation with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the source Resource or target Facet does not exist (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation creation

createConsistsOf

public String createConsistsOf(String consistsOf)
                        throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new ConsistsOf relation instance from JSON representation. Corresponding REST API: POST /instances/{consistsof-type-name} Operation Behavior:

• Creates a new ConsistsOf relation between a Resource and a Facet from JSON representation
• ConsistsOf relations represent the composition relationship where a Resource consists of one or more Facets
• The relation instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the relation if not already set
• Returns the created relation as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: ConsistsOf relation successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: ConsistsOf relation with the same UUID already exists
• 404 Not Found: Source Resource or target Facet does not exist
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying a ConsistsOf type
• Must conform to the Information System model JSON schema for ConsistsOf relations
• Must include valid source and target references
• All required properties for the specified relation type must be present.

Schema Validation:

• JSON structure is validated against the Information System model
• Source and target entity references are validated
• Relation constraints and cardinality rules are enforced
• ConsistsOf-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• User must have write permissions in the current context
• Both source Resource and target Facet must be available in the current context.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a ConsistsOf relation from JSON
 String consistsOfJson = "...";
 String createdRelationJson = publisher.createConsistsOf(consistsOfJson);
 

This method is a type-safe wrapper that delegates to create(String) for implementation details.

Specified by:

createConsistsOf in interface ResourceRegistryPublisher

Parameters:

consistsOf - JSON representation of the ConsistsOf relation to create

Returns:

JSON representation of the created ConsistsOf relation with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAlreadyPresentException - If a relation with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the source Resource or target Facet does not exist (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation creation or JSON parsing

readConsistsOf

public <C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Facet>>
C readConsistsOf(C consistsOf)
          throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a ConsistsOf relation instance from the Resource Registry using a provided instance object. Corresponding REST API: GET /instances/{consistsof-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing ConsistsOf relation by extracting type and UUID from the provided instance
• The relation must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete ConsistsOf relation with source Resource, target Facet, and all properties
• The type is automatically determined from the provided instance object.

HTTP Response Codes:

• 200 OK: ConsistsOf relation successfully retrieved
• 404 Not Found: No ConsistsOf relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks read permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The ConsistsOf type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header
• The returned object will be of the same ConsistsOf relation type as the provided instance.

Context Access:

• The ConsistsOf relation must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Relation Context:

• ConsistsOf relations represent aggregation relationships between Resources and Facets
• The source of the relation is always a Resource, the target is always a Facet
• The relation defines how a Resource is composed of various Facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read a ConsistsOf relation
 ConsistsOf<EService, SoftwareFacet> co = new ConsistsOf<>();
 co.setHeader(new Header(uuid));
 ConsistsOf<EService, SoftwareFacet> readCO = publisher.readConsistsOf(co);
 

This method is a type-safe wrapper that delegates to read(ERElem) for implementation details.

Specified by:

readConsistsOf in interface ResourceRegistryPublisher

Type Parameters:

C - The specific type of ConsistsOf relation to read

Parameters:

consistsOf - Instance object containing at least the UUID in the header

Returns:

The complete ConsistsOf relation instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If no ConsistsOf relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAvailableInAnotherContextException - If the relation exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation retrieval

readConsistsOf

public String readConsistsOf(String consistsOfType,
 UUID uuid)
                      throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a ConsistsOf relation instance from the Resource Registry by its type and UUID. Corresponding REST API: GET /instances/{consistsof-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing ConsistsOf relation by its type name and unique identifier
• The relation must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete ConsistsOf relation as JSON with source Resource, target Facet, and all properties
• Type validation ensures the UUID corresponds to a ConsistsOf relation of the specified type.

HTTP Response Codes:

• 200 OK: ConsistsOf relation successfully retrieved
• 404 Not Found: No ConsistsOf relation found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The specified type must be a valid ConsistsOf relation type in the Information System model
• Supports all ConsistsOf relation types and their subtypes as defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a ConsistsOf relation of exactly the specified type (no polymorphic matching).

Context Access:

• The ConsistsOf relation must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Relation Context:

• ConsistsOf relations represent aggregation relationships between Resources and Facets
• The JSON response includes source Resource reference, target Facet reference, and relation properties
• Relation cardinality and constraints are validated according to the Information System model.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read a ConsistsOf relation by type and UUID
 UUID relationUuid = UUID.fromString("...");
 String relationJson = publisher.readConsistsOf("ConsistsOf", relationUuid);
 

This method is a type-safe wrapper that delegates to read(String, UUID) for implementation details.

Specified by:

readConsistsOf in interface ResourceRegistryPublisher

Parameters:

consistsOfType - The exact type name of the ConsistsOf relation to read

uuid - The unique identifier of the ConsistsOf relation to read

Returns:

JSON representation of the complete ConsistsOf relation instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If no ConsistsOf relation is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAvailableInAnotherContextException - If the relation exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation retrieval

updateConsistsOf

public <C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Facet>>
C updateConsistsOf(C consistsOf)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing ConsistsOf relation instance in the Resource Registry. REST Endpoint: PUT /instances/{consistsof-type-name}/{consistsof-uuid} Request Examples:

• Basic update: ConsistsOf updatedRelation = publisher.updateConsistsOf(relationToUpdate);
• With metadata in response: publisher.includeMeta(true); ConsistsOf updatedRelation = publisher.updateConsistsOf(relationToUpdate);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); ConsistsOf updatedRelation = publisher.updateConsistsOf(relationToUpdate);
• With context information: publisher.includeContexts(true); ConsistsOf updatedRelation = publisher.updateConsistsOf(relationToUpdate);.

Update Behavior:

• Updates an existing ConsistsOf relation with new property values from the provided instance
• The ConsistsOf relation must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• The ConsistsOf UUID cannot be changed during update operations
• Source Resource and target Facet cannot be changed during update (only properties)
• The source Resource is automatically revalidated after ConsistsOf update to ensure schema compliance.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response ConsistsOf relation
• Default value: false (basic information only)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for ConsistsOf relations in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: ConsistsOf relation successfully updated
• 400 Bad Request: Invalid relation data or schema validation failed
• 404 Not Found: The ConsistsOf relation does not exist
• 403 Forbidden: Insufficient permissions to update the ConsistsOf relation.

Response Format:

• Returns the updated ConsistsOf relation object with its properties
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are included according to the current configuration.

This method is a type-safe wrapper that delegates to update(ERElem) for implementation details.

Specified by:

updateConsistsOf in interface ResourceRegistryPublisher

Type Parameters:

C - The specific type of ConsistsOf relation to update

Parameters:

consistsOf - The ConsistsOf relation instance with updated values (must contain valid UUID)

Returns:

The updated ConsistsOf relation object with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated ConsistsOf relation violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If the ConsistsOf relation to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during ConsistsOf relation update

updateConsistsOf

public String updateConsistsOf(String consistsOf)
                        throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing ConsistsOf relation instance in the Resource Registry using JSON representation. REST Endpoint: PUT /instances/{consistsof-type-name}/{consistsof-uuid} Request Examples:

• Basic update: String updatedRelation = publisher.updateConsistsOf(relationJsonString);
• With metadata in response: publisher.includeMeta(true); String updatedRelation = publisher.updateConsistsOf(relationJsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String updatedRelation = publisher.updateConsistsOf(relationJsonString);
• With context information: publisher.includeContexts(true); String updatedRelation = publisher.updateConsistsOf(relationJsonString);.

Update Behavior:

• Updates an existing ConsistsOf relation using JSON representation
• The JSON must contain the UUID of the ConsistsOf relation to update
• The ConsistsOf type is automatically detected from the JSON content
• The ConsistsOf relation must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• Source Resource and target Facet cannot be changed during update (only properties)
• The source Resource is automatically revalidated after ConsistsOf update to ensure schema compliance.

JSON Format Requirements:

• Valid JSON representation of a ConsistsOf relation instance
• Must include the "id" field with the UUID of the ConsistsOf relation to update
• Must include the "@class" field to identify the ConsistsOf type
• Must conform to the schema of the specified ConsistsOf type
• Source and target references should remain unchanged.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response ConsistsOf relation
• Default value: false (basic information only)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for ConsistsOf relations in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: ConsistsOf relation successfully updated
• 400 Bad Request: Invalid JSON format, missing required fields, or schema validation failed
• 404 Not Found: The ConsistsOf relation does not exist
• 403 Forbidden: Insufficient permissions to update the ConsistsOf relation.

Response Format:

• Returns a JSON string containing the updated ConsistsOf relation
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are included according to the current configuration.

This method is a type-safe wrapper that delegates to update(String) for implementation details.

Specified by:

updateConsistsOf in interface ResourceRegistryPublisher

Parameters:

consistsOf - JSON representation of the ConsistsOf relation to update

Returns:

JSON string containing the updated ConsistsOf relation with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated ConsistsOf relation violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If the ConsistsOf relation to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during ConsistsOf relation update

deleteConsistsOf

public <C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Facet>>
boolean deleteConsistsOf(C consistsOf)
                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a ConsistsOf relation instance from the Resource Registry. Corresponding REST API: DELETE /instances/{consistsof-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified ConsistsOf relation instance from the Resource Registry
• The type and UUID are automatically extracted from the provided ConsistsOf object
• The ConsistsOf relation must exist and be accessible in the current context
• This operation removes the relationship between a Resource and a Facet
• This is a destructive operation that cannot be undone
• The connected Resource and Facet elements may be affected based on propagation constraints.

HTTP Response Codes:

• 200 OK: ConsistsOf relation successfully deleted
• 404 Not Found: ConsistsOf relation does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the ConsistsOf relation
• 409 Conflict: ConsistsOf relation cannot be deleted due to schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type name is automatically derived from the provided ConsistsOf object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the ConsistsOf relation's header
• Supports all ConsistsOf relation types and their specializations.

Deletion Effects and Propagation:

• ConsistsOf Relations: When a ConsistsOf relation is deleted, the relationship between the Resource and Facet is removed
• Connected Resource: The source Resource remains but loses the connection to the target Facet
• Connected Facet: The target Facet may become orphaned if this was its only connection to a Resource
• Orphaned Facets: Facets that become orphaned (not connected to any Resource) may be automatically deleted based on schema configuration
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for the specific ConsistsOf type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the ConsistsOf relation will not violate schema constraints
• If deletion would leave the Resource incomplete or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a ConsistsOf relation to a required Facet (violates min cardinality); • Removing mandatory relationships that make the Resource invalid according to its schema; • Operations that would violate schema-defined constraints for the Resource type. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the ConsistsOf relation exists.

IS-Manager:

• Can delete any ConsistsOf relation in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any ConsistsOf relation in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete ConsistsOf relations only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete ConsistsOf relations only in contexts where they have appropriate permissions
• Operations are limited to relations they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete a ConsistsOf relation instance
 ConsistsOf<EService, StateFacet> consistsOf = publisher.readConsistsOf(ConsistsOf.class, relationUUID);
 boolean deleted = publisher.deleteConsistsOf(consistsOf);
 
 // Delete a specific ConsistsOf relation between a HostingNode and a StateFacet
 ConsistsOf<HostingNode, StateFacet> hostState = publisher.readConsistsOf(ConsistsOf.class, hostStateUUID);
 boolean relationDeleted = publisher.deleteConsistsOf(hostState);
 

This method is a type-safe wrapper that delegates to delete(ERElem) for implementation details.

Specified by:

deleteConsistsOf in interface ResourceRegistryPublisher

Type Parameters:

C - The specific type of ConsistsOf relation to delete

Parameters:

consistsOf - The ConsistsOf relation instance to delete (must contain a valid UUID in the header)

Returns:

true if the ConsistsOf relation was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the ConsistsOf relation would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If the ConsistsOf relation does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

deleteConsistsOf

public boolean deleteConsistsOf(String consistsOfType,
 UUID uuid)
                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a ConsistsOf relation instance from the Resource Registry using type name and UUID. Corresponding REST API: DELETE /instances/{consistsof-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified ConsistsOf relation instance from the Resource Registry
• The ConsistsOf relation is identified by its type name and UUID
• The ConsistsOf relation must exist and be accessible in the current context
• This operation removes the relationship between a Resource and a Facet
• This is a destructive operation that cannot be undone
• The connected Resource and Facet elements may be affected based on propagation constraints.

HTTP Response Codes:

• 200 OK: ConsistsOf relation successfully deleted
• 404 Not Found: ConsistsOf relation does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the ConsistsOf relation
• 409 Conflict: ConsistsOf relation cannot be deleted due to schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The consistsOfType parameter must be a valid ConsistsOf relation type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all ConsistsOf relation types and their specializations
• The UUID must be a valid UUID that identifies an existing ConsistsOf relation instance.

Deletion Effects and Propagation:

• ConsistsOf Relations: When a ConsistsOf relation is deleted, the relationship between the Resource and Facet is removed
• Connected Resource: The source Resource remains but loses the connection to the target Facet
• Connected Facet: The target Facet may become orphaned if this was its only connection to a Resource
• Orphaned Facets: Facets that become orphaned (not connected to any Resource) may be automatically deleted based on schema configuration
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for the specific ConsistsOf type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the ConsistsOf relation will not violate schema constraints
• If deletion would leave the Resource incomplete or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a ConsistsOf relation to a required Facet (violates min cardinality); • Removing mandatory relationships that make the Resource invalid according to its schema; • Operations that would violate schema-defined constraints for the Resource type. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the ConsistsOf relation exists.

IS-Manager:

• Can delete any ConsistsOf relation in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any ConsistsOf relation in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete ConsistsOf relations only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete ConsistsOf relations only in contexts where they have appropriate permissions
• Operations are limited to relations they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete a ConsistsOf relation by type and UUID
 UUID relationUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 boolean deleted = publisher.deleteConsistsOf("ConsistsOf", relationUUID);
 
 // Delete a specific ConsistsOf relation type
 UUID specificRelationUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 boolean relationDeleted = publisher.deleteConsistsOf("SpecificConsistsOfType", specificRelationUUID);
 

This method is a type-safe wrapper that delegates to delete(String, UUID) for implementation details.

Specified by:

deleteConsistsOf in interface ResourceRegistryPublisher

Parameters:

consistsOfType - The exact type name of the ConsistsOf relation to delete

uuid - The UUID of the ConsistsOf relation instance to delete

Returns:

true if the ConsistsOf relation was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the ConsistsOf relation would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If the ConsistsOf relation does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

createIsRelatedTo

public <I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Resource>>
I createIsRelatedTo(I isRelatedTo)
             throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new IsRelatedTo relation instance in the Resource Registry. Corresponding REST API: POST /instances/{isrelatedto-type-name} Operation Behavior:

• Creates a new IsRelatedTo relation between two Resources
• IsRelatedTo relations represent various types of relationships between Resources (e.g., dependency, hosting, derivation)
• The relation instance is automatically associated with the current context
• Validates the relation against the Information System model schema
• Generates a new UUID for the relation if not already set
• Returns the created relation with server-generated metadata.

HTTP Response Codes:

• 201 Created: IsRelatedTo relation successfully created
• 400 Bad Request: Invalid relation data or schema validation failure
• 409 Conflict: IsRelatedTo relation with the same UUID already exists
• 404 Not Found: Source Resource or target Resource does not exist
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The relation type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Supports all IsRelatedTo subtypes defined in the Information System model.

Schema Validation:

• All relation properties are validated against the Information System model
• Source and target Resources must exist and be accessible in compatible contexts
• Relation constraints and cardinality rules are enforced
• IsRelatedTo-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• User must have write permissions in the current context
• Both source and target Resources must be available in the current context.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create an IsRelatedTo relation between two EServices
 Activates<EService, EService> activates = new Activates<>();
 activates.setSource(sourceService);
 activates.setTarget(targetService);
 ...
 Activates<EService, EService> createdRelation = publisher.createIsRelatedTo(activates);
 

This method is a type-safe wrapper that delegates to create(ERElem) for implementation details.

Specified by:

createIsRelatedTo in interface ResourceRegistryPublisher

Type Parameters:

I - The specific type of IsRelatedTo relation to create

Parameters:

isRelatedTo - The IsRelatedTo relation instance to create in the Resource Registry

Returns:

The created IsRelatedTo relation with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the relation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAlreadyPresentException - If a relation with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the source or target Resource does not exist (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation creation

createIsRelatedTo

public String createIsRelatedTo(String isRelatedTo)
                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new IsRelatedTo relation instance from JSON representation. Corresponding REST API: POST /instances/{isrelatedto-type-name} Operation Behavior:

• Creates a new IsRelatedTo relation between two Resources from JSON representation
• IsRelatedTo relations represent various types of relationships between Resources (e.g., dependency, hosting, derivation)
• The relation instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the relation if not already set
• Returns the created relation as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: IsRelatedTo relation successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: IsRelatedTo relation with the same UUID already exists
• 404 Not Found: Source Resource or target Resource does not exist
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying an IsRelatedTo type
• Must conform to the Information System model JSON schema for IsRelatedTo relations
• Must include valid source and target Resource references
• All required properties for the specified relation type must be present.

Schema Validation:

• JSON structure is validated against the Information System model
• Source and target Resource references are validated
• Relation constraints and cardinality rules are enforced
• IsRelatedTo-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• User must have write permissions in the current context
• Both source and target Resources must be available in the current context.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create an IsRelatedTo relation from JSON
 String isRelatedToJson = "...";
 String createdRelationJson = publisher.createIsRelatedTo(isRelatedToJson);
 

This method is a type-safe wrapper that delegates to create(String) for implementation details.

Specified by:

createIsRelatedTo in interface ResourceRegistryPublisher

Parameters:

isRelatedTo - JSON representation of the IsRelatedTo relation to create

Returns:

JSON representation of the created IsRelatedTo relation with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAlreadyPresentException - If a relation with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the source or target Resource does not exist (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation creation or JSON parsing

readIsRelatedTo

public <I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Resource>>
I readIsRelatedTo(I isRelatedTo)
           throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads an IsRelatedTo relation instance from the Resource Registry by its UUID. Corresponding REST API: GET /instances/{isrelatedto-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing IsRelatedTo relation by its unique identifier
• The relation must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete relation instance with all properties and metadata
• The type is automatically determined from the provided object instance.

HTTP Response Codes:

• 200 OK: IsRelatedTo relation successfully retrieved
• 404 Not Found: No IsRelatedTo relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks read permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The relation type is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The returned object will be of the same type as the provided instance.

Context Access:

• The relation must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an Activates relation
 Activates<EService, EService> activates = new Activates<>();
 activates.setHeader(new Header(uuid));
 Activates<EService, EService> readActivates = publisher.readIsRelatedTo(activates);
 

This method is a type-safe wrapper that delegates to read(ERElem) for implementation details.

Specified by:

readIsRelatedTo in interface ResourceRegistryPublisher

Type Parameters:

I - The specific type of IsRelatedTo relation to read

Parameters:

isRelatedTo - Instance object containing at least the UUID in the header

Returns:

The complete IsRelatedTo relation instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no IsRelatedTo relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAvailableInAnotherContextException - If the IsRelatedTo relation is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation retrieval

readIsRelatedTo

public String readIsRelatedTo(String isRelatedToType,
 UUID uuid)
                       throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads an IsRelatedTo relation instance from the Resource Registry by its type and UUID. Corresponding REST API: GET /instances/{isrelatedto-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing IsRelatedTo relation by its type name and unique identifier
• The relation must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete relation instance as JSON with all properties and metadata
• Type validation ensures the UUID corresponds to a relation of the specified type.

HTTP Response Codes:

• 200 OK: IsRelatedTo relation successfully retrieved
• 404 Not Found: No IsRelatedTo relation found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

hierarchical (configurable via client configuration, admin-only):

• Whether to include instances from child contexts of the current context
• Default value: false (child contexts not included)
• Usage: publisher.setHierarchicalMode(true)
• Values: true (includes child contexts) | false (current context only)
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.

Input Processing:

• The specified type must be a valid IsRelatedTo type in the Information System model
• Supports all IsRelatedTo types and their subtypes as defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a relation of exactly the specified type (no polymorphic matching). *

Context Access:

• The relation must be accessible in the current context or child contexts (depending on hierarchical mode)
• IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
• Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an Activates relation by type and UUID
 UUID relationUuid = UUID.fromString("...");
 String relationJson = publisher.readIsRelatedTo("Activates", relationUuid);
 

This method is a type-safe wrapper that delegates to read(String, UUID) for implementation details.

Specified by:

readIsRelatedTo in interface ResourceRegistryPublisher

Parameters:

isRelatedToType - The exact type name of the IsRelatedTo relation to read

uuid - The unique identifier of the IsRelatedTo relation to read

Returns:

JSON representation of the complete IsRelatedTo relation instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAvailableInAnotherContextException - If the relation exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation retrieval

updateIsRelatedTo

public <I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Resource>>
I updateIsRelatedTo(I isRelatedTo)
             throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing IsRelatedTo relation instance in the Resource Registry. Corresponding REST API: PUT /instances/{isrelatedto-type-name}/{uuid} Operation Behavior:

• Updates an existing IsRelatedTo relation with new property values
• The relation must exist and be accessible in the current context
• All provided properties will replace the existing ones (full update, not partial)
• Validates the updated relation against the Information System model schema
• Preserves the original UUID and creation metadata
• Returns the updated relation with current metadata.

HTTP Response Codes:

• 200 OK: IsRelatedTo relation successfully updated
• 400 Bad Request: Invalid relation data or schema validation failure
• 404 Not Found: No IsRelatedTo relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks write permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The relation type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Type cannot be changed during update (UUID must correspond to existing relation of same type).

Schema Validation:

• All relation properties are validated against the Information System model
• Source and target Resources must exist and be accessible in compatible contexts
• Relation constraints and cardinality rules are enforced
• IsRelatedTo-specific validation rules are applied.

Update Behavior:

• This is a complete replacement of the relation (not a merge)
• All properties not specified in the update will be lost
• Source and target Resource references can be changed if valid
• Context association cannot be changed through update.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Update an Activates relation
 Activates<EService, EService> relation = ...; // Retrieved relation
 // Modify properties
 relation.setStartTime(...);
 Activates<EService, EService> updatedRelation = publisher.updateIsRelatedTo(relation);
 

This method is a type-safe wrapper that delegates to update(ERElem) for implementation details.

Specified by:

updateIsRelatedTo in interface ResourceRegistryPublisher

Type Parameters:

I - The specific type of IsRelatedTo relation to update

Parameters:

isRelatedTo - The IsRelatedTo relation instance with updated values

Returns:

The updated IsRelatedTo relation with current server metadata

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated relation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation update

updateIsRelatedTo

public String updateIsRelatedTo(String isRelatedTo)
                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing IsRelatedTo relation instance from JSON representation. Corresponding REST API: PUT /instances/{isrelatedto-type-name}/{uuid} Operation Behavior:

• Updates an existing IsRelatedTo relation with new property values from JSON representation
• The relation must exist and be accessible in the current context
• All provided properties will replace the existing ones (full update, not partial)
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Preserves the original UUID and creation metadata
• Returns the updated relation as JSON with current metadata.

HTTP Response Codes:

• 200 OK: IsRelatedTo relation successfully updated
• 400 Bad Request: Invalid JSON data or schema validation failure
• 404 Not Found: No IsRelatedTo relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks write permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying an IsRelatedTo type
• Must contain a valid header with the UUID of the relation to update
• Must conform to the Information System model JSON schema for IsRelatedTo relations
• Must include valid source and target Resource references
• All required properties for the specified relation type must be present.

Schema Validation:

• JSON structure is validated against the Information System model
• Source and target Resource references are validated
• Relation constraints and cardinality rules are enforced
• IsRelatedTo-specific validation rules are applied.

Update Behavior:

• This is a complete replacement of the relation (not a merge)
• All properties not specified in the JSON will be lost
• Source and target Resource references can be changed if valid
• Context association cannot be changed through update.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Update an IsRelatedTo relation from JSON
 String updatedRelationJson = "..."; // JSON with same UUID but updated properties
 String resultJson = publisher.updateIsRelatedTo(updatedRelationJson);
 

This method is a type-safe wrapper that delegates to update(String) for implementation details.

Specified by:

updateIsRelatedTo in interface ResourceRegistryPublisher

Parameters:

isRelatedTo - JSON representation of the IsRelatedTo relation with updated values

Returns:

JSON representation of the updated IsRelatedTo relation with current server metadata

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation update or JSON parsing

deleteIsRelatedTo

public <I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Resource>>
boolean deleteIsRelatedTo(I isRelatedTo)
                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes an IsRelatedTo relation instance from the Resource Registry. Corresponding REST API: DELETE /instances/{isrelatedto-type-name}/{uuid} Operation Behavior:

• Permanently removes an IsRelatedTo relation from the Resource Registry
• The relation must exist and be accessible in the current context
• Only the relation is deleted; source and target Resources remain unaffected
• The operation is irreversible once completed
• Returns boolean indicating successful deletion.

HTTP Response Codes:

• 204 No Content: IsRelatedTo relation successfully deleted
• 404 Not Found: No IsRelatedTo relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks write permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The relation type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Only the UUID from the header is used for identification.

Deletion Behavior:

• The relation is permanently removed from the Information System
• Source and target Resources are not affected by the deletion
• Any cascading effects depend on Information System model constraints
• The operation cannot be undone.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an Activates relation
 Activates<EService, EService> relation = new Activates<>();
 relation.setHeader(new Header(uuid));
 boolean deleted = publisher.deleteIsRelatedTo(relation);
 

This method is a type-safe wrapper that delegates to delete(ERElem) for implementation details.

Specified by:

deleteIsRelatedTo in interface ResourceRegistryPublisher

Type Parameters:

I - The specific type of IsRelatedTo relation to delete

Parameters:

isRelatedTo - Instance object containing at least the UUID in the header

Returns:

true if the IsRelatedTo relation was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation deletion

deleteIsRelatedTo

public boolean deleteIsRelatedTo(String isRelatedToType,
 UUID uuid)
                          throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes an IsRelatedTo relation instance from the Resource Registry by its type and UUID. Corresponding REST API: DELETE /instances/{isrelatedto-type-name}/{uuid} Operation Behavior:

• Permanently removes an IsRelatedTo relation from the Resource Registry
• The relation must exist and be accessible in the current context
• Only the relation is deleted; source and target Resources remain unaffected
• Type validation ensures the UUID corresponds to a relation of the specified type
• The operation is irreversible once completed
• Returns boolean indicating successful deletion.

HTTP Response Codes:

• 204 No Content: IsRelatedTo relation successfully deleted
• 404 Not Found: No IsRelatedTo relation found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks write permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The specified type must be a valid IsRelatedTo type in the Information System model
• Supports all IsRelatedTo types and their subtypes as defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a relation of exactly the specified type (no polymorphic matching). *

Deletion Behavior:

• The relation is permanently removed from the Information System
• Source and target Resources are not affected by the deletion
• Any cascading effects depend on Information System model constraints
• The operation cannot be undone.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an Activates relation by type and UUID
 UUID relationUuid = UUID.fromString("...");
 boolean deleted = publisher.deleteIsRelatedTo("Activates", relationUuid);
 

This method is a type-safe wrapper that delegates to delete(String, UUID) for implementation details.

Specified by:

deleteIsRelatedTo in interface ResourceRegistryPublisher

Parameters:

isRelatedToType - The exact type name of the IsRelatedTo relation to delete

uuid - The unique identifier of the IsRelatedTo relation to delete

Returns:

true if the IsRelatedTo relation was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation deletion

addToContext

public List<org.gcube.informationsystem.model.reference.ERElement> addToContext(String type,
 UUID instanceUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an Information System element instance to a specific context. Corresponding REST API: PUT /instances/{type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing instance (Entity or Relation) to the specified target context
• The instance must already exist and be accessible in the context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the instance itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them.

HTTP Response Codes:

• 200 OK: Instance successfully added to context (or dry-run completed)
• 404 Not Found: Instance or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of an instance to a context even if the instance is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding an instance to a context even if the instance exists only in other contexts
• When false: Standard validation applies - instance must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name must be a valid Information System model type
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
• Type names are case-sensitive and must match exactly the class names defined in the Information System model.

Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Facets: When added to a context, the Resource that reference it (via ConsistsOf relation) is also added to the same context
• ConsistsOf Relations: add both facet and resource to the same context
• IsRelatedTo Relations: add both source and target resources to the same context.

Propagation Constraints and Cascade Effects:

• When an instance is added to a context, related instances may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding instances that violate cardinality constraints (max occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to add instances.

IS-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService to a specific context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addToContext("EService", serviceUUID, targetContextUUID, false);
 
 // Preview what would be affected by adding a ContactFacet to a context
 UUID facetUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.addToContext("ContactFacet", facetUUID, targetContextUUID, true);
 

Specified by:

addToContext in interface ResourceRegistryPublisher

Parameters:

type - The exact type name of the Information System element to add

instanceUUID - The UUID of the instance to add to the context

contextUUID - The UUID of the target context where the instance should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance or context is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addToContext

public List<org.gcube.informationsystem.model.reference.ERElement> addToContext(org.gcube.informationsystem.model.reference.ERElement er,
 UUID contextUUID,
 Boolean dryRun)
                                                                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an Information System element instance to a specific context using a provided instance object. Corresponding REST API: PUT /instances/{type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing instance (Entity or Relation) to the specified target context
• The type and UUID are automatically extracted from the provided instance object
• The instance must already exist and be accessible in the context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the instance itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them.

HTTP Response Codes:

• 200 OK: Instance successfully added to context (or dry-run completed)
• 404 Not Found: Instance or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of an instance to a context even if the instance is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding an instance to a context even if the instance exists only in other contexts
• When false: Standard validation applies - instance must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• Type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• UUID is extracted from the instance's header using standard Information System model conventions
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
• Type names are case-sensitive and must match exactly the class names defined in the Information System model.

Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Facets: When added to a context, the Resource that reference it (via ConsistsOf relation) is also added to the same context
• ConsistsOf Relations: add both facet and resource to the same context
• IsRelatedTo Relations: add both source and target resources to the same context.

Propagation Constraints and Cascade Effects:

• When an instance is added to a context, related instances may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding instances that violate cardinality constraints (max occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to add instances.

IS-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService instance to a specific context
 EService service = new EService();
 service.setHeader(new Header(serviceUUID));
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addToContext(service, targetContextUUID, false);
 
 // Preview what would be affected by adding a ContactFacet to a context
 ContactFacet contact = publisher.read(ContactFacet.class, contactUUID);
 List<ERElement> preview = publisher.addToContext(contact, targetContextUUID, true);
 

Specified by:

addToContext in interface ResourceRegistryPublisher

Parameters:

er - The instance to add to the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context where the instance should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance or context is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addToCurrentContext

public List<org.gcube.informationsystem.model.reference.ERElement> addToCurrentContext(String type,
 UUID instanceUUID,
 Boolean dryRun)
                                                                                throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an Information System element instance to the current context. Corresponding REST API: PUT /instances/{type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing instance (Entity or Relation) to the current context derived from the authorization token
• The instance must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the instance itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID.

HTTP Response Codes:

• 200 OK: Instance successfully added to current context (or dry-run completed)
• 404 Not Found: Instance does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of an instance to a context even if the instance is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding an instance to a context even if the instance exists only in other contexts
• When false: Standard validation applies - instance must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name must be a valid Information System model type
• Supports all Information System model types: Entities (Resources, Facets) and Relations (ConsistsOf, IsRelatedTo) and their specialization
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Facets: When added to a context, the Resource that reference it (via ConsistsOf relation) is also added to the same context
• ConsistsOf Relations: add both facet and resource to the same context
• IsRelatedTo Relations: add both source and target resources to the same context.

Propagation Constraints and Cascade Effects:

• When an instance is added to a context, related instances may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding instances that violate cardinality constraints (max occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add instances.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService to the current context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addToCurrentContext("EService", serviceUUID, false);
 
 // Preview what would be affected by adding a ContactFacet to the current context
 UUID facetUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.addToCurrentContext("ContactFacet", facetUUID, true);
 

Specified by:

addToCurrentContext in interface ResourceRegistryPublisher

Parameters:

type - The exact type name of the Information System element to add

instanceUUID - The UUID of the instance to add to the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addToCurrentContext

public List<org.gcube.informationsystem.model.reference.ERElement> addToCurrentContext(org.gcube.informationsystem.model.reference.ERElement er,
 Boolean dryRun)
                                                                                throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an Information System element instance to the current context using a provided instance object. Corresponding REST API: PUT /instances/{type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing instance (Entity or Relation) to the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided instance object
• The instance must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the instance itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID.

HTTP Response Codes:

• 200 OK: Instance successfully added to current context (or dry-run completed)
• 404 Not Found: Instance does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of an instance to a context even if the instance is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding an instance to a context even if the instance exists only in other contexts
• When false: Standard validation applies - instance must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• Type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• UUID is extracted from the instance's header using standard Information System model conventions
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
• Type names are case-sensitive and must match exactly the class names defined in the Information System model.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Facets: When added to a context, the Resource that reference it (via ConsistsOf relation) is also added to the same context
• ConsistsOf Relations: add both facet and resource to the same context
• IsRelatedTo Relations: add both source and target resources to the same context.

Propagation Constraints and Cascade Effects:

• When an instance is added to a context, related instances may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding instances that violate cardinality constraints (max occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add instances.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService instance to the current context
 EService service = new EService();
 service.setHeader(new Header(serviceUUID));
 List<ERElement> affected = publisher.addToCurrentContext(service, false);
 
 // Preview what would be affected by adding a ContactFacet to the current context
 ContactFacet contact = publisher.read(ContactFacet.class, contactUUID);
 List<ERElement> preview = publisher.addToCurrentContext(contact, true);
 

Specified by:

addToCurrentContext in interface ResourceRegistryPublisher

Parameters:

er - The instance to add to the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

removeFromContext

public List<org.gcube.informationsystem.model.reference.ERElement> removeFromContext(String type,
 UUID instanceUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an Information System element instance from a specific context. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{type-name}/{instance-uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing instance (Entity or Relation) from the specified target context
• The instance must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the instance itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them.

HTTP Response Codes:

• 200 OK: Instance successfully removed from context (or dry-run completed)
• 404 Not Found: Instance or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name must be a valid Information System model type
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
• Type names are case-sensitive and must match exactly the class names defined in the Information System model.

Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Facets: When removed from a context, the Resource that reference it (via ConsistsOf relation) is also removed from the same context if the Facet was the last one required by the Resource in that context
• ConsistsOf Relations: Remove both facet and resource from the same context
• IsRelatedTo Relations: Remove both source and target resources from the same context.

Propagation Constraints and Cascade Effects:

• When an instance is removed from a context, related instances may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet or ConsistsOf relation from a Resource; • Removing instances that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove instances.

IS-Manager:

• Can perform REMOVE operations on any instance in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any instance in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on instances accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on instances accessible in their current context
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService from a specific context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFromContext("EService", serviceUUID, targetContextUUID, false);
 
 // Preview what would be affected by removing a ContactFacet from a context
 UUID facetUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeFromContext("ContactFacet", facetUUID, targetContextUUID, true);
 

Specified by:

removeFromContext in interface ResourceRegistryPublisher

Parameters:

type - The exact type name of the Information System element to remove

instanceUUID - The UUID of the instance to remove from the context

contextUUID - The UUID of the target context from which the instance should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance or context is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFromContext

public List<org.gcube.informationsystem.model.reference.ERElement> removeFromContext(org.gcube.informationsystem.model.reference.ERElement er,
 UUID contextUUID,
 Boolean dryRun)
                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an Information System element instance from a specific context using a provided instance object. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{type-name}/{instance-uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing instance (Entity or Relation) from the specified target context
• The instance must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the instance itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method accepts an Information System instance object directly, which provides type safety and convenience.

HTTP Response Codes:

• 200 OK: Instance successfully removed from context (or dry-run completed)
• 404 Not Found: Instance or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the instance and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The instance object must contain a valid UUID in its header
• Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
• The actual type is determined from the instance object's class.

Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Facets: When removed from a context, the Resource that reference it (via ConsistsOf relation) is also removed from the same context if the Facet was the last one required by the Resource in that context
• ConsistsOf Relations: Remove both facet and resource from the same context
• IsRelatedTo Relations: Remove both source and target resources from the same context.

Propagation Constraints and Cascade Effects:

• When an instance is removed from a context, related instances may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet or ConsistsOf relation from a Resource; • Removing instances that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove instances.

IS-Manager:

• Can perform REMOVE operations on any instance in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any instance in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on instances accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on instances accessible in their current context
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService instance from a specific context
 EService service = publisher.read(EService.class, serviceUUID);
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFromContext(service, targetContextUUID, false);
 
 // Preview what would be affected by removing a ContactFacet from a context
 ContactFacet contact = publisher.read(ContactFacet.class, contactUUID);
 List<ERElement> preview = publisher.removeFromContext(contact, targetContextUUID, true);
 

Specified by:

removeFromContext in interface ResourceRegistryPublisher

Parameters:

er - The instance to remove from the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context from which the instance should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance or context is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFromCurrentContext

public List<org.gcube.informationsystem.model.reference.ERElement> removeFromCurrentContext(String type,
 UUID instanceUUID,
 Boolean dryRun)
                                                                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an ERElement instance from the current context. Corresponding REST API: POST /sharing/contexts/{type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing ERElement instance from the current context derived from the authorization token
• The ERElement (Resource or Facet) must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the ERElement itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method works with both Resource and Facet types.

HTTP Response Codes:

• 200 OK: ERElement successfully removed from current context (or dry-run completed)
• 404 Not Found: ERElement does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the ERElement and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present.

Input Processing:

• The type name must be a valid ERElement type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet)
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• ConsistsOf Relations: All ConsistsOf relations connecting Resources to Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When an ERElement is removed from a context, related elements may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation:

• When an ERElement is removed from a context, the ERElement is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Removing a required/mandatory Facet from a Resource; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related elements incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove ERElements.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any ERElement in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any ERElement in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on ERElements accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on ERElements accessible in their current context
• Operations are limited to ERElements they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService from the current context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFromCurrentContext("EService", serviceUUID, false);
 
 // Preview what would be affected by removing a StateFacet from the current context
 UUID stateFacetUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeFromCurrentContext("StateFacet", stateFacetUUID, true);
 

Specified by:

removeFromCurrentContext in interface ResourceRegistryPublisher

Parameters:

type - The exact type name of the ERElement to remove

instanceUUID - The UUID of the ERElement instance to remove from the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the ERElement itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the ERElement is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFromCurrentContext

public List<org.gcube.informationsystem.model.reference.ERElement> removeFromCurrentContext(org.gcube.informationsystem.model.reference.ERElement er,
 Boolean dryRun)
                                                                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an ERElement instance from the current context using a provided ERElement object. Corresponding REST API: POST /sharing/contexts/{type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing ERElement instance from the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided ERElement object
• The ERElement (Resource or Facet) must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the ERElement itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for both Resource and Facet types.

HTTP Response Codes:

• 200 OK: ERElement successfully removed from current context (or dry-run completed)
• 404 Not Found: ERElement does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the ERElement and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present.

Input Processing:

• The type name is automatically derived from the provided ERElement object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the ERElement's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• ConsistsOf Relations: All ConsistsOf relations connecting Resources to Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When an ERElement is removed from a context, related elements may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation:

• When an ERElement is removed from a context, the ERElement is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Removing a required/mandatory Facet from a Resource; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related elements incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove ERElements.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any ERElement in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any ERElement in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on ERElements accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on ERElements accessible in their current context
• Operations are limited to ERElements they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService instance from the current context
 EService service = publisher.read(EService.class, serviceUUID);
 List<ERElement> affected = publisher.removeFromCurrentContext(service, false);
 
 // Preview what would be affected by removing a StateFacet from the current context
 StateFacet facet = publisher.read(StateFacet.class, facetUUID);
 List<ERElement> preview = publisher.removeFromCurrentContext(facet, true);
 

Specified by:

removeFromCurrentContext in interface ResourceRegistryPublisher

Parameters:

er - The ERElement instance to remove from the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the ERElement itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the ERElement is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException

getElementContexts

public Map<UUID,String> getElementContexts(String type,
 UUID instanceUUID)
                                    throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Information System element is present in the Resource Registry. Corresponding REST API: GET /instances/{type-name}/{instance-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified element (Resource, Facet, ConsistsOf, or IsRelatedTo) is present
• The element must exist and be accessible to the user
• Returns a map where keys are context UUIDs and values are the full context paths
• No filtering, pagination, or metadata options are available
• Context information is determined by the element's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Element does not exist with the specified type and UUID
• 403 Forbidden: Element exists but is not accessible for context listing in the current authorization scope
• 401 Unauthorized: Invalid or missing authentication credentials.

Authorization Requirements:

• IS-Manager: Can retrieve context information for any element across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any element across the entire infrastructure
• Context-Manager: Can retrieve context information for elements accessible within their managed contexts
• Other Users: Can retrieve context information for elements accessible through their authorization token.

Response Format:

• Returns a Map where keys are context UUIDs (UUID) and values are full context paths (String)
• Empty map is returned if the element exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Element Context Rules:

• Resources: Present in all contexts that form the union of contexts of all their Facets
• Facets: Present in the contexts where they are explicitly available
• ConsistsOf Relations: Present in all contexts where their target Facets are present
• IsRelatedTo Relations: Present based on their specific context assignments.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get contexts for an EService by type and UUID
 UUID serviceUuid = UUID.fromString("48af15ad-7e56-4157-b624-71c98cea4f8f");
 Map<UUID, String> contexts = publisher.getElementContexts("EService", serviceUuid);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Specified by:

getElementContexts in interface ResourceRegistryPublisher

Parameters:

type - The exact type name of the Information System element (e.g., "EService", "ContactFacet")

instanceUUID - The unique identifier of the element whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the element is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If no element is found with the specified type and UUID

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

getElementContexts

public <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
Map<UUID,String> getElementContexts(ERElem er)
                             throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Information System element is present in the Resource Registry. Corresponding REST API: GET /instances/{type-name}/{instance-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified element object (Resource, Facet, ConsistsOf, or IsRelatedTo) is present
• The element's type and UUID are automatically extracted from the provided object
• The element must exist and be accessible to the user
• Returns a map where keys are context UUIDs and values are the full context paths
• No filtering, pagination, or metadata options are available
• Context information is determined by the element's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Element does not exist or is not accessible
• 403 Forbidden: Element exists but is not accessible for context listing in the current authorization scope
• 401 Unauthorized: Invalid or missing authentication credentials.

Authorization Requirements:

• IS-Manager: Can retrieve context information for any element across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any element across the entire infrastructure
• Context-Manager: Can retrieve context information for elements accessible within their managed contexts
• Other Users: Can retrieve context information for elements accessible through their authorization token.

Response Format:

• Returns a Map where keys are context UUIDs (UUID) and values are full context paths (String)
• Empty map is returned if the element exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Element Context Rules:

• Resources: Present in all contexts that form the union of contexts of all their Facets
• Facets: Present in the contexts where they are explicitly available
• ConsistsOf Relations: Present in all contexts where their target Facets are present
• IsRelatedTo Relations: Present based on their specific context assignments.

Type Safety:

• This method provides compile-time type safety by accepting any ERElement subtype
• The element's type is automatically determined from the object's class
• Supports all Information System element types including Resources, Facets, and Relations.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Assuming you have an EService instance
 EService service = ...; // Retrieved from previous operations
 
 // Get contexts for the service object
 Map<UUID, String> contexts = publisher.getElementContexts(service);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Specified by:

getElementContexts in interface ResourceRegistryPublisher

Type Parameters:

ERElem - The type of Information System element (Resource, Facet, ConsistsOf, or IsRelatedTo)

Parameters:

er - The Information System element whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the element is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the specified element does not exist or is not accessible

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

addResourceToContext

public List<org.gcube.informationsystem.model.reference.ERElement> addResourceToContext(String resourceType,
 UUID resourceUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Resource instance to a specific context. Corresponding REST API: PUT /instances/{resource-type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing Resource instance to the specified target context
• The Resource must already exist and be accessible in the context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Resource itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully added to context (or dry-run completed)
• 404 Not Found: Resource or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Resource to a context even if the Resource is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Resource to a context even if the Resource exists only in other contexts
• When false: Standard validation applies - Resource must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name must be a valid Resource type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Type name is case-sensitive and must match exactly.

Resource-Specific Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically included
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also added to the context.

Propagation Constraints and Cascade Effects:

• When a Resource is added to a context, all related Facets may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is added to a context, the Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Resource that violates cardinality constraints defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to add Resources.

IS-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService to a specific context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addResourceToContext("EService", serviceUUID, targetContextUUID, false);
 
 // Preview what would be affected by adding a HostingNode to a context
 UUID hostUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.addResourceToContext("HostingNode", hostUUID, targetContextUUID, true);
 

Specified by:

addResourceToContext in interface ResourceRegistryPublisher

Parameters:

resourceType - The exact type name of the Resource to add

resourceUUID - The UUID of the Resource instance to add to the context

contextUUID - The UUID of the target context where the Resource should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addResourceToContext

public <R extends org.gcube.informationsystem.model.reference.entities.Resource>
List<org.gcube.informationsystem.model.reference.ERElement> addResourceToContext(R resource,
 UUID contextUUID,
 Boolean dryRun)
                                                                          throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Resource instance to a specific context using a provided Resource object. Corresponding REST API: PUT /instances/{resource-type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing Resource instance to the specified target context
• The type and UUID are automatically extracted from the provided Resource object
• The Resource must already exist and be accessible in the context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Resource itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This method provides compile-time type safety for Resource types.

HTTP Response Codes:

• 200 OK: Resource successfully added to context (or dry-run completed)
• 404 Not Found: Resource or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Resource to a context even if the Resource is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Resource to a context even if the Resource exists only in other contexts
• When false: Standard validation applies - Resource must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name is automatically derived from the provided Resource object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Resource's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software).

Resource-Specific Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically included
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also added to the context.

Propagation Constraints and Cascade Effects:

• When a Resource is added to a context, all related Facets may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is added to a context, the Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Resource that violates cardinality constraints defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to add Resources.

IS-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService instance to a specific context
 EService service = new EService();
 service.setHeader(new Header(serviceUUID));
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addResourceToContext(service, targetContextUUID, false);
 
 // Preview what would be affected by adding a HostingNode to a context
 HostingNode host = publisher.read(HostingNode.class, hostUUID);
 List<ERElement> preview = publisher.addResourceToContext(host, targetContextUUID, true);
 

Specified by:

addResourceToContext in interface ResourceRegistryPublisher

Type Parameters:

R - The specific type of Resource to add

Parameters:

resource - The Resource instance to add to the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context where the Resource should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addResourceToCurrentContext

public List<org.gcube.informationsystem.model.reference.ERElement> addResourceToCurrentContext(String resourceType,
 UUID resourceUUID,
 Boolean dryRun)
                                                                                        throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Resource instance to the current context. Corresponding REST API: PUT /instances/{resource-type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing Resource instance to the current context derived from the authorization token
• The Resource must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Resource itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully added to current context (or dry-run completed)
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Resource to a context even if the Resource is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Resource to a context even if the Resource exists only in other contexts
• When false: Standard validation applies - Resource must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name must be a valid Resource type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Resource-Specific Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically included
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also added to the context.

Propagation Constraints and Cascade Effects:

• When a Resource is added to a context, all related Facets may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is added to a context, the Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Resource that violates cardinality constraints defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add Resources.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService to the current context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addResourceToCurrentContext("EService", serviceUUID, false);
 
 // Preview what would be affected by adding a HostingNode to the current context
 UUID hostUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.addResourceToCurrentContext("HostingNode", hostUUID, true);
 

Specified by:

addResourceToCurrentContext in interface ResourceRegistryPublisher

Parameters:

resourceType - The exact type name of the Resource to add

resourceUUID - The UUID of the Resource instance to add to the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addResourceToCurrentContext

public <R extends org.gcube.informationsystem.model.reference.entities.Resource>
List<org.gcube.informationsystem.model.reference.ERElement> addResourceToCurrentContext(R resource,
 Boolean dryRun)
                                                                                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Resource instance to the current context using a provided Resource object. Corresponding REST API: PUT /instances/{resource-type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing Resource instance to the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided Resource object
• The Resource must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Resource itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for Resource types.

HTTP Response Codes:

• 200 OK: Resource successfully added to current context (or dry-run completed)
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Resource to a context even if the Resource is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Resource to a context even if the Resource exists only in other contexts
• When false: Standard validation applies - Resource must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name is automatically derived from the provided Resource object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Resource's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Resource-Specific Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically included
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also added to the context.

Propagation Constraints and Cascade Effects:

• When a Resource is added to a context, all related Facets may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is added to a context, the Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Resource that violates cardinality constraints defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add Resources.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService instance to the current context
 EService service = new EService();
 service.setHeader(new Header(serviceUUID));
 List<ERElement> affected = publisher.addResourceToCurrentContext(service, false);
 
 // Preview what would be affected by adding a HostingNode to the current context
 HostingNode host = publisher.read(HostingNode.class, hostUUID);
 List<ERElement> preview = publisher.addResourceToCurrentContext(host, true);
 

Specified by:

addResourceToCurrentContext in interface ResourceRegistryPublisher

Type Parameters:

R - The specific type of Resource to add

Parameters:

resource - The Resource instance to add to the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

removeResourceFromContext

public List<org.gcube.informationsystem.model.reference.ERElement> removeResourceFromContext(String resourceType,
 UUID resourceUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                                      throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Resource instance from a specific context. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{resource-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Resource instance from the specified target context
• The Resource must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Resource itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully removed from context (or dry-run completed)
• 404 Not Found: Resource or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name must be a valid Resource type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Type name is case-sensitive and must match exactly.

Resource-Specific Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically removed if they become orphaned
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Resource is removed from a context, all related Facets may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is removed from a context, the Resource is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove Resources.

IS-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService from a specific context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeResourceFromContext("EService", serviceUUID, targetContextUUID, false);
 
 // Preview what would be affected by removing a HostingNode from a context
 UUID hostUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeResourceFromContext("HostingNode", hostUUID, targetContextUUID, true);
 

Specified by:

removeResourceFromContext in interface ResourceRegistryPublisher

Parameters:

resourceType - The exact type name of the Resource to remove

resourceUUID - The UUID of the Resource instance to remove from the context

contextUUID - The UUID of the target context from which the Resource should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeResourceFromContext

public <R extends org.gcube.informationsystem.model.reference.entities.Resource>
List<org.gcube.informationsystem.model.reference.ERElement> removeResourceFromContext(R resource,
 UUID contextUUID,
 Boolean dryRun)
                                                                               throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Resource instance from a specific context using a provided Resource object. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{resource-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Resource instance from the specified target context
• The Resource must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Resource itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method accepts a Resource instance object directly, which provides type safety and convenience
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully removed from context (or dry-run completed)
• 404 Not Found: Resource or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The Resource object must contain a valid UUID in its header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• The actual type is determined from the Resource object's class.

Resource-Specific Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically removed if they become orphaned
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Resource is removed from a context, all related Facets may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is removed from a context, the Resource is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove Resources.

IS-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService instance from a specific context
 EService service = publisher.read(EService.class, serviceUUID);
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeResourceFromContext(service, targetContextUUID, false);
 
 // Preview what would be affected by removing a HostingNode from a context
 HostingNode host = publisher.read(HostingNode.class, hostUUID);
 List<ERElement> preview = publisher.removeResourceFromContext(host, targetContextUUID, true);
 

Specified by:

removeResourceFromContext in interface ResourceRegistryPublisher

Type Parameters:

R - The type of Resource (EService, HostingNode, Software, etc.)

Parameters:

resource - The Resource instance to remove from the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context from which the Resource should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeResourceFromCurrentContext

public List<org.gcube.informationsystem.model.reference.ERElement> removeResourceFromCurrentContext(String resourceType,
 UUID resourceUUID,
 Boolean dryRun)
                                                                                             throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Resource instance from the current context. Corresponding REST API: POST /sharing/contexts/{resource-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Resource instance from the current context derived from the authorization token
• The Resource must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Resource itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully removed from current context (or dry-run completed)
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name must be a valid Resource type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Resource-Specific Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically removed if they become orphaned
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Resource is removed from a context, all related Facets may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is removed from a context, the Resource is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove Resources.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService from the current context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeResourceFromCurrentContext("EService", serviceUUID, false);
 
 // Preview what would be affected by removing a HostingNode from the current context
 UUID hostUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeResourceFromCurrentContext("HostingNode", hostUUID, true);
 

Specified by:

removeResourceFromCurrentContext in interface ResourceRegistryPublisher

Parameters:

resourceType - The exact type name of the Resource to remove

resourceUUID - The UUID of the Resource instance to remove from the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeResourceFromCurrentContext

public <R extends org.gcube.informationsystem.model.reference.entities.Resource>
List<org.gcube.informationsystem.model.reference.ERElement> removeResourceFromCurrentContext(R resource,
 Boolean dryRun)
                                                                                      throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Resource instance from the current context using a provided Resource object. Corresponding REST API: POST /sharing/contexts/{resource-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Resource instance from the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided Resource object
• The Resource must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Resource itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for Resource types.

HTTP Response Codes:

• 200 OK: Resource successfully removed from current context (or dry-run completed)
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.

Input Processing:

• The type name is automatically derived from the provided Resource object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Resource's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Resource-Specific Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically removed if they become orphaned
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Resource is removed from a context, all related Facets may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is removed from a context, the Resource is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove Resources.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService instance from the current context
 EService service = publisher.read(EService.class, serviceUUID);
 List<ERElement> affected = publisher.removeResourceFromCurrentContext(service, false);
 
 // Preview what would be affected by removing a HostingNode from the current context
 HostingNode host = publisher.read(HostingNode.class, hostUUID);
 List<ERElement> preview = publisher.removeResourceFromCurrentContext(host, true);
 

Specified by:

removeResourceFromCurrentContext in interface ResourceRegistryPublisher

Type Parameters:

R - The specific type of Resource to remove

Parameters:

resource - The Resource instance to remove from the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

getResourceContexts

public Map<UUID,String> getResourceContexts(String resourceType,
 UUID resourceUUID)
                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Resource is present in the Resource Registry. Corresponding REST API: GET /instances/{resource-type-name}/{resource-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified Resource is present
• The Resource must exist and be accessible to the user
• Returns a map where keys are context UUIDs and values are the full context paths
• No filtering, pagination, or metadata options are available
• Context information is determined by the Resource's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Resource does not exist with the specified type and UUID
• 403 Forbidden: Resource exists but is not accessible for context listing in the current authorization scope
• 401 Unauthorized: Invalid or missing authentication credentials.

Authorization Requirements:

• IS-Manager: Can retrieve context information for any Resource across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any Resource across the entire infrastructure
• Context-Manager: Can retrieve context information for Resources accessible within their managed contexts
• Other Users: Can retrieve context information for Resources accessible through their authorization token.

Response Format:

• Returns a Map where keys are context UUIDs (UUID) and values are full context paths (String)
• Empty map is returned if the Resource exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Resource Context Rules:

• Resources: Present in all contexts that form the union of contexts of all their Facets
• A Resource is present in a context if at least one of its associated Facets (via ConsistsOf relations) is present in that context
• If a Resource has no Facets, it may still be present in contexts based on direct context assignments.

Type Safety:

• This method is specifically designed for Resource types and provides compile-time type safety
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software, Dataset).

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get contexts for an EService by type and UUID
 UUID serviceUuid = UUID.fromString("48af15ad-7e56-4157-b624-71c98cea4f8f");
 Map<UUID, String> contexts = publisher.getResourceContexts("EService", serviceUuid);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Specified by:

getResourceContexts in interface ResourceRegistryPublisher

Parameters:

resourceType - The exact type name of the Resource (e.g., "EService", "HostingNode")

resourceUUID - The unique identifier of the Resource whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the Resource is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If no Resource is found with the specified type and UUID

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

getResourceContexts

public <R extends org.gcube.informationsystem.model.reference.entities.Resource>
Map<UUID,String> getResourceContexts(R resource)
                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Resource is present in the Resource Registry. Corresponding REST API: GET /instances/{resource-type-name}/{resource-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified Resource object is present
• The Resource's type and UUID are automatically extracted from the provided object
• The Resource must exist and be accessible to the user
• Returns a map where keys are context UUIDs and values are the full context paths
• No filtering, pagination, or metadata options are available
• Context information is determined by the Resource's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: Resource exists but is not accessible for context listing in the current authorization scope
• 401 Unauthorized: Invalid or missing authentication credentials.

Authorization Requirements:

• IS-Manager: Can retrieve context information for any Resource across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any Resource across the entire infrastructure
• Context-Manager: Can retrieve context information for Resources accessible within their managed contexts
• Other Users: Can retrieve context information for Resources accessible through their authorization token.

Response Format:

• Returns a Map where keys are context UUIDs (UUID) and values are full context paths (String)
• Empty map is returned if the Resource exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Resource Context Rules:

• Resources: Present in all contexts that form the union of contexts of all their Facets
• A Resource is present in a context if at least one of its associated Facets (via ConsistsOf relations) is present in that context
• If a Resource has no Facets, it may still be present in contexts based on direct context assignments.

Type Safety:

• This method provides compile-time type safety by accepting any Resource subtype
• The Resource's type is automatically determined from the object's class
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software, Dataset).

Object-based Operation:

• This method accepts a Resource instance object directly, which provides convenience and type safety
• The Resource object must contain a valid UUID in its header metadata
• The type is automatically inferred from the object's runtime class.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Assuming you have an EService instance
 EService service = ...; // Retrieved from previous operations
 
 // Get contexts for the service object
 Map<UUID, String> contexts = publisher.getResourceContexts(service);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Specified by:

getResourceContexts in interface ResourceRegistryPublisher

Type Parameters:

R - The type of Resource (EService, HostingNode, Software, etc.)

Parameters:

resource - The Resource instance whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the Resource is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the specified Resource does not exist or is not accessible

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

addFacetToContext

public List<org.gcube.informationsystem.model.reference.ERElement> addFacetToContext(String facetType,
 UUID facetUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Facet instance to a specific context using type name and UUID. Corresponding REST API: PUT /instances/{facet-type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing Facet instance to the specified context
• The Facet must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the target context
• Returns the list of affected elements (the Facet itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them.

HTTP Response Codes:

• 200 OK: Facet successfully added to specified context (or dry-run completed)
• 404 Not Found: Facet or context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the target context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Facet to a context even if the Facet is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Facet to a context even if the Facet exists only in other contexts
• When false: Standard validation applies - Facet must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Facet and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet is present in all contexts that are part of the union of contexts of all Resources that use it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their source Resources and target Facets are both present.

Input Processing:

• The facetType parameter must be a valid Facet type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all Facet types and their specializations (e.g., StateFacet, SoftwareFacet, AccessPointFacet).

Target Context:

• The contextUUID parameter specifies the exact context where the Facet should be added
• The user must have appropriate permissions in this context
• The context must exist and be accessible.

Facet-Specific Context Propagation Rules:

• Facets: When added to a context, no automatic propagation occurs as Facets do not have dependent elements
• Related Resources: Resources that use this Facet via ConsistsOf relations are NOT automatically added to the context
• Consistency Check: The Facet must be associated with Resources that are already present in the target context
• Important: Adding a Facet to a context where its associated Resources are not present may create inconsistencies.

Propagation Constraints and Cascade Effects:

• When a Facet is added to a context, there are typically no cascade effects since Facets are leaf elements
• However, the schema may define specific constraints for certain Facet types that could trigger validation
• The response includes the Facet instance and any validation-related information.

Schema Validation for Facet:

• When a Facet is added to a context, the Facet is automatically validated against its schema definition
• If the Facet is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Facet that violates property constraints defined in the schema; • Operations that make the Facet incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Facet type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Facet type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the target context where they want to add Facets.

IS-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Facets accessible in contexts where they have Context-Manager role
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Facets accessible in contexts where they have appropriate permissions
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Facets they have access to in their authorized contexts
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add a StateFacet instance to a specific context
 UUID stateFacetUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 UUID targetContextUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 List<ERElement> affected = publisher.addFacetToContext("StateFacet", stateFacetUUID, targetContextUUID, false);
 
 // Preview what would be affected by adding an AccessPointFacet to a specific context
 UUID accessPointUUID = UUID.fromString("11223344-5566-7788-9900-aabbccddeeff");
 UUID contextUUID = UUID.fromString("ffeeddcc-bbaa-0099-8877-665544332211");
 List<ERElement> preview = publisher.addFacetToContext("AccessPointFacet", accessPointUUID, contextUUID, true);
 

Specified by:

addFacetToContext in interface ResourceRegistryPublisher

Parameters:

facetType - The type name of the Facet to add (must be a valid Facet type)

facetUUID - The UUID of the Facet instance to add to the specified context

contextUUID - The UUID of the target context where the Facet should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addFacetToContext

public <F extends org.gcube.informationsystem.model.reference.entities.Facet>
List<org.gcube.informationsystem.model.reference.ERElement> addFacetToContext(F facet,
 UUID contextUUID,
 Boolean dryRun)
                                                                       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Facet instance to a specific context using a provided Facet object. Corresponding REST API: PUT /instances/{facet-type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing Facet instance to the specified context
• The type and UUID are automatically extracted from the provided Facet object
• The Facet must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the target context
• Returns the list of affected elements (the Facet itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This method provides compile-time type safety for Facet types.

HTTP Response Codes:

• 200 OK: Facet successfully added to specified context (or dry-run completed)
• 404 Not Found: Facet or context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the target context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Facet to a context even if the Facet is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Facet to a context even if the Facet exists only in other contexts
• When false: Standard validation applies - Facet must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Facet and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet is present in all contexts that are part of the union of contexts of all Resources that use it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their source Resources and target Facets are both present.

Input Processing:

• The type name is automatically derived from the provided Facet object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Facet's header
• Supports all Facet types and their specializations (e.g., StateFacet, SoftwareFacet, AccessPointFacet).

Target Context:

• The contextUUID parameter specifies the exact context where the Facet should be added
• The user must have appropriate permissions in this context
• The context must exist and be accessible.

Facet-Specific Context Propagation Rules:

• Facets: When added to a context, no automatic propagation occurs as Facets do not have dependent elements
• Related Resources: Resources that use this Facet via ConsistsOf relations are NOT automatically added to the context
• Consistency Check: The Facet must be associated with Resources that are already present in the target context
• Important: Adding a Facet to a context where its associated Resources are not present may create inconsistencies.

Propagation Constraints and Cascade Effects:

• When a Facet is added to a context, there are typically no cascade effects since Facets are leaf elements
• However, the schema may define specific constraints for certain Facet types that could trigger validation
• The response includes the Facet instance and any validation-related information.

Schema Validation for Facet:

• When a Facet is added to a context, the Facet is automatically validated against its schema definition
• If the Facet is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Facet that violates property constraints defined in the schema; • Operations that make the Facet incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Facet type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Facet type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the target context where they want to add Facets.

IS-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Facets accessible in contexts where they have Context-Manager role
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Facets accessible in contexts where they have appropriate permissions
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Facets they have access to in their authorized contexts
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add a StateFacet instance to a specific context
 StateFacet facet = new StateFacet();
 facet.setHeader(new Header(facetUUID));
 UUID targetContextUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 List<ERElement> affected = publisher.addFacetToContext(facet, targetContextUUID, false);
 
 // Preview what would be affected by adding an AccessPointFacet to a specific context
 AccessPointFacet accessPoint = publisher.read(AccessPointFacet.class, accessPointUUID);
 UUID contextUUID = UUID.fromString("ffeeddcc-bbaa-0099-8877-665544332211");
 List<ERElement> preview = publisher.addFacetToContext(accessPoint, contextUUID, true);
 

Specified by:

addFacetToContext in interface ResourceRegistryPublisher

Type Parameters:

F - The specific type of Facet to add

Parameters:

facet - The Facet instance to add to the specified context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context where the Facet should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addFacetToCurrentContext

public List<org.gcube.informationsystem.model.reference.ERElement> addFacetToCurrentContext(String facetType,
 UUID facetUUID,
 Boolean dryRun)
                                                                                     throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Facet instance to the current context using type name and UUID. Corresponding REST API: PUT /instances/{facet-type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing Facet instance to the current context derived from the authorization token
• The Facet must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Facet itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID.

HTTP Response Codes:

• 200 OK: Facet successfully added to current context (or dry-run completed)
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Facet to a context even if the Facet is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Facet to a context even if the Facet exists only in other contexts
• When false: Standard validation applies - Facet must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Facet and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet is present in all contexts that are part of the union of contexts of all Resources that use it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their source Resources and target Facets are both present.

Input Processing:

• The facetType parameter must be a valid Facet type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all Facet types and their specializations (e.g., StateFacet, SoftwareFacet, AccessPointFacet).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Facet-Specific Context Propagation Rules:

• Facets: When added to a context, no automatic propagation occurs as Facets do not have dependent elements
• Related Resources: Resources that use this Facet via ConsistsOf relations are NOT automatically added to the context
• Consistency Check: The Facet must be associated with Resources that are already present in the target context
• Important: Adding a Facet to a context where its associated Resources are not present may create inconsistencies.

Propagation Constraints and Cascade Effects:

• When a Facet is added to a context, there are typically no cascade effects since Facets are leaf elements
• However, the schema may define specific constraints for certain Facet types that could trigger validation
• The response includes the Facet instance and any validation-related information.

Schema Validation for Facet:

• When a Facet is added to a context, the Facet is automatically validated against its schema definition
• If the Facet is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Facet that violates property constraints defined in the schema; • Operations that make the Facet incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Facet type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Facet type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add Facets.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Facets accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Facets accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add a StateFacet instance to the current context
 UUID stateFacetUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 List<ERElement> affected = publisher.addFacetToCurrentContext("StateFacet", stateFacetUUID, false);
 
 // Preview what would be affected by adding an AccessPointFacet to the current context
 UUID accessPointUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 List<ERElement> preview = publisher.addFacetToCurrentContext("AccessPointFacet", accessPointUUID, true);
 

Specified by:

addFacetToCurrentContext in interface ResourceRegistryPublisher

Parameters:

facetType - The type name of the Facet to add (must be a valid Facet type)

facetUUID - The UUID of the Facet instance to add to the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addFacetToCurrentContext

public <F extends org.gcube.informationsystem.model.reference.entities.Facet>
List<org.gcube.informationsystem.model.reference.ERElement> addFacetToCurrentContext(F facet,
 Boolean dryRun)
                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Facet instance to the current context using a provided Facet object. Corresponding REST API: PUT /instances/{facet-type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing Facet instance to the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided Facet object
• The Facet must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Facet itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for Facet types.

HTTP Response Codes:

• 200 OK: Facet successfully added to current context (or dry-run completed)
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Facet to a context even if the Facet is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Facet to a context even if the Facet exists only in other contexts
• When false: Standard validation applies - Facet must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Facet and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet is present in all contexts that are part of the union of contexts of all Resources that use it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their source Resources and target Facets are both present.

Input Processing:

• The type name is automatically derived from the provided Facet object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Facet's header
• Supports all Facet types and their specializations (e.g., StateFacet, SoftwareFacet, AccessPointFacet).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Facet-Specific Context Propagation Rules:

• Facets: When added to a context, no automatic propagation occurs as Facets do not have dependent elements
• Related Resources: Resources that use this Facet via ConsistsOf relations are NOT automatically added to the context
• Consistency Check: The Facet must be associated with Resources that are already present in the target context
• Important: Adding a Facet to a context where its associated Resources are not present may create inconsistencies.

Propagation Constraints and Cascade Effects:

• When a Facet is added to a context, there are typically no cascade effects since Facets are leaf elements
• However, the schema may define specific constraints for certain Facet types that could trigger validation
• The response includes the Facet instance and any validation-related information.

Schema Validation for Facet:

• When a Facet is added to a context, the Facet is automatically validated against its schema definition
• If the Facet is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Facet that violates property constraints defined in the schema; • Operations that make the Facet incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Facet type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Facet type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add Facets.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Facets accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Facets accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add a StateFacet instance to the current context
 StateFacet facet = new StateFacet();
 facet.setHeader(new Header(facetUUID));
 List<ERElement> affected = publisher.addFacetToCurrentContext(facet, false);
 
 // Preview what would be affected by adding an AccessPointFacet to the current context
 AccessPointFacet accessPoint = publisher.read(AccessPointFacet.class, accessPointUUID);
 List<ERElement> preview = publisher.addFacetToCurrentContext(accessPoint, true);
 

Specified by:

addFacetToCurrentContext in interface ResourceRegistryPublisher

Type Parameters:

F - The specific type of Facet to add

Parameters:

facet - The Facet instance to add to the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

removeFacetFromContext

public List<org.gcube.informationsystem.model.reference.ERElement> removeFacetFromContext(String facetType,
 UUID facetUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Facet instance from a specific context. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{facet-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Facet instance from the specified target context
• The Facet must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Facet itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method is specifically designed for Facet types and provides type safety.

HTTP Response Codes:

• 200 OK: Facet successfully removed from context (or dry-run completed)
• 404 Not Found: Facet or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, parent Resources, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Facet and its related elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets.

Input Processing:

• The type name must be a valid Facet type in the Information System model
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet)
• Type name is case-sensitive and must match exactly.

Facet-Specific Context Propagation Rules:

• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• Associated Resources: Parent Resources connected to the Facet via ConsistsOf relations are automatically affected based on propagation constraints
• ConsistsOf Relations: All ConsistsOf relations connecting parent Resources to this Facet are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Facet is removed from a context, related Resources may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Facets and ConsistsOf Relations:

• When a Facet is removed from a context, the parent Resources are automatically validated against their schema definitions
• If any parent Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet from a Resource; • Removing Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make parent Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove Facets.

IS-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove a StateFacet from a specific context with actual changes
 UUID stateFacetUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFacetFromContext("StateFacet", stateFacetUUID, targetContextUUID, false);
 
 // Preview what would be affected by removing an AccessPointFacet from a context
 UUID accessPointUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeFacetFromContext("AccessPointFacet", accessPointUUID, targetContextUUID, true);
 

Specified by:

removeFacetFromContext in interface ResourceRegistryPublisher

Parameters:

facetType - The exact type name of the Facet to remove

facetUUID - The UUID of the Facet instance to remove from the context

contextUUID - The UUID of the target context from which the Facet should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFacetFromContext

public <F extends org.gcube.informationsystem.model.reference.entities.Facet>
List<org.gcube.informationsystem.model.reference.ERElement> removeFacetFromContext(F facet,
 UUID contextUUID,
 Boolean dryRun)
                                                                            throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Facet instance from a specific context using a provided Facet object. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{facet-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Facet instance from the specified target context
• The Facet must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Facet itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method accepts a Facet instance object directly, which provides type safety and convenience
• This method is specifically designed for Facet types and provides type safety.

HTTP Response Codes:

• 200 OK: Facet successfully removed from context (or dry-run completed)
• 404 Not Found: Facet or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, parent Resources, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Facet and its related elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets.

Input Processing:

• The Facet object must contain a valid UUID in its header
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet)
• The actual type is determined from the Facet object's class.

Facet-Specific Context Propagation Rules:

• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• Associated Resources: Parent Resources connected to the Facet via ConsistsOf relations are automatically affected based on propagation constraints
• ConsistsOf Relations: All ConsistsOf relations connecting parent Resources to this Facet are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Facet is removed from a context, related Resources may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Facets and ConsistsOf Relations:

• When a Facet is removed from a context, the parent Resources are automatically validated against their schema definitions
• If any parent Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet from a Resource; • Removing Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make parent Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove Facets.

IS-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove a StateFacet instance from a specific context
 StateFacet facet = publisher.read(StateFacet.class, facetUUID);
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFacetFromContext(facet, targetContextUUID, false);
 
 // Preview what would be affected by removing an AccessPointFacet from a context
 AccessPointFacet accessPoint = publisher.read(AccessPointFacet.class, accessPointUUID);
 List<ERElement> preview = publisher.removeFacetFromContext(accessPoint, targetContextUUID, true);
 

Specified by:

removeFacetFromContext in interface ResourceRegistryPublisher

Type Parameters:

F - The type of Facet (StateFacet, ContactFacet, AccessPointFacet, etc.)

Parameters:

facet - The Facet instance to remove from the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context from which the Facet should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFacetFromCurrentContext

public List<org.gcube.informationsystem.model.reference.ERElement> removeFacetFromCurrentContext(String facetType,
 UUID facetUUID,
 Boolean dryRun)
                                                                                          throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Facet instance from the current context. Corresponding REST API: POST /sharing/contexts/{facet-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Facet instance from the current context derived from the authorization token
• The Facet must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Facet itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method is specifically designed for Facet types and provides type safety.

HTTP Response Codes:

• 200 OK: Facet successfully removed from current context (or dry-run completed)
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, parent Resources, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Facet and its related elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets.

Input Processing:

• The type name must be a valid Facet type in the Information System model
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet)
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Facet-Specific Context Propagation Rules:

• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• Associated Resources: Parent Resources connected to the Facet via ConsistsOf relations are automatically affected based on propagation constraints
• ConsistsOf Relations: All ConsistsOf relations connecting parent Resources to this Facet are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Facet is removed from a context, related Resources may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Facets and ConsistsOf Relations:

• When a Facet is removed from a context, the parent Resources are automatically validated against their schema definitions
• If any parent Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet from a Resource; • Removing Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make parent Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove Facets.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove a StateFacet from the current context with actual changes
 UUID stateFacetUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFacetFromCurrentContext("StateFacet", stateFacetUUID, false);
 
 // Preview what would be affected by removing an AccessPointFacet from the current context
 UUID accessPointUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeFacetFromCurrentContext("AccessPointFacet", accessPointUUID, true);
 

Specified by:

removeFacetFromCurrentContext in interface ResourceRegistryPublisher

Parameters:

facetType - The exact type name of the Facet to remove

facetUUID - The UUID of the Facet instance to remove from the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFacetFromCurrentContext

public <F extends org.gcube.informationsystem.model.reference.entities.Facet>
List<org.gcube.informationsystem.model.reference.ERElement> removeFacetFromCurrentContext(F facet,
 Boolean dryRun)
                                                                                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Facet instance from the current context using a provided Facet object. Corresponding REST API: POST /sharing/contexts/{facet-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Facet instance from the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided Facet object
• The Facet must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Facet itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for Facet types.

HTTP Response Codes:

• 200 OK: Facet successfully removed from current context (or dry-run completed)
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.setIncludeMeta(true)
• Values: true (includes metadata with role-based filtering) | false (basic information only)
• Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
• Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.

allMeta (configurable via client configuration):

• Whether to include metadata for all nested instances (ConsistsOf relations, parent Resources, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.setAllMeta(true)
• Values: true (complete metadata) | false (main instance only, more readable)
• Purpose: When false, produces more human-readable responses with less JSON to process
• Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.

includeContexts (configurable via client configuration):

• Whether to include the list of contexts where the Facet and its related elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets.

Input Processing:

• The type name is automatically derived from the provided Facet object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Facet's header
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Facet-Specific Context Propagation Rules:

• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• Associated Resources: Parent Resources connected to the Facet via ConsistsOf relations are automatically affected based on propagation constraints
• ConsistsOf Relations: All ConsistsOf relations connecting parent Resources to this Facet are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Facet is removed from a context, related Resources may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Facets and ConsistsOf Relations:

• When a Facet is removed from a context, the parent Resources are automatically validated against their schema definitions
• If any parent Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet from a Resource; • Removing Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make parent Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove Facets.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove a StateFacet instance from the current context
 StateFacet facet = publisher.read(StateFacet.class, facetUUID);
 List<ERElement> affected = publisher.removeFacetFromCurrentContext(facet, false);
 
 // Preview what would be affected by removing an AccessPointFacet from the current context
 AccessPointFacet accessPoint = publisher.read(AccessPointFacet.class, accessPointUUID);
 List<ERElement> preview = publisher.removeFacetFromCurrentContext(accessPoint, true);
 

Specified by:

removeFacetFromCurrentContext in interface ResourceRegistryPublisher

Type Parameters:

F - The specific type of Facet to remove

Parameters:

facet - The Facet instance to remove from the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

getFacetContexts

public Map<UUID,String> getFacetContexts(String facetType,
 UUID facetUUID)
                                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Facet is present in the Resource Registry. Corresponding REST API: GET /instances/{facet-type-name}/{facet-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified Facet is present
• The Facet must exist and be accessible to the user
• Returns a map where keys are context UUIDs and values are the full context paths
• No filtering, pagination, or metadata options are available
• Context information is determined by the Facet's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Facet does not exist with the specified type and UUID
• 403 Forbidden: Facet exists but is not accessible for context listing in the current authorization scope
• 401 Unauthorized: Invalid or missing authentication credentials.

Authorization Requirements:

• IS-Manager: Can retrieve context information for any Facet across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any Facet across the entire infrastructure
• Context-Manager: Can retrieve context information for Facets accessible within their managed contexts
• Other Users: Can retrieve context information for Facets accessible through their authorization token.

Response Format:

• Returns a Map where keys are context UUIDs (UUID) and values are full context paths (String)
• Empty map is returned if the Facet exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Facet Context Rules:

• Facets: Present in the contexts where they are explicitly available
• A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Facets are present in contexts based on their direct context assignments and their association with Resources.

Type Safety:

• This method is specifically designed for Facet types and provides compile-time type safety
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet, SoftwareFacet).

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get contexts for a ContactFacet by type and UUID
 UUID contactUuid = UUID.fromString("4023d5b2-8601-47a5-83ef-49ffcbfc7d86");
 Map<UUID, String> contexts = publisher.getFacetContexts("ContactFacet", contactUuid);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Specified by:

getFacetContexts in interface ResourceRegistryPublisher

Parameters:

facetType - The exact type name of the Facet (e.g., "ContactFacet", "StateFacet")

facetUUID - The unique identifier of the Facet whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the Facet is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If no Facet is found with the specified type and UUID

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

getFacetContexts

public <F extends org.gcube.informationsystem.model.reference.entities.Facet>
Map<UUID,String> getFacetContexts(F facet)
                           throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Facet is present in the Resource Registry. Corresponding REST API: GET /instances/{facet-type-name}/{facet-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified Facet object is present
• The Facet's type and UUID are automatically extracted from the provided object
• The Facet must exist and be accessible to the user
• Returns a map where keys are context UUIDs and values are the full context paths
• No filtering, pagination, or metadata options are available
• Context information is determined by the Facet's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: Facet exists but is not accessible for context listing in the current authorization scope
• 401 Unauthorized: Invalid or missing authentication credentials.

Authorization Requirements:

• IS-Manager: Can retrieve context information for any Facet across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any Facet across the entire infrastructure
• Context-Manager: Can retrieve context information for Facets accessible within their managed contexts
• Other Users: Can retrieve context information for Facets accessible through their authorization token.

Response Format:

• Returns a Map where keys are context UUIDs (UUID) and values are full context paths (String)
• Empty map is returned if the Facet exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Facet Context Rules:

• Facets: Present in the contexts where they are explicitly available
• A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Facets are present in contexts based on their direct context assignments and their association with Resources.

Type Safety:

• This method provides compile-time type safety by accepting any Facet subtype
• The Facet's type is automatically determined from the object's class
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet, SoftwareFacet).

Object-based Operation:

• This method accepts a Facet instance object directly, which provides convenience and type safety
• The Facet object must contain a valid UUID in its header metadata
• The type is automatically inferred from the object's runtime class.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Assuming you have a ContactFacet instance
 ContactFacet contact = ...; // Retrieved from previous operations
 
 // Get contexts for the facet object
 Map<UUID, String> contexts = publisher.getFacetContexts(contact);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Specified by:

getFacetContexts in interface ResourceRegistryPublisher

Type Parameters:

F - The type of Facet (ContactFacet, StateFacet, AccessPointFacet, etc.)

Parameters:

facet - The Facet instance whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the Facet is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the specified Facet does not exist or is not accessible

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval