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 deferred class Document from CDM
19 inherits Transient from Standard
21 ---Purpose: An applicative document is an instance of a class inheriting CDM_Document.
22 -- These documents have the following properties:
23 -- - they can have references to other documents.
24 -- - the modifications of a document are propagated to the referencing
26 -- - a document can be stored in different formats, with or
27 -- without a persistent model.
28 -- - the drivers for storing and retrieving documents are
29 -- plugged in when necessary.
30 -- - a document has a modification counter. This counter is
31 -- incremented when the document is modified. When a document
32 -- is stored, the current counter value is memorized as the
33 -- last storage version of the document. A document is
34 -- considered to be modified when the counter value is
35 -- different from the storage version. Once the document is
36 -- saved the storage version and the counter value are
37 -- identical. The document is now not considered to be
39 -- - a reference is a link between two documents. A reference has two
40 -- components: the "From Document" and the "To Document". When
41 -- a reference is created, an identifier of the reference is generated.
42 -- This identifier is unique in the scope of the From Document and
43 -- is conserved during storage and retrieval. This means that the
44 -- referenced document will be always accessible through this
46 -- - a reference memorizes the counter value of the To Document when
47 -- the reference is created. The From Document is considered to
48 -- be up to date relative to the To Document when the
49 -- reference counter value is equal to the To Document counter value.
50 -- - retrieval of a document having references does not imply
51 -- the retrieving of the referenced documents.
55 ReferenceIterator from CDM,
56 ExtendedString from TCollection,MetaData from CDM, Application from CDM,
57 ListOfReferences from CDM, SequenceOfExtendedString from TColStd,
58 GUID from Standard,Manager from Resource,CanCloseStatus from CDM
61 raises NoSuchObject from Standard,Failure from Standard,DomainError from Standard
66 ---Category: virtual methods
67 Destroy(me: mutable) is virtual protected;
71 Update(me: mutable; aToDocument: Document from CDM; aReferenceIdentifier: Integer from Standard; aModifContext: Address from Standard)
72 ---Purpose: The Update method will be called once for each
73 -- reference, but it should not perform any computation,
74 -- to avoid multiple computation of a same document.
78 Update(me:mutable; ErrorString: out ExtendedString from TCollection)
79 returns Boolean from Standard
80 ---Purpose: 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
91 returns ExtendedString from TCollection
92 ---Purpose: The Storage Format is the key which is used to determine in the
93 -- application resources the storage driver plugin, the file
94 -- extension and other data used to store the document.
97 Extensions(me; Extensions: out SequenceOfExtendedString from TColStd)
99 ---Purpose: by default empties the extensions.
102 GetAlternativeDocument(me: mutable; aFormat: ExtendedString from TCollection;
103 anAlternativeDocument: out Document from CDM)
104 returns Boolean from Standard
105 ---Purpose: This method can be redefined to extract another document in
106 -- a different format. For example, to extract a MDTV-Shape
107 -- from an applicative document.
110 ---Category: Reference management.
112 CreateReference(me: mutable; anOtherDocument: Document from CDM)
113 returns Integer from Standard;
114 ---Purpose: Creates a reference from this document to {anOtherDocument}.
115 -- Returns a reference identifier. This reference identifier
116 -- is unique in the document and will not be used for the
117 -- next references, even after the storing of the document.
118 -- If there is already a reference between the two documents,
119 -- the reference is not created, but its reference identifier
123 RemoveReference(me: mutable; aReferenceIdentifier: Integer from Standard);
124 ---Purpose: Removes the reference between the From Document and the
125 -- To Document identified by a reference identifier.
128 RemoveAllReferences(me: mutable);
129 ---Purpose: Removes all references having this document for From Document.
131 Document(me; aReferenceIdentifier: Integer from Standard)
132 returns Document from CDM
133 ---Purpose: Returns the To Document of the reference identified by
134 -- aReferenceIdentifier. If the ToDocument is stored and
135 -- has not yet been retrieved, this method will retrieve it.
136 raises NoSuchObject from Standard;
138 IsInSession(me; aReferenceIdentifier: Integer from Standard)
139 returns Boolean from Standard
140 ---Purpose: returns True if the To Document of the reference
141 -- identified by aReferenceIdentifier is in session, False
142 -- if it corresponds to a not yet retrieved document.
143 raises NoSuchObject from Standard;
145 IsStored(me; aReferenceIdentifier: Integer from Standard)
146 returns Boolean from Standard
147 ---Purpose: returns True if the To Document of the reference
148 -- identified by aReferenceIdentifier has already been stored,
150 raises NoSuchObject from Standard;
152 Name(me; aReferenceIdentifier: Integer from Standard)
153 returns ExtendedString from TCollection
154 ---Purpose: returns the name of the metadata of the To Document of
155 -- the reference identified by aReferenceIdentifier.
156 raises DomainError from Standard;
157 ---Warning: if the corresponding document is not stored.
159 UpdateFromDocuments(me; aModifContext: Address from Standard);
160 ---Purpose: call virtual method Update on all referencing
161 -- documents. This method keeps the list of the --
162 -- documents to process.It may be the starting of an
163 -- update -- cycle. If not, the reentrant calls made by
164 -- Update method (without argument) will append the
165 -- referencing documents to the list and call the Update method
166 -- (with arguments). Only the first call to UpdateFromDocuments
167 -- generate call to Update().
169 ToReferencesNumber(me)
170 returns Integer from Standard;
171 ---Purpose: returns the number of references having this document as
175 FromReferencesNumber(me)
176 returns Integer from Standard;
177 ---Purpose: returns the number of references having this document as
180 ShallowReferences(me; aDocument: Document from CDM)
181 returns Boolean from Standard;
182 ---Purpose: returns True is this document references aDocument;
184 DeepReferences(me; aDocument: Document from CDM)
185 returns Boolean from Standard;
186 ---Purpose: returns True is this document references aDocument;
188 CopyReference(me: mutable; aFromDocument: Document from CDM; aReferenceIdentifier: Integer from Standard)
189 returns Integer from Standard;
190 ---Purpose: Copies a reference to this document. This method
191 -- avoid retrieval of referenced document. The arguments
192 -- are the original document and a valid reference
193 -- identifier Returns the local identifier.
195 ---Category: Modifications Counter management.
197 IsReadOnly(me) returns Boolean from Standard;
198 ---Purpose: indicates that this document cannot be modified.
202 IsReadOnly(me; aReferenceIdentifier: Integer from Standard)
203 returns Boolean from Standard;
204 ---Purpose: indicates that the referenced document cannot be modified,
207 SetIsReadOnly(me: mutable);
209 UnsetIsReadOnly(me: mutable);
212 ---Purpose: Indicates that this document has been modified.
213 -- This method increments the modification counter.
215 Modifications(me) returns Integer from Standard;
216 ---Purpose: returns the current modification counter.
218 UnModify(me: mutable);
220 IsUpToDate(me; aReferenceIdentifier: Integer from Standard)
221 returns Boolean from Standard;
222 ---Purpose: returns true if the modification counter found in the given
223 -- reference is equal to the actual modification counter of
224 -- the To Document. This method is able to deal with a reference
225 -- to a not retrieved document.
228 SetIsUpToDate(me: mutable; aReferenceIdentifier: Integer from Standard);
229 ---Purpose: Resets the modification counter in the given reference
230 -- to the actual modification counter of its To Document.
231 -- This method should be called after the application has updated
235 SetComment(me: mutable; aComment: ExtendedString from TCollection);
236 ---Purpose: associates a comment with this document.
238 AddComment(me: mutable; aComment: ExtendedString from TCollection);
239 ---Purpose: appends a comment into comments of this document.
241 SetComments(me: mutable; aComments: SequenceOfExtendedString from TColStd);
242 ---Purpose: associates a comments with this document.
244 Comments(me; aComments: out SequenceOfExtendedString from TColStd);
245 ---Purpose: returns the associated comments through <aComments>.
246 -- Returns empty sequence if no comments are associated.
248 Comment(me) returns ExtString from Standard;
249 ---Purpose: returns the first of associated comments. By defaut
250 -- the comment is an empty string.
252 ---Category: presentation methods. The presentation is an alphanumeric string.
253 -- In a given session a presentation cannot be given to two differents
256 Presentation(me: mutable) returns ExtString from Standard;
257 ---Purpose: Returns an alphanumeric string identifying this document
258 -- in a unique manner in the current process. The presentation
259 -- may change when the document is stored.
260 -- Tries to get the 'FileFormat`.Presentation resource
261 -- This item is used to give a default presentation
263 FindFromPresentation(myclass; aPresentation: ExtendedString from TCollection)
264 returns Document from CDM
265 ---Purpose: returns the document having the given alphanumeric presentation.
266 raises NoSuchObject from Standard;
269 FindPresentation(myclass; aPresentation: ExtendedString from TCollection)
270 returns Boolean from Standard;
271 ---Purpose: indicates whether a document having the given presentation
274 ---Category: database related methods
275 IsStored(me) returns Boolean from Standard;
277 StorageVersion(me) returns Integer from Standard;
278 ---Purpose: returns the value of the modification counter at the
279 -- time of storage. By default returns 0.
282 SetMetaData(me: mutable; aMetaData: MetaData from CDM);
283 ---Purpose: associates database information to a document which
284 -- has been stored. The name of the document is now the
285 -- name which has beenused to store the data.
288 UnsetIsStored(me: mutable);
290 MetaData(me) returns MetaData from CDM
291 raises NoSuchObject from Standard;
293 Folder(me) returns ExtendedString from TCollection
294 raises NoSuchObject from Standard;
295 ---Warning: if the object is not stored;
298 ---Category: methods to define where to store the document, the name
299 -- under which it has to be stored and some other metadatas.
303 SetRequestedFolder(me: mutable; aFolder: ExtendedString from TCollection);
304 ---Purpose: defines the folder in which the object should be stored.
306 RequestedFolder(me) returns ExtendedString from TCollection
307 raises NoSuchObject from Standard;
310 HasRequestedFolder(me) returns Boolean from Standard;
315 SetRequestedName(me: mutable; aName: ExtendedString from TCollection);
316 ---Purpose: defines the name under which the object should be stored.
317 RequestedName(me:mutable) returns ExtendedString from TCollection;
318 ---Purpose: determines under which the document is going to be
319 -- store. By default the name of the document wil be --
320 -- used. If the document has no name its presentation
323 SetRequestedPreviousVersion(me: mutable; aPreviousVersion: ExtendedString from TCollection);
325 UnsetRequestedPreviousVersion(me: mutable);
327 HasRequestedPreviousVersion(me) returns Boolean from Standard;
328 RequestedPreviousVersion(me) returns ExtendedString from TCollection
329 raises NoSuchObject from Standard;
331 SetRequestedComment(me: mutable; aComment: ExtendedString from TCollection);
332 ---Purpose: defines the Comment with which the object should be stored.
334 RequestedComment(me) returns ExtendedString from TCollection;
337 ---Category: resource reading methods
342 -- Resources are read once at the creation of the document
343 -- until LoadResources is called again.
346 LoadResources(me: mutable);
347 ---Purpose: read (or rereads) the following resource.
349 StorageResource(me: mutable) returns Manager from Resource
351 ---Purpose: the manager returned by this method will be
352 -- used to search for the following resource items.
354 FindFileExtension(me: mutable) returns Boolean from Standard;
356 FileExtension(me: mutable) returns ExtendedString from TCollection;
357 ---Purpose: gets the Desktop.Domain.Application.`FileFormat`.FileExtension resource.
358 FindDataType(me: mutable) returns Boolean from Standard;
360 DataType(me: mutable) returns ExtendedString from TCollection;
361 ---Purpose: this datatype will be used if the DBMS deals with this concept
362 ---Purpose: gets the `FileFormat`.DataType resource.
365 FindVersionDataType(me: mutable) returns Boolean from Standard;
367 VersionDataType(me: mutable) returns ExtendedString from TCollection;
368 ---Purpose: this datatype will be used if the DBMS deals with this concept
369 ---Purpose: gets the `FileFormat`.VersionDataType resource.
371 FindDescription(me: mutable) returns Boolean from Standard;
373 Description(me: mutable) returns ExtendedString from TCollection;
374 ---Purpose: gets the `FileFormat`.Description resource.
376 FindDomain(me: mutable) returns Boolean from Standard;
378 Domain(me: mutable) returns ExtendedString from TCollection;
379 ---Purpose: gets the `FileFormat`.Domain resource.
382 FindStoragePlugin(me: mutable) returns Boolean from Standard;
384 StoragePlugin(me: mutable) returns GUID from Standard;
386 ---Category: Miscellaneous methods
388 IsModified(me) returns Boolean from Standard;
389 ---Purpose: returns true if the version is greater than the
392 ---Category: print method
393 Print(me; anOStream: in out OStream from Standard)
394 returns OStream from Standard;
396 ---C++: alias "Standard_OStream& operator << (Standard_OStream& anOStream);"
398 ---Category: activation controll
400 IsOpened(me) returns Boolean from Standard;
402 Open(me: mutable; anApplication: Application from CDM);
405 CanClose(me) returns CanCloseStatus from CDM;
407 --Returns CDM_CCS_OK true if it is possible to close the document.
408 -- Otherwise, returns:
409 -- CDM_CSS_NotOpen if the document has not been opened
410 -- CDM_CCS_UnstoredReferenced if the document is not stored if it
412 -- CDM_CSS_ModifiedReferenced if the document has been modified,
413 -- if it is referenced, since it has been stored.
414 -- CDM_CCS_ReferenceRejection if one of the referencing documents
415 -- does not allow the closing of the document.
418 Application(me) returns Application from CDM
419 raises Failure from Standard;
420 ---C++: return const &
421 ---Warning: exception if the document is not open
424 CanCloseReference(me; aDocument: Document from CDM;
425 aReferenceIdentifier: Integer from Standard)
426 returns Boolean from Standard
428 ---Purpose: A referenced document may indicate through this
429 -- virtual method that it does not allow the closing of
430 -- aDocument which it references through the reference
431 -- aReferenceIdentifier. By default returns Standard_True;;
433 CloseReference(me: mutable; aDocument: Document from CDM;
434 aReferenceIdentifier: Integer from Standard)
436 ---Purpose: A referenced document may update its internal
437 -- data structure when {aDocument} which it references
438 -- through the reference {aReferenceIdentifier} is being closed.
439 -- By default this method does nothing.
441 IsOpened(me; aReferenceIdentifier: Integer from Standard)
442 returns Boolean from Standard;
443 ---Purpose: returns true if the document corresponding to the
444 -- given reference has been retrieved and opened.
445 -- Otherwise returns false. This method does not retrieve
446 -- the referenced document
448 ---Category: private methods;
450 Reference(me; aReferenceIdentifier: Integer from Standard)
451 returns Reference from CDM
454 ComputePresentation(me: mutable)
457 UnvalidPresentation(me: mutable)
460 CreateReference(me: mutable; aMetaData: MetaData from CDM; aReferenceIdentifier: Integer from Standard; anApplication: Application from CDM; aToDocumentVersion: Integer from Standard; UseStorageConfiguration: Boolean from Standard);
462 CreateReference(me: mutable; aMetaData: MetaData from CDM; anApplication: Application from CDM; aDocumentVersion: Integer from Standard; UseStorageConfiguration: Boolean from Standard)
463 returns Integer from Standard;
465 AddToReference(me: mutable; aReference: Reference from CDM)
468 AddFromReference(me: mutable; aReference: Reference from CDM)
471 RemoveFromReference(me: mutable; aReferenceIdentifier: Integer from Standard)
474 SetModifications(me: mutable; Modifications: Integer from Standard)
477 ReferenceCounter(me) returns Integer from Standard;
479 SetReferenceCounter(me: mutable; aReferenceCounter: Integer from Standard)
482 ---Category: obsolete methods
486 ---Purpose: the following method should be used instead:
488 -- Update(me:mutable; ErrorString: out ExtendedString from TCollection)
489 -- returns Boolean from Standard
494 myComments: SequenceOfExtendedString from TColStd;
496 myPresentation: ExtendedString from TCollection;
497 myValidPresentation: Boolean from Standard;
499 myFromReferences: ListOfReferences from CDM;
500 myToReferences: ListOfReferences from CDM;
501 myVersion: Integer from Standard;
503 myActualReferenceIdentifier: Integer from Standard;
505 myStorageVersion: Integer from Standard;
506 myMetaData: MetaData from CDM;
508 myRequestedComment: ExtendedString from TCollection;
510 myRequestedFolder: ExtendedString from TCollection;
511 myRequestedFolderIsDefined: Boolean from Standard;
513 myRequestedName: ExtendedString from TCollection;
514 myRequestedNameIsDefined: Boolean from Standard;
516 myRequestedPreviousVersionIsDefined: Boolean from Standard;
517 myRequestedPreviousVersion: ExtendedString from TCollection;
519 ---Category: resources.
520 myFileExtension,myDataType,myVersionDataType,myDescription,myDomain,myDefaultPresentation: ExtendedString from TCollection;
522 myFileExtensionWasFound,myDataTypeWasFound,myVersionDataTypeWasFound,myDescriptionWasFound,myDomainWasFound,myStoragePluginWasFound,myDefaultPresentationWasFound: Boolean from Standard;
523 myResourcesAreLoaded: Boolean from Standard is protected;
524 myStoragePlugin: GUID from Standard;
525 myApplication: Application from CDM;
528 class Reference from CDM,
529 class ReferenceIterator from CDM,
530 class Application from CDM
532 end Document from CDM;