src/apps/cortex/Persistence/XML.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 // XML.h
  33 // * PURPOSE
  34 //   A central access point for Cortex's XML import/export
  35 //   services.  A completely static class.
  36 //
  37 // * RESPONSIBILITIES
  38 //   - Maintain a set of XML::DocumentType objects, each
  39 //     containing the information needed to import a particular
  40 //     kind of XML document into native objects.
  41 //
  42 //   - Provide a simple API for importing and exporting
  43 //     IPersistent objects from/to streams.
  44 //
  45 // * HISTORY
  46 //   e.moon             4oct99          API changes:
  47 //                                                                                      - BDataIO used in place of standard streams.
  48 //                                                                                      - Factory folded into XML::DocumentType
  49 //
  50 //   e.moon             29jun99         Begun
  51
  52 #ifndef __XML_H__
  53 #define __XML_H__
  54
  55 #include "IPersistent.h"
  56 #include "XMLElementMapping.h"
  57
  58 #include <map>
  59 #include <set>
  60
  61 #include <DataIO.h>
  62 #include <Locker.h>
  63 #include <Mime.h>
  64 #include <String.h>
  65
  66 #include "cortex_defs.h"
  67 __BEGIN_CORTEX_NAMESPACE
  68
  69 class Importer;
  70
  71 // -------------------------------------------------------- //
  72 // class XML
  73 // -------------------------------------------------------- //
  74
  75 class XML {
  76         // internal import helper
  77         friend class Importer;
  78
  79 public:                                                                                                 // *** types
  80         class DocumentType;
  81
  82 public:                                                                                                 // *** document type operations
  83
  84         // takes responsibility for the given type object
  85         static void AddDocumentType(
  86                 XML::DocumentType*                                      type);
  87
  88 public:                                                                                                 // *** import/export operations
  89
  90         // identify object in stream.
  91         // returns:
  92         // - B_OK on success, or
  93         // - B_BAD_TYPE if no document type matches the root
  94         //   element of the stream, or
  95         // - B_IO_ERROR if the document is malformed, or if a
  96         //   read error occurs.
  97
  98         static status_t Identify(
  99                 BDataIO*                                                                                stream,
 100                 DocumentType**                                                  outType,
 101                 std::list<BString>*                                             outErrors);
 102
 103         // create & populate the root object from the given
 104         // XML stream.
 105         // returns:
 106         // - B_OK on success, or
 107         // - B_IO_ERROR if the document is malformed, or if a
 108         //   read error occurs, or
 109         // - B_ERROR
 110
 111         static status_t Read(
 112                 BDataIO*                                                                                stream,
 113                 IPersistent**                                                           outObject,
 114                 std::list<BString>*                                             outErrors);
 115
 116         static status_t Read(
 117                 BDataIO*                                                                                stream,
 118                 IPersistent**                                                           outObject,
 119                 ImportContext*                                                  context); //nyi
 120
 121         // [e.moon 26nov99]
 122         // populate the provided root object from the given
 123         // XML stream.  you need to provide a document type
 124         // that corresponds to the given object.
 125         // returns:
 126         // - B_OK on success, or
 127         // - B_IO_ERROR if the document is malformed, or if a
 128         //   read error occurs, or
 129         // - B_ERROR
 130
 131         static status_t Read(
 132                 BDataIO*                                                                                stream,
 133                 IPersistent*                                                            rootObject,
 134                 XML::DocumentType*                                      documentType,
 135                 std::list<BString>*                                             outErrors);
 136
 137         static status_t Read(
 138                 BDataIO*                                                                                stream,
 139                 IPersistent*                                                            rootObject,
 140                 XML::DocumentType*                                      documentType,
 141                 ImportContext*                                                  context);
 142
 143         // create an ExportContext and use it to write the given object
 144         // to the given stream
 145
 146         static status_t Write(
 147                 BDataIO*                                                                                stream,
 148                 IPersistent*                                                            object,
 149                 BString*                                                                                outError);
 150
 151 private:                                                                                                // static members
 152
 153         typedef std::map<BString, DocumentType*> doc_type_map;
 154
 155         static doc_type_map                                             s_docTypeMap;
 156         static BLocker                                                          s_docTypeLock;
 157
 158 private:                                                                                                // implementation
 159         static status_t _DoRead(
 160                 BDataIO*                                                                                stream,
 161                 Importer&                                                                               i,
 162                 std::list<BString>*                                             outErrors); //nyi
 163 };
 164
 165 // -------------------------------------------------------- //
 166 // class XML::DocumentType
 167 // -------------------------------------------------------- //
 168
 169 class XML::DocumentType {
 170 public:                                                                                                 // *** constant members
 171         const BString                                                                   rootElement;
 172         const BMimeType                                                         mimeType;
 173
 174         static const BMimeType                          s_defaultMimeType;
 175
 176 public:                                                                                                 // *** ctor/dtors
 177         virtual ~DocumentType();
 178
 179         DocumentType(
 180                 const char*                                                                     _rootElement,
 181                 const char*                                                                     _mimeType=0);
 182
 183 public:                                                                                                 // *** 'factory' interface
 184
 185         // The DocumentType takes ownership of the given mapping
 186         // object.  If a mapping for the element already exists,
 187         // the provided object is deleted and the method returns
 188         // B_NAME_IN_USE.
 189         virtual status_t addMapping(
 190                 XMLElementMapping*                                      mapping);
 191
 192         // returns 0 if no mapping found for the given element
 193         virtual IPersistent* objectFor(
 194                 const char*                                                                     element);
 195
 196 private:                                                                                                // implementation
 197
 198         typedef std::set<XMLElementMapping*, _mapping_ptr_less> mapping_set;
 199         mapping_set                                                                             m_mappingSet;
 200 };
 201
 202 __END_CORTEX_NAMESPACE
 203
 204 #endif /*__XML_H__*/