0031918: Application Framework - New binary format for fast reading part of OCAF...
[occt.git] / src / CDF / CDF_Application.hxx
1 // Created on: 1997-08-07
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 _CDF_Application_HeaderFile
18 #define _CDF_Application_HeaderFile
19
20 #include <TCollection_ExtendedString.hxx>
21 #include <PCDM_ReaderStatus.hxx>
22 #include <CDF_TypeOfActivation.hxx>
23 #include <CDF_MetaDataDriver.hxx>
24 #include <CDM_Application.hxx>
25 #include <CDM_CanCloseStatus.hxx>
26 #include <TColStd_SequenceOfExtendedString.hxx>
27 #include <Standard_IStream.hxx>
28 #include <NCollection_IndexedDataMap.hxx>
29
30 class Standard_NoSuchObject;
31 class Standard_GUID;
32 class CDM_Document;
33 class TCollection_ExtendedString;
34 class PCDM_Reader;
35 class CDM_MetaData;
36 class PCDM_RetrievalDriver;
37 class PCDM_StorageDriver;
38 class CDF_Directory;
39 class CDF_Application;
40 DEFINE_STANDARD_HANDLE(CDF_Application, CDM_Application)
41
42
43 class CDF_Application : public CDM_Application
44 {
45
46 public:
47
48   
49   //! plugs an application.
50   //!
51   //! Open is used
52   //! - for opening a Document that has been created in an application
53   //! - for opening a Document from the database
54   //! - for opening a Document from a file.
55   //! The Open methods always add the document in the session directory and
56   //! calls the virtual Activate method. The document is considered to be
57   //! opened until Close is used. To be storable, a document must be
58   //! opened by an application since the application resources are
59   //! needed to store it.
60   Standard_EXPORT static Handle(CDF_Application) Load (const Standard_GUID& aGUID);
61
62   //! Constructs an new empty document.
63   //! This document will have the specified format.
64   //! If InitDocument() is redefined for a specific
65   //! application, the new document is handled by the
66   //! applicative session.
67   Standard_EXPORT virtual void NewDocument(const TCollection_ExtendedString& theFormat, Handle(CDM_Document)& theDoc);
68
69   //! Initialize a document for the applicative session.
70   //! This virtual function is called by NewDocument
71   //! and should be redefined for each specific application.
72   Standard_EXPORT virtual void InitDocument(const Handle(CDM_Document)& theDoc) const;
73
74   //! puts the document in the current session directory
75   //! and calls the virtual method Activate on it.
76   Standard_EXPORT void Open (const Handle(CDM_Document)& aDocument);
77   
78   Standard_EXPORT CDM_CanCloseStatus CanClose (const Handle(CDM_Document)& aDocument);
79   
80   //! removes the document of the current session directory
81   //! and closes the document;
82   Standard_EXPORT void Close (const Handle(CDM_Document)& aDocument);
83   
84   //! This method retrieves a document from the database.
85   //! If the Document references other documents which have
86   //! been updated, the latest version of these documents will
87   //! be used if {UseStorageConfiguration} is Standard_True.
88   //! The content of {aFolder}, {aName} and {aVersion} depends on
89   //! the Database Manager system. If the DBMS is only based on
90   //! the OS, {aFolder} is a directory and {aName} is the name of a
91   //! file. In this case the use of the syntax with {aVersion}
92   //! has no sense. For example:
93   //!
94   //! Handle(CDM_Document) theDocument=myApplication->Retrieve("/home/cascade","box.dsg");
95   //! If the DBMS is EUCLID/Design Manager, {aFolder}, {aName}
96   //! have the form they have in EUCLID/Design Manager. For example:
97   //!
98   //! Handle(CDM_Document) theDocument=myApplication->Retrieve("|user|cascade","box");
99   //!
100   //! Since  the version is not specified in  this syntax, the  latest will be used.
101   //! A link is kept with the database through an instance of CDM_MetaData
102   Standard_EXPORT Handle(CDM_Document) Retrieve
103     (const TCollection_ExtendedString& aFolder,
104      const TCollection_ExtendedString& aName,
105      const Standard_Boolean UseStorageConfiguration = Standard_True,
106      const Handle(PCDM_ReaderFilter)& theFilter = Handle(PCDM_ReaderFilter)(),
107      const Message_ProgressRange& theRange = Message_ProgressRange());
108   
109   //! This method retrieves  a  document from the database.
110   //! If the  Document references other documents which have
111   //! been  updated, the  latest version of  these documents
112   //! will    be   used  if   {UseStorageConfiguration}  is
113   //! Standard_True.  --  If the DBMS is  only  based on the
114   //! OS, this syntax  should not be used.
115   //!
116   //! If the DBMS is EUCLID/Design Manager, {aFolder}, {aName}
117   //! and  {aVersion} have the form they have in
118   //! EUCLID/Design Manager. For example:
119   //!
120   //! Handle(CDM_Document) theDocument=myApplication->Retrieve("|user|cascade","box","2");
121   //! A link is kept with the database through an instance
122   //! of CDM_MetaData
123   Standard_EXPORT Handle(CDM_Document) Retrieve
124     (const TCollection_ExtendedString& aFolder, 
125      const TCollection_ExtendedString& aName, 
126      const TCollection_ExtendedString& aVersion, 
127      const Standard_Boolean UseStorageConfiguration = Standard_True,
128      const Handle(PCDM_ReaderFilter)& theFilter = Handle(PCDM_ReaderFilter)(),
129      const Message_ProgressRange& theRange = Message_ProgressRange());
130   
131   Standard_EXPORT PCDM_ReaderStatus CanRetrieve (const TCollection_ExtendedString& theFolder,
132                                                  const TCollection_ExtendedString& theName,
133                                                  const bool theAppendMode);
134   
135   Standard_EXPORT PCDM_ReaderStatus CanRetrieve (const TCollection_ExtendedString& theFolder,
136                                                  const TCollection_ExtendedString& theName,
137                                                  const TCollection_ExtendedString& theVersion,
138                                                  const bool theAppendMode);
139   
140   //! Checks  status  after  Retrieve
141   PCDM_ReaderStatus GetRetrieveStatus() const { return myRetrievableStatus; }
142   
143   //! Reads theDocument from standard SEEKABLE stream theIStream,
144   //! the stream should support SEEK functionality
145   Standard_EXPORT void Read
146     (Standard_IStream& theIStream,
147      Handle(CDM_Document)& theDocument,
148      const Handle(PCDM_ReaderFilter)& theFilter = Handle(PCDM_ReaderFilter)(),
149      const Message_ProgressRange& theRange = Message_ProgressRange());
150  
151   //! Returns instance of read driver for specified format.
152   //!
153   //! Default implementation uses plugin mechanism to load reader dynamically.
154   //! For this to work, application resources should define GUID of
155   //! the plugin as value of [Format].RetrievalPlugin, and "Plugin"
156   //! resource should define name of plugin library to be loaded as
157   //! value of [GUID].Location. Plugin library should provide
158   //! method PLUGINFACTORY returning instance of the reader for the
159   //! same GUID (see Plugin_Macro.hxx).
160   //!
161   //! In case if reader is not available, will raise Standard_NoSuchObject
162   //! or other exception if raised by plugin loader.
163   Standard_EXPORT virtual Handle(PCDM_Reader) ReaderFromFormat (const TCollection_ExtendedString& aFormat);
164   
165   //! Returns instance of storage driver for specified format.
166   //!
167   //! Default implementation uses plugin mechanism to load driver dynamically.
168   //! For this to work, application resources should define GUID of
169   //! the plugin as value of [Format].StoragePlugin, and "Plugin"
170   //! resource should define name of plugin library to be loaded as
171   //! value of [GUID].Location. Plugin library should provide
172   //! method PLUGINFACTORY returning instance of the reader for the
173   //! same GUID (see Plugin_Macro.hxx).
174   //!
175   //! In case if driver is not available, will raise Standard_NoSuchObject
176   //! or other exception if raised by plugin loader.
177   Standard_EXPORT virtual Handle(PCDM_StorageDriver) WriterFromFormat (const TCollection_ExtendedString& aFormat);
178   
179   //! try to  retrieve a Format  directly in the  file or in
180   //! application   resource  by using   extension. returns
181   //! True if found;
182   Standard_EXPORT Standard_Boolean Format (const TCollection_ExtendedString& aFileName,
183                                            TCollection_ExtendedString& theFormat);
184   
185   Standard_EXPORT Standard_ExtString DefaultFolder();
186   
187   Standard_EXPORT Standard_Boolean SetDefaultFolder (const Standard_ExtString aFolder);
188
189   //! returns MetaDatdDriver of this application
190   Standard_EXPORT Handle(CDF_MetaDataDriver) MetaDataDriver() const;
191
192   DEFINE_STANDARD_RTTIEXT(CDF_Application,CDM_Application)
193
194   Handle(CDF_MetaDataDriver) myMetaDataDriver;
195   Handle(CDF_Directory) myDirectory;
196 private:
197
198   
199   //! Informs the  application that aDocument has  been
200   //! activated. A document is activated when it is created or
201   //! retrieved.
202   //! aTypeOfActivation will be:
203   //! - CDF_TOA_New if the document is a new one
204   //! (even empty or retrieved from the database for
205   //! the first time).
206   //! - CDF_TOA_Unchanged if the document was already
207   //! retrieved but had no changes since the previous retrieval.
208   //! - CDF_TOA_Modified if the document was already
209   //! retrieved and modified since the previous retrieval.
210   //! You do not need to call <Activate>, but you should  redefine
211   //! this method to implement application specific behavior.
212   Standard_EXPORT virtual void Activate (const Handle(CDM_Document)& aDocument,
213                                          const CDF_TypeOfActivation aTypeOfActivation);
214   
215   Standard_EXPORT Handle(CDM_Document) Retrieve
216     (const Handle(CDM_MetaData)& aMetaData, 
217      const Standard_Boolean UseStorageConfiguration, 
218      const Handle(PCDM_ReaderFilter)& theFilter = Handle(PCDM_ReaderFilter)(),
219      const Message_ProgressRange& theRange = Message_ProgressRange()) Standard_OVERRIDE;
220   
221   Standard_EXPORT Handle(CDM_Document) Retrieve
222     (const Handle(CDM_MetaData)& aMetaData,
223      const Standard_Boolean UseStorageConfiguration, 
224      const Standard_Boolean IsComponent, 
225      const Handle(PCDM_ReaderFilter)& theFilter = Handle(PCDM_ReaderFilter)(),
226      const Message_ProgressRange& theRange = Message_ProgressRange());
227   
228   Standard_EXPORT Standard_Integer DocumentVersion (const Handle(CDM_MetaData)& theMetaData) Standard_OVERRIDE;
229   
230   Standard_EXPORT CDF_TypeOfActivation TypeOfActivation (const Handle(CDM_MetaData)& aMetaData);
231   
232   Standard_EXPORT PCDM_ReaderStatus CanRetrieve (const Handle(CDM_MetaData)& aMetaData, const bool theAppendMode);
233
234 protected:
235
236   Standard_EXPORT CDF_Application();
237
238   PCDM_ReaderStatus myRetrievableStatus;
239   NCollection_IndexedDataMap<TCollection_ExtendedString, Handle(PCDM_RetrievalDriver)> myReaders;
240   NCollection_IndexedDataMap<TCollection_ExtendedString, Handle(PCDM_StorageDriver)> myWriters;
241
242 private:
243   TCollection_ExtendedString myDefaultFolder;
244 };
245
246 #endif // _CDF_Application_HeaderFile