CDM_Document Class Reference

An applicative document is an instance of a class inheriting CDM_Document. These documents have the following properties: More...

#include <CDM_Document.hxx>

Inheritance diagram for CDM_Document:

Public Member Functions
virtual void	Update (const occ::handle< CDM_Document > &aToDocument, const int aReferenceIdentifier, void *const aModifContext)
	The Update method will be called once for each reference, but it should not perform any computation, to avoid multiple computation of a same document.
virtual bool	Update (TCollection_ExtendedString &ErrorString)
	This method Update will be called to signal the end of the modified references list. The document should be recomputed and UpdateFromDocuments should be called. Update should returns True in case of success, false otherwise. In case of Failure, additional information can be given in ErrorString.
virtual TCollection_ExtendedString	StorageFormat () const =0
	The Storage Format is the key which is used to determine in the application resources the storage driver plugin, the file extension and other data used to store the document.
virtual void	Extensions (NCollection_Sequence< TCollection_ExtendedString > &Extensions) const
	by default empties the extensions.
virtual bool	GetAlternativeDocument (const TCollection_ExtendedString &aFormat, occ::handle< CDM_Document > &anAlternativeDocument)
	This method can be redefined to extract another document in a different format. For example, to extract a Shape from an applicative document.
int	CreateReference (const occ::handle< CDM_Document > &anOtherDocument)
	Creates a reference from this document to {anOtherDocument}. Returns a reference identifier. This reference identifier is unique in the document and will not be used for the next references, even after the storing of the document. If there is already a reference between the two documents, the reference is not created, but its reference identifier is returned.
void	RemoveReference (const int aReferenceIdentifier)
	Removes the reference between the From Document and the To Document identified by a reference identifier.
void	RemoveAllReferences ()
	Removes all references having this document for From Document.
occ::handle< CDM_Document >	Document (const int aReferenceIdentifier) const
	Returns the To Document of the reference identified by aReferenceIdentifier. If the ToDocument is stored and has not yet been retrieved, this method will retrieve it.
bool	IsInSession (const int aReferenceIdentifier) const
	returns True if the To Document of the reference identified by aReferenceIdentifier is in session, False if it corresponds to a not yet retrieved document.
bool	IsStored (const int aReferenceIdentifier) const
	returns True if the To Document of the reference identified by aReferenceIdentifier has already been stored, False otherwise.
TCollection_ExtendedString	Name (const int aReferenceIdentifier) const
	returns the name of the metadata of the To Document of the reference identified by aReferenceIdentifier.
void	UpdateFromDocuments (void *const aModifContext) const
	call virtual method Update on all referencing documents. This method keeps the list of the documents to process. It may be the starting of an update cycle. If not, the reentrant calls made by Update method (without argument) will append the referencing documents to the list and call the Update method (with arguments). Only the first call to UpdateFromDocuments generate call to Update().
int	ToReferencesNumber () const
	returns the number of references having this document as From Document.
int	FromReferencesNumber () const
	returns the number of references having this document as To Document.
bool	ShallowReferences (const occ::handle< CDM_Document > &aDocument) const
	returns True is this document references aDocument;
bool	DeepReferences (const occ::handle< CDM_Document > &aDocument) const
	returns True is this document references aDocument;
int	CopyReference (const occ::handle< CDM_Document > &aFromDocument, const int aReferenceIdentifier)
	Copies a reference to this document. This method avoid retrieval of referenced document. The arguments are the original document and a valid reference identifier Returns the local identifier.
bool	IsReadOnly () const
	indicates that this document cannot be modified.
bool	IsReadOnly (const int aReferenceIdentifier) const
	indicates that the referenced document cannot be modified,
void	SetIsReadOnly ()
void	UnsetIsReadOnly ()
void	Modify ()
	Indicates that this document has been modified. This method increments the modification counter.
int	Modifications () const
	returns the current modification counter.
void	UnModify ()
bool	IsUpToDate (const int aReferenceIdentifier) const
	returns true if the modification counter found in the given reference is equal to the actual modification counter of the To Document. This method is able to deal with a reference to a not retrieved document.
void	SetIsUpToDate (const int aReferenceIdentifier)
	Resets the modification counter in the given reference to the actual modification counter of its To Document. This method should be called after the application has updated this document.
void	SetComment (const TCollection_ExtendedString &aComment)
	associates a comment with this document.
void	AddComment (const TCollection_ExtendedString &aComment)
	appends a comment into comments of this document.
void	SetComments (const NCollection_Sequence< TCollection_ExtendedString > &aComments)
	associates a comments with this document.
void	Comments (NCollection_Sequence< TCollection_ExtendedString > &aComments) const
	returns the associated comments through <aComments>. Returns empty sequence if no comments are associated.
const char16_t *	Comment () const
	Returns the first of associated comments. By default the comment is an empty string.
bool	IsStored () const
int	StorageVersion () const
	returns the value of the modification counter at the time of storage. By default returns 0.
void	SetMetaData (const occ::handle< CDM_MetaData > &aMetaData)
	associates database information to a document which has been stored. The name of the document is now the name which has beenused to store the data.
void	UnsetIsStored ()
occ::handle< CDM_MetaData >	MetaData () const
TCollection_ExtendedString	Folder () const
void	SetRequestedFolder (const TCollection_ExtendedString &aFolder)
	defines the folder in which the object should be stored.
TCollection_ExtendedString	RequestedFolder () const
bool	HasRequestedFolder () const
void	SetRequestedName (const TCollection_ExtendedString &aName)
	defines the name under which the object should be stored.
TCollection_ExtendedString	RequestedName ()
	Determines under which the document is going to be store. By default the name of the document will be used. If the document has no name its presentation will be used.
void	SetRequestedPreviousVersion (const TCollection_ExtendedString &aPreviousVersion)
void	UnsetRequestedPreviousVersion ()
bool	HasRequestedPreviousVersion () const
TCollection_ExtendedString	RequestedPreviousVersion () const
void	SetRequestedComment (const TCollection_ExtendedString &aComment)
	defines the Comment with which the object should be stored.
TCollection_ExtendedString	RequestedComment () const
void	LoadResources ()
	read (or rereads) the following resource.
bool	FindFileExtension ()
TCollection_ExtendedString	FileExtension ()
	gets the Desktop.Domain.Application.FileFormat.FileExtension resource.
bool	FindDescription ()
TCollection_ExtendedString	Description ()
	gets the FileFormat.Description resource.
bool	IsModified () const
	returns true if the version is greater than the storage version
Standard_OStream &	Print (Standard_OStream &anOStream) const
Standard_OStream &	operator<< (Standard_OStream &anOStream)
bool	IsOpened () const
void	Open (const occ::handle< CDM_Application > &anApplication)
CDM_CanCloseStatus	CanClose () const
void	Close ()
const occ::handle< CDM_Application > &	Application () const
virtual bool	CanCloseReference (const occ::handle< CDM_Document > &aDocument, const int aReferenceIdentifier) const
	A referenced document may indicate through this virtual method that it does not allow the closing of aDocument which it references through the reference aReferenceIdentifier. By default returns true.
virtual void	CloseReference (const occ::handle< CDM_Document > &aDocument, const int aReferenceIdentifier)
	A referenced document may update its internal data structure when {aDocument} which it references through the reference {aReferenceIdentifier} is being closed. By default this method does nothing.
bool	IsOpened (const int aReferenceIdentifier) const
	returns true if the document corresponding to the given reference has been retrieved and opened. Otherwise returns false. This method does not retrieve the referenced document
void	CreateReference (const occ::handle< CDM_MetaData > &aMetaData, const int aReferenceIdentifier, const occ::handle< CDM_Application > &anApplication, const int aToDocumentVersion, const bool UseStorageConfiguration)
int	CreateReference (const occ::handle< CDM_MetaData > &aMetaData, const occ::handle< CDM_Application > &anApplication, const int aDocumentVersion, const bool UseStorageConfiguration)
int	ReferenceCounter () const
virtual void	Update ()
	the following method should be used instead:
occ::handle< CDM_Reference >	Reference (const int aReferenceIdentifier) const
void	SetModifications (const int Modifications)
void	SetReferenceCounter (const int aReferenceCounter)
void	DumpJson (Standard_OStream &theOStream, int theDepth=-1) const
	Dumps the content of me into the stream.
Public Member Functions inherited from Standard_Transient
	Standard_Transient ()
	Empty constructor.
	Standard_Transient (const Standard_Transient &)
	Copy constructor – does nothing.
Standard_Transient &	operator= (const Standard_Transient &)
	Assignment operator, needed to avoid copying reference counter.
virtual	~Standard_Transient ()=default
	Destructor must be virtual.
virtual const opencascade::handle< Standard_Type > &	DynamicType () const
	Returns a type descriptor about this object.
bool	IsInstance (const opencascade::handle< Standard_Type > &theType) const
	Returns a true value if this is an instance of Type.
bool	IsInstance (const char *const theTypeName) const
	Returns a true value if this is an instance of TypeName.
bool	IsKind (const opencascade::handle< Standard_Type > &theType) const
	Returns true if this is an instance of Type or an instance of any class that inherits from Type. Note that multiple inheritance is not supported by OCCT RTTI mechanism.
bool	IsKind (const char *const theTypeName) const
	Returns true if this is an instance of TypeName or an instance of any class that inherits from TypeName. Note that multiple inheritance is not supported by OCCT RTTI mechanism.
Standard_Transient *	This () const
	Returns non-const pointer to this object (like const_cast). For protection against creating handle to objects allocated in stack or call from constructor, it will raise exception Standard_ProgramError if reference counter is zero.
int	GetRefCount () const noexcept
	Get the reference counter of this object.
void	IncrementRefCounter () noexcept
	Increments the reference counter of this object. Uses relaxed memory ordering since incrementing only requires atomicity, not synchronization with other memory operations.
int	DecrementRefCounter () noexcept
	Decrements the reference counter of this object; returns the decremented value. Uses release ordering for the decrement to ensure all writes to the object are visible before the count reaches zero. An acquire fence is added only when the count reaches zero, ensuring proper synchronization before deletion. This is more efficient than using acq_rel for every decrement.
virtual void	Delete () const
	Memory deallocator for transient classes.

Protected Member Functions
	CDM_Document ()
	~CDM_Document () override

Protected Attributes
bool	myResourcesAreLoaded

Additional Inherited Members
Public Types inherited from Standard_Transient
typedef void	base_type
	Returns a type descriptor about this object.
Static Public Member Functions inherited from Standard_Transient
static constexpr const char *	get_type_name ()
	Returns a type descriptor about this object.
static const opencascade::handle< Standard_Type > &	get_type_descriptor ()
	Returns type descriptor of Standard_Transient class.

Detailed Description

An applicative document is an instance of a class inheriting CDM_Document. These documents have the following properties:

• they can have references to other documents.
• the modifications of a document are propagated to the referencing documents.
• a document can be stored in different formats, with or without a persistent model.
• the drivers for storing and retrieving documents are plugged in when necessary.
• a document has a modification counter. This counter is incremented when the document is modified. When a document is stored, the current counter value is memorized as the last storage version of the document. A document is considered to be modified when the counter value is different from the storage version. Once the document is saved the storage version and the counter value are identical. The document is now not considered to be modified.
• a reference is a link between two documents. A reference has two components: the "From Document" and the "To Document". When a reference is created, an identifier of the reference is generated. This identifier is unique in the scope of the From Document and is conserved during storage and retrieval. This means that the referenced document will be always accessible through this identifier.
• a reference memorizes the counter value of the To Document when the reference is created. The From Document is considered to be up to date relative to the To Document when the reference counter value is equal to the To Document counter value.
• retrieval of a document having references does not imply the retrieving of the referenced documents.

Constructor & Destructor Documentation

CDM_Document()

CDM_Document::CDM_Document ( )

protected

~CDM_Document()

CDM_Document::~CDM_Document ( )

overrideprotected

Member Function Documentation

AddComment()

void CDM_Document::AddComment

(

const TCollection_ExtendedString &

aComment

)

appends a comment into comments of this document.

Application()

const occ::handle< CDM_Application > & CDM_Document::Application

(

)

const

CanClose()

CDM_CanCloseStatus CDM_Document::CanClose

(

)

const

CanCloseReference()

virtual bool CDM_Document::CanCloseReference ( const occ::handle< CDM_Document > & aDocument, const int aReferenceIdentifier ) const

virtual

A referenced document may indicate through this virtual method that it does not allow the closing of aDocument which it references through the reference aReferenceIdentifier. By default returns true.

Close()

void CDM_Document::Close

(

)

CloseReference()

virtual void CDM_Document::CloseReference ( const occ::handle< CDM_Document > & aDocument, const int aReferenceIdentifier )

virtual

A referenced document may update its internal data structure when {aDocument} which it references through the reference {aReferenceIdentifier} is being closed. By default this method does nothing.

Comment()

const char16_t * CDM_Document::Comment

(

)

const

Returns the first of associated comments. By default the comment is an empty string.

Comments()

void CDM_Document::Comments

(

NCollection_Sequence< TCollection_ExtendedString > &

aComments

)

const

returns the associated comments through <aComments>. Returns empty sequence if no comments are associated.

CopyReference()

int CDM_Document::CopyReference	(	const occ::handle< CDM_Document > &	aFromDocument,
		const int	aReferenceIdentifier )

Copies a reference to this document. This method avoid retrieval of referenced document. The arguments are the original document and a valid reference identifier Returns the local identifier.

CreateReference() [1/3]

int CDM_Document::CreateReference

(

const occ::handle< CDM_Document > &

anOtherDocument

)

Creates a reference from this document to {anOtherDocument}. Returns a reference identifier. This reference identifier is unique in the document and will not be used for the next references, even after the storing of the document. If there is already a reference between the two documents, the reference is not created, but its reference identifier is returned.

CreateReference() [2/3]

void CDM_Document::CreateReference	(	const occ::handle< CDM_MetaData > &	aMetaData,
		const int	aReferenceIdentifier,
		const occ::handle< CDM_Application > &	anApplication,
		const int	aToDocumentVersion,
		const bool	UseStorageConfiguration )

CreateReference() [3/3]

int CDM_Document::CreateReference	(	const occ::handle< CDM_MetaData > &	aMetaData,
		const occ::handle< CDM_Application > &	anApplication,
		const int	aDocumentVersion,
		const bool	UseStorageConfiguration )

DeepReferences()

bool CDM_Document::DeepReferences

(

const occ::handle< CDM_Document > &

aDocument

)

const

returns True is this document references aDocument;

Description()

TCollection_ExtendedString CDM_Document::Description

(

)

gets the FileFormat.Description resource.

Document()

occ::handle< CDM_Document > CDM_Document::Document

(

const int

aReferenceIdentifier

)

const

Returns the To Document of the reference identified by aReferenceIdentifier. If the ToDocument is stored and has not yet been retrieved, this method will retrieve it.

DumpJson()

void CDM_Document::DumpJson	(	Standard_OStream &	theOStream,
		int	theDepth = -1 ) const

Dumps the content of me into the stream.

Extensions()

virtual void CDM_Document::Extensions ( NCollection_Sequence< TCollection_ExtendedString > & Extensions ) const

virtual

by default empties the extensions.

FileExtension()

TCollection_ExtendedString CDM_Document::FileExtension

(

)

gets the Desktop.Domain.Application.FileFormat.FileExtension resource.

FindDescription()

bool CDM_Document::FindDescription

(

)

FindFileExtension()

bool CDM_Document::FindFileExtension

(

)

Folder()

TCollection_ExtendedString CDM_Document::Folder

(

)

const

FromReferencesNumber()

int CDM_Document::FromReferencesNumber

(

)

const

returns the number of references having this document as To Document.

GetAlternativeDocument()

virtual bool CDM_Document::GetAlternativeDocument ( const TCollection_ExtendedString & aFormat, occ::handle< CDM_Document > & anAlternativeDocument )

virtual

This method can be redefined to extract another document in a different format. For example, to extract a Shape from an applicative document.

HasRequestedFolder()

bool CDM_Document::HasRequestedFolder

(

)

const

HasRequestedPreviousVersion()

bool CDM_Document::HasRequestedPreviousVersion

(

)

const

IsInSession()

bool CDM_Document::IsInSession

(

const int

aReferenceIdentifier

)

const

returns True if the To Document of the reference identified by aReferenceIdentifier is in session, False if it corresponds to a not yet retrieved document.

IsModified()

bool CDM_Document::IsModified

(

)

const

returns true if the version is greater than the storage version

IsOpened() [1/2]

bool CDM_Document::IsOpened

(

)

const

IsOpened() [2/2]

bool CDM_Document::IsOpened

(

const int

aReferenceIdentifier

)

const

returns true if the document corresponding to the given reference has been retrieved and opened. Otherwise returns false. This method does not retrieve the referenced document

IsReadOnly() [1/2]

bool CDM_Document::IsReadOnly

(

)

const

indicates that this document cannot be modified.

IsReadOnly() [2/2]

bool CDM_Document::IsReadOnly

(

const int

aReferenceIdentifier

)

const

indicates that the referenced document cannot be modified,

IsStored() [1/2]

bool CDM_Document::IsStored

(

)

const

IsStored() [2/2]

bool CDM_Document::IsStored

(

const int

aReferenceIdentifier

)

const

returns True if the To Document of the reference identified by aReferenceIdentifier has already been stored, False otherwise.

IsUpToDate()

bool CDM_Document::IsUpToDate

(

const int

aReferenceIdentifier

)

const

returns true if the modification counter found in the given reference is equal to the actual modification counter of the To Document. This method is able to deal with a reference to a not retrieved document.

LoadResources()

void CDM_Document::LoadResources

(

)

read (or rereads) the following resource.

MetaData()

occ::handle< CDM_MetaData > CDM_Document::MetaData

(

)

const

Modifications()

int CDM_Document::Modifications

(

)

const

returns the current modification counter.

Modify()

void CDM_Document::Modify

(

)

Indicates that this document has been modified. This method increments the modification counter.

Name()

TCollection_ExtendedString CDM_Document::Name

(

const int

aReferenceIdentifier

)

const

returns the name of the metadata of the To Document of the reference identified by aReferenceIdentifier.

Open()

void CDM_Document::Open

(

const occ::handle< CDM_Application > &

anApplication

)

operator<<()

Standard_OStream & CDM_Document::operator<<

(

Standard_OStream &

anOStream

)

Print()

Standard_OStream & CDM_Document::Print

(

Standard_OStream &

anOStream

)

const

Reference()

occ::handle< CDM_Reference > CDM_Document::Reference

(

const int

aReferenceIdentifier

)

const

ReferenceCounter()

int CDM_Document::ReferenceCounter

(

)

const

RemoveAllReferences()

void CDM_Document::RemoveAllReferences

(

)

Removes all references having this document for From Document.

RemoveReference()

void CDM_Document::RemoveReference

(

const int

aReferenceIdentifier

)

Removes the reference between the From Document and the To Document identified by a reference identifier.

RequestedComment()

TCollection_ExtendedString CDM_Document::RequestedComment

(

)

const

RequestedFolder()

TCollection_ExtendedString CDM_Document::RequestedFolder

(

)

const

RequestedName()

TCollection_ExtendedString CDM_Document::RequestedName

(

)

Determines under which the document is going to be store. By default the name of the document will be used. If the document has no name its presentation will be used.

RequestedPreviousVersion()

TCollection_ExtendedString CDM_Document::RequestedPreviousVersion

(

)

const

SetComment()

void CDM_Document::SetComment

(

const TCollection_ExtendedString &

aComment

)

associates a comment with this document.

SetComments()

void CDM_Document::SetComments

(

const NCollection_Sequence< TCollection_ExtendedString > &

aComments

)

associates a comments with this document.

SetIsReadOnly()

void CDM_Document::SetIsReadOnly

(

)

SetIsUpToDate()

void CDM_Document::SetIsUpToDate

(

const int

aReferenceIdentifier

)

Resets the modification counter in the given reference to the actual modification counter of its To Document. This method should be called after the application has updated this document.

SetMetaData()

void CDM_Document::SetMetaData

(

const occ::handle< CDM_MetaData > &

aMetaData

)

associates database information to a document which has been stored. The name of the document is now the name which has beenused to store the data.

SetModifications()

void CDM_Document::SetModifications

(

const int

Modifications

)

SetReferenceCounter()

void CDM_Document::SetReferenceCounter

(

const int

aReferenceCounter

)

SetRequestedComment()

void CDM_Document::SetRequestedComment

(

const TCollection_ExtendedString &

aComment

)

defines the Comment with which the object should be stored.

SetRequestedFolder()

void CDM_Document::SetRequestedFolder

(

const TCollection_ExtendedString &

aFolder

)

defines the folder in which the object should be stored.

SetRequestedName()

void CDM_Document::SetRequestedName

(

const TCollection_ExtendedString &

aName

)

defines the name under which the object should be stored.

SetRequestedPreviousVersion()

void CDM_Document::SetRequestedPreviousVersion

(

const TCollection_ExtendedString &

aPreviousVersion

)

ShallowReferences()

bool CDM_Document::ShallowReferences

(

const occ::handle< CDM_Document > &

aDocument

)

const

returns True is this document references aDocument;

StorageFormat()

virtual TCollection_ExtendedString CDM_Document::StorageFormat ( ) const

pure virtual

The Storage Format is the key which is used to determine in the application resources the storage driver plugin, the file extension and other data used to store the document.

Implemented in TDocStd_Document.

StorageVersion()

int CDM_Document::StorageVersion

(

)

const

returns the value of the modification counter at the time of storage. By default returns 0.

ToReferencesNumber()

int CDM_Document::ToReferencesNumber

(

)

const

returns the number of references having this document as From Document.

UnModify()

void CDM_Document::UnModify

(

)

UnsetIsReadOnly()

void CDM_Document::UnsetIsReadOnly

(

)

UnsetIsStored()

void CDM_Document::UnsetIsStored

(

)

UnsetRequestedPreviousVersion()

void CDM_Document::UnsetRequestedPreviousVersion

(

)

Update() [1/3]

virtual void CDM_Document::Update ( )

virtual

the following method should be used instead:

Update(me:mutable; ErrorString: out ExtendedString from TCollection) returns Boolean from Standard

Update() [2/3]

virtual void CDM_Document::Update ( const occ::handle< CDM_Document > & aToDocument, const int aReferenceIdentifier, void *const aModifContext )

virtual

The Update method will be called once for each reference, but it should not perform any computation, to avoid multiple computation of a same document.

Reimplemented in TDocStd_Document.

Update() [3/3]

virtual bool CDM_Document::Update ( TCollection_ExtendedString & ErrorString )

virtual

This method Update will be called to signal the end of the modified references list. The document should be recomputed and UpdateFromDocuments should be called. Update should returns True in case of success, false otherwise. In case of Failure, additional information can be given in ErrorString.

UpdateFromDocuments()

void CDM_Document::UpdateFromDocuments

(

void *const

aModifContext

)

const

call virtual method Update on all referencing documents. This method keeps the list of the documents to process. It may be the starting of an update cycle. If not, the reentrant calls made by Update method (without argument) will append the referencing documents to the list and call the Update method (with arguments). Only the first call to UpdateFromDocuments generate call to Update().

Field Documentation

myResourcesAreLoaded

bool CDM_Document::myResourcesAreLoaded

protected

---

The documentation for this class was generated from the following file:

• CDM_Document.hxx