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