vreMessageId.h

Go to the documentation of this file.

/*********************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*********************************************************************************/
 
//! \file vreMessageId.h
//! \brief Defines message identifier class for the VREngage messaging system
//!
//! This file contains the DtVreMessageId class which provides unique identification
//! and hierarchical matching for VREngage messages. Message IDs support dot-notation
//! hierarchies and wildcard matching, enabling flexible message routing and filtering.
 
#pragma once
 
#include "vreMessageManager/export.h"
 
#include <string>
#include <vector>
 
#include <vlutil/vlHash.h>
 
namespace makVre
{
 
//! \brief Message identifier class for the VREngage messaging system
//!
//! This class provides unique identification and hierarchical matching for VREngage
//! messages. It supports dot-notation hierarchies (e.g., "category.subcategory.name")
//! and wildcard matching using the "*" character. Message IDs are used for message
//! routing, filtering, and identification in the VREngage messaging system.
//!
//! Message IDs are created from string type names, which are hashed for efficient
//! comparison. The string is also tokenized by dots to support hierarchical matching.
class MESSAGEMANAGER_DLL DtVreMessageId
{
public:
   //! \brief Default constructor
   //!
   //! Initializes a new message ID with an "INVALID TYPE" type string.
   //! This constructor should generally not be used directly.
   DtVreMessageId();
 
   //! \brief Constructor with type string
   //! \param name Type name string for the message ID
   //!
   //! Initializes a new message ID with the specified type string.
   //! The type string is hashed for efficient comparison and tokenized
   //! by dots to support hierarchical matching. The string can contain
   //! wildcards (*) to match any value at a specific hierarchy level.
   DtVreMessageId(const std::string& name);
 
   //! \brief Copy constructor
   //! \param orig Message ID to copy
   //!
   //! Creates a new message ID that is a copy of the specified message ID.
   DtVreMessageId(const DtVreMessageId& orig);
 
   //! \brief Destructor
   //!
   //! Cleans up resources used by the message ID.
   ~DtVreMessageId();
 
   //! \brief Checks if this message ID matches another message ID
   //! \param id Message ID to compare against
   //! \return True if the IDs match, false otherwise
   //!
   //! This method checks if this message ID matches the specified message ID.
   //! If the hash values match exactly, the result is true. Otherwise, it performs
   //! a hierarchical comparison, taking wildcards into account. A wildcard in this
   //! ID will match any value in the corresponding position of the other ID.
   bool matches(const DtVreMessageId& id) const;
 
   //! \brief Checks if this message ID matches another message ID at a specific depth
   //! \param id Message ID to compare against
   //! \param depth Hierarchy level to compare at (0-based index)
   //! \return True if the IDs match at the specified depth, false otherwise
   //!
   //! This method checks if this message ID matches the specified message ID
   //! at the given hierarchy depth. It compares the hash values at the specified
   //! depth, taking wildcards into account. A wildcard in this ID will match any
   //! value in the corresponding position of the other ID.
   bool matches(const DtVreMessageId& id, int depth) const;
 
   //! \brief Gets the type string of this message ID
   //! \return Reference to the type string
   //!
   //! This method returns the original type string used to create this message ID.
   const std::string& type() const { return myType; }
 
   //! \brief Sets a new type string for this message ID
   //! \param newType New type string to set
   //!
   //! This method sets a new type string for this message ID and recomputes
   //! the hash values and tokenized hierarchy. It is generally not recommended
   //! to change the type of a message ID after creation.
   void setType(const std::string& newType);
 
   //! \brief Gets the hash value at a specific hierarchy depth
   //! \param depth Hierarchy level to get the hash for (0-based index)
   //! \return Hash value at the specified depth
   //!
   //! This method returns the hash value at the specified hierarchy depth.
   //! It is used for hierarchical matching in the message routing system.
   DtHashId idAtDepth(int depth) const { return myIds[depth]; }
 
   //! \brief Gets the hash value of the complete type string
   //! \return Hash value of the type string
   //!
   //! This method returns the hash value of the complete type string.
   //! It is used for efficient message type identification and comparison.
   DtHashId hashType() const { return myHashType; }
 
   //! \brief Equality operator
   //! \param rhs Right-hand side message ID to compare with
   //! \return True if the message IDs have the same hash value, false otherwise
   //!
   //! This operator compares the hash values of the two message IDs.
   //! Two message IDs are considered equal if their hash values match exactly.
   bool operator==(const DtVreMessageId& rhs) const;
 
   //! \brief Inequality operator
   //! \param rhs Right-hand side message ID to compare with
   //! \return True if the message IDs have different hash values, false otherwise
   //!
   //! This operator is the logical negation of the equality operator.
   bool operator!=(const DtVreMessageId& rhs) const { return !(*this == rhs); }
 
protected:
   //! \brief Hash value of the complete type string
   //!
   //! This hash value is used for efficient message type identification and comparison.
   DtHashId myHashType;
 
   //! \brief Original type string used to create this message ID
   std::string myType;
 
   //! \brief Vector of hash values for each hierarchy level
   //!
   //! This vector contains the hash values for each level of the dot-separated
   //! hierarchy. Wildcards are represented by the special theWildcard value.
   std::vector<DtHashId> myIds;
 
   //! \brief Special hash value used to represent wildcards in the hierarchy
   //!
   //! This value is used in the myIds vector to represent wildcards (*)
   //! in the type string hierarchy.
   static DtHashId theWildcard;
};
 
} // namespace makVre