Thread-safe bridge between the REST API layer and MITK DataStorage. More...

#include <mitkDataStorageBridge.h>

Classes
struct	CreateNodeResult
	Result of a node creation operation. More...

struct	DeleteResult
	Result of a node deletion operation. More...

struct	GetNodeDataResult
	Result of a GetNodeData operation. More...

struct	NodeQueryResult
	Result of a node query with pagination metadata. More...

struct	ReplacePropertiesResult
	Result of a ReplaceNodeProperties operation. More...

Public Types
enum class	OperationStatus { Success , NodeNotFound , PropertyNotFound , InvalidInput , InternalError }
	Status codes for mutation operations. More...

using	Json = nlohmann::json

Public Member Functions
	DataStorageBridge ()

	~DataStorageBridge ()

	DataStorageBridge (const DataStorageBridge &)=delete

DataStorageBridge &	operator= (const DataStorageBridge &)=delete

	DataStorageBridge (DataStorageBridge &&)=delete

DataStorageBridge &	operator= (DataStorageBridge &&)=delete

void	SetDispatcher (StorageThreadDispatcherBase *dispatcher)
	Set the dispatcher for thread-safe DataStorage operations. More...

void	SetDataStorage (DataStorage *dataStorage)
	Set the DataStorage to operate on. More...

DataStorage::Pointer	GetDataStorage () const
	Get the current DataStorage. More...

bool	HasDataStorage () const
	Check if a DataStorage is connected. More...

std::string	GetNodeUid (DataNode *node) const
	Get the UID for a DataNode. More...

NodeQueryResult	GetNodes (const NodeQueryParams &params) const
	Get nodes with full query parameter support. More...

std::optional< Json >	GetNode (const std::string &uid) const
	Get a single node by UID. More...

CreateNodeResult	CreateNode (const Json &nodeData, const std::optional< std::string > &parentUid=std::nullopt)
	Create a new node. More...

bool	UpdateNode (const std::string &uid, const Json &updates)
	Update a node. More...

DeleteResult	DeleteNode (const std::string &uid, bool recursive=false)
	Delete a node. More...

GetNodeDataResult	GetNodeData (const std::string &uid) const
	Get a clone of the node's data for thread-safe processing. More...

DataNode::ConstPointer	FindDataNode (const std::string &uid) const
	Look up a DataNode by UID. More...

OperationStatus	SetNodeData (const std::string &uid, BaseData *data)
	Set or replace the data on a node. More...

std::optional< Json >	GetNodeProperties (const std::string &uid, const PropertyQueryParams &params={}) const
	Get properties of a node with scope filtering. More...

std::optional< Json >	GetNodeProperty (const std::string &uid, const std::string &key, const PropertyQueryParams &params={}) const
	Get a single property of a node. More...

OperationStatus	SetNodeProperty (const std::string &uid, const std::string &key, const Json &value, const PropertyQueryParams &params)
	Set a single property on a node. More...

OperationStatus	DeleteNodeProperty (const std::string &uid, const std::string &key, const PropertyQueryParams &params)
	Delete a property from a node. More...

ReplacePropertiesResult	ReplaceNodeProperties (const std::string &uid, const Json &properties, const PropertyQueryParams &params)
	Replace all properties on a node (PUT semantics). More...

std::optional< Json >	GetNodeAvailableContexts (const std::string &uid) const
	Get available property contexts for a node. More...

Static Public Attributes
static constexpr const char *	INTERNAL_PROPERTY_PREFIX
	Prefix for internal REST API properties (filtered from responses, protected from modification). More...

static constexpr const char *	MODIFIED_PROPERTY_KEY
	Property key for tracking if a node was modified via the REST API. More...

static constexpr const char *	LAST_MODIFICATION_PROPERTY_KEY
	Property key for tracking the last modification operation (string property). More...

Detailed Description

Thread-safe bridge between the REST API layer and MITK DataStorage.

This class abstracts between the concrete REST/HTTP implementation and MITK-specific handling of requests, translating between DataStorage content and REST message content (as JSON).

Provides:

Thread-safe CRUD operations on DataNodes
UID-based node identification via NodeUidMapper
JSON serialization of nodes and properties

Internal Properties

Properties with keys starting with "restapi." are internal metadata used by the REST API (e.g., "restapi.uid" for node identification). These properties are:

Filtered out from all property query responses (not leaked to clients)
Protected from modification via SetNodeProperty
Protected from deletion via DeleteNodeProperty and ReplaceNodeProperties
Clients cannot set, get, or delete these properties via the API

Modification Tracking

When a node is modified through the bridge (create, update, property changes), the bridge automatically adds two internal properties to the node:

"restapi.modified" (string): Timestamp of the last modification via REST API.
"restapi.lastmodification" (string): Description of the last modification operation.

Possible lastmodification values:

"created" – Node was created via CreateNode
"reparented" – Node was moved to a different parent via UpdateNode
"property_set:\<key\>" – A property was set via SetNodeProperty
"property_deleted:\<key\>" – A property was deleted via DeleteNodeProperty
"properties_replaced" – Properties were replaced via ReplaceNodeProperties

All public methods are thread-safe.

See also: NodeUidMapper, RestServer, IRestServerService

Definition at line 74 of file mitkDataStorageBridge.h.

Member Typedef Documentation

◆ Json

using mitk::DataStorageBridge::Json = nlohmann::json

Definition at line 77 of file mitkDataStorageBridge.h.

Member Enumeration Documentation

◆ OperationStatus

enum mitk::DataStorageBridge::OperationStatus

strong

Status codes for mutation operations.

Enables controllers to produce precise HTTP responses:

Success 200/204
NodeNotFound 404
PropertyNotFound 404
InvalidInput 400
InternalError 500

Enumerator
Success
NodeNotFound	Target node does not exist 404.
PropertyNotFound	Property absent in target scope 404.
InvalidInput	Malformed value or unsupported scope 400.
InternalError	No DataStorage or unexpected state 500.

Definition at line 141 of file mitkDataStorageBridge.h.

Constructor & Destructor Documentation

◆ DataStorageBridge() [1/3]

mitk::DataStorageBridge::DataStorageBridge ( )

◆ ~DataStorageBridge()

mitk::DataStorageBridge::~DataStorageBridge ( )

◆ DataStorageBridge() [2/3]

mitk::DataStorageBridge::DataStorageBridge ( const DataStorageBridge & )

delete

◆ DataStorageBridge() [3/3]

mitk::DataStorageBridge::DataStorageBridge ( DataStorageBridge && )

delete

Member Function Documentation

◆ CreateNode()

CreateNodeResult mitk::DataStorageBridge::CreateNode	(	const Json &	nodeData,
		const std::optional< std::string > &	parentUid = `std::nullopt`
	)

Create a new node.

Creates a new DataNode with the specified name and properties. Properties that fail to deserialize are logged and reported in the result, but do not prevent node creation.

Parameters

nodeData	JSON object with node data (name, properties).
parentUid	Optional parent node UID. If provided, creates as child of parent.

Returns: CreateNodeResult with success status, UID, and any failed properties.

◆ DeleteNode()

DeleteResult mitk::DataStorageBridge::DeleteNode	(	const std::string &	uid,
		bool	recursive = `false`
	)

Delete a node.

Parameters

uid	The node UID.
recursive	If true, also delete all children recursively.

Returns: DeleteResult with success status and deleted UIDs.

◆ DeleteNodeProperty()

OperationStatus mitk::DataStorageBridge::DeleteNodeProperty	(	const std::string &	uid,
		const std::string &	key,
		const PropertyQueryParams &	params
	)

Delete a property from a node.

Parameters

uid	The node UID.
key	The property key.
params	Query parameters for scope and context.

Returns: OperationStatus::Success, ::NodeNotFound, ::PropertyNotFound, ::InvalidInput, or ::InternalError.

◆ FindDataNode()

DataNode::ConstPointer mitk::DataStorageBridge::FindDataNode ( const std::string & uid ) const

Look up a DataNode by UID.

Returns a const strong reference to the node, keeping it alive for the duration of the caller's use. Returns null if the UID is not registered.

Intended for read-only access (e.g. inspecting geometry, properties). Do not retain the returned pointer beyond the immediate call site without understanding the threading implications.

Parameters

uid	The node UID.

Returns: DataNode::ConstPointer to the node, or null if not found.

◆ GetDataStorage()

DataStorage::Pointer mitk::DataStorageBridge::GetDataStorage ( ) const

Get the current DataStorage.

Returns: The DataStorage, or nullptr if not connected.

◆ GetNode()

std::optional<Json> mitk::DataStorageBridge::GetNode ( const std::string & uid ) const

Get a single node by UID.

Parameters

uid	The node UID.

Returns: JSON object for the node, or std::nullopt if not found.

◆ GetNodeAvailableContexts()

std::optional<Json> mitk::DataStorageBridge::GetNodeAvailableContexts ( const std::string & uid ) const

Get available property contexts for a node.

Returns a JSON array containing null (for default context) and strings for each named context available on the node.

Parameters

uid	The node UID.

Returns: JSON array of contexts, or std::nullopt if node not found.

◆ GetNodeData()

GetNodeDataResult mitk::DataStorageBridge::GetNodeData ( const std::string & uid ) const

Get a clone of the node's data for thread-safe processing.

Returns a clone of the BaseData attached to the node. The clone is independent of the original data and can be safely processed (e.g., serialized) without holding locks and without affecting the original.

This method is designed for scenarios where the caller needs to perform potentially slow operations on the data (like serialization) without blocking other DataStorage operations.

Parameters

uid	The node UID.

Returns

GetNodeDataResult with nodeFound status and cloned data.

nodeFound=false: Node does not exist
nodeFound=true, data=nullptr: Node exists but has no data
nodeFound=true, data!=nullptr: Node exists and data is cloned

◆ GetNodeProperties()

std::optional<Json> mitk::DataStorageBridge::GetNodeProperties	(	const std::string &	uid,
		const PropertyQueryParams &	params = `{}`
	)		const

Get properties of a node with scope filtering.

Parameters

uid	The node UID.
params	Query parameters for property filtering.

Returns: JSON object with properties, or std::nullopt if node not found.

◆ GetNodeProperty()

std::optional<Json> mitk::DataStorageBridge::GetNodeProperty	(	const std::string &	uid,
		const std::string &	key,
		const PropertyQueryParams &	params = `{}`
	)		const

Get a single property of a node.

Returns the property in standard JSON serialization format:

Simple properties: {"property_name": value}
Complex properties: {"property_name": {"value": ..., "type": "..."}}

Parameters

uid	The node UID.
key	The property key.
params	Query parameters for scope and context.

Returns: JSON object with the property, or std::nullopt if not found.

◆ GetNodes()

NodeQueryResult mitk::DataStorageBridge::GetNodes ( const NodeQueryParams & params ) const

Get nodes with full query parameter support.

Parameters

params Query parameters including filters, pagination, etc.

Returns: Query result with nodes and metadata.

◆ GetNodeUid()

std::string mitk::DataStorageBridge::GetNodeUid ( DataNode * node ) const

Get the UID for a DataNode.

Creates a UID if the node doesn't have one yet.

Parameters

[in] node The node to get the UID for. Must not be nullptr.

Returns: The UID string for this node.

Exceptions

std::invalid_argument if node is nullptr.

◆ HasDataStorage()

bool mitk::DataStorageBridge::HasDataStorage ( ) const

Check if a DataStorage is connected.

Returns: true if a DataStorage is available.

◆ operator=() [1/2]

DataStorageBridge& mitk::DataStorageBridge::operator= ( const DataStorageBridge & )

delete

◆ operator=() [2/2]

DataStorageBridge& mitk::DataStorageBridge::operator= ( DataStorageBridge && )

delete

◆ ReplaceNodeProperties()

ReplacePropertiesResult mitk::DataStorageBridge::ReplaceNodeProperties	(	const std::string &	uid,
		const Json &	properties,
		const PropertyQueryParams &	params
	)

Replace all properties on a node (PUT semantics).

Parameters

uid	The node UID.
properties	JSON object with all properties (replaces existing).
params	Query parameters for scope and context.

Returns: ReplacePropertiesResult with status and, on success, the replaced/removed lists.

◆ SetDataStorage()

void mitk::DataStorageBridge::SetDataStorage ( DataStorage * dataStorage )

Set the DataStorage to operate on.

Parameters

[in] dataStorage The DataStorage, or nullptr to disconnect.

◆ SetDispatcher()

void mitk::DataStorageBridge::SetDispatcher ( StorageThreadDispatcherBase * dispatcher )

Set the dispatcher for thread-safe DataStorage operations.

If set, all public operations (reads and writes) are dispatched to the storage-owning thread. This is necessary because even read operations may set restapi.uid properties on first access, triggering Modified events that cascade into Qt widget updates.

If not set, operations execute directly on the calling thread (suitable for tests/headless scenarios).

Parameters

[in] dispatcher The dispatcher, or nullptr to clear.

◆ SetNodeData()

OperationStatus mitk::DataStorageBridge::SetNodeData	(	const std::string &	uid,
		BaseData *	data
	)

Set or replace the data on a node.

Thread-safe assignment of BaseData to a node. The data is assigned directly (not cloned), so the caller should not modify the data object after calling this method.

Can be used to:

Set data on an empty node (data_type was null)
Replace existing data with new data

Parameters

uid	The node UID.
data	The data to assign. Can be nullptr to clear the node's data.

Returns: OperationStatus::Success, ::NodeNotFound, or ::InternalError.

◆ SetNodeProperty()

OperationStatus mitk::DataStorageBridge::SetNodeProperty	(	const std::string &	uid,
		const std::string &	key,
		const Json &	value,
		const PropertyQueryParams &	params
	)

Set a single property on a node.

Parameters

uid	The node UID.
key	The property key.
value	The property value as JSON.
params	Query parameters for scope and context.

Returns: OperationStatus::Success, ::NodeNotFound, ::InvalidInput, or ::InternalError.

◆ UpdateNode()

bool mitk::DataStorageBridge::UpdateNode	(	const std::string &	uid,
		const Json &	updates
	)

Update a node.

Currently supports reparenting via "parent_uid" field. Reparenting is done by removing the node from DataStorage and re-adding it under the new parent (same approach as Data Manager UI).

Parameters

uid	The node UID.
updates	JSON object with fields to update (e.g., "parent_uid").

Returns: true if updated successfully.

Member Data Documentation

◆ INTERNAL_PROPERTY_PREFIX

constexpr const char* mitk::DataStorageBridge::INTERNAL_PROPERTY_PREFIX

staticconstexpr

Prefix for internal REST API properties (filtered from responses, protected from modification).

Definition at line 80 of file mitkDataStorageBridge.h.

◆ LAST_MODIFICATION_PROPERTY_KEY

constexpr const char* mitk::DataStorageBridge::LAST_MODIFICATION_PROPERTY_KEY

staticconstexpr

Property key for tracking the last modification operation (string property).

Definition at line 91 of file mitkDataStorageBridge.h.

◆ MODIFIED_PROPERTY_KEY

constexpr const char* mitk::DataStorageBridge::MODIFIED_PROPERTY_KEY

staticconstexpr

Property key for tracking if a node was modified via the REST API.

If this string property exists on a node, it was modified via the REST API and its value is the timestamp of the last modification.

Definition at line 88 of file mitkDataStorageBridge.h.

The documentation for this class was generated from the following file:

mitkDataStorageBridge.h

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Internal Properties

Modification Tracking

Member Typedef Documentation

◆ Json

Member Enumeration Documentation

◆ OperationStatus

Constructor & Destructor Documentation

◆ DataStorageBridge() [1/3]

◆ ~DataStorageBridge()

◆ DataStorageBridge() [2/3]

◆ DataStorageBridge() [3/3]

Member Function Documentation

◆ CreateNode()

◆ DeleteNode()

◆ DeleteNodeProperty()

◆ FindDataNode()

◆ GetDataStorage()

◆ GetNode()

◆ GetNodeAvailableContexts()

◆ GetNodeData()

◆ GetNodeProperties()

◆ GetNodeProperty()

◆ GetNodes()

◆ GetNodeUid()

◆ HasDataStorage()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ReplaceNodeProperties()

◆ SetDataStorage()

◆ SetDispatcher()

◆ SetNodeData()

◆ SetNodeProperty()

◆ UpdateNode()

Member Data Documentation

◆ INTERNAL_PROPERTY_PREFIX

◆ LAST_MODIFICATION_PROPERTY_KEY

◆ MODIFIED_PROPERTY_KEY