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