[occt.git] / src / Storage / Storage_Schema.cdl

-- Created on: 1996-12-03
-- Created by: Christophe LEYNADIER
-- Copyright (c) 1996-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and/or modify it under
-- the terms of the GNU Lesser General Public License version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

class Schema from Storage inherits TShared from MMgt
    	---Purpose:
    	-- Root class for basic storage/retrieval algorithms.
    	-- A Storage_Schema object processes:
    	-- -   writing of a set of persistent data into a
    	--   container (store mechanism),
    	-- -   reading of a container to extract all the
    	--   contained persistent data (retrieve mechanism).
    	-- A Storage_Schema object is based on the data
    	-- schema for the persistent data of the application, i.e.:
    	-- -   the list of all persistent objects which may be
    	--   known by the application,
    	-- -   the organization of their data; a data schema
    	--   knows how to browse each persistent object it contains.
    	--   During the store or retrieve operation, only
    	-- persistent objects known from the data schema
    	-- can be processed; they are then stored or
    	-- retrieved according to their description in the schema.
    	-- A data schema is specific to the object classes to
    	-- be read or written. Tools dedicated to the
    	-- environment in use allow a description of the
    	-- application persistent data structure.
    	-- Storage_Schema algorithms are called basic
    	-- because they do not support external references
    	-- between containers.
        
uses SequenceOfAsciiString from TColStd,
     HSequenceOfAsciiString from TColStd,
     AsciiString from TCollection,
     BaseDriver from Storage,
     Data from Storage,
     HeaderData from Storage,
     MapOfCallBack from Storage,
     CallBack from Storage,
     CallBack from Storage,
     RootData from Storage,
     TypeData from Storage,
     HArrayOfSchema from Storage,
     SolveMode from Storage

raises StreamFormatError from Storage
       
is 
 
    Create returns Schema from Storage;
    	---Purpose: Builds a storage/retrieval algorithm based on a
    	-- given data schema.
    	-- Example
    	--   For example, if ShapeSchema is the class
    	-- inheriting from Storage_Schema and containing
    	-- the description of your application data schema,
    	-- you create a storage/retrieval algorithm as follows:
    	-- Handle(ShapeSchema) s = new
    	-- ShapeSchema;
    -- -------- --
    -- USER API -- --------------------------------------------------------------
    -- -------- --

    SetVersion(me : mutable; aVersion : AsciiString from TCollection);
    ---Purpose: returns version of the schema
  
    Version(me) returns AsciiString from TCollection;
        ---Purpose: returns the version of the schema

    SetName(me : mutable; aSchemaName : AsciiString from TCollection);
        ---Purpose: set the schema's name

    Name(me) returns AsciiString from TCollection;
        ---Purpose: returns the schema's name

    Write(me; s : in out BaseDriver from Storage; 
              aData : Data from Storage);
        ---Purpose: Writes the data aggregated in aData into the
    	-- container defined by the driver s. The storage
    	-- operation is performed according to the data
    	-- schema with which this algorithm is working.
    	-- Note: aData may aggregate several root objects
    	-- to be stored together.

    Read(me; s : in out BaseDriver from Storage) 
        returns Data from Storage;
        ---Purpose:  Returns the data read from the container defined
    	-- by the driver s. The retrieval operation is
    	-- performed according to the data schema with
    	-- which this algorithm is working.
    	-- These data are aggregated in a Storage_Data
    	-- object which may be browsed in order to extract
    	-- the root objects from the container.

    ReadHeaderSection(me; s : in out BaseDriver from Storage)
        returns HeaderData from Storage;
        ---Purpose: read the header part of the stream
        --  Arguments:
        --   s: driver to read

    ReadTypeSection(me; s : in out BaseDriver from Storage) 
        returns TypeData from Storage;
        ---Purpose: fill the TypeData with the  names of the type used
        --          in a stream
        --  Arguments:
        --   s: driver to read

    ReadRootSection(me; s : in out BaseDriver from Storage) 
        returns RootData from Storage;
        ---Purpose: read root part of the file
        --  Arguments:
        --   s: driver to read

    SchemaKnownTypes(me)
    returns SequenceOfAsciiString from TColStd is virtual;
        ---C++: return const &
        ---Purpose: returns the known types of a schema

    HasUnknownType(me; aDriver         : in out BaseDriver from Storage; 
                       theUnknownTypes : out SequenceOfAsciiString from TColStd) 
        returns Boolean from Standard;
        ---Purpose: indicates whether  the  are  types  in  the driver
        --          which are not known from  the schema and for which
        --          no callbacks have been set. The unknown types can
        --          be read in <theUnknownTypes>.

    GetAllSchemaKnownTypes(me)
        returns HSequenceOfAsciiString from TColStd;
        ---Purpose: returns the all known types  of a schema and their
        --          nested schemes.

    SetNestedSchemas(me : mutable; theSchemas : HArrayOfSchema from Storage);

    ClearNestedSchemas(me : mutable);

    NestedSchemas(me) returns HArrayOfSchema from Storage;

    ICreationDate(myclass) returns AsciiString from TCollection;
        ---Purpose: return a current date string 
	
    CheckTypeMigration(myclass; theTypeName : AsciiString from TCollection; 
    	    	    	    	theNewName  : in out AsciiString from TCollection) 
        returns Boolean from Standard;		 
	---Purpose: returns True if theType migration is identified 
	
        -- --------------------------- --
        -- USER API : CALLBACK SUPPORT -- 
        -- --------------------------- -- 

        ---Purpose: the callback support provides a way to read a file
        --          with a incomplete schema.
        --          ex. : A file contains 3 types a,b and c.
        --                The  application's  schema  contains  only 2
        --                type a and b. If you try to read the file in
        --                the application, you  will  have an error.To
        --                bypass this  problem  you  can  give to your
        --                application's schema  a  callback  used when
        --                the schema dosent  know  how  to handle this
        --                type.
        ---Warning: : the callback  can  only  be used with persistent
        --          types (not with  storable  types). the constructor
        --          function  can  return  a   null  handle  the  read
        --          function can be empty

    AddReadUnknownTypeCallBack(me : mutable; 
                               aTypeName : AsciiString from TCollection; 
                               aCallBack : CallBack from Storage);
        ---Purpose: add two functions to the callback list

    RemoveReadUnknownTypeCallBack(me : mutable; 
                                  aTypeName : AsciiString from TCollection);
        ---Purpose: remove a callback for a type

    InstalledCallBackList(me)
    	returns HSequenceOfAsciiString from TColStd;
        ---Purpose: returns  a  list  of   type  name  with  installed
        --          callback.

    ClearCallBackList(me : mutable);
        ---Purpose: clear all callback from schema instance.

    UseDefaultCallBack(me : mutable);
        ---Purpose: install  a  callback  for  all  unknown  type. the
        --          objects with unknown types  will be skipped. (look
        --          SkipObject method in BaseDriver)
    
    DontUseDefaultCallBack(me : mutable);
        ---Purpose: tells schema to uninstall the default callback.

    IsUsingDefaultCallBack(me) returns Boolean from Standard;
        ---Purpose: ask if the schema is using the default callback.
    
    SetDefaultCallBack(me : mutable; f : CallBack from Storage);
        ---Purpose: overload the  default  function  for build.(use to
        --          set an  error  message  or  skip  an  object while
        --          reading an unknown type).

    ResetDefaultCallBack(me : mutable);      
        ---Purpose: reset  the  default  function  defined  by Storage
        --          package.

    DefaultCallBack(me) returns CallBack from Storage;
        ---Purpose: returns   the   read   function   used   when  the
        --          UseDefaultCallBack() is set.

    -- ---------------- --
    -- INTERNAL METHODS -- 
    -- ---------------- --

    SetNested(me : mutable) returns Boolean from Standard is private;
    IsNested(me) returns Boolean from Standard is protected;
    UnsetNested(me : mutable) returns Boolean from Standard is private;

    ResolveUnknownType(me; aTypeName : AsciiString from TCollection;
                           aPers : Persistent from Standard; 
                           aMode : SolveMode from Storage)
        returns CallBack from Storage is protected;

    CallBackSelection(me; tName : AsciiString from TCollection)
    returns CallBack from Storage is virtual;
        ---Level: Internal

    AddTypeSelection(me; sp : Persistent from Standard)
    returns CallBack from Storage is virtual;
        ---Level: Internal

    HasTypeBinding(me; aTypeName : AsciiString from TCollection)
        returns Boolean from Standard is protected;
        ---Level: Internal
        ---C++: inline

    BindType(me; aTypeName : AsciiString from TCollection; 
                 aCallBack : CallBack from Storage) is protected;
        ---Level: Internal

    TypeBinding(me; aTypeName :  AsciiString from TCollection)
        returns CallBack from Storage is protected;
        ---Level: Internal

    WritePersistentObjectHeader(me : mutable; 
                                sp : Persistent; 
                                s : in out BaseDriver from Storage);
        ---C++: inline
        ---Level: Internal

    ReadPersistentObjectHeader(me : mutable; s : in out BaseDriver from Storage);
        ---C++: inline
        ---Level: Internal

    WritePersistentReference(me : mutable; sp : Persistent; 
                                           s : in out BaseDriver from Storage);
        ---C++: inline
    ReadPersistentReference(me : mutable; sp : in out Persistent;
                                          s : in out BaseDriver from Storage);
        ---Level: Internal

    AddPersistent(me; sp : Persistent; tName : CString) returns Boolean;
        ---Level: Internal

    PersistentToAdd(me; sp : Persistent) returns Boolean;
        ---Level: Internal

    Clear(me) is private;
        ---Level: Internal

    IReadHeaderSection(me; s : in out BaseDriver from Storage;
                           iData : HeaderData from Storage) returns Boolean 
        raises StreamFormatError is private;
        ---Level: Internal

    IReadTypeSection(me; s : in out BaseDriver from Storage;
                         tData : TypeData from Storage) returns Boolean
        raises StreamFormatError is private;
        ---Level: Internal

    IReadRootSection(me; s : in out BaseDriver from Storage; 
                         rData : RootData from Storage) returns Boolean
        raises StreamFormatError is private;
        ---Level: Internal

    ISetCurrentData(myclass; dData : Data from Storage) is private;
        ---Level: Internal

    ICurrentData(myclass) returns Data from Storage is private;
        ---Level: Internal
        ---C++: return &

fields

    myCallBack           : MapOfCallBack from Storage;
    myCallBackState      : Boolean from Standard;
    myDefaultCallBack    : CallBack from Storage;

    myName               : AsciiString from TCollection;
    myVersion            : AsciiString from TCollection;
    myArrayOfSchema      : HArrayOfSchema from Storage;
    myNestedState        : Boolean from Standard;

end;
Commit	Line	Data
b311480e	1	-- Created on: 1996-12-03
	2	-- Created by: Christophe LEYNADIER
	3	-- Copyright (c) 1996-1999 Matra Datavision
973c2be1	4	-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e	5	--
973c2be1	6	-- This file is part of Open CASCADE Technology software library.
b311480e	7	--
d5f74e42	8	-- This library is free software; you can redistribute it and/or modify it under
d5f74e42	9	-- the terms of the GNU Lesser General Public License version 2.1 as published
973c2be1	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.
b311480e	13	--
973c2be1	14	-- Alternatively, this file may be used under the terms of Open CASCADE
973c2be1	15	-- commercial license or contractual agreement.
7fd59977	16
	17	class Schema from Storage inherits TShared from MMgt
	18	---Purpose:
	19	-- Root class for basic storage/retrieval algorithms.
	20	-- A Storage_Schema object processes:
	21	-- - writing of a set of persistent data into a
	22	-- container (store mechanism),
	23	-- - reading of a container to extract all the
	24	-- contained persistent data (retrieve mechanism).
	25	-- A Storage_Schema object is based on the data
	26	-- schema for the persistent data of the application, i.e.:
	27	-- - the list of all persistent objects which may be
	28	-- known by the application,
	29	-- - the organization of their data; a data schema
	30	-- knows how to browse each persistent object it contains.
	31	-- During the store or retrieve operation, only
	32	-- persistent objects known from the data schema
	33	-- can be processed; they are then stored or
	34	-- retrieved according to their description in the schema.
	35	-- A data schema is specific to the object classes to
	36	-- be read or written. Tools dedicated to the
	37	-- environment in use allow a description of the
	38	-- application persistent data structure.
	39	-- Storage_Schema algorithms are called basic
	40	-- because they do not support external references
	41	-- between containers.
	42
	43	uses SequenceOfAsciiString from TColStd,
	44	HSequenceOfAsciiString from TColStd,
	45	AsciiString from TCollection,
	46	BaseDriver from Storage,
	47	Data from Storage,
	48	HeaderData from Storage,
	49	MapOfCallBack from Storage,
	50	CallBack from Storage,
	51	CallBack from Storage,
	52	RootData from Storage,
	53	TypeData from Storage,
	54	HArrayOfSchema from Storage,
	55	SolveMode from Storage
	56
	57	raises StreamFormatError from Storage
	58
	59	is
	60
	61	Create returns Schema from Storage;
	62	---Purpose: Builds a storage/retrieval algorithm based on a
	63	-- given data schema.
	64	-- Example
	65	-- For example, if ShapeSchema is the class
	66	-- inheriting from Storage_Schema and containing
	67	-- the description of your application data schema,
	68	-- you create a storage/retrieval algorithm as follows:
	69	-- Handle(ShapeSchema) s = new
	70	-- ShapeSchema;
	71	-- -------- --
	72	-- USER API -- --------------------------------------------------------------
	73	-- -------- --
	74
	75	SetVersion(me : mutable; aVersion : AsciiString from TCollection);
	76	---Purpose: returns version of the schema
	77
	78	Version(me) returns AsciiString from TCollection;
	79	---Purpose: returns the version of the schema
80
81	SetName(me : mutable; aSchemaName : AsciiString from TCollection);
82	---Purpose: set the schema's name
83
84	Name(me) returns AsciiString from TCollection;
85	---Purpose: returns the schema's name
86
87	Write(me; s : in out BaseDriver from Storage;
6e33d3ce	88	aData : Data from Storage);
7fd59977	89	---Purpose: Writes the data aggregated in aData into the
	90	-- container defined by the driver s. The storage
	91	-- operation is performed according to the data
	92	-- schema with which this algorithm is working.
	93	-- Note: aData may aggregate several root objects
	94	-- to be stored together.
	95
	96	Read(me; s : in out BaseDriver from Storage)
6e33d3ce	97	returns Data from Storage;
7fd59977	98	---Purpose: Returns the data read from the container defined
	99	-- by the driver s. The retrieval operation is
	100	-- performed according to the data schema with
	101	-- which this algorithm is working.
	102	-- These data are aggregated in a Storage_Data
	103	-- object which may be browsed in order to extract
	104	-- the root objects from the container.
	105
	106	ReadHeaderSection(me; s : in out BaseDriver from Storage)
6e33d3ce	107	returns HeaderData from Storage;
7fd59977	108	---Purpose: read the header part of the stream
	109	-- Arguments:
	110	-- s: driver to read
	111
	112	ReadTypeSection(me; s : in out BaseDriver from Storage)
6e33d3ce	113	returns TypeData from Storage;
7fd59977	114	---Purpose: fill the TypeData with the names of the type used
	115	-- in a stream
	116	-- Arguments:
	117	-- s: driver to read
	118
	119	ReadRootSection(me; s : in out BaseDriver from Storage)
6e33d3ce	120	returns RootData from Storage;
7fd59977	121	---Purpose: read root part of the file
	122	-- Arguments:
	123	-- s: driver to read
	124
	125	SchemaKnownTypes(me)
	126	returns SequenceOfAsciiString from TColStd is virtual;
	127	---C++: return const &
	128	---Purpose: returns the known types of a schema
	129
	130	HasUnknownType(me; aDriver : in out BaseDriver from Storage;
	131	theUnknownTypes : out SequenceOfAsciiString from TColStd)
	132	returns Boolean from Standard;
	133	---Purpose: indicates whether the are types in the driver
	134	-- which are not known from the schema and for which
	135	-- no callbacks have been set. The unknown types can
	136	-- be read in <theUnknownTypes>.
	137
	138	GetAllSchemaKnownTypes(me)
	139	returns HSequenceOfAsciiString from TColStd;
	140	---Purpose: returns the all known types of a schema and their
	141	-- nested schemes.
	142
	143	SetNestedSchemas(me : mutable; theSchemas : HArrayOfSchema from Storage);
	144
	145	ClearNestedSchemas(me : mutable);
	146
	147	NestedSchemas(me) returns HArrayOfSchema from Storage;
	148
	149	ICreationDate(myclass) returns AsciiString from TCollection;
	150	---Purpose: return a current date string
	151
	152	CheckTypeMigration(myclass; theTypeName : AsciiString from TCollection;
	153	theNewName : in out AsciiString from TCollection)
	154	returns Boolean from Standard;
	155	---Purpose: returns True if theType migration is identified
	156
	157	-- --------------------------- --
	158	-- USER API : CALLBACK SUPPORT --
	159	-- --------------------------- --
	160
	161	---Purpose: the callback support provides a way to read a file
	162	-- with a incomplete schema.
	163	-- ex. : A file contains 3 types a,b and c.
	164	-- The application's schema contains only 2
	165	-- type a and b. If you try to read the file in
	166	-- the application, you will have an error.To
	167	-- bypass this problem you can give to your
	168	-- application's schema a callback used when
	169	-- the schema dosent know how to handle this
	170	-- type.
	171	---Warning: : the callback can only be used with persistent
	172	-- types (not with storable types). the constructor
	173	-- function can return a null handle the read
	174	-- function can be empty
	175
	176	AddReadUnknownTypeCallBack(me : mutable;
	177	aTypeName : AsciiString from TCollection;
	178	aCallBack : CallBack from Storage);
	179	---Purpose: add two functions to the callback list
	180
	181	RemoveReadUnknownTypeCallBack(me : mutable;
	182	aTypeName : AsciiString from TCollection);
	183	---Purpose: remove a callback for a type
	184
185	InstalledCallBackList(me)
186	returns HSequenceOfAsciiString from TColStd;
187	---Purpose: returns a list of type name with installed
188	-- callback.
189
190	ClearCallBackList(me : mutable);
191	---Purpose: clear all callback from schema instance.
192
193	UseDefaultCallBack(me : mutable);
194	---Purpose: install a callback for all unknown type. the
195	-- objects with unknown types will be skipped. (look
196	-- SkipObject method in BaseDriver)
197
198	DontUseDefaultCallBack(me : mutable);
199	---Purpose: tells schema to uninstall the default callback.
200
201	IsUsingDefaultCallBack(me) returns Boolean from Standard;
202	---Purpose: ask if the schema is using the default callback.
203
204	SetDefaultCallBack(me : mutable; f : CallBack from Storage);
205	---Purpose: overload the default function for build.(use to
206	-- set an error message or skip an object while
207	-- reading an unknown type).
208
209	ResetDefaultCallBack(me : mutable);
210	---Purpose: reset the default function defined by Storage
211	-- package.
212
213	DefaultCallBack(me) returns CallBack from Storage;
214	---Purpose: returns the read function used when the
215	-- UseDefaultCallBack() is set.
216
217	-- ---------------- --
218	-- INTERNAL METHODS --
219	-- ---------------- --
220
221	SetNested(me : mutable) returns Boolean from Standard is private;
222	IsNested(me) returns Boolean from Standard is protected;
223	UnsetNested(me : mutable) returns Boolean from Standard is private;
224
225	ResolveUnknownType(me; aTypeName : AsciiString from TCollection;
226	aPers : Persistent from Standard;
227	aMode : SolveMode from Storage)
228	returns CallBack from Storage is protected;
229
230	CallBackSelection(me; tName : AsciiString from TCollection)
231	returns CallBack from Storage is virtual;
232	---Level: Internal
233
234	AddTypeSelection(me; sp : Persistent from Standard)
235	returns CallBack from Storage is virtual;
236	---Level: Internal
237
238	HasTypeBinding(me; aTypeName : AsciiString from TCollection)
239	returns Boolean from Standard is protected;
240	---Level: Internal
241	---C++: inline
242
243	BindType(me; aTypeName : AsciiString from TCollection;
244	aCallBack : CallBack from Storage) is protected;
245	---Level: Internal
246
247	TypeBinding(me; aTypeName : AsciiString from TCollection)
248	returns CallBack from Storage is protected;
249	---Level: Internal
250
251	WritePersistentObjectHeader(me : mutable;
252	sp : Persistent;
253	s : in out BaseDriver from Storage);
254	---C++: inline
255	---Level: Internal
256
257	ReadPersistentObjectHeader(me : mutable; s : in out BaseDriver from Storage);
258	---C++: inline
259	---Level: Internal
260
261	WritePersistentReference(me : mutable; sp : Persistent;
262	s : in out BaseDriver from Storage);
263	---C++: inline
264	ReadPersistentReference(me : mutable; sp : in out Persistent;
265	s : in out BaseDriver from Storage);
266	---Level: Internal
267
268	AddPersistent(me; sp : Persistent; tName : CString) returns Boolean;
269	---Level: Internal
270
271	PersistentToAdd(me; sp : Persistent) returns Boolean;
272	---Level: Internal
273
274	Clear(me) is private;
275	---Level: Internal
276
277	IReadHeaderSection(me; s : in out BaseDriver from Storage;
6e33d3ce	278	iData : HeaderData from Storage) returns Boolean
7fd59977	279	raises StreamFormatError is private;
	280	---Level: Internal
	281
	282	IReadTypeSection(me; s : in out BaseDriver from Storage;
6e33d3ce	283	tData : TypeData from Storage) returns Boolean
7fd59977	284	raises StreamFormatError is private;
	285	---Level: Internal
	286
	287	IReadRootSection(me; s : in out BaseDriver from Storage;
6e33d3ce	288	rData : RootData from Storage) returns Boolean
7fd59977	289	raises StreamFormatError is private;
	290	---Level: Internal
	291
6e33d3ce	292	ISetCurrentData(myclass; dData : Data from Storage) is private;
7fd59977	293	---Level: Internal
7fd59977	294
6e33d3ce	295	ICurrentData(myclass) returns Data from Storage is private;
7fd59977	296	---Level: Internal
	297	---C++: return &
	298
	299	fields
	300
	301	myCallBack : MapOfCallBack from Storage;
	302	myCallBackState : Boolean from Standard;
	303	myDefaultCallBack : CallBack from Storage;
	304
	305	myName : AsciiString from TCollection;
	306	myVersion : AsciiString from TCollection;
	307	myArrayOfSchema : HArrayOfSchema from Storage;
	308	myNestedState : Boolean from Standard;
	309
	310	end;