Base class for defining and detecting property-based relations between data objects. More...
#include <mitkPropertyRelationRuleBase.h>
Public Types | |
| enum class | RelationType { None , Data , ID , Complete } |
| using | RuleIDType = std::string |
| using | RelationUIDType = Identifiable::UIDType |
| using | RelationUIDVectorType = std::vector< RelationUIDType > |
| using | RelationVectorType = std::vector< RelationType > |
| using | InstanceIDType = std::string |
Static Public Member Functions | |
| static PropertyKeyPath | GetRootKeyPath () |
| static PropertyKeyPath | GetRIIPropertyKeyPath (const std::string propName, const InstanceIDType &instanceID) |
| static PropertyKeyPath | GetRIIRelationUIDPropertyKeyPath (const InstanceIDType &instanceID="") |
| static PropertyKeyPath | GetRIIRuleIDPropertyKeyPath (const InstanceIDType &instanceID="") |
| static PropertyKeyPath | GetRIIDestinationUIDPropertyKeyPath (const InstanceIDType &instanceID="") |
Protected Types | |
| using | InstanceIDVectorType = std::vector< InstanceIDType > |
| using | DataRelationUIDVectorType = std::vector< std::pair< RelationUIDType, RuleIDType > > |
Static Protected Member Functions | |
| static InstanceIDType | NULL_INSTANCE_ID () |
| static InstanceIDType | GetInstanceIDByPropertyName (const std::string propName) |
| static std::vector< std::string > | GetPropertyKeys (const IPropertyProvider *owner) |
Detailed Description
Base class for defining and detecting property-based relations between data objects.
This class standardizes, abstracts, and encapsulates rules and business logic for detecting and defining directed, property-based relations in MITK. Relations point from a source IPropertyOwner to a destination IPropertyOwner.
Key concepts:
- Abstract vs. concrete rules: Abstract rules (IsAbstract() == true) can detect and disconnect relations but cannot create new connections. Concrete rules can create, detect, and disconnect relations. Abstract rules match multiple concrete rule types (e.g., GenericIDRelationRule in abstract mode detects all ID relations).
- Uniqueness: A specific source-destination pair may have only one relation per concrete rule ID, but may have multiple relations for an abstract rule.
- Zombie relations: Deleting a destination does not implicitly remove the relation. The relation becomes a "zombie" that must be explicitly disconnected.
- Relation UID: Each relation has a unique identifier (relationUID).
The relation identification uses two layers:
- ID-layer: Uses IIdentifiable UIDs for explicit, strong relation encoding. Fully implemented by this base class.
- Data-layer: Uses properties of source and destination to deduce relations. Implemented by concrete rule subclasses.
Relations are stored as Relation Instance Identifying (RII) properties on the source:
Definition at line 63 of file mitkPropertyRelationRuleBase.h.
Member Typedef Documentation
◆ DataRelationUIDVectorType
|
protected |
Definition at line 284 of file mitkPropertyRelationRuleBase.h.
◆ InstanceIDType
| using mitk::PropertyRelationRuleBase::InstanceIDType = std::string |
Definition at line 89 of file mitkPropertyRelationRuleBase.h.
◆ InstanceIDVectorType
|
protected |
Definition at line 268 of file mitkPropertyRelationRuleBase.h.
◆ RelationUIDType
Definition at line 71 of file mitkPropertyRelationRuleBase.h.
◆ RelationUIDVectorType
| using mitk::PropertyRelationRuleBase::RelationUIDVectorType = std::vector<RelationUIDType> |
Definition at line 72 of file mitkPropertyRelationRuleBase.h.
◆ RelationVectorType
| using mitk::PropertyRelationRuleBase::RelationVectorType = std::vector<RelationType> |
Definition at line 84 of file mitkPropertyRelationRuleBase.h.
◆ RuleIDType
| using mitk::PropertyRelationRuleBase::RuleIDType = std::string |
Definition at line 70 of file mitkPropertyRelationRuleBase.h.
Member Enumeration Documentation
◆ RelationType
|
strong |
Enum class for different types of relations.
| Enumerator | |
|---|---|
| None | Two IPropertyOwner have no relation under the rule. |
| Data | Two IPropertyOwner have a relation, but it is "only" deduced from the Data-layer (so a bit "weaker" as ID). Reasons for the missing ID connection could be that Destintination has not IIdentifiable implemented. |
| ID | Two IPropertyOwner have a relation and are explicitly connected via the ID of IIdentifiable of the Destination. |
| Complete | Two IPropertyOwner have a relation and are fully explicitly connected (via data layer and ID layer). |
Definition at line 75 of file mitkPropertyRelationRuleBase.h.
Constructor & Destructor Documentation
◆ PropertyRelationRuleBase() [1/2]
|
protecteddefault |
◆ PropertyRelationRuleBase() [2/2]
|
inlineprotected |
Definition at line 265 of file mitkPropertyRelationRuleBase.h.
◆ ~PropertyRelationRuleBase()
|
overrideprotecteddefault |
Member Function Documentation
◆ CastProviderAsIdentifiable()
|
protected |
Helper method that tries to cast the provider to the Identifiable interface.
◆ Clone()
| Pointer mitk::PropertyRelationRuleBase::Clone | ( | ) | const |
◆ Connect()
|
protected |
Explicitly connects the passed instances. Afterwards they have a relation of Data (if data layer is supported), ID (if a destination implements IIdentifiable) or Complete (if Data and ID could be connected). If the passed instance are already connected the old connection will be overwritten (and raised to the highest possible connection level).
- Remarks
- This method has protected visibility in the base implementation, because it is a design decision of derived rule classes which interface they want to offer for connecting. It may just be made public (e.g. GenericIDRelationRule) or used by own implementations.
- Precondition
- source must be a valid instance.
- destination must be a valid instance.
- the rule instance must not be abstract.
- Returns
- Return the relation uid of the relation connected by this method call
◆ Connect_datalayer()
|
protectedpure virtual |
Is called by Connect() to ensure that source has correctly set properties to resemble the relation on the data layer. This means that the method should set the properties that describe and encode the relation on the data layer (data-layer-specific relation properties). If the passed instance are already connected, the old settings should be overwritten. Connect() will ensure that source and destination are valid pointers.
- Parameters
-
source destination instanceID is the ID for the relation instance that should be connected. Existence of the relation instance is ensured.
- Precondition
- source must be a valid instance.
- destination must be a valid instance.
Implemented in mitk::SegSourceImageRelationRule, mitk::SourceImageRelationRule, and mitk::GenericIDRelationRule.
◆ Disconnect() [1/2]
| void mitk::PropertyRelationRuleBase::Disconnect | ( | IPropertyOwner * | source, |
| const IPropertyProvider * | destination, | ||
| RelationType | layer = RelationType::Complete |
||
| ) | const |
Disconnect the passed instances by modifying source. One can specify which layer should be disconnected via the argument "layer". Default is the complete disconnection. All RII-properties or properties that define the connection on the data layer in the source for the passed destination will be removed.
- Precondition
- source must be a valid instance.
- destination must be a valid instance.
- Parameters
-
source destination layer Defines the way of disconnection. Data: Only the remove the connection on the data layer. ID: Only remove the connection on the ID layer. Complete: Remove the connection on all layers. If a connection does not exist on a selected layer, it is silently ignored.
◆ Disconnect() [2/2]
| void mitk::PropertyRelationRuleBase::Disconnect | ( | IPropertyOwner * | source, |
| RelationUIDType | relationUID, | ||
| RelationType | layer = RelationType::Complete |
||
| ) | const |
Disconnect the source from the passed relationUID (useful for "zombie relations"). One can specify which layer should be disconnected via the argument "layer". Default is the complete disconnection. All RII-properties or properties that define the connection on the data layer in the source for the passed destination will be removed. If the relationUID is not part of the source. Nothing will be changed.
- Precondition
- source must be a valid instance.
- Parameters
-
source relationUID layer Defines the way of disconnection. Data: Only the remove the connection on the data layer. ID: Only remove the connection on the ID layer. Complete: Remove the connection on all layers. If a connection does not exist on a selected layer, it is silently ignored.
◆ Disconnect_datalayer()
|
protectedpure virtual |
This method is called by Disconnect() to remove all properties of the relation from the source that are set by Connect_datalayer().
- Remarks
- This method should remove all properties that are set for a specific relation by Connect_datalayer(...). If the relationUID is not part of the source, nothing will be changed. Disconnect() ensures that source is a valid pointer if called.
- Disconnect() ensures that source is valid and only invokes if instance exists.
Implemented in mitk::SegSourceImageRelationRule, mitk::ModelFitResultRelationRule, mitk::SourceImageRelationRule, and mitk::GenericIDRelationRule.
◆ GetConnectedSourcesDetector()
| NodePredicateBase::ConstPointer mitk::PropertyRelationRuleBase::GetConnectedSourcesDetector | ( | ) | const |
Predicate that can be used to find nodes that are Sources of that rule and connected. Thus all nodes where IsSource() returns true.
◆ GetDestinationCandidateIndicator()
| NodePredicateBase::ConstPointer mitk::PropertyRelationRuleBase::GetDestinationCandidateIndicator | ( | ) | const |
Predicate that can be used to find nodes that qualify as destination for that rule (but must not be a destination yet). Thus all nodes where IsDestinationCandidate() returns true.
◆ GetDestinationDetector()
| NodePredicateBase::ConstPointer mitk::PropertyRelationRuleBase::GetDestinationDetector | ( | const IPropertyProvider * | source, |
| RelationUIDType | relationUID | ||
| ) | const |
Returns a predicate that can be used to find the Destination of the passed Source for a given relationUID.
- Parameters
-
source Pointer to the Source instance that should be used for detection. relationUID
- Precondition
- source must be a valid instance.
- relationUID must identify a relation of the passed source and rule. (This must be in the return of this->GetExistingRelations(source).
◆ GetDestinationRoleName()
|
pure virtual |
Returns a human readable string that can be used to describe the role of a destination in context of the rule instance.
Implemented in mitk::SourceImageRelationRule, and mitk::GenericIDRelationRule.
◆ GetDestinationsDetector()
| NodePredicateBase::ConstPointer mitk::PropertyRelationRuleBase::GetDestinationsDetector | ( | const IPropertyProvider * | source, |
| RelationType | exclusiveRelation = RelationType::None |
||
| ) | const |
Predicate that can be used to find nodes that are as Destination related to the passed Source under the rule
- Parameters
-
source Pointer to the Source instance that should be used for detection. exclusiveRelation Defines if only special types of relations should detected. None: All relations (default); Data: must be a data relation (so Data or Complete); ID: must be an ID relation (so ID or Complete); Complete: only complete relations.
- Precondition
- Source must be a valid instance.
◆ GetDestinationUIDByInstanceID()
|
protected |
Helper function that retrieves the destination UID of a relation instance of a passed source. If the relation has no destination UID, an empty string will be returned.
- Precondition
- source must be valid.
◆ GetDisplayName()
|
pure virtual |
Returns a human readable string that can be used to describe the rule. Does not need to be unique.
Implemented in mitk::SourceImageRelationRule, and mitk::GenericIDRelationRule.
◆ GetExistingRelations()
| RelationUIDVectorType mitk::PropertyRelationRuleBase::GetExistingRelations | ( | const IPropertyProvider * | source, |
| RelationType | layer = RelationType::None |
||
| ) | const |
Returns a vector of relation UIDs for all relations of this rule instance that are defined for the passed source.
- Precondition
- source must be a pointer to a valid IPropertyOwner instance.
- Parameters
-
source layer Defines the layer the relations must be reflected. None: does not matter which one, as long as at least one is present. Data: Only data layer exclusive connections, ID: Only ID layer exclusive connections. Complete: Only relations that are connected on both layers.
◆ GetInstanceID_IDLayer()
|
protected |
Returns the instance IDs for the passed source and destination for this rule instance. If the passed source and destination instances has no explicit relation on the ID layer (Connected_ID), an empty vector will be returned.
- Remarks
- Per definition of property relation rules only 0 or 1 instance should be found for one provider pair and concrete rule. But there might be more then one instanceID because either 1) the rule is abstract and supports multiple rule IDs or 2) the data layer may be ambiguous and therefore multiple relation instances of the rule instance could match. The implementation of this function should report all relation instances. The calling function will take care.
- Precondition
- source must be a pointer to a valid IPropertyProvider instance.
- destination must be a pointer to a valid IPropertyProvider instance.
◆ GetInstanceIDByPropertyName()
|
staticprotected |
Helper function that deduces the instance ID out of a property name. If it cannot be deduced an MITK exception is thrown.
◆ GetInstanceIDByRelationUID()
|
protected |
Helper function that deduces the relation instance ID given the relation UID. If it cannot be deduced an NoPropertyRelationException is thrown.
◆ GetPropertyKeys()
|
staticprotected |
helper method that serves as a workaround until T24729 is done. Please remove if T24728 is done then could directly use owner->GetPropertyKeys() again.
◆ GetRelationPropertyPaths()
| std::vector<PropertyKeyPath> mitk::PropertyRelationRuleBase::GetRelationPropertyPaths | ( | const IPropertyProvider * | source, |
| RelationUIDType | relationUID, | ||
| RelationType | layer = RelationType::Data |
||
| ) | const |
Get all property key paths relevant for a given relation.
- Parameters
-
[in] source Pointer to the Source instance containing the relation properties. [in] relationUID UID of the relation to query. [in] layer Defines which layer to query: - RelationType::ID: returns all RII properties belonging to the relation.
- RelationType::Data: returns all data-layer properties (default).
- RelationType::Complete: returns all properties (ID + Data).
- Returns
- A vector of PropertyKeyPath entries for the matching properties.
- Precondition
sourcemust be a valid instance.-
relationUIDmust identify a relation of the passed source and this rule (must be in the return of GetExistingRelations(source)).
◆ GetRelationTypes()
| RelationVectorType mitk::PropertyRelationRuleBase::GetRelationTypes | ( | const IPropertyProvider * | source, |
| const IPropertyProvider * | destination | ||
| ) | const |
Returns all relation types of the passed IPropertyOwner instances.
- Remarks
- Abstract rules may have several relationtypes between the instances (from different supported concrete rules), that cover both ID and Data relations; thus it returns a vector of RelationTypes.
- Returns
- Vector of all relation types that exist between the given instances. Empty vector equals none relation at all.
- Precondition
- source must be a pointer to a valid IPropertyProvider instance.
- destination must be a pointer to a valid IPropertyProvider instance.
◆ GetRelationUID()
| RelationUIDType mitk::PropertyRelationRuleBase::GetRelationUID | ( | const IPropertyProvider * | source, |
| const IPropertyProvider * | destination | ||
| ) | const |
Returns the relation UID for the passed source and destination of this rule instance. If the passed instances have no relation, no ID can be deduced and an exception will be thrown. If more than one relation is found, also an exception will be thrown. Thus only use this convenience method, if you are sure that one(!) relation UID can exist.
- Precondition
- source must be a pointer to a valid IPropertyOwner instance.
- destination must be a pointer to a valid IPropertyOwner instance.
- Source and destination have one relation; otherwise if no relation exists a NoPropertyRelationException is thrown; if more than one relation exists a default MITK exception is thrown.
◆ GetRelationUIDByInstanceID()
|
protected |
Helper function that deduces the relation UID of the given relation instance. If it cannot be deduced an NoPropertyRelationException is thrown.
◆ GetRelationUIDs()
| RelationUIDVectorType mitk::PropertyRelationRuleBase::GetRelationUIDs | ( | const IPropertyProvider * | source, |
| const IPropertyProvider * | destination | ||
| ) | const |
Returns the relation UID(s) for the passed source and destination of this rule instance. If the rule is abstract multiple relation UIDs might be returned. In case of concrete rule only one relation UID.
- Precondition
- source must be a pointer to a valid IPropertyOwner instance.
- destination must be a pointer to a valid IPropertyOwner instance.
◆ GetRelationUIDs_DataLayer()
|
protectedpure virtual |
Returns the RelationUIDs of all relations that are defined by the data layer of source for this rule instance and, if defined, destination. If the passed source (and destination) instance has no relation on the data layer, an empty vector will be returned.
- Remarks
- Per definition for property relation rules only 0 or 1 instance should be found for one provider pair and concrete rule. But there might be more then one instance because either 1) the rule is abstract and supports multiple rule IDs or 2) the data layer may be ambiguous (e.g. because the destination was not specified) and therefore multiple relation instances of the rule instance could match. The implementation of this function should report all relation instances. The calling function will take care.
- Parameters
-
source destination Destination the find relations should point to. If destination is NULL any relation on the data layer for this rule and source are wanted. instances_IDLayer List of relation instances that are already defined by the ID layer. The implementation of this function should only cover relations that are not already resembled in the passed relarions_IDLayer.
- Precondition
- source must be a pointer to a valid IPropertyProvider instance.
Implemented in mitk::ModelFitResultRelationRule, mitk::SourceImageRelationRule, and mitk::GenericIDRelationRule.
◆ GetRIIDestinationUIDPropertyKeyPath()
|
static |
Returns the property key path for RII DestinationUID properties.
- Parameters
-
instanceID If not empty, the PropertyKeyPath is only for a specific instance. If empty, it is wildcarded and will match RII DestinationUIDs property of any instance.
◆ GetRIIPropertyKeyPath()
|
static |
Returns the property key path for a RII property.
- Parameters
-
propName If not empty a PropertyPath element will added (with the passed value) after the <InstanceID> element. instanceID If not empty, the PropertyKeyPath is only for a specific instance. If empty, it is wildcarded and will match RIIs property of any instance.
◆ GetRIIPropertyRegEx()
|
protected |
Helper function that generates a reg ex that can be used to find a specific RII property for the rule instance.
- Parameters
-
propName If not empty a PropertyPath element will be added (with the passed value) after the <InstanceID> element. instanceID If not empty only for the reg ex will only valid for the passed instanceID. Otherwise for all.
◆ GetRIIRelationUIDPropertyKeyPath()
|
static |
Returns the property key path for RII RelationUID properties.
- Parameters
-
instanceID If not empty, the PropertyKeyPath is only for a specific instance. If empty, it is wildcarded and will match RII RelationUIDs property of any instance.
◆ GetRIIRuleIDPropertyKeyPath()
|
static |
Returns the property key path for RII RuleID properties.
- Parameters
-
instanceID If not empty, the PropertyKeyPath is only for a specific instance. If empty, it is wildcarded and will match RII RuleIDs property of any instance.
◆ GetRootKeyPath()
|
static |
Returns the generic root path for relation rules ("MITK.Relations").
◆ GetRuleID()
|
pure virtual |
Returns an ID string that identifies the rule class.
- Postcondition
- The returned rule ID must met the preconditions of a PropertyKeyPath element name (see mitk::PropertyKeyPath
Implemented in mitk::SourceImageRelationRule, and mitk::GenericIDRelationRule.
◆ GetRuleIDByInstanceID()
|
protected |
Helper function that retrieves the rule ID of a relation instance of a passed source.
- Precondition
- source must be valid.
- source must have a relation instance with this ID
◆ GetSourceCandidateIndicator()
| NodePredicateBase::ConstPointer mitk::PropertyRelationRuleBase::GetSourceCandidateIndicator | ( | ) | const |
Predicate that can be used to find nodes that qualify as source for that rule (but must not be a source yet). Thus all nodes where IsSourceCandidate() returns true.
◆ GetSourceRoleName()
|
pure virtual |
Returns a human readable string that can be used to describe the role of a source in context of the rule instance.
Implemented in mitk::SourceImageRelationRule, and mitk::GenericIDRelationRule.
◆ GetSourcesDetector()
| NodePredicateBase::ConstPointer mitk::PropertyRelationRuleBase::GetSourcesDetector | ( | const IPropertyProvider * | destination, |
| RelationType | exclusiveRelation = RelationType::None |
||
| ) | const |
Predicate that can be used to find nodes that are as source related to the passed Destination under the rule
- Parameters
-
destination Pointer to the Destination instance that should be used for detection. exclusiveRelation Defines if only special types of relations should detected. None: All relations (default); Data: must be a data relation (so Data or Complete); ID: must be an ID relation (so ID or Complete); Complete: only complete relations.
- Precondition
- Destination must be a valid instance.
◆ HasRelation()
| bool mitk::PropertyRelationRuleBase::HasRelation | ( | const IPropertyProvider * | source, |
| const IPropertyProvider * | destination, | ||
| RelationType | requiredRelation = RelationType::None |
||
| ) | const |
Indicates if passed IPropertyOwner instances have a relation of a certain type.
- Remarks
- Abstract rules may also indicate RelationType::Complete if there are multiple relations (from different supported concrete rules), that cover both ID and Data relations.
- Parameters
-
source destination requiredRelation Defines the type of relation that should be present. None: does not matter which one, as long as at least one is present. Data: Only data layer exclusive connections, ID: Only ID layer exclusive connections. Complete: Only relations that are connected on both layers.
- Precondition
- source must be a pointer to a valid IPropertyProvider instance.
- destination must be a pointer to a valid IPropertyProvider instance.
◆ IsAbstract()
|
virtual |
Returns if the instance is a abstract rule (true). Default implementation is true. Overwrite and reimplement if another behavior is needed.
Reimplemented in mitk::SourceImageRelationRule, and mitk::GenericIDRelationRule.
◆ IsDestinationCandidate()
|
virtual |
This method checks if owner is eligible to be a Destination for the rule. The default implementation returns a True for every valid IPropertyProvider (so only a null_ptr results into false). May be reimplement by derived rules if they have requirements on potential Sources).
Reimplemented in mitk::ModelFitResultRelationRule, and mitk::SourceImageRelationRule.
◆ IsSource()
| bool mitk::PropertyRelationRuleBase::IsSource | ( | const IPropertyProvider * | owner | ) | const |
Returns true if the passed owner is a Source of a relation defined by the rule.
- Precondition
- owner must be a pointer to a valid IPropertyProvider instance.
◆ IsSourceCandidate()
|
virtual |
This method checks if owner is eligible to be a Source for the rule. The default implementation returns a True for every valid IPropertyProvider (so only a null_ptr results into false). May be reimplement by derived rules if they have requirements on potential Sources).
◆ IsSupportedRuleID()
|
protectedvirtual |
Returns if the passed rule ID is supported/relevant for the rule. Either because it is the very ID of the rule (default implementation) or because it is an abstract rule which also supports the rule ID.
- Returns
- true: If the rule ID can handle the rule ID. false: the rule does not support the rule ID.
Reimplemented in mitk::SourceImageRelationRule, and mitk::GenericIDRelationRule.
◆ itkCreateAnotherMacro()
| mitk::PropertyRelationRuleBase::itkCreateAnotherMacro | ( | Self | ) |
◆ mitkClassMacroItkParent()
| mitk::PropertyRelationRuleBase::mitkClassMacroItkParent | ( | PropertyRelationRuleBase | , |
| itk::Object | |||
| ) |
◆ NULL_INSTANCE_ID()
|
staticprotected |
The documentation for this class was generated from the following file:
