src/Storage/Storage_Schema.hxx

   1 // Created on: 1996-12-03
   2 // Created by: Christophe LEYNADIER
   3 // Copyright (c) 1996-1999 Matra Datavision
   4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 //
   6 // This file is part of Open CASCADE Technology software library.
   7 //
   8 // This library is free software; you can redistribute it and/or modify it under
   9 // the terms of the GNU Lesser General Public License version 2.1 as published
  10 // by the Free Software Foundation, with special exception defined in the file
  11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 // distribution for complete text of the license and disclaimer of any warranty.
  13 //
  14 // Alternatively, this file may be used under the terms of Open CASCADE
  15 // commercial license or contractual agreement.
  16
  17 #ifndef _Storage_Schema_HeaderFile
  18 #define _Storage_Schema_HeaderFile
  19
  20 #include <Standard.hxx>
  21 #include <Standard_Type.hxx>
  22
  23 #include <Storage_MapOfCallBack.hxx>
  24 #include <Standard_Boolean.hxx>
  25 #include <TCollection_AsciiString.hxx>
  26 #include <Storage_HArrayOfSchema.hxx>
  27 #include <Standard_Transient.hxx>
  28 #include <TColStd_SequenceOfAsciiString.hxx>
  29 #include <TColStd_HSequenceOfAsciiString.hxx>
  30 #include <Storage_SolveMode.hxx>
  31 #include <Standard_CString.hxx>
  32 class Storage_CallBack;
  33 class Storage_StreamFormatError;
  34 class TCollection_AsciiString;
  35 class Storage_BaseDriver;
  36 class Storage_Data;
  37 class Storage_HeaderData;
  38 class Storage_TypeData;
  39 class Storage_RootData;
  40 class Standard_Persistent;
  41
  42
  43 class Storage_Schema;
  44 DEFINE_STANDARD_HANDLE(Storage_Schema, Standard_Transient)
  45
  46
  47 //! Root class for basic storage/retrieval algorithms.
  48 //! A Storage_Schema object processes:
  49 //! -   writing of a set of persistent data into a
  50 //! container (store mechanism),
  51 //! -   reading of a container to extract all the
  52 //! contained persistent data (retrieve mechanism).
  53 //! A Storage_Schema object is based on the data
  54 //! schema for the persistent data of the application, i.e.:
  55 //! -   the list of all persistent objects which may be
  56 //! known by the application,
  57 //! -   the organization of their data; a data schema
  58 //! knows how to browse each persistent object it contains.
  59 //! During the store or retrieve operation, only
  60 //! persistent objects known from the data schema
  61 //! can be processed; they are then stored or
  62 //! retrieved according to their description in the schema.
  63 //! A data schema is specific to the object classes to
  64 //! be read or written. Tools dedicated to the
  65 //! environment in use allow a description of the
  66 //! application persistent data structure.
  67 //! Storage_Schema algorithms are called basic
  68 //! because they do not support external references
  69 //! between containers.
  70 class Storage_Schema : public Standard_Transient
  71 {
  72
  73 public:
  74
  75
  76   //! Builds a storage/retrieval algorithm based on a
  77   //! given data schema.
  78   //! Example
  79   //! For example, if ShapeSchema is the class
  80   //! inheriting from Storage_Schema and containing
  81   //! the description of your application data schema,
  82   //! you create a storage/retrieval algorithm as follows:
  83   //! Handle(ShapeSchema) s = new
  84   //! ShapeSchema;
  85   //! -------- --
  86   //! USER API -- --------------------------------------------------------------
  87   //! -------- --
  88   Standard_EXPORT Storage_Schema();
  89
  90   //! returns version of the schema
  91   Standard_EXPORT void SetVersion (const TCollection_AsciiString& aVersion);
  92
  93   //! returns the version of the schema
  94   Standard_EXPORT TCollection_AsciiString Version() const;
  95
  96   //! set the schema's name
  97   Standard_EXPORT void SetName (const TCollection_AsciiString& aSchemaName);
  98
  99   //! returns the schema's name
 100   Standard_EXPORT TCollection_AsciiString Name() const;
 101
 102   //! Writes the data aggregated in aData into the
 103   //! container defined by the driver s. The storage
 104   //! operation is performed according to the data
 105   //! schema with which this algorithm is working.
 106   //! Note: aData may aggregate several root objects
 107   //! to be stored together.
 108   Standard_EXPORT void Write (Storage_BaseDriver& s, const Handle(Storage_Data)& aData) const;
 109
 110   //! return a current date string
 111   Standard_EXPORT static TCollection_AsciiString ICreationDate();
 112
 113   //! returns True if theType migration is identified
 114   //! the callback support provides a way to read a file
 115   //! with a incomplete schema.
 116   //! ex. : A file contains 3 types a,b and c.
 117   //! The  application's  schema  contains  only 2
 118   //! type a and b. If you try to read the file in
 119   //! the application, you  will  have an error.To
 120   //! bypass this  problem  you  can  give to your
 121   //! application's schema  a  callback  used when
 122   //! the schema dosent  know  how  to handle this
 123   //! type.
 124   Standard_EXPORT static Standard_Boolean CheckTypeMigration (const TCollection_AsciiString& theTypeName, TCollection_AsciiString& theNewName);
 125
 126   //! add two functions to the callback list
 127   Standard_EXPORT void AddReadUnknownTypeCallBack (const TCollection_AsciiString& aTypeName, const Handle(Storage_CallBack)& aCallBack);
 128
 129   //! remove a callback for a type
 130   Standard_EXPORT void RemoveReadUnknownTypeCallBack (const TCollection_AsciiString& aTypeName);
 131
 132   //! returns  a  list  of   type  name  with  installed
 133   //! callback.
 134   Standard_EXPORT Handle(TColStd_HSequenceOfAsciiString) InstalledCallBackList() const;
 135
 136   //! clear all callback from schema instance.
 137   Standard_EXPORT void ClearCallBackList();
 138
 139   //! install  a  callback  for  all  unknown  type. the
 140   //! objects with unknown types  will be skipped. (look
 141   //! SkipObject method in BaseDriver)
 142   Standard_EXPORT void UseDefaultCallBack();
 143
 144   //! tells schema to uninstall the default callback.
 145   Standard_EXPORT void DontUseDefaultCallBack();
 146
 147   //! ask if the schema is using the default callback.
 148   Standard_EXPORT Standard_Boolean IsUsingDefaultCallBack() const;
 149
 150   //! overload the  default  function  for build.(use to
 151   //! set an  error  message  or  skip  an  object while
 152   //! reading an unknown type).
 153   Standard_EXPORT void SetDefaultCallBack (const Handle(Storage_CallBack)& f);
 154
 155   //! reset  the  default  function  defined  by Storage
 156   //! package.
 157   Standard_EXPORT void ResetDefaultCallBack();
 158
 159   //! returns   the   read   function   used   when  the
 160   //! UseDefaultCallBack() is set.
 161   Standard_EXPORT Handle(Storage_CallBack) DefaultCallBack() const;
 162
 163     void WritePersistentObjectHeader (const Handle(Standard_Persistent)& sp, Storage_BaseDriver& s);
 164
 165     void WritePersistentReference (const Handle(Standard_Persistent)& sp, Storage_BaseDriver& s);
 166
 167   Standard_EXPORT Standard_Boolean AddPersistent (const Handle(Standard_Persistent)& sp, const Standard_CString tName) const;
 168
 169   Standard_EXPORT Standard_Boolean PersistentToAdd (const Handle(Standard_Persistent)& sp) const;
 170
 171
 172
 173
 174   DEFINE_STANDARD_RTTIEXT(Storage_Schema,Standard_Transient)
 175
 176 protected:
 177
 178     Standard_Boolean HasTypeBinding (const TCollection_AsciiString& aTypeName) const;
 179
 180   Standard_EXPORT void BindType (const TCollection_AsciiString& aTypeName, const Handle(Storage_CallBack)& aCallBack) const;
 181
 182   Standard_EXPORT Handle(Storage_CallBack) TypeBinding (const TCollection_AsciiString& aTypeName) const;
 183
 184
 185
 186 private:
 187
 188   Standard_EXPORT void Clear() const;
 189
 190   Standard_EXPORT static void ISetCurrentData (const Handle(Storage_Data)& dData);
 191
 192   Standard_EXPORT static Handle(Storage_Data)& ICurrentData();
 193
 194   Storage_MapOfCallBack myCallBack;
 195   Standard_Boolean myCallBackState;
 196   Handle(Storage_CallBack) myDefaultCallBack;
 197   TCollection_AsciiString myName;
 198   TCollection_AsciiString myVersion;
 199 };
 200
 201
 202 #include <Storage_Schema.lxx>
 203
 204
 205
 206
 207
 208 #endif // _Storage_Schema_HeaderFile