Class: TDocumentStore

Declaration: BasicDocumentStorage.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TStore

Inherited By:

TCompoundDocumentStore

Purpose:

TDocumentStore is a TStore derived class used for storing documents. It uses a multiple bin storage mechanism for storing the data of a document. TDocumentStore provides protocols to access its storage mechanism, to manage document data, to manage its list of document component stores, to manage its containment hierarchy, and to look up an instance of itself given a reference.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class could be derived from to add protocol for storing derived classes of TDocument.

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: TDocumentStore::TDocumentStore

TDocumentStore (TMultiBinStorageMechanism *)
TDocumentStore ()
TDocumentStore (const TDocumentStore &)

Interface Category:

API.

Purpose:

Creates a document store with the specified storage mechanism.
Default constructor. Used to resurrect a flattened document store instance.
Copy constructor.

Calling Context:

Called to create a document store with the given storage mechanism.
Called by the stream-in operators.
Called to copy an object.

Parameters:

TMultiBinStorageMechanism * -The storage to be adopted by this store.
Takes no parameters.
const TDocumentStore & aStore -The store to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

The default and copy constructors are protected.

Member Function: TDocumentStore::~TDocumentStore

virtual ~ TDocumentStore ()

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: TDocumentStore::CopyStoreAliasFor

static TDocumentStore * CopyStoreAliasFor (const TDocumentReference &)

Interface Category:

API.

Purpose:

Looks up and makes a copy of the store used to store the document. The store is then returned to the caller.

Calling Context:

Call this function directly.

Parameters:

const TDocumentReference & -The document reference of the document associated with the store.

Return Value:

None.

Exceptions:

Throws TDocumentException::kUndefinedDocumentReference if the specified document is not defined. Throws TDocumentException::kNoStoreForDocument if the document references does not have a store.

Concurrency:

Multithread safe.

Other Considerations:

Preconditions: Assertion (theDocumentReference != NIL).

Member Function: TDocumentStore::CreateSession

virtual TDocumentSession* CreateSession (TStore::EAccessMode, TDocumentStore::ESharingMode)

Interface Category:

API.

Purpose:

Creates the document session for this document.

Calling Context:

Called to create the document session for this document.

Parameters:

TStore::EAccessMode -The access mode for the new document session.
TDocumentStore::ESharingMode -The sharing mode for the new document session.

Return Value:

Returns a new TDocumentSession instance.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentStore::GetStorageMechanism

TMultiBinStorageMechanism * GetStorageMechanism ()
const TMultiBinStorageMechanism * 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 pointer to the storage mechanism.
Returns const pointer to the storage mechanism.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentStore::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: TDocumentStore::CreateIn

virtual void CreateIn (TDocumentStore & parent)

Interface Category:

API.

Purpose:

Creates the document store inside the parent store. This CreateIn operation depends on the type of storage mechanism used. For standard storage mechanism types, this results in the document store's storage mechanism's directory being created underneath the parent store's standard storage mechanism's directory.

Calling Context:

Call this function directly.

Parameters:

TDocumentStore & parent -The document store in which to create the storage bin.

Return Value:

None.

Exceptions:

Throws TDocumentException::kDocumentStoreAlreadyExists.

Concurrency:

Multithread safe.

Other Considerations:

Postcondition: Assertion( *GetParent() ==*parent ).

Member Function: TDocumentStore::MoveInto

virtual void MoveInto (TDocumentStore & parent)

Interface Category:

API.

Purpose:

Moves the document store into the specified parent store. This move into operation depends on the type of storage mechanism used. For standard storage mechanism types, this results in the document store's storage mechanism's directory being moved underneath the parent store's standard storage mechanism's directory.

Calling Context:

Call this function directly.

Parameters:

TDocumentStore & parent -The new parent.

Return Value:

None.

Exceptions:

Throws TDocumentException::kNILStorageMechanism if the specified parent store's storage mechanism is NIL.

Concurrency:

Multithread safe.

Other Considerations:

Precondition: Assertion( GetStorageMechanism() != NIL ). Assertion( parent.GetStorageMechanism() != NIL ).

Member Function: TDocumentStore::CopyInto

virtual TDocumentStore * CopyInto (TDocumentStore & parent)

Interface Category:

API.

Purpose:

Copies the document store into the specified parent store. This copy into operation depends on the type of storage mechanism used. For standard storage mechanism types, this results in the document store's storage mechanism's directory being copied into the parent store's standard storage mechanism's directory.

Calling Context:

Call this function directly.

Parameters:

TDocumentStore & parent -The document store into which to copy the storage mechanism.

Return Value:

Returns a new instance of TDocumentStore.

Exceptions:

Throws TDocumentException::kNILStorageMechanism if the specified parent store's storage mechanism is NIL.

Concurrency:

Multithread safe.

Other Considerations:

Precondition: Assertion( GetStorageMechanism() != NIL ). Assertion( parent.GetStorageMechanism() != NIL ).

Member Function: TDocumentStore::Delete

virtual void Delete ()

Interface Category:

API.

Purpose:

Deletes the underlying physical storage.

Calling Context:

Call this function directly.

Parameters:

None.

Return Value:

None.

Exceptions:

Throws kStoreDoesNotExist if the store has not been created or has already been deleted.

Concurrency:

Multithread safe.

Other Considerations:

Postcondition: Assertion( *GetParent() ==*theParent ).

Member Function: TDocumentStore::DoesExistIn

virtual bool DoesExistIn (const TDocumentStore & parent) const

Interface Category:

API.

Purpose:

Determines whether or not this store exists in the specified parent. This operation depends on the type of storage mechanism used. For standard storage mechanism types, this function tests whether or not the document store's storage mechanism's directory is in the parent store's standard storage mechanism's directory.

Calling Context:

Call this function directly.

Parameters:

const TDocumentStore & parent -The parent store.

Return Value:

Returns true if this document store exists in the specified parent; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Precondition: Assertion( GetStorageMechanism() != NIL ). Assertion( parent.GetStorageMechanism() != NIL ).

Member Function: TDocumentStore::CopyParent

virtual TStore* CopyParent () const

Interface Category:

API.

Purpose:

Returns a copy of the parent store.

Calling Context:

Call this function directly.

Parameters:

None.

Return Value:

Returns a copy of the parent store or NIL if it has no parent.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Postcondition: Assertion( *CopyParent() ==*theParent ).

Member Function: TDocumentStore::Resurrect

virtual void Resurrect (TDocument * &)

Interface Category:

API.

Purpose:

Resurrects a prototypical version of this document.

Calling Context:

Called to resurrect the document.

Parameters:

TDocument * & -The parameter is filled out to point to where the resurrected document lies.

Return Value:

None.

Exceptions:

Throws TDocumentException:: kNILDocumentCrossReferenceTable if the cross reference table is NIL.

Concurrency:

Multithread safe.

Other Considerations:

Postcondition: Assertion (theDocument != NIL).

Member Function: TDocumentStore::Commit

virtual void Commit (TDocument &)

Interface Category:

API.

Purpose:

Commits a document to storage. This function calls the document's FileOut member functions to file out the document's data.

Calling Context:

Called to resurrect the document.

Parameters:

TDocument & -The document to commit to the store.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Postcondition: Assertion (theDocument != NIL).

Member Function: TDocumentStore::GetDocumentReference

virtual TDocumentReference GetDocumentReference () const

Interface Category:

API.

Purpose:

Creates and returns a TDocumentReference object for this TDocumentStore.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentStore::AddAttribute

virtual void AddAttribute (const TDocumentAttribute & theAttribute)

Interface Category:

API.

Purpose:

Adds the specified document attribute to the document store's attribute list replacing a matching attribute if one exists.

Calling Context:

Call this function directly.

Parameters:

const TDocumentAttribute & theAttribute -The attribute to be added.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Postconditions: Assertion (CopyAttribute(const TDocumentReference&, const TDocumentAttribute) != NIL).

Member Function: TDocumentStore::DeleteAttribute

virtual void DeleteAttribute (const TDocumentAttribute & thePatternToMatch)

Interface Category:

API.

Purpose:

Deletes the attribute from this document store's attribute list if it exists.

Calling Context:

Call this function directly.

Parameters:

const TDocumentAttribute & thePatternToMatch -The attribute to delete.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Postconditions: Assertion (CopyDocumentAttribute(const TDocumentReference&, const TDocumentAttribute) ==NIL).

Member Function: TDocumentStore::CopyAttribute

virtual TDocumentAttribute * CopyAttribute (const TDocumentAttribute & thePatternToMatch) const

Interface Category:

API.

Purpose:

Copies the specified attribute from a document store if it exists.

Calling Context:

Call this function directly.

Parameters:

const TDocumentAttribute & thePatternToMatch -The attribute to copy.

Return Value:

Returns a copy of the specified attribute or NIL if the attribute did not exist.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentStore::DeleteAllAttributes

virtual void DeleteAllAttributes ()

Interface Category:

API.

Purpose:

Deletes all the attributes for this document store.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Postconditions: Assertion (CopyAttribute(TDocumentReference&, TDocumentAttribute&) ==NIL) for all attributes.

Member Function: TDocumentStore::CopyAllAttributes

virtual void CopyAllAttributes (TCollectionOf<TDocumentAttribute> &) const

Interface Category:

API.

Purpose:

Copies all the attributes for this document store.

Calling Context:

Call this function directly.

Parameters:

TCollectionOf<TDocumentAttribute> & -The collection to fill with copied attributes.

Return Value:

None

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentStore::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: TDocumentStore::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: TDocumentStore::AdoptMechanism

virtual void AdoptMechanism (TStorageMechanism *)

Interface Category:

API.

Purpose:

Allows a new mechanism to be adopted into the store. This overrides the TStore::AdoptMechanism to enforce that the specified mechanism is really a TMultiBinStorageMechanism.

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.

Member Function: TDocumentStore::operator=

TDocumentStore & operator =(const TDocumentStore &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TDocumentStore & -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:

This operator is protected.

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