0029822: Make TDocStd_Document extensible

Two virtual methods NewDocument() and InitDocument() are moved from TDocStd_Application to its parent class CDF_Application. In TDocStd_Application these methods remain redefined. These little changes allow creation of a new document only in one virtual method NewDocument(). The methods CreateDocument() in all retrieval drivers are deleted.

Modified files:
- CDF_Application.hxx and cxx: two virtual methods NewDocument() and InitDocument() are moved from TDocStd_Application. The input parameter TDocStd_Document is changed to parent class CDM_Document.
- TDocStd_Application.hxx and cxx: redefines new virtual methods NewDocument() and InitDocument() of the parent class CDF_Application.
- BinLDrivers_DocumentRetrievalDriver.hxx and cxx, StdLDrivers_DocumentRetrievalDriver.hxx and cxx, XmlLDrivers_DocumentRetrievalDriver.hxx and cxx, PCDM_Reader.hxx: a virtual method CreateDocument() is deleted.
- TObj_Application.cxx, XCAFApp_Application.hxx and cxx: down-casting to a descendant class TDocStd_Document is applied.

Documentation:
- upgrade.md is modified.

dox/upgrade/upgrade.md

@@ -2198,3 +2198,7 @@ In order to save a document in an older storage format version, call the method
 This value will be used by storage drivers of a corresponding OCAF file format (XML or binary) and the document will be saved
 following the rules of the specified storage format version (corresponding to an older version of Open CASCADE Technology).
 This way an application based on an old version of Open CASCADE Technology may read documents saved by new applications (based on newer version of Open CASCADE Technology).
+
+@subsection upgrade_760_createdocument New OCAF document
+
+A new OCAF document may be created only by means of the method *NewDocument()* from CDF_Application (redefined in TDocStd_Application). The methods *CreateDocument()* are deleted in all retrieval drivers.

src/BinLDrivers/BinLDrivers_DocumentRetrievalDriver.cxx

@@ -63,16 +63,6 @@ BinLDrivers_DocumentRetrievalDriver::BinLDrivers_DocumentRetrievalDriver ()
   myReaderStatus = PCDM_RS_OK;
 }
 
-//=======================================================================
-//function : CreateDocument
-//purpose  : pure virtual method definition
-//=======================================================================
-
-Handle(CDM_Document) BinLDrivers_DocumentRetrievalDriver::CreateDocument()
-{
-  return new TDocStd_Document(PCDM_RetrievalDriver::GetFormat());
-}
-
 //=======================================================================
 //function : Read
 //purpose  :

src/BinLDrivers/BinLDrivers_DocumentRetrievalDriver.hxx

@@ -55,9 +55,6 @@ public:
   //! Constructor
   Standard_EXPORT BinLDrivers_DocumentRetrievalDriver();
   
-  //! pure virtual method definition
-  Standard_EXPORT virtual Handle(CDM_Document) CreateDocument() Standard_OVERRIDE;
-  
   //! retrieves the content of the file into a new Document.
   Standard_EXPORT virtual void Read (const TCollection_ExtendedString& theFileName,
                                      const Handle(CDM_Document)& theNewDocument, 

src/CDF/CDF_Application.cxx

@@ -52,6 +52,24 @@ Handle(CDF_Application) CDF_Application::Load(const Standard_GUID& aGUID) {
   return Handle(CDF_Application)::DownCast(Plugin::Load(aGUID));
 }
 
+//=======================================================================
+//function : NewDocument
+//purpose  :
+//=======================================================================
+
+void CDF_Application::NewDocument(const TCollection_ExtendedString& /*theFormat*/, Handle(CDM_Document)& /*theDoc*/)
+{
+}
+
+//=======================================================================
+//function : InitDocument
+//purpose  : do nothing
+//=======================================================================
+
+void CDF_Application::InitDocument(const Handle(CDM_Document)& /*theDoc*/) const
+{
+}
+
 //=======================================================================
 //function : Open
 //purpose  : 
@@ -264,7 +282,7 @@ Handle(CDM_Document) CDF_Application::Retrieve (const Handle(CDM_MetaData)& aMet
       theDocument->RemoveAllReferences();
     }
     else
-      theDocument=theReader->CreateDocument();
+      NewDocument(aFormat, theDocument);
     
     SetReferenceCounter(theDocument,PCDM_RetrievalDriver::ReferenceCounter(aMetaData->FileName(), MessageDriver()));
     
@@ -362,7 +380,7 @@ Handle(CDM_Document) CDF_Application::Read (Standard_IStream& theIStream,
   Handle(PCDM_Reader) aReader = ReaderFromFormat (aFormat);
 
   // 2. create document with the detected reader
-  aDoc = aReader->CreateDocument();
+  NewDocument(aFormat, aDoc);
 
   // 3. read the content of theIStream to aDoc
   try

src/CDF/CDF_Application.hxx

@@ -58,7 +58,19 @@ public:
   //! opened by an application since the application resources are
   //! needed to store it.
   Standard_EXPORT static Handle(CDF_Application) Load (const Standard_GUID& aGUID);
-  
+
+  //! Constructs an new empty document.
+  //! This document will have the specified format.
+  //! If InitDocument() is redefined for a specific
+  //! application, the new document is handled by the
+  //! applicative session.
+  Standard_EXPORT virtual void NewDocument(const TCollection_ExtendedString& theFormat, Handle(CDM_Document)& theDoc);
+
+  //! Initialize a document for the applicative session.
+  //! This virtual function is called by NewDocument
+  //! and should be redefined for each specific application.
+  Standard_EXPORT virtual void InitDocument(const Handle(CDM_Document)& theDoc) const;
+
   //! puts the document in the current session directory
   //! and calls the virtual method Activate on it.
   Standard_EXPORT void Open (const Handle(CDM_Document)& aDocument);

src/PCDM/PCDM_Reader.hxx

@@ -41,10 +41,6 @@ class PCDM_Reader : public Standard_Transient
 
 public:
 
-  
-  //! this method is called by the framework before the read method.
-  Standard_EXPORT virtual Handle(CDM_Document) CreateDocument() = 0;
-  
   //! retrieves the content of the file into a new Document.
   Standard_EXPORT virtual void Read (const TCollection_ExtendedString& aFileName, 
                                      const Handle(CDM_Document)& aNewDocument, 

src/StdLDrivers/StdLDrivers_DocumentRetrievalDriver.cxx

@@ -38,15 +38,6 @@
 
 IMPLEMENT_STANDARD_RTTIEXT (StdLDrivers_DocumentRetrievalDriver, PCDM_RetrievalDriver)
 
-//=======================================================================
-//function : CreateDocument
-//purpose  : Create an empty TDocStd_Document
-//=======================================================================
-Handle(CDM_Document) StdLDrivers_DocumentRetrievalDriver::CreateDocument()
-{
-  return new TDocStd_Document (PCDM_RetrievalDriver::GetFormat());
-}
-
 //=======================================================================
 //function : Read
 //purpose  : Retrieve the content of a file into a new document

src/StdLDrivers/StdLDrivers_DocumentRetrievalDriver.hxx

@@ -24,8 +24,6 @@ class StdObjMgt_Persistent;
 class StdLDrivers_DocumentRetrievalDriver : public PCDM_RetrievalDriver
 {
 public:
-  //! Create an empty TDocStd_Document.
-  Standard_EXPORT virtual Handle(CDM_Document) CreateDocument() Standard_OVERRIDE;
 
   //! Retrieve the content of a file into a new document.
   Standard_EXPORT virtual void Read (const TCollection_ExtendedString& theFileName,

src/TDocStd/TDocStd_Application.cxx

@@ -181,7 +181,7 @@ void TDocStd_Application::GetDocument(const Standard_Integer index,Handle(TDocSt
 //purpose  :
 //=======================================================================
 
-void TDocStd_Application::NewDocument(const TCollection_ExtendedString& format,Handle(TDocStd_Document)& aDoc)
+void TDocStd_Application::NewDocument(const TCollection_ExtendedString& format, Handle(CDM_Document)& aDoc)
 {
   Handle(TDocStd_Document) D = new TDocStd_Document(format);
   InitDocument (D);
@@ -189,12 +189,25 @@ void TDocStd_Application::NewDocument(const TCollection_ExtendedString& format,H
   aDoc = D;
 }
 
+//=======================================================================
+//function : NewDocument
+//purpose  : A non-virtual method taking a TDocStd_Documment object as an input.
+//         : Internally it calls a virtual method NewDocument() with CDM_Document object.
+//=======================================================================
+
+void TDocStd_Application::NewDocument (const TCollection_ExtendedString& format, Handle(TDocStd_Document)& aDoc)
+{
+  Handle(CDM_Document) aCDMDoc;
+  NewDocument (format, aCDMDoc);
+  aDoc = Handle(TDocStd_Document)::DownCast (aCDMDoc);
+}
+
 //=======================================================================
 //function : InitDocument
 //purpose  : do nothing
 //=======================================================================
 
-void TDocStd_Application::InitDocument(const Handle(TDocStd_Document)& /*aDoc*/) const
+void TDocStd_Application::InitDocument(const Handle(CDM_Document)& /*aDoc*/) const
 {
 }
 

src/TDocStd/TDocStd_Application.hxx

@@ -29,10 +29,11 @@
 #include <TColStd_SequenceOfAsciiString.hxx>
 #include <PCDM_ReaderStatus.hxx>
 #include <PCDM_StoreStatus.hxx>
+#include <TDocStd_Document.hxx>
 
 class Resource_Manager;
 class Standard_NoSuchObject;
-class TDocStd_Document;
+class CDM_Document;
 class TCollection_ExtendedString;
 
 class TDocStd_Application;
@@ -180,7 +181,11 @@ public:
   //! If InitDocument is redefined for a specific
   //! application, the new document is handled by the
   //! applicative session.
-  Standard_EXPORT virtual void NewDocument (const TCollection_ExtendedString& format, Handle(TDocStd_Document)& aDoc);
+  Standard_EXPORT virtual void NewDocument (const TCollection_ExtendedString& format, Handle(CDM_Document)& aDoc) Standard_OVERRIDE;
+
+  //! A non-virtual method taking a TDocStd_Documment object as an input.
+  //! Internally it calls a virtual method NewDocument() with CDM_Document object.
+  Standard_EXPORT void NewDocument (const TCollection_ExtendedString& format, Handle(TDocStd_Document)& aDoc);
   
   //! Initialize the document aDoc for the applicative session.
   //! This virtual function is called by NewDocument
@@ -189,7 +194,7 @@ public:
   //! =============
   //! to open/save a document
   //! =======================
-  Standard_EXPORT virtual void InitDocument (const Handle(TDocStd_Document)& aDoc) const;
+  Standard_EXPORT virtual void InitDocument (const Handle(CDM_Document)& aDoc) const Standard_OVERRIDE;
   
   //! Close the given document. the document is not any more
   //! handled by the applicative session.

src/XCAFApp/XCAFApp_Application.cxx

@@ -64,9 +64,9 @@ Standard_CString XCAFApp_Application::ResourcesName()
 //purpose  : 
 //=======================================================================
 
-void XCAFApp_Application::InitDocument(const Handle(TDocStd_Document)& aDoc) const
+void XCAFApp_Application::InitDocument(const Handle(CDM_Document)& aDoc) const
 {
-  XCAFDoc_DocumentTool::Set(aDoc->Main());
+  XCAFDoc_DocumentTool::Set(Handle(TDocStd_Document)::DownCast(aDoc)->Main());
 }
 
 //=======================================================================

src/XCAFApp/XCAFApp_Application.hxx

@@ -39,7 +39,7 @@ public:
   Standard_EXPORT virtual Standard_CString ResourcesName() Standard_OVERRIDE;
   
   //! Set XCAFDoc_DocumentTool attribute
-  Standard_EXPORT virtual void InitDocument (const Handle(TDocStd_Document)& aDoc) const Standard_OVERRIDE;
+  Standard_EXPORT virtual void InitDocument (const Handle(CDM_Document)& aDoc) const Standard_OVERRIDE;
   
   //! Initializes (for the first time) and returns the
   //! static object (XCAFApp_Application)

src/XmlLDrivers/XmlLDrivers_DocumentRetrievalDriver.cxx

@@ -161,15 +161,6 @@ XmlLDrivers_DocumentRetrievalDriver::XmlLDrivers_DocumentRetrievalDriver()
   myReaderStatus = PCDM_RS_OK;
 }
 
-//=======================================================================
-//function : CreateDocument
-//purpose  : pure virtual method definition
-//=======================================================================
-Handle(CDM_Document) XmlLDrivers_DocumentRetrievalDriver::CreateDocument()
-{
-  return new TDocStd_Document(PCDM_RetrievalDriver::GetFormat());
-}
-
 //=======================================================================
 //function : Read
 //purpose  : 

src/XmlLDrivers/XmlLDrivers_DocumentRetrievalDriver.hxx

@@ -47,8 +47,6 @@ public:
   
   Standard_EXPORT XmlLDrivers_DocumentRetrievalDriver();
   
-  Standard_EXPORT virtual Handle(CDM_Document) CreateDocument() Standard_OVERRIDE;
-  
   Standard_EXPORT virtual void Read (const TCollection_ExtendedString& theFileName, 
                                      const Handle(CDM_Document)& theNewDocument,
                                      const Handle(CDM_Application)& theApplication,