1 /* 2 * Copyright (c) 1999-2000, Eric Moon. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * 1. Redistributions of source code must retain the above copyright 10 * notice, this list of conditions, and the following disclaimer. 11 * 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions, and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * 3. The name of the author may not be used to endorse or promote products 17 * derived from this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR 20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 21 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 23 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 26 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 27 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 31 32 // IPersistant.h 33 // * PURPOSE 34 // Interface to be implemented by objects that want to 35 // be persistent (loadable/savable) via XML. 36 // 37 // * TO DO +++++ IN PROGRESS 8jul99 38 // - Make the export API friendlier: classes shouldn't have to 39 // know how to format XML, and it should be easy to extend 40 // the serialization capabilities in a subclass. [8jul99] 41 // * should this stuff be exposed via ExportContext methods? 42 // 43 // - FBC stuffing? [29jun99] 44 // 45 // * HISTORY 46 // e.moon 29jun99 Reworking; merging with the interface 47 // formerly known as Condenser. 48 // e.moon 28jun99 Begun 49 50 #ifndef __IPersistent_H__ 51 #define __IPersistent_H__ 52 53 #include "ImportContext.h" 54 #include "ExportContext.h" 55 56 #include <iostream> 57 58 #include "cortex_defs.h" 59 __BEGIN_CORTEX_NAMESPACE 60 61 class IPersistent { 62 63 public: 64 // empty virtual dtor 65 virtual ~IPersistent() {} 66 67 public: // *** REQUIRED INTERFACE 68 69 // 8jul99 export rework 70 // // EXPORT: 71 // // write an XML representation of this object (including 72 // // any child objects) to the given stream. use the 73 // // provided context object to format the output nicely. 74 // 75 // virtual void xmlExport( 76 // ostream& stream, 77 // ExportContext& context) const =0; 78 79 // EXPORT: 80 // implement this method to write a start tag via 81 // context.startElement(). You can also write comments or 82 // processing instructions directly to the stream. 83 84 virtual void xmlExportBegin( 85 ExportContext& context) const=0; 86 87 // EXPORT: 88 // implement this method to write all the attributes needed 89 // to represent your object, via context.writeAttribute(). 90 // (If subclassing an IPersistent implementation, don't forget 91 // to call up to its version of this method.) 92 93 virtual void xmlExportAttributes( 94 ExportContext& context) const=0; 95 96 // EXPORT: optional 97 // implement this method to write any child objects, using 98 // context.writeObject(). You can also write text content 99 // directly to the stream. 100 // (If subclassing an IPersistent implementation, don't forget 101 // to call up to its version of this method.) 102 103 virtual void xmlExportContent( 104 ExportContext& context) const { TOUCH(context); } 105 106 // EXPORT: 107 // implement this method to write an end tag via 108 // context.endElement(). 109 110 virtual void xmlExportEnd( 111 ExportContext& context) const=0; 112 113 // IMPORT: 114 // called when the start tag of the element corresponding to 115 // this object is encountered, immediately after this object 116 // is constructed. no action is required. 117 // 118 // context.element() will return the element name that produced 119 // this object. 120 121 virtual void xmlImportBegin( 122 ImportContext& context) =0; 123 124 // IMPORT: 125 // called for each attribute/value pair found in 126 // the element corresponding to this object. 127 128 virtual void xmlImportAttribute( 129 const char* key, 130 const char* value, 131 ImportContext& context) =0; 132 133 // IMPORT: 134 // called when character data is encountered for the 135 // element corresponding to this object. data is not 136 // 0-terminated; this method may be called several times 137 // (if, for example, the character data is broken up 138 // by child elements.) 139 140 virtual void xmlImportContent( 141 const char* data, 142 uint32 length, 143 ImportContext& context) =0; 144 145 // IMPORT: 146 // called when an object has been successfully 147 // constructed 'beneath' this one. 148 // 149 // context.element() will return the element name corresponding 150 // to the child object. 151 152 virtual void xmlImportChild( 153 IPersistent* child, 154 ImportContext& context) =0; 155 156 // IMPORT: 157 // called when close tag is encountered for the element 158 // corresponding to this object. a good place to do 159 // validation. 160 // 161 // context.element() will return the element name that produced 162 // this object. 163 164 virtual void xmlImportComplete( 165 ImportContext& context) =0; 166 167 public: // *** OPTIONAL CHILD-IMPORT INTERFACE 168 // These methods allow an IPersistent object 169 // to directly import nested elements: handy for 170 // condensing more complicated document structures 171 // into a single object (see MediaFormatIO for an 172 // example.) 173 174 virtual void xmlImportChildBegin( 175 const char* name, 176 ImportContext& context) { 177 TOUCH(name); 178 context.reportWarning("Nested element not supported."); 179 } 180 181 virtual void xmlImportChildAttribute( 182 const char* key, 183 const char* value, 184 ImportContext& context) {TOUCH(key); TOUCH(value); TOUCH(context);} 185 186 virtual void xmlImportChildContent( 187 const char* data, 188 uint32 length, 189 ImportContext& context) {TOUCH(data); TOUCH(length); TOUCH(context);} 190 191 virtual void xmlImportChildComplete( 192 const char* name, 193 ImportContext& context) {TOUCH(name); TOUCH(context);} 194 }; 195 196 __END_CORTEX_NAMESPACE 197 198 #endif /*__IPersistent_H__*/ 199