1 // IPersistant.h 2 // * PURPOSE 3 // Interface to be implemented by objects that want to 4 // be persistent (loadable/savable) via XML. 5 // 6 // * TO DO +++++ IN PROGRESS 8jul99 7 // - Make the export API friendlier: classes shouldn't have to 8 // know how to format XML, and it should be easy to extend 9 // the serialization capabilities in a subclass. [8jul99] 10 // * should this stuff be exposed via ExportContext methods? 11 // 12 // - FBC stuffing? [29jun99] 13 // 14 // * HISTORY 15 // e.moon 29jun99 Reworking; merging with the interface 16 // formerly known as Condenser. 17 // e.moon 28jun99 Begun 18 19 #ifndef __IPersistent_H__ 20 #define __IPersistent_H__ 21 22 #include "ImportContext.h" 23 #include "ExportContext.h" 24 25 #include <ostream.h> 26 27 #include "cortex_defs.h" 28 __BEGIN_CORTEX_NAMESPACE 29 30 class IPersistent { 31 32 public: 33 // empty virtual dtor 34 virtual ~IPersistent() {} 35 36 public: // *** REQUIRED INTERFACE 37 38 // 8jul99 export rework 39 // // EXPORT: 40 // // write an XML representation of this object (including 41 // // any child objects) to the given stream. use the 42 // // provided context object to format the output nicely. 43 // 44 // virtual void xmlExport( 45 // ostream& stream, 46 // ExportContext& context) const =0; 47 48 // EXPORT: 49 // implement this method to write a start tag via 50 // context.startElement(). You can also write comments or 51 // processing instructions directly to the stream. 52 53 virtual void xmlExportBegin( 54 ExportContext& context) const=0; 55 56 // EXPORT: 57 // implement this method to write all the attributes needed 58 // to represent your object, via context.writeAttribute(). 59 // (If subclassing an IPersistent implementation, don't forget 60 // to call up to its version of this method.) 61 62 virtual void xmlExportAttributes( 63 ExportContext& context) const=0; 64 65 // EXPORT: optional 66 // implement this method to write any child objects, using 67 // context.writeObject(). You can also write text content 68 // directly to the stream. 69 // (If subclassing an IPersistent implementation, don't forget 70 // to call up to its version of this method.) 71 72 virtual void xmlExportContent( 73 ExportContext& context) const { TOUCH(context); } 74 75 // EXPORT: 76 // implement this method to write an end tag via 77 // context.endElement(). 78 79 virtual void xmlExportEnd( 80 ExportContext& context) const=0; 81 82 // IMPORT: 83 // called when the start tag of the element corresponding to 84 // this object is encountered, immediately after this object 85 // is constructed. no action is required. 86 // 87 // context.element() will return the element name that produced 88 // this object. 89 90 virtual void xmlImportBegin( 91 ImportContext& context) =0; 92 93 // IMPORT: 94 // called for each attribute/value pair found in 95 // the element corresponding to this object. 96 97 virtual void xmlImportAttribute( 98 const char* key, 99 const char* value, 100 ImportContext& context) =0; 101 102 // IMPORT: 103 // called when character data is encountered for the 104 // element corresponding to this object. data is not 105 // 0-terminated; this method may be called several times 106 // (if, for example, the character data is broken up 107 // by child elements.) 108 109 virtual void xmlImportContent( 110 const char* data, 111 uint32 length, 112 ImportContext& context) =0; 113 114 // IMPORT: 115 // called when an object has been successfully 116 // constructed 'beneath' this one. 117 // 118 // context.element() will return the element name corresponding 119 // to the child object. 120 121 virtual void xmlImportChild( 122 IPersistent* child, 123 ImportContext& context) =0; 124 125 // IMPORT: 126 // called when close tag is encountered for the element 127 // corresponding to this object. a good place to do 128 // validation. 129 // 130 // context.element() will return the element name that produced 131 // this object. 132 133 virtual void xmlImportComplete( 134 ImportContext& context) =0; 135 136 public: // *** OPTIONAL CHILD-IMPORT INTERFACE 137 // These methods allow an IPersistent object 138 // to directly import nested elements: handy for 139 // condensing more complicated document structures 140 // into a single object (see MediaFormatIO for an 141 // example.) 142 143 virtual void xmlImportChildBegin( 144 const char* name, 145 ImportContext& context) { 146 TOUCH(name); 147 context.reportWarning("Nested element not supported."); 148 } 149 150 virtual void xmlImportChildAttribute( 151 const char* key, 152 const char* value, 153 ImportContext& context) {TOUCH(key); TOUCH(value); TOUCH(context);} 154 155 virtual void xmlImportChildContent( 156 const char* data, 157 uint32 length, 158 ImportContext& context) {TOUCH(data); TOUCH(length); TOUCH(context);} 159 160 virtual void xmlImportChildComplete( 161 const char* name, 162 ImportContext& context) {TOUCH(name); TOUCH(context);} 163 }; 164 165 __END_CORTEX_NAMESPACE 166 167 #endif /*__IPersistent_H__*/ 168