src/apps/cortex/Persistence/Importer.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 // Importer.h
  33 //
  34 // * PURPOSE
  35 //   Given a stream of XML parser events, produce the object[s]
  36 //   represented by the markup.
  37 //
  38 // * HISTORY
  39 //   e.moon             30jun99   Moved actual object-building responsibility
  40 //                      to IPersistent; this class is now internal
  41 //                      to Cortex::XML.
  42 //   e.moon             28jun99         Begun.  [was 'Importer']
  43
  44 #ifndef __Importer_H__
  45 #define __Importer_H__
  46
  47 #include <list>
  48 #include <String.h>
  49
  50 #include "ImportContext.h"
  51 #include "XML.h"
  52 #include "expat.h"
  53
  54 #include "cortex_defs.h"
  55 __BEGIN_CORTEX_NAMESPACE
  56
  57 class Importer {
  58
  59 public:                                                                                                 // *** ctor/dtor
  60         virtual ~Importer();
  61
  62         // constructs a format-guessing Importer (uses the
  63         // DocumentType registry)
  64         Importer(
  65                 std::list<BString>&                                             errors);
  66
  67         // the Importer takes ownership of the given context!
  68         Importer(
  69                 ImportContext*                                                  context);
  70
  71         // constructs a manual Importer; the given root
  72         // object is populated
  73         Importer(
  74                 std::list<BString>&                                             errors,
  75                 IPersistent*                                                            rootObject,
  76                 XML::DocumentType*                                      docType);
  77
  78         // the Importer takes ownership of the given context!
  79         Importer(
  80                 ImportContext*                                                  context,
  81                 IPersistent*                                                            rootObject,
  82                 XML::DocumentType*                                      docType);
  83
  84 public:                                                                                                 // *** accessors
  85
  86         // the import context
  87         const ImportContext& context() const;
  88
  89         // matched document type
  90         XML::DocumentType* docType() const;
  91
  92         // completed object (available if
  93         // context().state() == ImportContext::COMPLETE, or
  94         // if a root object was provided to the ctor)
  95         IPersistent* target() const;
  96
  97 public:                                                                                                 // *** operations
  98
  99         // put the importer into 'identify mode'
 100         // (disengaged once the first element is encountered)
 101         void setIdentifyMode();
 102
 103         // prepare to read the document after an identify cycle
 104         void reset();
 105
 106         // handle a buffer; return false if an error occurs
 107         bool parseBuffer(
 108                 const char*                                                                     buffer,
 109                 uint32                                                                                  length,
 110                 bool                                                                                            last);
 111
 112 public:                                                                                                 // *** internal operations
 113
 114         // create & initialize parser
 115         void initParser();
 116
 117         // clean up the parser
 118         void freeParser();
 119
 120 public:                                                                                                 // *** XML parser event hooks
 121
 122         virtual void xmlElementStart(
 123                 const char*                                                                     name,
 124                 const char**                                                            attributes);
 125
 126         virtual void xmlElementEnd(
 127                 const char*                                                                     name);
 128
 129         virtual void xmlProcessingInstruction(
 130                 const char*                                                                     target,
 131                 const char*                                                                     data);
 132
 133         // not 0-terminated
 134         virtual void xmlCharacterData(
 135                 const char*                                                                     data,
 136                 int32                                                                                           length);
 137
 138         // not 0-terminated
 139         virtual void xmlDefaultData(
 140                 const char*                                                                     data,
 141                 int32                                                                                           length);
 142
 143 private:                                                                                                // *** implementation
 144
 145         XML_Parser                                                                              m_parser;
 146         XML::DocumentType*                                              m_docType;
 147
 148         // if true, the importer is being used to identify the
 149         // document type -- it should halt as soon as the first
 150         // element is encountered.
 151         bool                                                                                                    m_identify;
 152
 153         ImportContext* const                                    m_context;
 154
 155         // the constructed object: if no rootObject was provided
 156         // in the ctor, this is only filled in once the document
 157         // end tag has been encountered.
 158         IPersistent*                                                                    m_rootObject;
 159 };
 160
 161 __END_CORTEX_NAMESPACE
 162 #endif /*__Importer_H__*/