Class: TStorageMechanism

Declaration: BasicDocumentStorage.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TMultiBinStorageMechanism TSingleBinStorageMechanism

Purpose:

TStorageMechanism provides an abstraction to separate the mechanics of storage from the semantics of storage and acts as the interface between a store object and a physical storage. TStorageMechanism's responsibilities are: (1) to allow access to the physical storage; and (2) to hide the particular kind of physical storage used. The storage mechanism must be understood only if a client developer wishes to supply a new physical storage or needs to extend the storage mechanism API to add new ways of storing data, for example, adding a dictionary interface.

Instantiation:

TStorageMechanism is an abstract base class and only instantiated as part of a derived class.

Deriving Classes:

TStorageMechanism is an abstract base classes. Derived classes must implement the protocols defined by this class. Derived classes must override the pure virtual functions: GetAccessMode, Create, Delete, DoesExist, Open, IsOpened, Close, and CanBitWiseCopy.

Concurrency:

Multithread safe. Concurrency among threads within a team is provided by the shared hidden master. Concurrency between teams is provided by the underlying service used to implement the storage mechanism. In both cases, the semantics of multiple readers, or single writer will be enforced.

Resource Use:

TStorageMechanism is abstract and always created and deleted as part of a derived class.

Member Function: TStorageMechanism::~TStorageMechanism

virtual ~ TStorageMechanism ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStorageMechanism::GetAccessMode

virtual EAccessMode GetAccessMode() const

Interface Category:

API.

Purpose:

Returns the open access mode. This value is not meaningful unless the mechanism is opened.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the access mode.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TStorageMechanism.

Member Function: TStorageMechanism::Create

virtual void Create ()

Interface Category:

API.

Purpose:

Creates an underlying physical storage implementation of the storage mechanism.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TDocumentException::kDocumentStoreAlreadyExists if the store already exists.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TStorageMechanism. Preconditions: Assertion (an underlying physical storage implementation does not exist). Postconditions: Assertion (an underlying physical storage implementation exists).

Member Function: TStorageMechanism::Delete

virtual void Delete ()

Interface Category:

API.

Purpose:

Deletes an underlying physical storage implementation of the storage mechanism.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TDocumentException::kDocumentStoreDoesNotExist.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TStorageMechanism. Preconditions: Assertion (an underlying physical storage implementation exists). Postconditions: Assertion (an underlying physical storage implementation no longer exists).

Member Function: TStorageMechanism::DoesExist

virtual bool DoesExist () const

Interface Category:

API.

Purpose:

Checks whether an underlying physical storage implementation exists.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if an underlying physical storage implementation exists; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TStorageMechanism.

Member Function: TStorageMechanism::Open

virtual void Open (EAccessMode mode)

Interface Category:

API.

Purpose:

Opens the storage mechanism.

Calling Context:

Call this function directly.

Parameters:

EAccessMode mode -The access mode for the storage mechanism.

Return Value:

None.

Exceptions:

Throws TDocumentException::kDocumentStoreAccessDenied.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TStorageMechanism. Preconditions: Assertion (an underlying physical storage implementation exists). Postconditions: Assertion (storage mechanism is opened with specified access mode).

Member Function: TStorageMechanism::IsOpened

virtual bool IsOpened () const

Interface Category:

API.

Purpose:

Checks whether the storage mechanism is opened.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the mechanism is opened; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TStorageMechanism.

Member Function: TStorageMechanism::Close

virtual void Close ()

Interface Category:

API.

Purpose:

Closes the storage mechanism.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TDocumentException::kDocumentStoreDoesNotExist.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TStorageMechanism. Preconditions: Assertion (an underlying physical storage implementation exists). Postconditions: Assertion (storage mechanism is closed).

Member Function: TStorageMechanism::CanBitWiseCopy

virtual bool CanBitWiseCopy ()

Interface Category:

API.

Purpose:

Checks whether a storage mechanism supports bit-wise copying of underlying physical storage implementation.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if a storage mechanism supports bit-wise copying; false otherwise.

Exceptions:

Throws TDocumentException::kDocumentStoreDoesNotExist.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TStorageMechanism. Preconditions: Assertion (an underlying physical storage implementation exists).

Member Function: TStorageMechanism::MarkStreamForFiling

static void MarkStreamForFiling (TStream *)

Interface Category:

API.

Purpose:

Attaches an attribute to the specified stream so that subsequent streaming operations on it will assume filing semantics.

Calling Context:

Call this function directly.

Parameters:

TStream * -The stream on which to enable filing.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Precondition: Assertion (aStream != NIL). Postcondition: Assertion (aStream->IsFilingEnabled() ==true).

Member Function: TStorageMechanism::UnmarkStreamForFiling

static void UnmarkStreamForFiling (TStream *)

Interface Category:

API.

Purpose:

Removes an attribute from the specified stream so that subsequent streaming operations on it will resume streaming semantics.

Calling Context:

Call this function directly.

Parameters:

TStream * -The stream on which to disable filing.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Precondition: Assertion (aStream != NIL). Postcondition: Assertion (aStream->IsFilingEnabled() ==false).

Member Function: TStorageMechanism::IsStreamForFiling

static bool IsStreamForFiling (TStream *)

Interface Category:

API.

Purpose:

Checks to see if the specified stream has streaming or filing semantics.

Calling Context:

Called by filing functions of documents, models, and other objects for determining whether to stream in a reference or the real object.

Parameters:

TStream * -The stream on which to check if filing is enabled.

Return Value:

Returns true if the specified stream supports filing semantics; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Precondition: Assertion (aStream != NIL).

Member Function: TStorageMechanism::TStorageMechanism

TStorageMechanism ()
TStorageMechanism (const TStorageMechanism &)

Interface Category:

API.

Purpose:

Default constructor. Used to resurrect a flattened storage mechanism.
Copy constructor.

Calling Context:

Called by the stream-in operators and derived class constructors.
Called to copy an object.

Parameters:

Takes no parameters.
const TStorageMechanism & aStorageMechanism -The storage mechanism to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

TStorageMechanism is an abstract base class--all the constructors are protected. Do not instantiate this class.

Member Function: TStorageMechanism::operator=

TStorageMechanism & operator =(const TStorageMechanism &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TStorageMechanism & -The right-hand side object.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

TStorageMechanism is an abstract base class--all the constructors are protected. Do not instantiate this class.

Member Function: TStorageMechanism::IsEqual

virtual bool IsEqual (const MCollectible *) const

Interface Category:

API.

Purpose:

Tests two objects for equality. Overrides inherited MCollectible function.

Calling Context:

Called by collection classes.

Parameters:

const MCollectible * -The object to be compared with this one.

Return Value:

Returns true if the objects are equal; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.