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