spyXmlBlock.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 2006 MaK Technologies, Inc.
 ** All rights reserved.
 *********************************************************************/
/*******************************************************************************
 ** $RCSfile: spyXmlBlock.h,v $ $Revision: 1.8 $ $State: Exp $
 *******************************************************************************/
#ifndef DtSpyXmlBlock_H_
#define DtSpyXmlBlock_H_

#include <rtiMsConfig.h>
#include <mtl/env.h>
#include "spyXmlBlockElements.h"
#include <vlutil/vlSmartPointers.h>
#include <vlutil/vlString.h>
#include <iosfwd>
#include <set>

// Forward Declarations
class DtSpyXmlBlock;
template< typename Key, typename Product, typename ProductCreatorParameter > class DtPluggableFactory;

typedef DtBoost::shared_ptr<DtSpyXmlBlock> DtSpyXmlBlockSP;
typedef DtBoost::weak_ptr<DtSpyXmlBlock>   DtSpyXmlBlockWP;
typedef std::set< DtSpyXmlBlockSP >        DtSpyXmlBlockSet;
typedef DtSpyXmlBlockSP (*DtSpyXmlBlockCreator)(MAKRti::DtEnvValueSP node);


class DT_DLL_WWW DtSpyXmlBlock
{
public:
   // TODO: Create a real exception class
   typedef MAKRti::DtString DtXMLParseError;

   // XmlSpyBlocks should register themselves with the factory, with a creator
   // which takes a pointer to their XML node and the creating parent's node (if any)
   typedef std::pair< MAKRti::DtEnvValueSP, MAKRti::DtEnvValueSP > DtNodeAndParentPair;


   // Create a new DtSpyXmlBlock from its XML representation
   static DtSpyXmlBlockSP create( MAKRti::DtEnvValueSP node, MAKRti::DtEnvValueSP parent );

   // Is this node of a type with a registered factory creator?
   static bool isCreatable( MAKRti::DtEnvValueSP node );

public:

   // Construct a basic container block
   // (must create a derived block if block has attributes)
   DtSpyXmlBlock( const MAKRti::DtString& name, const MAKRti::DtString& type, MAKRti::DtEnvValueSP parent );
   DtSpyXmlBlock( const DtSpyXmlBlock& orig );

   // Unless this node type is not registered with the factory, caller should
   // use the factory creator method when constructing from XML
   DtSpyXmlBlock( MAKRti::DtEnvValueSP node, MAKRti::DtEnvValueSP parent );

   // Assignment operator
   DtSpyXmlBlock& operator=( const DtSpyXmlBlock& orig );

   // Destructor
   virtual ~DtSpyXmlBlock();

   // Get the block name
   inline const MAKRti::DtString& name() const;

   // Get the block type
   inline const MAKRti::DtString& type() const;

   // Get a pointer to the Node's XML rep.
   inline MAKRti::DtEnvValueSP objectNode() const;

   // Add a pointer to a new child block keyed by its specific type
   inline void addChild( DtSpyXmlBlockSP child );

   // Remove all pointers to a child block
   inline void removeChild( DtSpyXmlBlockSP child );

   // Get a list of all child blocks
   inline const DtSpyXmlBlockSet& children() const;
   inline DtSpyXmlBlockSet& children();

   // Get a list of all child blocks by type (may be slow - creates a new sub-list)
   virtual DtSpyXmlBlockSet childrenByType( const MAKRti::DtString& type ) const;

   // Get a specific child by name and type
   virtual DtSpyXmlBlockSP lookupChild( const MAKRti::DtString& name, const MAKRti::DtString& type ) const;

   // Get a list of elements contained by the block
   // (ie - the block's xml attributes and simple (non-block) sub-elements)
   inline const DtSpyXmlBlockElementsSet& subElements() const;
   inline DtSpyXmlBlockElementsSet& subElements();

   // Output
   virtual std::ostream& print( std::ostream& ostr ) const;

public:
   
   // Helper method to get children of a specific type
   template< typename SpyXmlBlockType >
   static std::set< DtBoost::shared_ptr<SpyXmlBlockType> > getChildrenOfType(
      const MAKRti::DtString& type, const DtSpyXmlBlock& block );

   // Helper method to lookup a child of a specific type by name
   template< typename SpyXmlBlockType >
   DtBoost::shared_ptr<SpyXmlBlockType> getChildByName( const MAKRti::DtString& name,
      const MAKRti::DtString& type, const DtSpyXmlBlock& block );

protected:

   // Output
   virtual std::ostream& printAttributes( std::ostream& ostr ) const;
   virtual std::ostream& printElements( std::ostream& ostr ) const;

protected:

   // IMPORTANT: The following functions must not be made virtual.  They 
   //            are used in initializer lists of derived blocks.

   // Add a new sub-element 
   // NOTE: generally it is best to make sub-elements members of derived blocks
   inline void addSubElement( DtSpyXmlBlockElements* element );

   // Remove a sub-element
   // NOTE: only use this for sub-elements added using add above
   inline void removeSubElement( DtSpyXmlBlockElements* element );

   // Reads the block's contained xml at construct time and populates the list of children
   void createChildren();

   // Direct access to the XML environment:
   // Note: sub-elements cannot have names or attributes otherwise they should be full children
   MAKRti::DtEnvValueSP findElement( const MAKRti::DtString& type );
   MAKRti::DtEnvValueSP findAttribute(  const MAKRti::DtString& name );
   MAKRti::DtEnvValueSP addElement( const MAKRti::DtString& type, const MAKRti::DtString& initialValue );
   MAKRti::DtEnvValueSP addAttribute(  const MAKRti::DtString& name, const MAKRti::DtString& initialValue );
   MAKRti::DtEnvValueSP removeElement( const MAKRti::DtString& type );
   MAKRti::DtEnvValueSP removeAttribute(  const MAKRti::DtString& name );
   MAKRti::DtEnvValueSP addComment(  const MAKRti::DtString& comment );

protected:

   // The DtFactory is a helper class that allows callers
   // to construct DtSpyXmlBlocks by name from their XML representation
   // 
   // USE: Sub-class DtSpyXmlBlocks should derive from DtPluggableFactoryProduct
   //      ex. class DtDerivedXmlSpyBlock : public 
   //             DtPluggableFactoryProduct< DtSpyXmlBlock, DtDerivedXmlSpyBlock >
   //      This will ensure that the sub-class blocks are registered with the factory.
   typedef DtPluggableFactory< MAKRti::DtString, DtSpyXmlBlock, DtNodeAndParentPair > DtFactory; 

protected:

   friend class DtSpyXmlBlockElements;

   MAKRti::DtString          myName;
   MAKRti::DtString          myType;
   MAKRti::DtEnvValueSP      myObjectNode; 
   MAKRti::DtEnvValueSP      myParentNode;
   DtSpyXmlBlockSet          myChildren;
   DtSpyXmlBlockElementsSet  myXmlElements;

   // Local xml env is rooted at the parent node, must be mutable
   // since environment has local settings that may change (myEnvironment
   // is stored only for convenience rather than creating it locally every time)
   mutable MAKRti::DtEnvironment myEnvironment;
};


inline std::ostream& operator<<( std::ostream& ostr, const DtSpyXmlBlock& block )
{
   return block.print( ostr );
}

const MAKRti::DtString& DtSpyXmlBlock::name() const
{
   return myName;
}

const MAKRti::DtString& DtSpyXmlBlock::type() const
{
   return myType;
}

MAKRti::DtEnvValueSP DtSpyXmlBlock::objectNode() const
{
   return myObjectNode;
}

void DtSpyXmlBlock::addChild( DtSpyXmlBlockSP child )
{
   // Need to re-parent to the child node if it is currently rooted to a different parent
   MAKRti::DtEnvValueSP childNode = child->objectNode();
   if ( childNode->parent() != myObjectNode )
   {
      myEnvironment.reparent( childNode, myObjectNode );
   }

   myChildren.insert( child );
}

void DtSpyXmlBlock::removeChild( DtSpyXmlBlockSP child )
{
   myChildren.erase( child );
   myEnvironment.remove( child->objectNode() );
}

const DtSpyXmlBlockSet& DtSpyXmlBlock::children() const
{
   return myChildren;
}

DtSpyXmlBlockSet& DtSpyXmlBlock::children()
{
   return myChildren;
}

void DtSpyXmlBlock::addSubElement( DtSpyXmlBlockElements* element )
{
   myXmlElements.insert( element );
}

void DtSpyXmlBlock::removeSubElement( DtSpyXmlBlockElements* element )
{
   myXmlElements.erase( element );
   myEnvironment.remove( element->xmlNode() );
}

const DtSpyXmlBlockElementsSet& DtSpyXmlBlock::subElements() const
{
   return myXmlElements;
}

DtSpyXmlBlockElementsSet& DtSpyXmlBlock::subElements()
{
   return myXmlElements;
}

template< typename SpyXmlBlockType >
std::set< DtBoost::shared_ptr<SpyXmlBlockType> > DtSpyXmlBlock::getChildrenOfType(
   const MAKRti::DtString& type, const DtSpyXmlBlock& block )
{
   std::set< DtBoost::shared_ptr<SpyXmlBlockType> > childrenOfType;
   DtSpyXmlBlockSet::const_iterator iter   = block.children().begin();
   DtSpyXmlBlockSet::const_iterator theEnd = block.children().end();
   for ( iter; iter != theEnd; ++iter )
   {
      if ( (*iter)->type() == type )
      {
         DtBoost::shared_ptr< SpyXmlBlockType > child =
            DtBoost::dynamic_pointer_cast<SpyXmlBlockType>( *iter );
         if ( child )
         {
            childrenOfType.insert( child );
         }
      }
   }
   return childrenOfType;
}

template< typename SpyXmlBlockType >
DtBoost::shared_ptr<SpyXmlBlockType> DtSpyXmlBlock::getChildByName(
   const MAKRti::DtString& name, const MAKRti::DtString& type, const DtSpyXmlBlock& block )
{
   DtBoost::shared_ptr<SpyXmlBlockType> child;
   DtSpyXmlBlockSet::const_iterator iter   = block.children().begin();
   DtSpyXmlBlockSet::const_iterator theEnd = block.children().end();
   for ( iter; iter != theEnd; ++iter )
   {
      if ( (*iter)->name() == name  && (*iter)->type() == type )
      {
         child = DtBoost::dynamic_pointer_cast<SpyXmlBlockType>( *iter );
         break;
      }
   }
   return child;
}


#endif // DtSpyXmlBlock_H_