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
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 _CDM_Document_HeaderFile
18 #define _CDM_Document_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_Type.hxx>
23 #include <CDM_ListOfReferences.hxx>
24 #include <CDM_CanCloseStatus.hxx>
25 #include <TColStd_SequenceOfExtendedString.hxx>
26 #include <TCollection_ExtendedString.hxx>
27 #include <Standard_OStream.hxx>
30 class CDM_Application;
31 class Standard_NoSuchObject;
32 class Standard_Failure;
33 class Standard_DomainError;
35 class CDM_ReferenceIterator;
36 class TCollection_ExtendedString;
37 class Resource_Manager;
40 DEFINE_STANDARD_HANDLE(CDM_Document, Standard_Transient)
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
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
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
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
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);
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
91 Standard_EXPORT virtual Standard_Boolean Update (TCollection_ExtendedString& ErrorString);
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;
98 //! by default empties the extensions.
99 Standard_EXPORT virtual void Extensions (TColStd_SequenceOfExtendedString& Extensions) const;
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);
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
113 Standard_EXPORT Standard_Integer CreateReference (const Handle(CDM_Document)& anOtherDocument);
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);
119 //! Removes all references having this document for From Document.
120 Standard_EXPORT void RemoveAllReferences();
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;
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;
132 //! returns True if the To Document of the reference
133 //! identified by aReferenceIdentifier has already been stored,
135 Standard_EXPORT Standard_Boolean IsStored (const Standard_Integer aReferenceIdentifier) const;
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;
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;
151 //! returns the number of references having this document as
153 Standard_EXPORT Standard_Integer ToReferencesNumber() const;
155 //! returns the number of references having this document as
157 Standard_EXPORT Standard_Integer FromReferencesNumber() const;
159 //! returns True is this document references aDocument;
160 Standard_EXPORT Standard_Boolean ShallowReferences (const Handle(CDM_Document)& aDocument) const;
162 //! returns True is this document references aDocument;
163 Standard_EXPORT Standard_Boolean DeepReferences (const Handle(CDM_Document)& aDocument) const;
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);
171 //! indicates that this document cannot be modified.
172 Standard_EXPORT Standard_Boolean IsReadOnly() const;
174 //! indicates that the referenced document cannot be modified,
175 Standard_EXPORT Standard_Boolean IsReadOnly (const Standard_Integer aReferenceIdentifier) const;
177 Standard_EXPORT void SetIsReadOnly();
179 Standard_EXPORT void UnsetIsReadOnly();
181 //! Indicates that this document has been modified.
182 //! This method increments the modification counter.
183 Standard_EXPORT void Modify();
185 //! returns the current modification counter.
186 Standard_EXPORT Standard_Integer Modifications() const;
188 Standard_EXPORT void UnModify();
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;
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
200 Standard_EXPORT void SetIsUpToDate (const Standard_Integer aReferenceIdentifier);
202 //! associates a comment with this document.
203 Standard_EXPORT void SetComment (const TCollection_ExtendedString& aComment);
205 //! appends a comment into comments of this document.
206 Standard_EXPORT void AddComment (const TCollection_ExtendedString& aComment);
208 //! associates a comments with this document.
209 Standard_EXPORT void SetComments (const TColStd_SequenceOfExtendedString& aComments);
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;
215 //! returns the first of associated comments. By defaut
216 //! the comment is an empty string.
217 Standard_EXPORT Standard_ExtString Comment() const;
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
225 Standard_EXPORT Standard_ExtString Presentation();
227 //! returns the document having the given alphanumeric presentation.
228 Standard_EXPORT static Handle(CDM_Document) FindFromPresentation (const TCollection_ExtendedString& aPresentation);
230 //! indicates whether a document having the given presentation
232 Standard_EXPORT static Standard_Boolean FindPresentation (const TCollection_ExtendedString& aPresentation);
234 Standard_EXPORT Standard_Boolean IsStored() const;
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;
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);
245 Standard_EXPORT void UnsetIsStored();
247 Standard_EXPORT Handle(CDM_MetaData) MetaData() const;
249 Standard_EXPORT TCollection_ExtendedString Folder() const;
251 //! defines the folder in which the object should be stored.
252 Standard_EXPORT void SetRequestedFolder (const TCollection_ExtendedString& aFolder);
254 Standard_EXPORT TCollection_ExtendedString RequestedFolder() const;
256 Standard_EXPORT Standard_Boolean HasRequestedFolder() const;
258 //! defines the name under which the object should be stored.
259 Standard_EXPORT void SetRequestedName (const TCollection_ExtendedString& aName);
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
265 Standard_EXPORT TCollection_ExtendedString RequestedName();
267 Standard_EXPORT void SetRequestedPreviousVersion (const TCollection_ExtendedString& aPreviousVersion);
269 Standard_EXPORT void UnsetRequestedPreviousVersion();
271 Standard_EXPORT Standard_Boolean HasRequestedPreviousVersion() const;
273 Standard_EXPORT TCollection_ExtendedString RequestedPreviousVersion() const;
275 //! defines the Comment with which the object should be stored.
276 Standard_EXPORT void SetRequestedComment (const TCollection_ExtendedString& aComment);
278 Standard_EXPORT TCollection_ExtendedString RequestedComment() const;
280 //! read (or rereads) the following resource.
281 Standard_EXPORT void LoadResources();
283 Standard_EXPORT Standard_Boolean FindFileExtension();
285 //! gets the Desktop.Domain.Application.`FileFormat`.FileExtension resource.
286 Standard_EXPORT TCollection_ExtendedString FileExtension();
288 Standard_EXPORT Standard_Boolean FindDescription();
290 //! gets the `FileFormat`.Description resource.
291 Standard_EXPORT TCollection_ExtendedString Description();
293 //! returns true if the version is greater than the
295 Standard_EXPORT Standard_Boolean IsModified() const;
297 Standard_EXPORT Standard_OStream& Print (Standard_OStream& anOStream) const;
298 Standard_OStream& operator << (Standard_OStream& anOStream);
300 Standard_EXPORT Standard_Boolean IsOpened() const;
302 Standard_EXPORT void Open (const Handle(CDM_Application)& anApplication);
304 Standard_EXPORT CDM_CanCloseStatus CanClose() const;
306 Standard_EXPORT void Close();
308 Standard_EXPORT const Handle(CDM_Application)& Application() const;
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;
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);
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;
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);
330 Standard_EXPORT Standard_Integer CreateReference (const Handle(CDM_MetaData)& aMetaData, const Handle(CDM_Application)& anApplication, const Standard_Integer aDocumentVersion, const Standard_Boolean UseStorageConfiguration);
332 Standard_EXPORT Standard_Integer ReferenceCounter() const;
334 //! the following method should be used instead:
336 //! Update(me:mutable; ErrorString: out ExtendedString from TCollection)
337 //! returns Boolean from Standard
338 Standard_EXPORT virtual void Update();
340 Standard_EXPORT Handle(CDM_Reference) Reference (const Standard_Integer aReferenceIdentifier) const;
342 Standard_EXPORT void SetModifications (const Standard_Integer Modifications);
344 Standard_EXPORT void SetReferenceCounter (const Standard_Integer aReferenceCounter);
346 //! Returns version of the format to be used to store the document
347 Standard_EXPORT Standard_Integer StorageFormatVersion() const;
349 //! Sets <theVersion> of the format to be used to store the document
350 Standard_EXPORT void ChangeStorageFormatVersion(const Standard_Integer theVersion);
352 //! Dumps the content of me into the stream
353 Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
355 friend class CDM_Reference;
356 friend class CDM_ReferenceIterator;
357 friend class CDM_Application;
360 DEFINE_STANDARD_RTTIEXT(CDM_Document,Standard_Transient)
365 Standard_EXPORT CDM_Document();
367 Standard_EXPORT ~CDM_Document();
369 Standard_Boolean myResourcesAreLoaded;
374 //! the manager returned by this method will be
375 //! used to search for the following resource items.
376 Standard_EXPORT Handle(Resource_Manager) StorageResource();
378 Standard_EXPORT void ComputePresentation();
380 Standard_EXPORT void UnvalidPresentation();
382 Standard_EXPORT void AddToReference (const Handle(CDM_Reference)& aReference);
384 Standard_EXPORT void AddFromReference (const Handle(CDM_Reference)& aReference);
386 Standard_EXPORT void RemoveFromReference (const Standard_Integer aReferenceIdentifier);
388 TColStd_SequenceOfExtendedString myComments;
389 TCollection_ExtendedString myPresentation;
390 Standard_Boolean myValidPresentation;
391 CDM_ListOfReferences myFromReferences;
392 CDM_ListOfReferences myToReferences;
393 Standard_Integer myVersion;
394 Standard_Integer myActualReferenceIdentifier;
395 Standard_Integer myStorageVersion;
396 Handle(CDM_MetaData) myMetaData;
397 TCollection_ExtendedString myRequestedComment;
398 TCollection_ExtendedString myRequestedFolder;
399 Standard_Boolean myRequestedFolderIsDefined;
400 TCollection_ExtendedString myRequestedName;
401 Standard_Boolean myRequestedNameIsDefined;
402 Standard_Boolean myRequestedPreviousVersionIsDefined;
403 TCollection_ExtendedString myRequestedPreviousVersion;
404 TCollection_ExtendedString myFileExtension;
405 TCollection_ExtendedString myDescription;
406 Standard_Boolean myFileExtensionWasFound;
407 Standard_Boolean myDescriptionWasFound;
408 Handle(CDM_Application) myApplication;
409 Standard_Integer myStorageFormatVersion;
419 #endif // _CDM_Document_HeaderFile