1 // Created on: 1997-02-06
3 // Copyright (c) 1997-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
6 // This file is part of Open CASCADE Technology software library.
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.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _Storage_Data_HeaderFile
18 #define _Storage_Data_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_Type.hxx>
23 #include <Storage_Error.hxx>
24 #include <TCollection_AsciiString.hxx>
25 #include <MMgt_TShared.hxx>
26 #include <TColStd_SequenceOfAsciiString.hxx>
27 #include <TColStd_SequenceOfExtendedString.hxx>
28 #include <Standard_Integer.hxx>
29 #include <Storage_HSeqOfRoot.hxx>
30 #include <Standard_Boolean.hxx>
31 #include <TColStd_HSequenceOfAsciiString.hxx>
32 class Storage_HeaderData;
33 class Storage_RootData;
34 class Storage_TypeData;
35 class Storage_InternalData;
37 class TCollection_AsciiString;
38 class TCollection_ExtendedString;
39 class Standard_Persistent;
44 DEFINE_STANDARD_HANDLE(Storage_Data, MMgt_TShared)
46 //! A picture memorizing the data stored in a
47 //! container (for example, in a file).
48 //! A Storage_Data object represents either:
49 //! - persistent data to be written into a container,
51 //! - persistent data which are read from a container.
52 //! A Storage_Data object is used in both the
53 //! storage and retrieval operations:
54 //! - Storage mechanism: create an empty
55 //! Storage_Data object, then add successively
56 //! persistent objects (roots) to be stored using
57 //! the function AddRoot. When the set of data is
58 //! complete, write it to a container using the
59 //! function Write in your Storage_Schema
60 //! storage/retrieval algorithm.
61 //! - Retrieval mechanism: a Storage_Data
62 //! object is returned by the Read function from
63 //! your Storage_Schema storage/retrieval
64 //! algorithm. Use the functions NumberOfRoots
65 //! and Roots to find the roots which were stored
66 //! in the read container.
67 //! The roots of a Storage_Data object may share
68 //! references on objects. The shared internal
69 //! references of a Storage_Data object are
70 //! maintained by the storage/retrieval mechanism.
71 //! Note: References shared by objects which are
72 //! contained in two distinct Storage_Data objects
73 //! are not maintained by the storage/retrieval
74 //! mechanism: external references are not
75 //! supported by Storage_Schema algorithm
76 class Storage_Data : public MMgt_TShared
83 //! Creates an empty set of data.
84 //! You explicitly create a Storage_Data object
85 //! when preparing the set of objects to be stored
86 //! together in a container (for example, in a file).
87 //! Then use the function AddRoot to add
88 //! persistent objects to the set of data.
89 //! A Storage_Data object is also returned by the
90 //! Read function of a Storage_Schema
91 //! storage/retrieval algorithm. Use the functions
92 //! NumberOfRoots and Roots to find the roots
93 //! which were stored in the read container.
94 Standard_EXPORT Storage_Data();
96 //! Returns Storage_VSOk if
97 //! - the last storage operation performed with the
99 //! - the last retrieval operation performed with the function Write
100 //! by a Storage_Schema algorithm, on this set of data was successful.
101 //! If the storage or retrieval operation was not
102 //! performed, the returned error status indicates the
103 //! reason why the operation failed. The algorithm
104 //! stops its analysis at the first detected error
105 Standard_EXPORT Storage_Error ErrorStatus() const;
108 //! Clears the error status positioned either by:
109 //! - the last storage operation performed with the
110 //! Read function, or
111 //! - the last retrieval operation performed with the Write function
112 //! by a Storage_Schema algorithm, on this set of data.
113 //! This error status may be read by the function ErrorStatus.
114 Standard_EXPORT void ClearErrorStatus();
116 Standard_EXPORT TCollection_AsciiString ErrorStatusExtension() const;
118 //! return the creation date
119 Standard_EXPORT TCollection_AsciiString CreationDate() const;
121 //! return the Storage package version
122 Standard_EXPORT TCollection_AsciiString StorageVersion() const;
124 //! get the version of the schema
125 Standard_EXPORT TCollection_AsciiString SchemaVersion() const;
127 //! get the schema's name
128 Standard_EXPORT TCollection_AsciiString SchemaName() const;
130 //! set the version of the application
131 Standard_EXPORT void SetApplicationVersion (const TCollection_AsciiString& aVersion);
133 //! get the version of the application
134 Standard_EXPORT TCollection_AsciiString ApplicationVersion() const;
136 //! set the name of the application
137 Standard_EXPORT void SetApplicationName (const TCollection_ExtendedString& aName);
139 //! get the name of the application
140 Standard_EXPORT TCollection_ExtendedString ApplicationName() const;
142 //! set the data type
143 Standard_EXPORT void SetDataType (const TCollection_ExtendedString& aType);
145 //! returns data type
146 Standard_EXPORT TCollection_ExtendedString DataType() const;
148 //! add <theUserInfo> to the user informations
149 Standard_EXPORT void AddToUserInfo (const TCollection_AsciiString& anInfo);
151 //! return the user informations
152 Standard_EXPORT const TColStd_SequenceOfAsciiString& UserInfo() const;
154 //! add <theUserInfo> to the user informations
155 Standard_EXPORT void AddToComments (const TCollection_ExtendedString& aComment);
157 //! return the user informations
158 Standard_EXPORT const TColStd_SequenceOfExtendedString& Comments() const;
160 //! the the number of persistent objects
162 //! the number of persistent objects readed
163 Standard_EXPORT Standard_Integer NumberOfObjects() const;
165 //! Returns the number of root objects in this set of data.
166 //! - When preparing a storage operation, the
167 //! result is the number of roots inserted into this
168 //! set of data with the function AddRoot.
169 //! - When retrieving an object, the result is the
170 //! number of roots stored in the read container.
171 //! Use the Roots function to get these roots in a sequence.
172 Standard_EXPORT Standard_Integer NumberOfRoots() const;
174 //! add a persistent root to write. the name of the root
175 //! is a driver reference number.
176 Standard_EXPORT void AddRoot (const Handle(Standard_Persistent)& anObject) const;
178 //! Adds the root anObject to this set of data.
179 //! The name of the root is aName if given; if not, it
180 //! will be a reference number assigned by the driver
181 //! when writing the set of data into the container.
182 //! When naming the roots, it is easier to retrieve
183 //! objects by significant references rather than by
184 //! references without any semantic values.
185 Standard_EXPORT void AddRoot (const TCollection_AsciiString& aName, const Handle(Standard_Persistent)& anObject) const;
187 //! Removes from this set of data the root object named aName.
189 //! Nothing is done if there is no root object whose
190 //! name is aName in this set of data.
191 Standard_EXPORT void RemoveRoot (const TCollection_AsciiString& aName);
193 //! Returns the roots of this set of data in a sequence.
194 //! - When preparing a storage operation, the
195 //! sequence contains the roots inserted into this
196 //! set of data with the function AddRoot.
197 //! - When retrieving an object, the sequence
198 //! contains the roots stored in the container read.
199 //! - An empty sequence is returned if there is no root in this set of data.
200 Standard_EXPORT Handle(Storage_HSeqOfRoot) Roots() const;
202 //! Gives the root object whose name is aName in
203 //! this set of data. The returned object is a
204 //! Storage_Root object, from which the object it
205 //! encapsulates may be extracted.
207 //! A null handle is returned if there is no root object
208 //! whose name is aName in this set of data.
209 Standard_EXPORT Handle(Storage_Root) Find (const TCollection_AsciiString& aName) const;
211 //! returns Standard_True if <me> contains a root named <aName>
212 Standard_EXPORT Standard_Boolean IsRoot (const TCollection_AsciiString& aName) const;
214 //! Returns the number of types of objects used in this set of data.
215 Standard_EXPORT Standard_Integer NumberOfTypes() const;
217 //! Returns true if this set of data contains an object of type aName.
218 //! Persistent objects from this set of data must
219 //! have types which are recognized by the
220 //! Storage_Schema algorithm used to store or retrieve them.
221 Standard_EXPORT Standard_Boolean IsType (const TCollection_AsciiString& aName) const;
224 //! Gives the list of types of objects used in this set of data in a sequence.
225 Standard_EXPORT Handle(TColStd_HSequenceOfAsciiString) Types() const;
228 friend class Storage_Schema;
231 DEFINE_STANDARD_RTTIEXT(Storage_Data,MMgt_TShared)
241 Standard_EXPORT Handle(Storage_HeaderData) HeaderData() const;
243 Standard_EXPORT Handle(Storage_RootData) RootData() const;
245 Standard_EXPORT Handle(Storage_TypeData) TypeData() const;
247 Standard_EXPORT Handle(Storage_InternalData) InternalData() const;
249 Standard_EXPORT void Clear() const;
251 Standard_EXPORT void SetErrorStatus (const Storage_Error anError);
253 Standard_EXPORT void SetErrorStatusExtension (const TCollection_AsciiString& anErrorExt);
255 Handle(Storage_HeaderData) myHeaderData;
256 Handle(Storage_RootData) myRootData;
257 Handle(Storage_TypeData) myTypeData;
258 Handle(Storage_InternalData) myInternal;
259 Storage_Error myErrorStatus;
260 TCollection_AsciiString myErrorStatusExt;
271 #endif // _Storage_Data_HeaderFile