src/apps/cortex/Persistence/IPersistent.h

   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__*/