Attribute.h

//=========================================================================
//  Copyright (c) Kitware, Inc.
//  All rights reserved.
//  See LICENSE.txt for details.
//
//  This software is distributed WITHOUT ANY WARRANTY; without even
//  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
//  PURPOSE.  See the above copyright notice for more information.
//=========================================================================
// .NAME smtkAttribute.h - Represents a standalone piece of simulation information
// .SECTION Description
// .SECTION See Also
 
#ifndef smtk_attribute_Attribute_h
#define smtk_attribute_Attribute_h
 
#include "smtk/CoreExports.h"
#include "smtk/PublicPointerDefs.h"
#include "smtk/resource/Component.h"
 
#include "smtk/attribute/CopyAssignmentOptions.h"
#include "smtk/attribute/ReferenceItem.h"
#include "smtk/attribute/SearchStyle.h"
#include "smtk/attribute/ValueItem.h"
 
#include "smtk/common/Deprecation.h"
#include "smtk/common/UUID.h" // for template associatedModelEntities()
 
#include <map>
#include <set>
#include <string>
#include <vector>
 
namespace smtk
{
namespace io
{
class Logger;
};
 
namespace attribute
{
class Evaluator;
class Item;
class Resource;
 
class SMTKCORE_EXPORT Attribute : public resource::Component
{
  friend class smtk::attribute::Definition;
  friend class smtk::attribute::Resource;
 
public:
  smtkTypeMacro(smtk::attribute::Attribute);
  smtkSuperclassMacro(smtk::resource::Component);
 
  struct SMTKCORE_EXPORT CompareByName
  {
    bool operator()(
      const smtk::attribute::AttributePtr& lhs,
      const smtk::attribute::AttributePtr& rhs) const
    {
      return lhs->name() < rhs->name();
    }
 
    bool operator()(
      const smtk::attribute::WeakAttributePtr& lhs,
      const smtk::attribute::WeakAttributePtr& rhs) const
    {
      auto left = lhs.lock();
      if (left == nullptr)
      {
        return true;
      }
      auto right = rhs.lock();
      if (right == nullptr)
      {
        return false;
      }
      return left->name() < right->name();
    }
  };
 
  static smtk::attribute::AttributePtr New(
    const std::string& myName,
    const smtk::attribute::DefinitionPtr& myDefinition,
    const smtk::common::UUID& myId)
  {
    return smtk::attribute::AttributePtr(new Attribute(myName, myDefinition, myId));
  }
 
  ~Attribute() override;
 
  AttributePtr shared_from_this()
  {
    return static_pointer_cast<Attribute>(Component::shared_from_this());
  }
 
  std::shared_ptr<const Attribute> shared_from_this() const
  {
    return static_pointer_cast<const Attribute>(Component::shared_from_this());
  }
 
  // NOTE: To rename an attribute use the resource!
  std::string name() const override { return m_name; }
 
  const std::string& type() const;
  std::vector<std::string> types() const;
  bool isA(const smtk::attribute::DefinitionPtr& def) const;
  const smtk::attribute::DefinitionPtr& definition() const { return m_definition; }
 
  const double* color() const;
  void setColor(double r, double g, double b, double alpha);
  void setColor(const double* l_color)
  {
    this->setColor(l_color[0], l_color[1], l_color[2], l_color[3]);
  }
  bool isColorSet() const { return m_isColorSet; }
  void unsetColor() { m_isColorSet = false; }
 
  unsigned int advanceLevel(int mode = 0) const;
  void setLocalAdvanceLevel(int mode, unsigned int level);
  unsigned int localAdvanceLevel(int mode = 0) const
  {
    return (mode == 1 ? m_localAdvanceLevel[1] : m_localAdvanceLevel[0]);
  }
  // unsetLocalAdvanceLevel causes the attribute to return its
  // definition advance level information for the specified mode when calling
  // the advanceLevel(mode) method
  void unsetLocalAdvanceLevel(int mode = 0);
  // Returns true if the attribute is returning its local
  // advance level information
  bool hasLocalAdvanceLevelInfo(int mode = 0) const
  {
    return (mode == 1 ? m_hasLocalAdvanceLevelInfo[1] : m_hasLocalAdvanceLevelInfo[0]);
  }
 
  const std::vector<smtk::attribute::ItemPtr>& items() const { return m_items; }
  smtk::attribute::ItemPtr item(int ith) const
  {
    return (ith < 0)
      ? smtk::attribute::ItemPtr()
      : (static_cast<unsigned int>(ith) >= m_items.size() ? smtk::attribute::ItemPtr()
                                                          : m_items[static_cast<std::size_t>(ith)]);
  }
 
  smtk::attribute::ConstItemPtr
  itemAtPath(const std::string& path, const std::string& sep = "/", bool activeOnly = false) const;
  smtk::attribute::ItemPtr
  itemAtPath(const std::string& path, const std::string& sep = "/", bool activeOnly = false);
 
  template<typename T>
  typename T::ConstPtr itemAtPathAs(
    const std::string& path,
    const std::string& sep = "/",
    bool activeOnly = false) const;
  template<typename T>
  typename T::Ptr
  itemAtPathAs(const std::string& path, const std::string& sep = "/", bool activeOnly = false);
 
  SMTK_DEPRECATED_IN_24_11("Use Item::path() instead.")
  std::string itemPath(const ItemPtr& item, const std::string& sep = "/") const;
 
  smtk::attribute::ItemPtr find(const std::string& name, SearchStyle style = RECURSIVE_ACTIVE);
  smtk::attribute::ConstItemPtr find(const std::string& name, SearchStyle style = RECURSIVE_ACTIVE)
    const;
  std::size_t numberOfItems() const { return m_items.size(); }
 
  template<typename T>
  typename T::Ptr findAs(const std::string& name, SearchStyle style = RECURSIVE_ACTIVE);
 
  template<typename T>
  typename T::ConstPtr findAs(const std::string& name, SearchStyle style = RECURSIVE_ACTIVE) const;
 
  template<typename T>
  void filterItems(
    T& values,
    std::function<bool(typename T::value_type)> test,
    bool activeChildren = true);
 
  IntItemPtr findInt(const std::string& name);
  ConstIntItemPtr findInt(const std::string& name) const;
 
  DoubleItemPtr findDouble(const std::string& name);
  ConstDoubleItemPtr findDouble(const std::string& name) const;
 
  StringItemPtr findString(const std::string& name);
  ConstStringItemPtr findString(const std::string& name) const;
 
  FileItemPtr findFile(const std::string& name);
  ConstFileItemPtr findFile(const std::string& name) const;
 
  DirectoryItemPtr findDirectory(const std::string& name);
  ConstDirectoryItemPtr findDirectory(const std::string& name) const;
 
  GroupItemPtr findGroup(const std::string& name);
  ConstGroupItemPtr findGroup(const std::string& name) const;
 
  ModelEntityItemPtr findModelEntity(const std::string& name);
  ConstModelEntityItemPtr findModelEntity(const std::string& name) const;
 
  VoidItemPtr findVoid(const std::string& name);
  ConstVoidItemPtr findVoid(const std::string& name) const;
 
  DateTimeItemPtr findDateTime(const std::string& name);
  ConstDateTimeItemPtr findDateTime(const std::string& name) const;
 
  ReferenceItemPtr findReference(const std::string& name);
  ConstReferenceItemPtr findReference(const std::string& name) const;
  template<typename T>
  T entityRefsAs(const std::string& name) const;
 
  ResourceItemPtr findResource(const std::string& name);
  ConstResourceItemPtr findResource(const std::string& name) const;
 
  ComponentItemPtr findComponent(const std::string& name);
  ConstComponentItemPtr findComponent(const std::string& name) const;
 
  ConstReferenceItemPtr associatedObjects() const { return m_associatedObjects; }
  ReferenceItemPtr associatedObjects() { return m_associatedObjects; }
 
  bool isObjectAssociated(const smtk::common::UUID& uid) const;
  bool isObjectAssociated(const smtk::resource::PersistentObjectPtr& componentPtr) const;
 
  bool canBeAssociated(const smtk::resource::PersistentObjectPtr& obj) const;
  bool canBeDisassociated(const smtk::resource::PersistentObjectPtr& obj, AttributePtr& probAtt)
    const;
  ConstReferenceItemPtr associations() const { return m_associatedObjects; }
  ReferenceItemPtr associations() { return m_associatedObjects; }
 
  bool isEntityAssociated(const smtk::common::UUID& entity) const;
  bool isEntityAssociated(const smtk::model::EntityRef& entityref) const;
 
  smtk::common::UUIDs associatedModelEntityIds() const;
  template<typename T>
  T associatedModelEntities() const;
 
  template<typename T>
  T associatedObjects() const;
 
  bool associate(smtk::resource::PersistentObjectPtr obj);
  bool associateEntity(const smtk::common::UUID& entity);
  bool associateEntity(const smtk::model::EntityRef& entity);
 
  void disassociateEntity(const smtk::common::UUID& entity, bool reverse = true);
  void disassociateEntity(const smtk::model::EntityRef& entity, bool reverse = true);
  bool
  disassociate(smtk::resource::PersistentObjectPtr obj, AttributePtr& probAtt, bool reverse = true);
  bool disassociate(smtk::resource::PersistentObjectPtr obj, bool reverse = true);
 
  bool assign(
    const AttributePtr& sourceAtt,
    const CopyAssignmentOptions& options = CopyAssignmentOptions());
 
  bool assign(
    const AttributePtr& sourceAtt,
    const CopyAssignmentOptions& options,
    smtk::io::Logger& logger);
 
  void detachItemsFromOwningResource();
 
  bool removeAllAssociations(bool partialRemovalOk = false);
 
  bool removeExpungedEntities(const smtk::model::EntityRefs& expungedEnts);
 
  // These methods only applies to Attributes whose
  // definition returns true for isNodal()
  bool appliesToBoundaryNodes() const { return m_appliesToBoundaryNodes; }
  void setAppliesToBoundaryNodes(bool appliesValue) { m_appliesToBoundaryNodes = appliesValue; }
  bool appliesToInteriorNodes() const { return m_appliesToInteriorNodes; }
  void setAppliesToInteriorNodes(bool appliesValue) { m_appliesToInteriorNodes = appliesValue; }
 
  const smtk::attribute::Categories& categories() const;
 
  bool isValid(bool useActiveCategories = true) const;
  bool isValid(const std::set<std::string>& categories) const;
 
  bool isRelevant(
    bool requestCatagories = true,
    bool includeReadAccess = false,
    unsigned int readAccessLevel = 0) const;
 
  smtk::attribute::ResourcePtr attributeResource() const;
  const smtk::resource::ResourcePtr resource() const override;
 
  void setUserData(const std::string& key, smtk::simulation::UserDataPtr value)
  {
    m_userData[key] = value;
  }
  smtk::simulation::UserDataPtr userData(const std::string& key) const;
  void clearUserData(const std::string& key) { m_userData.erase(key); }
  void clearAllUserData() { m_userData.clear(); }
 
  bool isAboutToBeDeleted() const { return m_aboutToBeDeleted; }
 
  const common::UUID& id() const override { return m_id; }
 
  bool setId(const common::UUID& uid) override;
 
  // These methods are use primarily by I/O operations.  The include ID corresponds to
  // the include directory information store in the attribute resource and is used
  // when writing out the resource to use include files
  void setIncludeIndex(std::size_t index) { m_includeIndex = index; }
 
  std::size_t includeIndex() const { return m_includeIndex; }
 
  // Returns true if an Evaluator can be created for this Attribute. Does not
  // indicate that evaluation would be successful if attempted. Use
  // doesEvaluate() for that information.
  bool canEvaluate() const;
 
  // If an Evaluator can be created for this Attribute, returns the result of
  // Evaluator::doesEvaluate(). Returns false if no Evaluator can be created.
  bool doesEvalaute() const;
 
  // Returns an Evaluator for this Attribute if this Attribute's Definition is
  // registered with an Evaluator, else returns nullptr.
  std::unique_ptr<smtk::attribute::Evaluator> createEvaluator() const;
 
  const std::string& units() const;
 
  const std::string& localUnits() const { return m_localUnits; }
 
  bool setLocalUnits(const std::string& newUnits);
 
  bool supportsUnits() const;
 
  class GuardedLinks
  {
  public:
    GuardedLinks(std::mutex& mutex, const smtk::resource::Component::Links& links)
      : m_guard(mutex)
      , m_links(links)
    {
    }
 
    const smtk::resource::Component::Links* operator->() const { return &m_links; }
 
    smtk::resource::Component::Links* operator->()
    {
      return const_cast<smtk::resource::Component::Links*>(&m_links);
    }
 
  private:
    std::unique_lock<std::mutex> m_guard;
    const smtk::resource::Component::Links& m_links;
  };
 
  // Attributes are uniquely used outside of an operation context, where they
  // are not guarded from concurrency issues. Specifically, ReferenceItems use
  // ResourceLinks to store references to other resources, and the
  // Resource::Links and Component::Links API is not thread-safe. This API
  // ensures thread safety when manipulating smtk::attribute::(Resource,Attribute
  // Links.
  const GuardedLinks guardedLinks() const;
  GuardedLinks guardedLinks();
 
protected:
  Attribute(
    const std::string& myName,
    const smtk::attribute::DefinitionPtr& myDefinition,
    const smtk::common::UUID& myId);
 
  void build();
 
  void removeAllItems();
  void forceDisassociate(smtk::resource::PersistentObjectPtr);
  void addItem(smtk::attribute::ItemPtr& iPtr) { m_items.push_back(iPtr); }
  void setName(const std::string& newname) { m_name = newname; }
 
  void resetId(const smtk::common::UUID& newId) { m_id = newId; }
 
  std::string m_name;
  std::vector<smtk::attribute::ItemPtr> m_items;
  ReferenceItemPtr m_associatedObjects;
  smtk::attribute::DefinitionPtr m_definition;
  bool m_appliesToBoundaryNodes;
  bool m_appliesToInteriorNodes;
  bool m_isColorSet;
  std::map<std::string, smtk::simulation::UserDataPtr> m_userData;
  // We need something to indicate that the attribute is in process of
  // being deleted - this is used skip certain clean up steps that
  // would need to be done otherwise
  bool m_aboutToBeDeleted;
  double m_color[4];
  smtk::common::UUID m_id;
  std::size_t m_includeIndex;
  bool m_hasLocalAdvanceLevelInfo[2];
  unsigned int m_localAdvanceLevel[2];
  std::string m_localUnits;
};
 
inline smtk::simulation::UserDataPtr Attribute::userData(const std::string& key) const
{
  std::map<std::string, smtk::simulation::UserDataPtr>::const_iterator it = m_userData.find(key);
  return ((it == m_userData.end()) ? smtk::simulation::UserDataPtr() : it->second);
}
 
inline void Attribute::setColor(double r, double g, double b, double a)
{
  m_isColorSet = true;
  m_color[0] = r;
  m_color[1] = g;
  m_color[2] = b;
  m_color[3] = a;
}
 
template<typename T>
T Attribute::entityRefsAs(const std::string& iname) const
{
  T result;
  ConstReferenceItemPtr itm = this->findReference(iname);
  if (!itm)
  {
    return result;
  }
 
  for (auto it = itm->begin(); it != itm->end(); ++it)
  {
    if (!it.isSet())
    {
      continue;
    }
 
    typename T::value_type entry = std::dynamic_pointer_cast<smtk::model::Entity>(*it);
    if (entry.isValid())
    {
      result.insert(result.end(), entry);
    }
  }
  return result;
}
 
template<typename T>
T Attribute::associatedObjects() const
{
  T result;
  if (!m_associatedObjects)
  {
    return result;
  }
 
  for (auto it = m_associatedObjects->begin(); it != m_associatedObjects->end(); ++it)
  {
    if (!it.isSet())
    {
      continue;
    }
 
    auto entry = std::dynamic_pointer_cast<typename T::value_type::element_type>(*it);
    if (entry)
    {
      result.insert(result.end(), entry);
    }
  }
  return result;
}
 
template<typename T>
T Attribute::associatedModelEntities() const
{
  T result;
  if (!m_associatedObjects)
  {
    return result;
  }
 
  for (auto it = m_associatedObjects->begin(); it != m_associatedObjects->end(); ++it)
  {
    if (!it.isSet())
    {
      continue;
    }
 
    typename T::value_type entry = std::dynamic_pointer_cast<smtk::model::Entity>(*it);
    if (entry.isValid())
    {
      result.insert(result.end(), entry);
    }
  }
  return result;
}
 
template<typename T>
typename T::Ptr
Attribute::itemAtPathAs(const std::string& path, const std::string& sep, bool activeOnly)
{
  return smtk::dynamic_pointer_cast<T>(this->itemAtPath(path, sep, activeOnly));
}
 
template<typename T>
typename T::ConstPtr
Attribute::itemAtPathAs(const std::string& path, const std::string& sep, bool activeOnly) const
{
  return smtk::dynamic_pointer_cast<const T>(this->itemAtPath(path, sep, activeOnly));
}
 
template<typename T>
typename T::Ptr Attribute::findAs(const std::string& iname, SearchStyle style)
{
  return smtk::dynamic_pointer_cast<T>(this->find(iname, style));
}
 
template<typename T>
typename T::ConstPtr Attribute::findAs(const std::string& iname, SearchStyle style) const
{
  return smtk::dynamic_pointer_cast<const T>(this->find(iname, style));
}
 
template<typename T>
void Attribute::filterItems(
  T& filtered,
  std::function<bool(typename T::value_type)> test,
  bool activeChildren)
{
  // Given an item, this lambda function which would recursively visit all children and apply test function
  std::function<void(ItemPtr, bool)> visitor =
    [&filtered, test, &visitor](smtk::attribute::ItemPtr item, bool activeChildrenLocal) {
      typename T::value_type testItem =
        smtk::dynamic_pointer_cast<typename T::value_type::element_type>(item);
      // base condition
      if (testItem && test(testItem))
      {
        filtered.insert(filtered.end(), testItem);
      }
      // Only items which have children would have a non-empty visitChildren method
      item->visitChildren(visitor, activeChildrenLocal);
    };
 
  for (std::size_t index = 0; index < this->numberOfItems(); ++index)
  {
    visitor(this->item(static_cast<int>(index)), activeChildren);
  }
}
 
} // namespace attribute
} // namespace smtk
 
#endif /* smtk_attribute_Attribute_h */