daeIDRef.h 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
  1. /*
  2. * Copyright 2006 Sony Computer Entertainment Inc.
  3. *
  4. * Licensed under the MIT Open Source License, for details please see license.txt or the website
  5. * http://www.opensource.org/licenses/mit-license.php
  6. *
  7. */
  8. #ifndef __DAE_IDREF_H__
  9. #define __DAE_IDREF_H__
  10. #include <string>
  11. #include <dae/daeTypes.h>
  12. #include <dae/daeElement.h>
  13. class DAE;
  14. /**
  15. * The @c daeIDRef is a simple class designed to aid in the parsing and resolution of
  16. * ID references inside of COLLADA elements.
  17. * A @c daeIDRef is created for every IDREF data type in the COLLADA schema.
  18. * It also has the capability to attempt to resolve this reference
  19. * into a @c daeElement. If a @c daeIDRef is stored within a @c daeElement it fills
  20. * in its container field to point to the containing element.
  21. *
  22. * The main API is the @c daeIDRef::resolveElement() will use a @c daeIDRefResolver
  23. * to search for the @c daeElement inside of a @c daeDatabase.
  24. *
  25. */
  26. class DLLSPEC daeIDRef
  27. {
  28. public:
  29. /**
  30. * An enum describing the status of the ID resolution process.
  31. */
  32. enum ResolveState{
  33. /** No ID specified */
  34. id_empty,
  35. /** ID specified but not resolved */
  36. id_loaded,
  37. /** ID resolution pending */
  38. id_pending,
  39. /** ID resolved correctly */
  40. id_success,
  41. /** Resolution failed because ID was not found */
  42. id_failed_id_not_found,
  43. /** Resolution failed because ID was invalid */
  44. id_failed_invalid_id,
  45. /** Resoltion failed due to invalid reference */
  46. id_failed_invalid_reference,
  47. /** Resolution failed due to an external error */
  48. id_failed_externalization,
  49. /** Resolution failed because we don't have a document in which to search for the element.
  50. This means you probably forgot to set a container element. */
  51. id_failed_no_document
  52. };
  53. private:
  54. /** ID used to refer to another element */
  55. std::string id;
  56. /** Element that owns this ID (if any) */
  57. daeElement* container;
  58. public:
  59. /**
  60. * Simple Constructor
  61. */
  62. daeIDRef();
  63. /**
  64. * Constructs an id reference via a string, using @c setID(); loads the status.
  65. * @param id ID to construct a reference for, passed to @c setID() automatically.
  66. */
  67. daeIDRef(daeString id);
  68. /**
  69. * Constructs a new id reference by copying an existing one.
  70. * @param constructFromIDRef @c daeIDRef to copy into this one.
  71. */
  72. daeIDRef(const daeIDRef& constructFromIDRef);
  73. /**
  74. * Constructs an id reference with a container element
  75. * @param container The container element.
  76. */
  77. daeIDRef(daeElement& container);
  78. /**
  79. * Gets the ID string
  80. * @return Returns the full ID string from <tt><i>id.</i></tt>
  81. */
  82. daeString getID() const;
  83. /**
  84. * Copies <tt><i>ID</i></tt> into the <tt><i>id </i></tt> data member.
  85. * After the call to @c setID(), the <tt><i>state</i></tt> is set to @c id_loaded
  86. * @param ID String to use to configure this @c daeIDRef.
  87. */
  88. void setID(daeString ID);
  89. /**
  90. * Gets the element that this URI resolves to in memory.
  91. * @return Returns a ref to the element.
  92. */
  93. daeElement* getElement() const;
  94. /**
  95. * Gets a pointer to the @c daeElement that contains this URI.
  96. * @return Returns the pointer to the containing daeElmement.
  97. */
  98. daeElement* getContainer() const;
  99. /**
  100. * Sets the pointer to the @c daeElement that contains this URI.
  101. * @param cont Pointer to the containing @c daeElmement.
  102. */
  103. void setContainer(daeElement* cont);
  104. /**
  105. * Outputs all components of this @c daeIDRef to stderr.
  106. */
  107. void print();
  108. /**
  109. * Resets this @c daeIDRef; frees all string references
  110. * and returns <tt><i>state</i></tt> to @c empty.
  111. */
  112. void reset();
  113. /**
  114. * Initializes the @c daeIDREf, setting <tt><i>id, element,</i></tt> and <tt><i>container</i></tt> to NULL.
  115. */
  116. void initialize();
  117. /**
  118. * Comparison operator.
  119. * @return Returns true if URI's are equal.
  120. */
  121. bool operator==(const daeIDRef& other) const;
  122. /**
  123. * Assignment operator.
  124. * @return Returns a reference to this object.
  125. */
  126. daeIDRef &operator=( const daeIDRef& other);
  127. // These methods are only provided for backwards compatibility. Use the listed alternatives.
  128. daeIDRef &get( daeUInt idx ); // Never should have existed. No alternative.
  129. size_t getCount() const; // Never should have existed. No alternative.
  130. daeIDRef& operator[](size_t index); // Never should have existed. No alternative.
  131. void resolveElement( daeString typeNameHint = NULL ); // Call getElement. No separate "resolve" step needed.
  132. void resolveID(); // Never should have existed. No alternative.
  133. void validate(); // Never should have existed. No alternative.
  134. void copyFrom(const daeIDRef& from); // Use the assignment operator instead.
  135. ResolveState getState() const; // Never should have existed. No alternative.
  136. };
  137. /**
  138. * The @c daeIDRefResolver class is the plugin point for @c daeIDRef resolution.
  139. * This class is an abstract base class that defines an interface for
  140. * resolving @c daeIDRefs.
  141. */
  142. class DLLSPEC daeIDRefResolver
  143. {
  144. public:
  145. /**
  146. * Constructor
  147. */
  148. daeIDRefResolver(DAE& dae);
  149. /**
  150. * Destructor
  151. */
  152. virtual ~daeIDRefResolver();
  153. /**
  154. * Provides an abstract interface to convert a @c daeIDRef into a @c daeElement.
  155. * @param id The ID of the element to find.
  156. * @param doc The document containing the element.
  157. * @return Returns a daeElement with matching ID, if one is found.
  158. */
  159. virtual daeElement* resolveElement(const std::string& id, daeDocument* doc) = 0;
  160. /**
  161. * Gets the name of this resolver.
  162. * @return Returns the string name.
  163. */
  164. virtual daeString getName() = 0;
  165. protected:
  166. DAE* dae;
  167. };
  168. /**
  169. * The @c daeDefaultIDRefResolver resolves a @c daeIDRef by checking with a database.
  170. * It is a concrete implementation for @c daeIDRefResolver.
  171. */
  172. class DLLSPEC daeDefaultIDRefResolver : public daeIDRefResolver
  173. {
  174. public:
  175. daeDefaultIDRefResolver(DAE& dae);
  176. ~daeDefaultIDRefResolver();
  177. virtual daeElement* resolveElement(const std::string& id, daeDocument* doc);
  178. virtual daeString getName();
  179. };
  180. // This is a container class for storing a modifiable list of daeIDRefResolver objects.
  181. class DLLSPEC daeIDRefResolverList {
  182. public:
  183. daeIDRefResolverList();
  184. ~daeIDRefResolverList();
  185. void addResolver(daeIDRefResolver* resolver);
  186. void removeResolver(daeIDRefResolver* resolver);
  187. daeElement* resolveElement(const std::string& id, daeDocument* doc);
  188. private:
  189. // Disabled copy constructor/assignment operator
  190. daeIDRefResolverList(const daeIDRefResolverList& resolverList) { };
  191. daeIDRefResolverList& operator=(const daeIDRefResolverList& resolverList) { return *this; };
  192. daeTArray<daeIDRefResolver*> resolvers;
  193. };
  194. #endif //__DAE_IDREF_H__