42cf5bc1 |
1 | // Created on: 1997-07-30 |
2 | // Created by: Jean-Louis Frenkel |
3 | // Copyright (c) 1997-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 _CDM_Document_HeaderFile |
18 | #define _CDM_Document_HeaderFile |
19 | |
20 | #include <Standard.hxx> |
21 | #include <Standard_Type.hxx> |
22 | |
23 | #include <TColStd_SequenceOfExtendedString.hxx> |
24 | #include <TCollection_ExtendedString.hxx> |
25 | #include <Standard_Boolean.hxx> |
26 | #include <CDM_ListOfReferences.hxx> |
27 | #include <Standard_Integer.hxx> |
28 | #include <Standard_GUID.hxx> |
29 | #include <Standard_Transient.hxx> |
30 | #include <Standard_Address.hxx> |
31 | #include <Standard_ExtString.hxx> |
32 | #include <Standard_OStream.hxx> |
33 | #include <CDM_CanCloseStatus.hxx> |
34 | class CDM_MetaData; |
35 | class CDM_Application; |
36 | class Standard_NoSuchObject; |
37 | class Standard_Failure; |
38 | class Standard_DomainError; |
39 | class CDM_Reference; |
40 | class CDM_ReferenceIterator; |
41 | class TCollection_ExtendedString; |
42 | class Resource_Manager; |
43 | class Standard_GUID; |
44 | |
45 | |
46 | class CDM_Document; |
47 | DEFINE_STANDARD_HANDLE(CDM_Document, Standard_Transient) |
48 | |
49 | //! An applicative document is an instance of a class inheriting CDM_Document. |
50 | //! These documents have the following properties: |
51 | //! - they can have references to other documents. |
52 | //! - the modifications of a document are propagated to the referencing |
53 | //! documents. |
54 | //! - a document can be stored in different formats, with or |
55 | //! without a persistent model. |
56 | //! - the drivers for storing and retrieving documents are |
57 | //! plugged in when necessary. |
58 | //! - a document has a modification counter. This counter is |
59 | //! incremented when the document is modified. When a document |
60 | //! is stored, the current counter value is memorized as the |
61 | //! last storage version of the document. A document is |
62 | //! considered to be modified when the counter value is |
63 | //! different from the storage version. Once the document is |
64 | //! saved the storage version and the counter value are |
65 | //! identical. The document is now not considered to be |
66 | //! modified. |
67 | //! - a reference is a link between two documents. A reference has two |
68 | //! components: the "From Document" and the "To Document". When |
69 | //! a reference is created, an identifier of the reference is generated. |
70 | //! This identifier is unique in the scope of the From Document and |
71 | //! is conserved during storage and retrieval. This means that the |
72 | //! referenced document will be always accessible through this |
73 | //! identifier. |
74 | //! - a reference memorizes the counter value of the To Document when |
75 | //! the reference is created. The From Document is considered to |
76 | //! be up to date relative to the To Document when the |
77 | //! reference counter value is equal to the To Document counter value. |
78 | //! - retrieval of a document having references does not imply |
79 | //! the retrieving of the referenced documents. |
80 | class CDM_Document : public Standard_Transient |
81 | { |
82 | |
83 | public: |
84 | |
85 | |
86 | //! The Update method will be called once for each |
87 | //! reference, but it should not perform any computation, |
88 | //! to avoid multiple computation of a same document. |
89 | Standard_EXPORT virtual void Update (const Handle(CDM_Document)& aToDocument, const Standard_Integer aReferenceIdentifier, const Standard_Address aModifContext); |
90 | |
91 | //! This method Update will be called |
92 | //! to signal the end of the modified references list. |
93 | //! The document should be recomputed and |
94 | //! UpdateFromDocuments should be called. Update should |
95 | //! returns True in case of success, false otherwise. In |
96 | //! case of Failure, additional information can be given in |
97 | //! ErrorString. |
98 | Standard_EXPORT virtual Standard_Boolean Update (TCollection_ExtendedString& ErrorString); |
99 | |
100 | //! The Storage Format is the key which is used to determine in the |
101 | //! application resources the storage driver plugin, the file |
102 | //! extension and other data used to store the document. |
103 | Standard_EXPORT virtual TCollection_ExtendedString StorageFormat() const = 0; |
104 | |
105 | //! by default empties the extensions. |
106 | Standard_EXPORT virtual void Extensions (TColStd_SequenceOfExtendedString& Extensions) const; |
107 | |
108 | //! This method can be redefined to extract another document in |
109 | //! a different format. For example, to extract a Shape |
110 | //! from an applicative document. |
111 | Standard_EXPORT virtual Standard_Boolean GetAlternativeDocument (const TCollection_ExtendedString& aFormat, Handle(CDM_Document)& anAlternativeDocument); |
112 | |
113 | //! Creates a reference from this document to {anOtherDocument}. |
114 | //! Returns a reference identifier. This reference identifier |
115 | //! is unique in the document and will not be used for the |
116 | //! next references, even after the storing of the document. |
117 | //! If there is already a reference between the two documents, |
118 | //! the reference is not created, but its reference identifier |
119 | //! is returned. |
120 | Standard_EXPORT Standard_Integer CreateReference (const Handle(CDM_Document)& anOtherDocument); |
121 | |
122 | //! Removes the reference between the From Document and the |
123 | //! To Document identified by a reference identifier. |
124 | Standard_EXPORT void RemoveReference (const Standard_Integer aReferenceIdentifier); |
125 | |
126 | //! Removes all references having this document for From Document. |
127 | Standard_EXPORT void RemoveAllReferences(); |
128 | |
129 | //! Returns the To Document of the reference identified by |
130 | //! aReferenceIdentifier. If the ToDocument is stored and |
131 | //! has not yet been retrieved, this method will retrieve it. |
132 | Standard_EXPORT Handle(CDM_Document) Document (const Standard_Integer aReferenceIdentifier) const; |
133 | |
134 | //! returns True if the To Document of the reference |
135 | //! identified by aReferenceIdentifier is in session, False |
136 | //! if it corresponds to a not yet retrieved document. |
137 | Standard_EXPORT Standard_Boolean IsInSession (const Standard_Integer aReferenceIdentifier) const; |
138 | |
139 | //! returns True if the To Document of the reference |
140 | //! identified by aReferenceIdentifier has already been stored, |
141 | //! False otherwise. |
142 | Standard_EXPORT Standard_Boolean IsStored (const Standard_Integer aReferenceIdentifier) const; |
143 | |
144 | //! returns the name of the metadata of the To Document of |
145 | //! the reference identified by aReferenceIdentifier. |
146 | Standard_EXPORT TCollection_ExtendedString Name (const Standard_Integer aReferenceIdentifier) const; |
147 | |
148 | //! call virtual method Update on all referencing |
149 | //! documents. This method keeps the list of the -- |
150 | //! documents to process.It may be the starting of an |
151 | //! update -- cycle. If not, the reentrant calls made by |
152 | //! Update method (without argument) will append the |
153 | //! referencing documents to the list and call the Update method |
154 | //! (with arguments). Only the first call to UpdateFromDocuments |
155 | //! generate call to Update(). |
156 | Standard_EXPORT void UpdateFromDocuments (const Standard_Address aModifContext) const; |
157 | |
158 | //! returns the number of references having this document as |
159 | //! From Document. |
160 | Standard_EXPORT Standard_Integer ToReferencesNumber() const; |
161 | |
162 | //! returns the number of references having this document as |
163 | //! To Document. |
164 | Standard_EXPORT Standard_Integer FromReferencesNumber() const; |
165 | |
166 | //! returns True is this document references aDocument; |
167 | Standard_EXPORT Standard_Boolean ShallowReferences (const Handle(CDM_Document)& aDocument) const; |
168 | |
169 | //! returns True is this document references aDocument; |
170 | Standard_EXPORT Standard_Boolean DeepReferences (const Handle(CDM_Document)& aDocument) const; |
171 | |
172 | //! Copies a reference to this document. This method |
173 | //! avoid retrieval of referenced document. The arguments |
174 | //! are the original document and a valid reference |
175 | //! identifier Returns the local identifier. |
176 | Standard_EXPORT Standard_Integer CopyReference (const Handle(CDM_Document)& aFromDocument, const Standard_Integer aReferenceIdentifier); |
177 | |
178 | //! indicates that this document cannot be modified. |
179 | Standard_EXPORT Standard_Boolean IsReadOnly() const; |
180 | |
181 | //! indicates that the referenced document cannot be modified, |
182 | Standard_EXPORT Standard_Boolean IsReadOnly (const Standard_Integer aReferenceIdentifier) const; |
183 | |
184 | Standard_EXPORT void SetIsReadOnly(); |
185 | |
186 | Standard_EXPORT void UnsetIsReadOnly(); |
187 | |
188 | //! Indicates that this document has been modified. |
189 | //! This method increments the modification counter. |
190 | Standard_EXPORT void Modify(); |
191 | |
192 | //! returns the current modification counter. |
193 | Standard_EXPORT Standard_Integer Modifications() const; |
194 | |
195 | Standard_EXPORT void UnModify(); |
196 | |
197 | //! returns true if the modification counter found in the given |
198 | //! reference is equal to the actual modification counter of |
199 | //! the To Document. This method is able to deal with a reference |
200 | //! to a not retrieved document. |
201 | Standard_EXPORT Standard_Boolean IsUpToDate (const Standard_Integer aReferenceIdentifier) const; |
202 | |
203 | //! Resets the modification counter in the given reference |
204 | //! to the actual modification counter of its To Document. |
205 | //! This method should be called after the application has updated |
206 | //! this document. |
207 | Standard_EXPORT void SetIsUpToDate (const Standard_Integer aReferenceIdentifier); |
208 | |
209 | //! associates a comment with this document. |
210 | Standard_EXPORT void SetComment (const TCollection_ExtendedString& aComment); |
211 | |
212 | //! appends a comment into comments of this document. |
213 | Standard_EXPORT void AddComment (const TCollection_ExtendedString& aComment); |
214 | |
215 | //! associates a comments with this document. |
216 | Standard_EXPORT void SetComments (const TColStd_SequenceOfExtendedString& aComments); |
217 | |
218 | //! returns the associated comments through <aComments>. |
219 | //! Returns empty sequence if no comments are associated. |
220 | Standard_EXPORT void Comments (TColStd_SequenceOfExtendedString& aComments) const; |
221 | |
222 | //! returns the first of associated comments. By defaut |
223 | //! the comment is an empty string. |
224 | Standard_EXPORT Standard_ExtString Comment() const; |
225 | |
226 | //! Returns an alphanumeric string identifying this document |
227 | //! in a unique manner in the current process. The presentation |
228 | //! may change when the document is stored. |
229 | //! Tries to get the 'FileFormat`.Presentation resource |
230 | //! This item is used to give a default presentation |
231 | //! to the document. |
232 | Standard_EXPORT Standard_ExtString Presentation(); |
233 | |
234 | //! returns the document having the given alphanumeric presentation. |
235 | Standard_EXPORT static Handle(CDM_Document) FindFromPresentation (const TCollection_ExtendedString& aPresentation); |
236 | |
237 | //! indicates whether a document having the given presentation |
238 | //! does exist. |
239 | Standard_EXPORT static Standard_Boolean FindPresentation (const TCollection_ExtendedString& aPresentation); |
240 | |
241 | Standard_EXPORT Standard_Boolean IsStored() const; |
242 | |
243 | //! returns the value of the modification counter at the |
244 | //! time of storage. By default returns 0. |
245 | Standard_EXPORT Standard_Integer StorageVersion() const; |
246 | |
247 | //! associates database information to a document which |
248 | //! has been stored. The name of the document is now the |
249 | //! name which has beenused to store the data. |
250 | Standard_EXPORT void SetMetaData (const Handle(CDM_MetaData)& aMetaData); |
251 | |
252 | Standard_EXPORT void UnsetIsStored(); |
253 | |
254 | Standard_EXPORT Handle(CDM_MetaData) MetaData() const; |
255 | |
256 | Standard_EXPORT TCollection_ExtendedString Folder() const; |
257 | |
258 | //! defines the folder in which the object should be stored. |
259 | Standard_EXPORT void SetRequestedFolder (const TCollection_ExtendedString& aFolder); |
260 | |
261 | Standard_EXPORT TCollection_ExtendedString RequestedFolder() const; |
262 | |
263 | Standard_EXPORT Standard_Boolean HasRequestedFolder() const; |
264 | |
265 | //! defines the name under which the object should be stored. |
266 | Standard_EXPORT void SetRequestedName (const TCollection_ExtendedString& aName); |
267 | |
268 | //! determines under which the document is going to be |
269 | //! store. By default the name of the document wil be -- |
270 | //! used. If the document has no name its presentation |
271 | //! will be used. |
272 | Standard_EXPORT TCollection_ExtendedString RequestedName(); |
273 | |
274 | Standard_EXPORT void SetRequestedPreviousVersion (const TCollection_ExtendedString& aPreviousVersion); |
275 | |
276 | Standard_EXPORT void UnsetRequestedPreviousVersion(); |
277 | |
278 | Standard_EXPORT Standard_Boolean HasRequestedPreviousVersion() const; |
279 | |
280 | Standard_EXPORT TCollection_ExtendedString RequestedPreviousVersion() const; |
281 | |
282 | //! defines the Comment with which the object should be stored. |
283 | Standard_EXPORT void SetRequestedComment (const TCollection_ExtendedString& aComment); |
284 | |
285 | Standard_EXPORT TCollection_ExtendedString RequestedComment() const; |
286 | |
287 | //! read (or rereads) the following resource. |
288 | Standard_EXPORT void LoadResources(); |
289 | |
290 | Standard_EXPORT Standard_Boolean FindFileExtension(); |
291 | |
292 | //! gets the Desktop.Domain.Application.`FileFormat`.FileExtension resource. |
293 | Standard_EXPORT TCollection_ExtendedString FileExtension(); |
294 | |
295 | Standard_EXPORT Standard_Boolean FindDataType(); |
296 | |
297 | //! this datatype will be used if the DBMS deals with this concept |
298 | //! gets the `FileFormat`.DataType resource. |
299 | //! concept. |
300 | Standard_EXPORT TCollection_ExtendedString DataType(); |
301 | |
302 | Standard_EXPORT Standard_Boolean FindVersionDataType(); |
303 | |
304 | //! this datatype will be used if the DBMS deals with this concept |
305 | //! gets the `FileFormat`.VersionDataType resource. |
306 | Standard_EXPORT TCollection_ExtendedString VersionDataType(); |
307 | |
308 | Standard_EXPORT Standard_Boolean FindDescription(); |
309 | |
310 | //! gets the `FileFormat`.Description resource. |
311 | Standard_EXPORT TCollection_ExtendedString Description(); |
312 | |
313 | Standard_EXPORT Standard_Boolean FindDomain(); |
314 | |
315 | //! gets the `FileFormat`.Domain resource. |
316 | Standard_EXPORT TCollection_ExtendedString Domain(); |
317 | |
318 | Standard_EXPORT Standard_Boolean FindStoragePlugin(); |
319 | |
320 | Standard_EXPORT Standard_GUID StoragePlugin(); |
321 | |
322 | //! returns true if the version is greater than the |
323 | //! storage version |
324 | Standard_EXPORT Standard_Boolean IsModified() const; |
325 | |
326 | Standard_EXPORT Standard_OStream& Print (Standard_OStream& anOStream) const; |
327 | Standard_OStream& operator << (Standard_OStream& anOStream); |
328 | |
329 | Standard_EXPORT Standard_Boolean IsOpened() const; |
330 | |
331 | Standard_EXPORT void Open (const Handle(CDM_Application)& anApplication); |
332 | |
333 | Standard_EXPORT CDM_CanCloseStatus CanClose() const; |
334 | |
335 | Standard_EXPORT void Close(); |
336 | |
337 | Standard_EXPORT const Handle(CDM_Application)& Application() const; |
338 | |
339 | //! A referenced document may indicate through this |
340 | //! virtual method that it does not allow the closing of |
341 | //! aDocument which it references through the reference |
342 | //! aReferenceIdentifier. By default returns Standard_True;; |
343 | Standard_EXPORT virtual Standard_Boolean CanCloseReference (const Handle(CDM_Document)& aDocument, const Standard_Integer aReferenceIdentifier) const; |
344 | |
345 | //! A referenced document may update its internal |
346 | //! data structure when {aDocument} which it references |
347 | //! through the reference {aReferenceIdentifier} is being closed. |
348 | //! By default this method does nothing. |
349 | Standard_EXPORT virtual void CloseReference (const Handle(CDM_Document)& aDocument, const Standard_Integer aReferenceIdentifier); |
350 | |
351 | //! returns true if the document corresponding to the |
352 | //! given reference has been retrieved and opened. |
353 | //! Otherwise returns false. This method does not retrieve |
354 | //! the referenced document |
355 | Standard_EXPORT Standard_Boolean IsOpened (const Standard_Integer aReferenceIdentifier) const; |
356 | |
357 | Standard_EXPORT void CreateReference (const Handle(CDM_MetaData)& aMetaData, const Standard_Integer aReferenceIdentifier, const Handle(CDM_Application)& anApplication, const Standard_Integer aToDocumentVersion, const Standard_Boolean UseStorageConfiguration); |
358 | |
359 | Standard_EXPORT Standard_Integer CreateReference (const Handle(CDM_MetaData)& aMetaData, const Handle(CDM_Application)& anApplication, const Standard_Integer aDocumentVersion, const Standard_Boolean UseStorageConfiguration); |
360 | |
361 | Standard_EXPORT Standard_Integer ReferenceCounter() const; |
362 | |
363 | //! the following method should be used instead: |
364 | //! |
365 | //! Update(me:mutable; ErrorString: out ExtendedString from TCollection) |
366 | //! returns Boolean from Standard |
367 | Standard_EXPORT virtual void Update(); |
368 | |
369 | friend class CDM_Reference; |
370 | friend class CDM_ReferenceIterator; |
371 | friend class CDM_Application; |
372 | |
373 | |
92efcf78 |
374 | DEFINE_STANDARD_RTTIEXT(CDM_Document,Standard_Transient) |
42cf5bc1 |
375 | |
376 | protected: |
377 | |
378 | |
379 | Standard_EXPORT CDM_Document(); |
380 | |
381 | Standard_EXPORT virtual void Destroy(); |
382 | ~CDM_Document() |
383 | { |
384 | Destroy(); |
385 | } |
386 | |
387 | Standard_Boolean myResourcesAreLoaded; |
388 | |
389 | |
390 | private: |
391 | |
392 | |
393 | //! the manager returned by this method will be |
394 | //! used to search for the following resource items. |
395 | Standard_EXPORT Handle(Resource_Manager) StorageResource(); |
396 | |
397 | Standard_EXPORT Handle(CDM_Reference) Reference (const Standard_Integer aReferenceIdentifier) const; |
398 | |
399 | Standard_EXPORT void ComputePresentation(); |
400 | |
401 | Standard_EXPORT void UnvalidPresentation(); |
402 | |
403 | Standard_EXPORT void AddToReference (const Handle(CDM_Reference)& aReference); |
404 | |
405 | Standard_EXPORT void AddFromReference (const Handle(CDM_Reference)& aReference); |
406 | |
407 | Standard_EXPORT void RemoveFromReference (const Standard_Integer aReferenceIdentifier); |
408 | |
409 | Standard_EXPORT void SetModifications (const Standard_Integer Modifications); |
410 | |
411 | Standard_EXPORT void SetReferenceCounter (const Standard_Integer aReferenceCounter); |
412 | |
413 | TColStd_SequenceOfExtendedString myComments; |
414 | TCollection_ExtendedString myPresentation; |
415 | Standard_Boolean myValidPresentation; |
416 | CDM_ListOfReferences myFromReferences; |
417 | CDM_ListOfReferences myToReferences; |
418 | Standard_Integer myVersion; |
419 | Standard_Integer myActualReferenceIdentifier; |
420 | Standard_Integer myStorageVersion; |
421 | Handle(CDM_MetaData) myMetaData; |
422 | TCollection_ExtendedString myRequestedComment; |
423 | TCollection_ExtendedString myRequestedFolder; |
424 | Standard_Boolean myRequestedFolderIsDefined; |
425 | TCollection_ExtendedString myRequestedName; |
426 | Standard_Boolean myRequestedNameIsDefined; |
427 | Standard_Boolean myRequestedPreviousVersionIsDefined; |
428 | TCollection_ExtendedString myRequestedPreviousVersion; |
429 | TCollection_ExtendedString myFileExtension; |
430 | TCollection_ExtendedString myDataType; |
431 | TCollection_ExtendedString myVersionDataType; |
432 | TCollection_ExtendedString myDescription; |
433 | TCollection_ExtendedString myDomain; |
434 | TCollection_ExtendedString myDefaultPresentation; |
435 | Standard_Boolean myFileExtensionWasFound; |
436 | Standard_Boolean myDataTypeWasFound; |
437 | Standard_Boolean myVersionDataTypeWasFound; |
438 | Standard_Boolean myDescriptionWasFound; |
439 | Standard_Boolean myDomainWasFound; |
440 | Standard_Boolean myStoragePluginWasFound; |
441 | Standard_Boolean myDefaultPresentationWasFound; |
442 | Standard_GUID myStoragePlugin; |
443 | Handle(CDM_Application) myApplication; |
444 | |
445 | |
446 | }; |
447 | |
448 | |
449 | |
450 | |
451 | |
452 | |
453 | |
454 | #endif // _CDM_Document_HeaderFile |