Class: TStore

Declaration: BasicDocumentStorage.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TDocumentComponentStore TDocumentStore

Purpose:

TStore provides an abstraction to express the semantics of storage and acts as the interface between a client object and a storage mechanism. TStore's responsibilities are: (1) to provide access to the storage mechanism; and (2) to support filing on a stream provided by the storage mechanism. In addition, TStore allows any storage mechanism to be plugged in to a particular store. For example, it is possible for one TDocumentComponentStore to use a Pluto-based storage mechanism and for another to use a Hoops-based storage mechanism.

Instantiation:

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

Deriving Classes:

Because TStore is an abstract base class, it contains no protocol which describes the semantics of storage. However, derived classes of TStore would provide the appropriate semantics. For example, TDocumentComponentStore contains protocols to file in or out the presenter state and the model associated with a document component. Provided classes include TDocumentStore.

Concurrency:

Multithread safe. This class enforces multiple readers or single writer semantics by delegating concurrency control to its storage mechanism.

Resource Use:

This class is responsible for managing its own resources.

Invariants:

Assertion (fStorageMechanism != NIL).

Member Function: TStore::~TStore

virtual ~ TStore ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object. This function will be called automatically by a TDocument destructor, for example, when a document instance is destroyed. This function deletes the underlying storage mechanism.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStore::GetStorageMechanism

TStorageMechanism * GetStorageMechanism ()
const TStorageMechanism * GetStorageMechanism () const

Interface Category:

API.

Purpose:

Returns the associated storage mechanism.

Calling Context:

Called to retrieve the underlying storage mechanism so that it can be passed as arguments to file-in functions of documents, models, and other objects.

Parameters:

Takes no parameters.

Return Value:

Returns const pointer to the storage mechanism.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStore::GetStorageMechanismType

TTypeDescription GetStorageMechanismType () const

Interface Category:

API.

Purpose:

Returns the type (classname) of the associated storage mechanism.

Calling Context:

Called by a model to choose a document component store with a storage mechanism that will meet its requirement.

Parameters:

Takes no parameters.

Return Value:

Returns the storage mechanism type (classname).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStore::GetAccessMode

EAccessMode GetAccessMode() const

Interface Category:

API.

Purpose:

Returns the open access mode. This value is not meaningful unless the store 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:

None.

Member Function: TStore::Create

virtual void Create ()

Interface Category:

API.

Purpose:

Creates an underlying physical storage implementation of a store.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TDocumentException::kDocumentStoreAlreadyExists.

Concurrency:

Multithread safe.

Other Considerations:

Preconditions: Assertion (fStorageMechanism.DoesExists() =false). Postconditions: Assertion (fStorageMechanism.DoesExists() =true).

Member Function: TStore::Delete

virtual void Delete ()

Interface Category:

API.

Purpose:

Deletes an underlying physical storage implementation of a store.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TDocumentException::kDocumentStoreDoesNotExist.

Concurrency:

Multithread safe.

Other Considerations:

Preconditions: Assertion (fStorageMechanism.DoesExists() =true). Postconditions: Assertion (fStorageMechanism.DoesExists() =false).

Member Function: TStore::DoesExist

virtual bool DoesExist () const

Interface Category:

API.

Purpose:

Checks whether or not an underlying physical storage implementation of a store 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:

None.

Member Function: TStore::IsOpened

virtual bool IsOpened () const

Interface Category:

API.

Purpose:

Checks whether or not the store has been opened.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the store has already been opened; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStore::Open

virtual void Open (EAccessMode mode)

Interface Category:

API.

Purpose:

Opens the store with specified access mode.

Calling Context:

Call this function directly.

Parameters:

EAccessMode mode -The access mode for opening a store.

Return Value:

None.

Exceptions:

Throws TDocumentException::kStoreCannotBeOpenedWithSpecifiedAccessMode.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStore::Close

virtual void Close ()

Interface Category:

API.

Purpose:

Closes access to the store.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TDocumentException::kStoreCannotBeClosed.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStore::CanBitWiseCopy

virtual bool CanBitWiseCopy ()

Interface Category:

API.

Purpose:

Checks whether or not a store supports bit-wise copying of its underlying physical storage implementation.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws TDocumentException::kDocumentStoreDoesNotExist.

Concurrency:

Multithread safe.

Other Considerations:

Preconditions: Assertion (fStorageMechanism.DoesExists() =true).

Member Function: TStore::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream to which the object streams itself out.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStore::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream from which the object streams itself in.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws a TInvalidVersionError if the version of the object on the stream is unknown to the version of the shared library installed.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStore::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Overrides inherited MCollectible function to return hash value.

Calling Context:

Called by collection classes.

Parameters:

Takes no parameters.

Return Value:

Returns hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStore::TStore

Interface Category:

API.

Purpose:

Creates a store with the given storage mechanism.
Default constructor. Used to resurrect a flattened store.
Copy constructor.

Calling Context:

Called by derived class constructors to provide a store with an associated storage mechanism.
Called by the stream-in operators and derived class constructors.
Called by derived class copy constructors.

Parameters:

TStorageMechanism * aMechanism -The storage mechanism to use for this store.
Takes no parameters.
const TStore & aStore -The store to be copied.

Return Value:

None.

Exceptions:

Throws TDocumentException::kNILStorageMechanism if the specified storage mechanism is NIL.
Throws no exceptions, passes all exceptions through.
Throws TDocumentException::kNILStorageMechanism if the copied object's storage mechanism is NIL.

Concurrency:

Multithread safe.

Other Considerations:

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

Precondition:

Member Function: TStore::operator=

TStore

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement. Called by derived classes when an object is assigned to another compatible object.

Parameters:

const TStore & aStore -The object to be copied.

Return Value:

Returns a const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

TStore is an abstract base class--this operator is protected. Do not instantiate this class. Precondition: Assertion (aStore.fStorageMechanism != NIL).

Member Function: TStore::AdoptMechanism

virtual void AdoptMechanism (TStorageMechanism *)

Interface Category:

API.

Purpose:

Allows a new mechanism to be adopted into the store. The storage mechanism for the store can also be set at construction time. This function deletes the previously adopted storage mechanism.

Calling Context:

Derived classes can call this function directly.

Parameters:

TStorageMechanism * -The storage mechanism to adopt.

Return Value:

None

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

AdoptMechanism is a protected member function.

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