Class: TDocumentReference

Declaration: BasicDocument.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

The is an address-space independent reference to a document object. The reference uses the document's ID, which is logically an ordered pair (store ID, local document ID). Document references for documents are not valid until the document has been committed to the store. A reference can be taken prematurely. The framework attempts to fix up all previous references to point to the correct document store in which the document is saved.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive from this class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TDocumentReference::TDocumentReference

TDocumentReference (const TAbstractDocument &)
TDocumentReference (const TDocumentReference &)
TDocumentReference ()

Interface Category:

API.

Purpose:

Creates a reference that points to the given document or document surrogate.
Copy constructor.
Default constructor. Creates an invalid reference.

Calling Context:

Call this function directly.
Called to copy an object.
Called by the stream-in operators or directly. Creates an invalid reference--that is, a reference that does not refer to any document.

Parameters:

const TAbstractDocument & -The document or document surrogate for which the new object is a reference.
const TDocumentReference & -The document reference to copy.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion (document is a valid document).

Member Function: TDocumentReference::~TDocumentReference

virtual ~ TDocumentReference ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy the document reference.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDocumentReference::IsReferenceFor

bool IsReferenceFor (const TAbstractDocument &) const

Interface Category:

API.

Purpose:

Checks to see if the document reference refers to the specified document or document surrogate.

Calling Context:

Call this function directly.

Parameters:

const TAbstractDocument & -The document or document surrogate.

Return Value:

Returns true if the reference refers to the specified document; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion (TAbstractDocument& is a valid document or surrogate).

Member Function: TDocumentReference::IsDefined

bool IsDefined () const

Interface Category:

API.

Purpose:

Determines whether this document reference refers to any document that exists or might have existed at one time. Note that the document that this reference refers to might no longer exist or might be unavailable for some other reason.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the reference refers to any document; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDocumentReference::operator=

TDocumentReference & operator =(const TDocumentReference & )

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement. The two objects refer to the same document.

Parameters:

const TDocumentReference & -The document reference to copy.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Post Conditions: Assertion (*this ==other).

Member Function: TDocumentReference::operator==

bool operator ==(const TDocumentReference &) const

Interface Category:

API.

Purpose:

Tests whether the two objects on either side of the ==symbol are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TDocumentReference & -The object to be compared to this object.

Return Value:

Returns true if the both document references refer to the same document; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion (TDocumentReference& is a valid object).

Member Function: TDocumentReference::operator!=

bool operator != (const TDocumentReference &) const

Interface Category:

API.

Purpose:

Tests whether the two objects on either side of the != symbol are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TDocumentReference & -The object to be compared to this object.

Return Value:

Returns true if the document reference objects do not refer to the same document; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion (TDocumentReference& is a valid object).

Member Function: TDocumentReference::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion (stream is opened for writing).

Member Function: TDocumentReference::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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

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:

Not multithread safe.

Other Considerations:

Preconditions: Assertion (stream is opened for reading).

Member Function: TDocumentReference::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value for collection classes.

Calling Context:

Called by the collection classes.

Parameters:

Takes no parameters.

Return Value:

Returns the hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Preconditions: Assertion ( IsDefined() ==true ).

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