b311480e |
1 | -- Created on: 1997-07-30 |
2 | -- Created by: Jean-Louis Frenkel |
3 | -- Copyright (c) 1997-1999 Matra Datavision |
4 | -- Copyright (c) 1999-2012 OPEN CASCADE SAS |
5 | -- |
6 | -- The content of this file is subject to the Open CASCADE Technology Public |
7 | -- License Version 6.5 (the "License"). You may not use the content of this file |
8 | -- except in compliance with the License. Please obtain a copy of the License |
9 | -- at http://www.opencascade.org and read it completely before using this file. |
10 | -- |
11 | -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its |
12 | -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France. |
13 | -- |
14 | -- The Original Code and all software distributed under the License is |
15 | -- distributed on an "AS IS" basis, without warranty of any kind, and the |
16 | -- Initial Developer hereby disclaims all such warranties, including without |
17 | -- limitation, any warranties of merchantability, fitness for a particular |
18 | -- purpose or non-infringement. Please see the License for the specific terms |
19 | -- and conditions governing the rights and limitations under the License. |
20 | |
7fd59977 |
21 | |
22 | deferred class Document from CDM |
23 | |
24 | inherits Transient from Standard |
25 | |
26 | ---Purpose: An applicative document is an instance of a class inheriting CDM_Document. |
27 | -- These documents have the following properties: |
28 | -- - they can have references to other documents. |
29 | -- - the modifications of a document are propagated to the referencing |
30 | -- documents. |
31 | -- - a document can be stored in different formats, with or |
32 | -- without a persistent model. |
33 | -- - the drivers for storing and retrieving documents are |
34 | -- plugged in when necessary. |
35 | -- - a document has a modification counter. This counter is |
36 | -- incremented when the document is modified. When a document |
37 | -- is stored, the current counter value is memorized as the |
38 | -- last storage version of the document. A document is |
39 | -- considered to be modified when the counter value is |
40 | -- different from the storage version. Once the document is |
41 | -- saved the storage version and the counter value are |
42 | -- identical. The document is now not considered to be |
43 | -- modified. |
44 | -- - a reference is a link between two documents. A reference has two |
45 | -- components: the "From Document" and the "To Document". When |
46 | -- a reference is created, an identifier of the reference is generated. |
47 | -- This identifier is unique in the scope of the From Document and |
48 | -- is conserved during storage and retrieval. This means that the |
49 | -- referenced document will be always accessible through this |
50 | -- identifier. |
51 | -- - a reference memorizes the counter value of the To Document when |
52 | -- the reference is created. The From Document is considered to |
53 | -- be up to date relative to the To Document when the |
54 | -- reference counter value is equal to the To Document counter value. |
55 | -- - retrieval of a document having references does not imply |
56 | -- the retrieving of the referenced documents. |
57 | |
58 | uses |
59 | Reference from CDM, |
60 | ReferenceIterator from CDM, |
61 | ExtendedString from TCollection,MetaData from CDM, Application from CDM, |
62 | ListOfReferences from CDM, SequenceOfExtendedString from TColStd, |
63 | GUID from Standard,Manager from Resource,CanCloseStatus from CDM |
64 | |
65 | |
66 | raises NoSuchObject from Standard,Failure from Standard,DomainError from Standard |
67 | is |
68 | |
69 | Initialize; |
70 | |
7fd59977 |
71 | ---Category: virtual methods |
24de79c3 |
72 | Destroy(me: mutable) is virtual protected; |
73 | ---C++: alias ~ |
74 | |
7fd59977 |
75 | |
76 | Update(me: mutable; aToDocument: Document from CDM; aReferenceIdentifier: Integer from Standard; aModifContext: Address from Standard) |
77 | ---Purpose: The Update method will be called once for each |
78 | -- reference, but it should not perform any computation, |
79 | -- to avoid multiple computation of a same document. |
80 | is virtual; |
81 | |
82 | |
83 | Update(me:mutable; ErrorString: out ExtendedString from TCollection) |
84 | returns Boolean from Standard |
85 | ---Purpose: This method Update will be called |
86 | -- to signal the end of the modified references list. |
87 | -- The document should be recomputed and |
88 | -- UpdateFromDocuments should be called. Update should |
89 | -- returns True in case of success, false otherwise. In |
90 | -- case of Failure, additional information can be given in |
91 | -- ErrorString. |
92 | is virtual; |
93 | |
94 | |
95 | StorageFormat(me) |
96 | returns ExtendedString from TCollection |
97 | ---Purpose: The Storage Format is the key which is used to determine in the |
98 | -- application resources the storage driver plugin, the file |
99 | -- extension and other data used to store the document. |
100 | is deferred; |
101 | |
102 | Extensions(me; Extensions: out SequenceOfExtendedString from TColStd) |
103 | is virtual; |
104 | ---Purpose: by default empties the extensions. |
105 | -- |
106 | |
107 | GetAlternativeDocument(me: mutable; aFormat: ExtendedString from TCollection; |
108 | anAlternativeDocument: out Document from CDM) |
109 | returns Boolean from Standard |
110 | ---Purpose: This method can be redefined to extract another document in |
111 | -- a different format. For example, to extract a MDTV-Shape |
112 | -- from an applicative document. |
113 | is virtual; |
114 | |
115 | ---Category: Reference management. |
116 | -- |
117 | CreateReference(me: mutable; anOtherDocument: Document from CDM) |
118 | returns Integer from Standard; |
119 | ---Purpose: Creates a reference from this document to {anOtherDocument}. |
120 | -- Returns a reference identifier. This reference identifier |
121 | -- is unique in the document and will not be used for the |
122 | -- next references, even after the storing of the document. |
123 | -- If there is already a reference between the two documents, |
124 | -- the reference is not created, but its reference identifier |
125 | -- is returned. |
126 | |
127 | |
128 | RemoveReference(me: mutable; aReferenceIdentifier: Integer from Standard); |
129 | ---Purpose: Removes the reference between the From Document and the |
130 | -- To Document identified by a reference identifier. |
131 | |
132 | |
133 | RemoveAllReferences(me: mutable); |
134 | ---Purpose: Removes all references having this document for From Document. |
135 | |
136 | Document(me; aReferenceIdentifier: Integer from Standard) |
137 | returns Document from CDM |
138 | ---Purpose: Returns the To Document of the reference identified by |
139 | -- aReferenceIdentifier. If the ToDocument is stored and |
140 | -- has not yet been retrieved, this method will retrieve it. |
141 | raises NoSuchObject from Standard; |
142 | |
143 | IsInSession(me; aReferenceIdentifier: Integer from Standard) |
144 | returns Boolean from Standard |
145 | ---Purpose: returns True if the To Document of the reference |
146 | -- identified by aReferenceIdentifier is in session, False |
147 | -- if it corresponds to a not yet retrieved document. |
148 | raises NoSuchObject from Standard; |
149 | |
150 | IsStored(me; aReferenceIdentifier: Integer from Standard) |
151 | returns Boolean from Standard |
152 | ---Purpose: returns True if the To Document of the reference |
153 | -- identified by aReferenceIdentifier has already been stored, |
154 | -- False otherwise. |
155 | raises NoSuchObject from Standard; |
156 | |
157 | Name(me; aReferenceIdentifier: Integer from Standard) |
158 | returns ExtendedString from TCollection |
159 | ---Purpose: returns the name of the metadata of the To Document of |
160 | -- the reference identified by aReferenceIdentifier. |
161 | raises DomainError from Standard; |
162 | ---Warning: if the corresponding document is not stored. |
163 | |
164 | UpdateFromDocuments(me; aModifContext: Address from Standard); |
165 | ---Purpose: call virtual method Update on all referencing |
166 | -- documents. This method keeps the list of the -- |
167 | -- documents to process.It may be the starting of an |
168 | -- update -- cycle. If not, the reentrant calls made by |
169 | -- Update method (without argument) will append the |
170 | -- referencing documents to the list and call the Update method |
171 | -- (with arguments). Only the first call to UpdateFromDocuments |
172 | -- generate call to Update(). |
173 | |
174 | ToReferencesNumber(me) |
175 | returns Integer from Standard; |
176 | ---Purpose: returns the number of references having this document as |
177 | -- From Document. |
178 | |
179 | |
180 | FromReferencesNumber(me) |
181 | returns Integer from Standard; |
182 | ---Purpose: returns the number of references having this document as |
183 | -- To Document. |
184 | |
185 | ShallowReferences(me; aDocument: Document from CDM) |
186 | returns Boolean from Standard; |
187 | ---Purpose: returns True is this document references aDocument; |
188 | -- |
189 | DeepReferences(me; aDocument: Document from CDM) |
190 | returns Boolean from Standard; |
191 | ---Purpose: returns True is this document references aDocument; |
192 | -- |
193 | CopyReference(me: mutable; aFromDocument: Document from CDM; aReferenceIdentifier: Integer from Standard) |
194 | returns Integer from Standard; |
195 | ---Purpose: Copies a reference to this document. This method |
196 | -- avoid retrieval of referenced document. The arguments |
197 | -- are the original document and a valid reference |
198 | -- identifier Returns the local identifier. |
199 | -- |
200 | ---Category: Modifications Counter management. |
201 | |
202 | IsReadOnly(me) returns Boolean from Standard; |
203 | ---Purpose: indicates that this document cannot be modified. |
204 | |
205 | |
206 | |
207 | IsReadOnly(me; aReferenceIdentifier: Integer from Standard) |
208 | returns Boolean from Standard; |
209 | ---Purpose: indicates that the referenced document cannot be modified, |
210 | |
211 | |
212 | SetIsReadOnly(me: mutable); |
213 | |
214 | UnsetIsReadOnly(me: mutable); |
215 | |
216 | Modify(me: mutable); |
217 | ---Purpose: Indicates that this document has been modified. |
218 | -- This method increments the modification counter. |
219 | -- |
220 | Modifications(me) returns Integer from Standard; |
221 | ---Purpose: returns the current modification counter. |
222 | |
223 | UnModify(me: mutable); |
224 | |
225 | IsUpToDate(me; aReferenceIdentifier: Integer from Standard) |
226 | returns Boolean from Standard; |
227 | ---Purpose: returns true if the modification counter found in the given |
228 | -- reference is equal to the actual modification counter of |
229 | -- the To Document. This method is able to deal with a reference |
230 | -- to a not retrieved document. |
231 | |
232 | |
233 | SetIsUpToDate(me: mutable; aReferenceIdentifier: Integer from Standard); |
234 | ---Purpose: Resets the modification counter in the given reference |
235 | -- to the actual modification counter of its To Document. |
236 | -- This method should be called after the application has updated |
237 | -- this document. |
238 | |
239 | |
240 | SetComment(me: mutable; aComment: ExtendedString from TCollection); |
241 | ---Purpose: associates a comment with this document. |
242 | |
243 | AddComment(me: mutable; aComment: ExtendedString from TCollection); |
244 | ---Purpose: appends a comment into comments of this document. |
245 | |
246 | SetComments(me: mutable; aComments: SequenceOfExtendedString from TColStd); |
247 | ---Purpose: associates a comments with this document. |
248 | |
249 | Comments(me; aComments: out SequenceOfExtendedString from TColStd); |
250 | ---Purpose: returns the associated comments through <aComments>. |
251 | -- Returns empty sequence if no comments are associated. |
252 | |
253 | Comment(me) returns ExtString from Standard; |
254 | ---Purpose: returns the first of associated comments. By defaut |
255 | -- the comment is an empty string. |
256 | |
257 | ---Category: presentation methods. The presentation is an alphanumeric string. |
258 | -- In a given session a presentation cannot be given to two differents |
259 | -- documents. |
260 | |
261 | Presentation(me: mutable) returns ExtString from Standard; |
262 | ---Purpose: Returns an alphanumeric string identifying this document |
263 | -- in a unique manner in the current process. The presentation |
264 | -- may change when the document is stored. |
265 | -- Tries to get the 'FileFormat`.Presentation resource |
266 | -- This item is used to give a default presentation |
267 | -- to the document. |
268 | FindFromPresentation(myclass; aPresentation: ExtendedString from TCollection) |
269 | returns Document from CDM |
270 | ---Purpose: returns the document having the given alphanumeric presentation. |
271 | raises NoSuchObject from Standard; |
272 | |
273 | |
274 | FindPresentation(myclass; aPresentation: ExtendedString from TCollection) |
275 | returns Boolean from Standard; |
276 | ---Purpose: indicates whether a document having the given presentation |
277 | -- does exist. |
278 | |
279 | ---Category: database related methods |
280 | IsStored(me) returns Boolean from Standard; |
281 | |
282 | StorageVersion(me) returns Integer from Standard; |
283 | ---Purpose: returns the value of the modification counter at the |
284 | -- time of storage. By default returns 0. |
285 | |
286 | |
287 | SetMetaData(me: mutable; aMetaData: MetaData from CDM); |
288 | ---Purpose: associates database information to a document which |
289 | -- has been stored. The name of the document is now the |
290 | -- name which has beenused to store the data. |
291 | |
292 | |
293 | UnsetIsStored(me: mutable); |
294 | |
295 | MetaData(me) returns MetaData from CDM |
296 | raises NoSuchObject from Standard; |
297 | |
298 | Folder(me) returns ExtendedString from TCollection |
299 | raises NoSuchObject from Standard; |
300 | ---Warning: if the object is not stored; |
301 | |
302 | |
303 | ---Category: methods to define where to store the document, the name |
304 | -- under which it has to be stored and some other metadatas. |
305 | |
306 | |
307 | |
308 | SetRequestedFolder(me: mutable; aFolder: ExtendedString from TCollection); |
309 | ---Purpose: defines the folder in which the object should be stored. |
310 | |
311 | RequestedFolder(me) returns ExtendedString from TCollection |
312 | raises NoSuchObject from Standard; |
313 | |
314 | |
315 | HasRequestedFolder(me) returns Boolean from Standard; |
316 | |
317 | |
318 | |
319 | |
320 | SetRequestedName(me: mutable; aName: ExtendedString from TCollection); |
321 | ---Purpose: defines the name under which the object should be stored. |
322 | RequestedName(me:mutable) returns ExtendedString from TCollection; |
323 | ---Purpose: determines under which the document is going to be |
324 | -- store. By default the name of the document wil be -- |
325 | -- used. If the document has no name its presentation |
326 | -- will be used. |
327 | |
328 | SetRequestedPreviousVersion(me: mutable; aPreviousVersion: ExtendedString from TCollection); |
329 | |
330 | UnsetRequestedPreviousVersion(me: mutable); |
331 | |
332 | HasRequestedPreviousVersion(me) returns Boolean from Standard; |
333 | RequestedPreviousVersion(me) returns ExtendedString from TCollection |
334 | raises NoSuchObject from Standard; |
335 | |
336 | SetRequestedComment(me: mutable; aComment: ExtendedString from TCollection); |
337 | ---Purpose: defines the Comment with which the object should be stored. |
338 | |
339 | RequestedComment(me) returns ExtendedString from TCollection; |
340 | |
341 | |
342 | ---Category: resource reading methods |
343 | -- |
344 | -- |
345 | -- |
346 | -- |
347 | -- Resources are read once at the creation of the document |
348 | -- until LoadResources is called again. |
349 | -- |
350 | -- |
351 | LoadResources(me: mutable); |
352 | ---Purpose: read (or rereads) the following resource. |
353 | |
354 | StorageResource(me: mutable) returns Manager from Resource |
355 | is private; |
356 | ---Purpose: the manager returned by this method will be |
357 | -- used to search for the following resource items. |
358 | |
359 | FindFileExtension(me: mutable) returns Boolean from Standard; |
360 | |
361 | FileExtension(me: mutable) returns ExtendedString from TCollection; |
362 | ---Purpose: gets the Desktop.Domain.Application.`FileFormat`.FileExtension resource. |
363 | FindDataType(me: mutable) returns Boolean from Standard; |
364 | |
365 | DataType(me: mutable) returns ExtendedString from TCollection; |
366 | ---Purpose: this datatype will be used if the DBMS deals with this concept |
367 | ---Purpose: gets the `FileFormat`.DataType resource. |
368 | -- concept. |
369 | |
370 | FindVersionDataType(me: mutable) returns Boolean from Standard; |
371 | |
372 | VersionDataType(me: mutable) returns ExtendedString from TCollection; |
373 | ---Purpose: this datatype will be used if the DBMS deals with this concept |
374 | ---Purpose: gets the `FileFormat`.VersionDataType resource. |
375 | -- |
376 | FindDescription(me: mutable) returns Boolean from Standard; |
377 | |
378 | Description(me: mutable) returns ExtendedString from TCollection; |
379 | ---Purpose: gets the `FileFormat`.Description resource. |
380 | |
381 | FindDomain(me: mutable) returns Boolean from Standard; |
382 | |
383 | Domain(me: mutable) returns ExtendedString from TCollection; |
384 | ---Purpose: gets the `FileFormat`.Domain resource. |
385 | |
386 | |
387 | FindStoragePlugin(me: mutable) returns Boolean from Standard; |
388 | |
389 | StoragePlugin(me: mutable) returns GUID from Standard; |
390 | |
391 | ---Category: Miscellaneous methods |
392 | |
393 | IsModified(me) returns Boolean from Standard; |
394 | ---Purpose: returns true if the version is greater than the |
395 | -- storage version |
396 | |
397 | ---Category: print method |
398 | Print(me; anOStream: in out OStream from Standard) |
399 | returns OStream from Standard; |
400 | ---C++: return & |
401 | ---C++: alias "Standard_OStream& operator << (Standard_OStream& anOStream);" |
402 | |
403 | ---Category: activation controll |
404 | |
405 | IsOpened(me) returns Boolean from Standard; |
406 | |
407 | Open(me: mutable; anApplication: Application from CDM); |
408 | |
409 | |
410 | CanClose(me) returns CanCloseStatus from CDM; |
411 | ---Purpose: |
412 | --Returns CDM_CCS_OK true if it is possible to close the document. |
413 | -- Otherwise, returns: |
414 | -- CDM_CSS_NotOpen if the document has not been opened |
415 | -- CDM_CCS_UnstoredReferenced if the document is not stored if it |
416 | -- is referenced. |
417 | -- CDM_CSS_ModifiedReferenced if the document has been modified, |
418 | -- if it is referenced, since it has been stored. |
419 | -- CDM_CCS_ReferenceRejection if one of the referencing documents |
420 | -- does not allow the closing of the document. |
421 | Close(me: mutable); |
422 | |
423 | Application(me) returns Application from CDM |
424 | raises Failure from Standard; |
425 | ---C++: return const & |
426 | ---Warning: exception if the document is not open |
427 | |
428 | |
429 | CanCloseReference(me; aDocument: Document from CDM; |
430 | aReferenceIdentifier: Integer from Standard) |
431 | returns Boolean from Standard |
432 | is virtual; |
433 | ---Purpose: A referenced document may indicate through this |
434 | -- virtual method that it does not allow the closing of |
435 | -- aDocument which it references through the reference |
436 | -- aReferenceIdentifier. By default returns Standard_True;; |
437 | |
438 | CloseReference(me: mutable; aDocument: Document from CDM; |
439 | aReferenceIdentifier: Integer from Standard) |
440 | is virtual; |
441 | ---Purpose: A referenced document may update its internal |
442 | -- data structure when {aDocument} which it references |
443 | -- through the reference {aReferenceIdentifier} is being closed. |
444 | -- By default this method does nothing. |
445 | |
446 | IsOpened(me; aReferenceIdentifier: Integer from Standard) |
447 | returns Boolean from Standard; |
448 | ---Purpose: returns true if the document corresponding to the |
449 | -- given reference has been retrieved and opened. |
450 | -- Otherwise returns false. This method does not retrieve |
451 | -- the referenced document |
452 | |
453 | ---Category: private methods; |
454 | -- |
455 | Reference(me; aReferenceIdentifier: Integer from Standard) |
456 | returns Reference from CDM |
457 | is private; |
458 | |
459 | ComputePresentation(me: mutable) |
460 | is private; |
461 | |
462 | UnvalidPresentation(me: mutable) |
463 | is private; |
464 | |
465 | CreateReference(me: mutable; aMetaData: MetaData from CDM; aReferenceIdentifier: Integer from Standard; anApplication: Application from CDM; aToDocumentVersion: Integer from Standard; UseStorageConfiguration: Boolean from Standard); |
466 | |
467 | CreateReference(me: mutable; aMetaData: MetaData from CDM; anApplication: Application from CDM; aDocumentVersion: Integer from Standard; UseStorageConfiguration: Boolean from Standard) |
468 | returns Integer from Standard; |
469 | |
470 | AddToReference(me: mutable; aReference: Reference from CDM) |
471 | is private; |
472 | |
473 | AddFromReference(me: mutable; aReference: Reference from CDM) |
474 | is private; |
475 | |
476 | RemoveFromReference(me: mutable; aReferenceIdentifier: Integer from Standard) |
477 | is private; |
478 | |
479 | SetModifications(me: mutable; Modifications: Integer from Standard) |
480 | is private; |
481 | |
482 | ReferenceCounter(me) returns Integer from Standard; |
483 | |
484 | SetReferenceCounter(me: mutable; aReferenceCounter: Integer from Standard) |
485 | is private; |
486 | |
487 | ---Category: obsolete methods |
488 | |
489 | Update(me: mutable) |
490 | is virtual; |
491 | ---Purpose: the following method should be used instead: |
492 | -- |
493 | -- Update(me:mutable; ErrorString: out ExtendedString from TCollection) |
494 | -- returns Boolean from Standard |
495 | |
496 | fields |
497 | |
498 | |
499 | myComments: SequenceOfExtendedString from TColStd; |
500 | |
501 | myPresentation: ExtendedString from TCollection; |
502 | myValidPresentation: Boolean from Standard; |
503 | |
504 | myFromReferences: ListOfReferences from CDM; |
505 | myToReferences: ListOfReferences from CDM; |
506 | myVersion: Integer from Standard; |
507 | |
508 | myActualReferenceIdentifier: Integer from Standard; |
509 | |
510 | myStorageVersion: Integer from Standard; |
511 | myMetaData: MetaData from CDM; |
512 | |
513 | myRequestedComment: ExtendedString from TCollection; |
514 | |
515 | myRequestedFolder: ExtendedString from TCollection; |
516 | myRequestedFolderIsDefined: Boolean from Standard; |
517 | |
518 | myRequestedName: ExtendedString from TCollection; |
519 | myRequestedNameIsDefined: Boolean from Standard; |
520 | |
521 | myRequestedPreviousVersionIsDefined: Boolean from Standard; |
522 | myRequestedPreviousVersion: ExtendedString from TCollection; |
523 | |
524 | ---Category: resources. |
525 | myFileExtension,myDataType,myVersionDataType,myDescription,myDomain,myDefaultPresentation: ExtendedString from TCollection; |
526 | |
527 | myFileExtensionWasFound,myDataTypeWasFound,myVersionDataTypeWasFound,myDescriptionWasFound,myDomainWasFound,myStoragePluginWasFound,myDefaultPresentationWasFound: Boolean from Standard; |
528 | myResourcesAreLoaded: Boolean from Standard is protected; |
529 | myStoragePlugin: GUID from Standard; |
530 | myApplication: Application from CDM; |
531 | |
532 | friends |
533 | class Reference from CDM, |
534 | class ReferenceIterator from CDM, |
535 | class Application from CDM |
536 | |
537 | end Document from CDM; |