Overview Class List Class Hierarchy Class Members Functions & Constants Defines Header Files

uima::CAS Class Reference

Detailed Description

The CAS (Common Analysis System) is the container where all feature structures are stored and maintained.

The CAS object provides access to the type system, to indexes, iterators and filters (constraints). It also lets you create new annotations, Sofas and other data structures.
Use uima::AnalysisEngine::newCAS() to instantiate a CAS.

The CAS APIs ( uima::CAS ) provide access to the following:

The creation of feature structures ( uima::FeatureStructure ).
These have one or more feature values which are like public data members of a feature structure.
The feature structures are organized in indexes ( uima::FSIndex ). Iterators ( uima::FSIterator ) over indexes are used to access individual feature structures.
The Type System ( uima::TypeSystem ) where all possible feature structures are defined in terms of types and features.
The creation of and access to Sofas ( uima::SofaFS ) and CAS views ( uima::CAS ) .
A set of predefined types, features, indexes and Utility Functions for text analysis.

Public Member Functions

virtual ~CAS ()

int getSofaNum ()

Returns the Sofa number.

bool isBackwardCompatibleCas ()

True if a CAS view.

CAS * getBaseCas ()

If a View, returns the base CAS, else returns itself.

bool isView ()

Returns true if a CAS view.

TyErrorId reset (void)

Resets the CAS.

FSFilterBuilder const & getFSFilterBuilder () const

get the FSFilterBuilder associated with this CAS.

TypeSystem const & getTypeSystem (void) const

Get the TypeSystem (const version).

uima::lowlevel::FSHeap * getHeap ()

Get the FSHeap pointer.

FeatureStructure createFS (Type const &crType)

create an FS of type crType

ArrayFS createArrayFS (size_t uiSize)

create a feature structure of type FS Array.

FloatArrayFS createFloatArrayFS (size_t uiSize)

create a feature structure of type FS Array.

IntArrayFS createIntArrayFS (size_t uiSize)

create a feature structure of type FS Array.

StringArrayFS createStringArrayFS (size_t uiSize)

create a feature structure of type FS Array.

ListFS createListFS ()

create a feature structure of type empty FS list (list length is zero) Each element in the list is a FeatureStructure.

FloatListFS createFloatListFS ()

create a feature structure of type empty float list (list length is zero).

IntListFS createIntListFS ()

create a feature structure of type empty int list (list length is zero).

StringListFS createStringListFS ()

create a feature structure of type empty string list (list length is zero).

BooleanArrayFS createBooleanArrayFS (size_t uiSize)

create a feature structure of type FS Array.

ByteArrayFS createByteArrayFS (size_t uiSize)

create a feature structure of type FS Array.

ShortArrayFS createShortArrayFS (size_t uiSize)

create a feature structure of type FS Array.

LongArrayFS createLongArrayFS (size_t uiSize)

create a feature structure of type FS Array.

DoubleArrayFS createDoubleArrayFS (size_t uiSize)

create a feature structure of type FS Array.

FSIndexRepository & getIndexRepository (void)

Return the index repository for index use
Exceptions:

CASException if View is the base CAS.

FSIndexRepository const & getIndexRepository (void) const

Return the index repository for index use (const-version).

uima::lowlevel::IndexRepository & getLowlevelIndexRepository (void) const

Get the lowlevel IndexRepository.

FSIndexRepository & getBaseIndexRepository (void)

Return the base index repository: for internal use only.

SofaFS createSofa (const SofaID &sofaName, const char *mimeType)

Create a SofaFS.

SofaFS getSofa (const SofaID &sofaName)

Retrieve the SofaFS as identified by the SofaID.

SofaFS getSofa ()

Get the Sofa feature structure associated with this CAS view.

CAS * getView (const icu::UnicodeString &localViewName)

Get the view for a Sofa (subject of analysis).

CAS * getView (SofaFS aSofa)

Get the view for a Sofa (subject of analysis).

CAS * createView (icu::UnicodeString const &localViewName)

Create a view and its underlying Sofa (subject of analysis).

UnicodeStringRef getViewName ()

Get the view name.

void setDocumentText (UnicodeStringRef const text)

Set the document text.

void setDocumentText (UChar const *cpBuffer, size_t uiLength, bool bCopyToCAS=false)

Set the document text, old style.

virtual void setSofaDataString (UnicodeStringRef const text, icu::UnicodeString const &mimetype)

Set the document text.

virtual UnicodeStringRef getDocumentText () const

Get the document text.

virtual DocumentFS const getDocumentAnnotation () const

Returns the FeaturesStructure of type document annotation representing the current document.

virtual DocumentFS getDocumentAnnotation ()

virtual void setSofaDataArray (FeatureStructure array, icu::UnicodeString const &mime)

Set the Sofa data as an ArrayFS.

virtual FeatureStructure getSofaDataArray ()

Get the Sofa data array.

virtual void setSofaDataURI (icu::UnicodeString const &uri, icu::UnicodeString const &mime)

Set the Sofa data as a URI.

virtual UnicodeStringRef getSofaDataURI ()

Get the Sofa data array.

virtual SofaDataStream * getSofaDataStream ()

Get the Sofa data as a byte stream.

void setCurrentComponentInfo (AnnotatorContext *info)

Informs the CAS of relevant information about the component that is currently procesing it.

FSIterator getSofaIterator ()

Get an iterator over all SofaFS.

FSIterator iterator ()

create an iterator over all the feature structures in this CAS.

virtual AnnotationFS createAnnotation (Type const &type, size_t uiBeginPos, size_t uiEndPos)

convenience function for creating an annotation.

bool moveToBeginPosition (ANIterator &itOfType, AnnotationFS const &crFromAnn)

CAS Utility functions for Annotation Iterators sets the index iterator to the begin position of crFromAnn.

Access to predefined indexes

virtual ANIndex getAnnotationIndex ()

get the index over all annotations.

virtual ANIndex getAnnotationIndex (Type const &crType)

get the index over annotations of type crType.

virtual ANIndex const getAnnotationIndex (Type const &crType) const

Access to predefined index IDs.

This should only be needed to get access to low level indexes.

icu::UnicodeString getAnnotationIndexID () const

Static Public Attributes

icu::UnicodeString const ustrCREATOR_ID_CAS

The creator id constant for types/features created by the CAS (e.g.

CAS string constants for the names of predefined basic types.

char const * NAME_SPACE_UIMA_CAS

Use this instead of a string literal.

char const * TYPE_NAME_TOP

Use this instead of a string literal.

char const * TYPE_NAME_INTEGER

Use this instead of a string literal.

char const * TYPE_NAME_STRING

Use this instead of a string literal.

char const * TYPE_NAME_FLOAT

Use this instead of a string literal.

char const * TYPE_NAME_ARRAY_BASE

Use this instead of a string literal.

char const * TYPE_NAME_FS_ARRAY

Use this instead of a string literal.

char const * TYPE_NAME_FLOAT_ARRAY

Use this instead of a string literal.

char const * TYPE_NAME_INTEGER_ARRAY

Use this instead of a string literal.

char const * TYPE_NAME_STRING_ARRAY

Use this instead of a string literal.

char const * TYPE_NAME_LIST_BASE

Use this instead of a string literal.

char const * TYPE_NAME_FS_LIST

Use this instead of a string literal.

char const * TYPE_NAME_EMPTY_FS_LIST

Use this instead of a string literal.

char const * TYPE_NAME_NON_EMPTY_FS_LIST

Use this instead of a string literal.

char const * TYPE_NAME_FLOAT_LIST

Use this instead of a string literal.

char const * TYPE_NAME_NON_EMPTY_FLOAT_LIST

Use this instead of a string literal.

char const * TYPE_NAME_EMPTY_FLOAT_LIST

Use this instead of a string literal.

char const * TYPE_NAME_INTEGER_LIST

Use this instead of a string literal.

char const * TYPE_NAME_NON_EMPTY_INTEGER_LIST

Use this instead of a string literal.

char const * TYPE_NAME_EMPTY_INTEGER_LIST

Use this instead of a string literal.

char const * TYPE_NAME_STRING_LIST

Use this instead of a string literal.

char const * TYPE_NAME_NON_EMPTY_STRING_LIST

Use this instead of a string literal.

char const * TYPE_NAME_EMPTY_STRING_LIST

Use this instead of a string literal.

char const * TYPE_NAME_SOFA

Use this instead of a string literal.

char const * TYPE_NAME_LOCALSOFA

Use this instead of a string literal.

char const * TYPE_NAME_REMOTESOFA

Use this instead of a string literal.

char const * NAME_DEFAULT_TEXT_SOFA

Use this instead of a string literal.

char const * NAME_DEFAULT_SOFA

Use this instead of a string literal.

char const * TYPE_NAME_ANNOTATION_BASE

Use this instead of a string literal.

char const * TYPE_NAME_ANNOTATION

Use this instead of a string literal.

char const * TYPE_NAME_DOCUMENT_ANNOTATION

Use this instead of a string literal.

char const * INDEXID_ANNOTATION

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_SOFA

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_SOFA

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_BEGIN

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_BEGIN

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_END

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_END

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_LANGUAGE

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_LANGUAGE

Use this instead of a string literal.

char const * TYPE_NAME_BOOLEAN

char const * TYPE_NAME_BYTE

char const * TYPE_NAME_SHORT

char const * TYPE_NAME_LONG

char const * TYPE_NAME_DOUBLE

char const * TYPE_NAME_BOOLEAN_ARRAY

char const * TYPE_NAME_BYTE_ARRAY

char const * TYPE_NAME_SHORT_ARRAY

char const * TYPE_NAME_LONG_ARRAY

char const * TYPE_NAME_DOUBLE_ARRAY

CAS string constants for the names of predefined basic features.

char const * FEATURE_BASE_NAME_HEAD

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_TAIL

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_FS_LIST_HEAD

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_FS_LIST_TAIL

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_SOFANUM

static char const * FEATURE_FULL_NAME_STRING_LIST_TAIL; Use this instead of a string literal

char const * FEATURE_BASE_NAME_SOFAID

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_SOFAMIME

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_SOFAURI

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_SOFASTRING

Use this instead of a string literal.

char const * FEATURE_BASE_NAME_SOFAARRAY

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_SOFANUM

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_SOFAID

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_SOFAMIME

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_SOFAURI

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_SOFASTRING

Use this instead of a string literal.

char const * FEATURE_FULL_NAME_SOFAARRAY

Use this instead of a string literal.

Protected Member Functions

int addString (icu::UnicodeString const &crString)

Add a copy of crString to the string heap.

int addString (UChar const *cpString, size_t uiLen)

Add a copy of cpString to the string heap.

int addString (const UnicodeStringRef &uls)

Add a copy of uls to the string heap.

UnicodeStringRef getString (int strRef)

Get a copy of crString from the string heap.

CAS (uima::internal::CASDefinition &, size_t uiFSHeapPageSize, size_t uiStringHeapPageSize, size_t uiStringRefHeapPageSize)

Construct a CAS.

CAS (uima::internal::CASDefinition &, bool bOwnsCASDefinition, size_t uiFSHeapPageSize, size_t uiStringHeapPageSize, size_t uiStringRefHeapPageSize)

Construct a CAS and specify ownership of CASDefinition object.

CAS (CAS *baseCas, SofaFS aSofa)

CAS * getViewBySofaNum (int sofaNum)

Only for internal use.

void registerInitialSofa ()

Only for internal use.

bool isInitialSofaCreated ()

Only for internal use.

SofaFS createInitialSofa (UnicodeStringRef const mimeType)

Only for internal use.

Protected Attributes

int iv_sofaNum

uima::internal::CASDefinition * iv_casDefinition

bool bOwnsCASDefinition

TypeSystem * iv_typeSystem

uima::lowlevel::FSHeap * iv_heap

uima::lowlevel::IndexRepository * iv_indexRepository

uima::FSFilterBuilder * iv_filterBuilder

int iv_sofaCount

std::map< int, CAS * > iv_sofa2tcasMap

std::vector< uima::lowlevel::IndexRepository * > iv_sofa2indexMap

CAS * iv_baseCas

CAS * iv_initialView

bool isbaseCas

bool initialSofaCreated

bool isDeletingViews

AnnotatorContext * iv_componentInfo

uima::lowlevel::TyFSType iv_utDocumentType

uima::lowlevel::TyFSFeature iv_utDocumentLangAsIntFeat

uima::lowlevel::TyFSFeature iv_utDocumentLangAsStrFeat

uima::lowlevel::TyFS iv_tyDocumentAnnotation

UChar const * iv_cpDocument

size_t iv_uiDocumentLength

UChar * iv_copyOfDocument

Friends

void uima::internal::fromHeapCellTempl (lowlevel::TyHeapCell, uima::CAS &, FeatureStructure &)

Constructor & Destructor Documentation

uima::CAS::CAS ( uima::internal::CASDefinition & ,

size_t uiFSHeapPageSize,

size_t uiStringHeapPageSize,

size_t uiStringRefHeapPageSize

) [protected]

Construct a CAS.

Parameters:

uiFSHeapPageSize the number of heap cells a heap page should contain.

uiStringHeapPageSize the number of bytes a string heap page should contain.

uiStringRefHeapPageSize the number of bytes a string-ref heap page should contain.

uima::CAS::CAS ( uima::internal::CASDefinition & ,

bool bOwnsCASDefinition,

size_t uiFSHeapPageSize,

size_t uiStringHeapPageSize,

size_t uiStringRefHeapPageSize

) [protected]

Construct a CAS and specify ownership of CASDefinition object.

uima::CAS::CAS ( CAS * baseCas,

SofaFS aSofa

) [protected]

virtual uima::CAS::~CAS ( ) [virtual]

Member Function Documentation

int uima::CAS::addString ( icu::UnicodeString const & crString ) [protected]

Add a copy of crString to the string heap.

Parameters:

crString the string to add

Returns:
an LString pointing to the new copy

int uima::CAS::addString ( UChar const * cpString,

size_t uiLen

) [protected]

Add a copy of cpString to the string heap.

Parameters:

cpString a pointer to the string to copy (maynot be zero terminated)

uiLen number of Unicode code units (not bytes!) to copy

Returns:
an LString pointing to the new copy

int uima::CAS::addString ( const UnicodeStringRef & uls ) [protected]

Add a copy of uls to the string heap.

Parameters:

uls a pointer to the string to copy (maynot be zero terminated)

Returns:
an LString pointing to the new copy

UnicodeStringRef uima::CAS::getString ( int strRef ) [protected]

Get a copy of crString from the string heap.

Parameters:

strRef the offset in the strRefHeap

Returns:
a UnicodeStringRef to the data in the stringHeap

CAS* uima::CAS::getViewBySofaNum ( int sofaNum ) [protected]

Only for internal use.
Return a View for given Sofa on heap

void uima::CAS::registerInitialSofa ( ) [protected]

Only for internal use.

bool uima::CAS::isInitialSofaCreated ( ) [protected]

Only for internal use.

SofaFS uima::CAS::createInitialSofa ( UnicodeStringRef const mimeType ) [protected]

Only for internal use.

int uima::CAS::getSofaNum ( ) [inline]

Returns the Sofa number.

bool uima::CAS::isBackwardCompatibleCas ( )

True if a CAS view.

CAS* uima::CAS::getBaseCas ( ) [inline]

If a View, returns the base CAS, else returns itself.

bool uima::CAS::isView ( ) [inline]

Returns true if a CAS view.

Deprecated:

TyErrorId uima::CAS::reset ( void )

Resets the CAS.
In particular, all data structures meant only to live throughout a document are deleted.

FSFilterBuilder const& uima::CAS::getFSFilterBuilder ( ) const

get the FSFilterBuilder associated with this CAS.

See also:
FSFilterBuilder

TypeSystem const& uima::CAS::getTypeSystem ( void ) const

Get the TypeSystem (const version).

uima::lowlevel::FSHeap* uima::CAS::getHeap ( )

Get the FSHeap pointer.

FeatureStructure uima::CAS::createFS ( Type const & crType )

create an FS of type crType

Parameters:

crType the type of FS to create

Exceptions:

CouldNotCreateFSOfFinalTypeException

Returns:
the created feature structure

ArrayFS uima::CAS::createArrayFS ( size_t uiSize )

create a feature structure of type FS Array.
Each of the uiSize elements in the array is a FeatureStructure.
Parameters:

uiSize the size of the array

FloatArrayFS uima::CAS::createFloatArrayFS ( size_t uiSize )

create a feature structure of type FS Array.
Each of the uiSize elements in the array is a float.
Parameters:

uiSize the size of the array

IntArrayFS uima::CAS::createIntArrayFS ( size_t uiSize )

create a feature structure of type FS Array.
Each of the uiSize elements in the array is a int.
Parameters:

uiSize the size of the array

StringArrayFS uima::CAS::createStringArrayFS ( size_t uiSize )

create a feature structure of type FS Array.
Each of the uiSize elements in the array is a string.
Parameters:

uiSize the size of the array

ListFS uima::CAS::createListFS ( )

create a feature structure of type empty FS list (list length is zero) Each element in the list is a FeatureStructure.

FloatListFS uima::CAS::createFloatListFS ( )

create a feature structure of type empty float list (list length is zero).
Each element in the list is a float.

IntListFS uima::CAS::createIntListFS ( )

create a feature structure of type empty int list (list length is zero).
Each element in the list is a int.

StringListFS uima::CAS::createStringListFS ( )

create a feature structure of type empty string list (list length is zero).
Each element in the list is a string.

BooleanArrayFS uima::CAS::createBooleanArrayFS ( size_t uiSize )

create a feature structure of type FS Array.
Each of the uiSize elements in the array is a byte.
Parameters:

uiSize the size of the array

ByteArrayFS uima::CAS::createByteArrayFS ( size_t uiSize )

create a feature structure of type FS Array.
Each of the uiSize elements in the array is a byte.
Parameters:

uiSize the size of the array

ShortArrayFS uima::CAS::createShortArrayFS ( size_t uiSize )

create a feature structure of type FS Array.
Each of the uiSize elements in the array is a short.
Parameters:

uiSize the size of the array

LongArrayFS uima::CAS::createLongArrayFS ( size_t uiSize )

create a feature structure of type FS Array.
Each of the uiSize elements in the array is a long.
Parameters:

uiSize the size of the arrayt

DoubleArrayFS uima::CAS::createDoubleArrayFS ( size_t uiSize )

create a feature structure of type FS Array.
Each of the uiSize elements in the array is a long.
Parameters:

uiSize the size of the array

FSIndexRepository& uima::CAS::getIndexRepository ( void )

Return the index repository for index use
Exceptions:

CASException if View is the base CAS.

FSIndexRepository const& uima::CAS::getIndexRepository ( void ) const

Return the index repository for index use (const-version).

uima::lowlevel::IndexRepository& uima::CAS::getLowlevelIndexRepository ( void ) const

Get the lowlevel IndexRepository.

FSIndexRepository& uima::CAS::getBaseIndexRepository ( void )

Return the base index repository: for internal use only.

SofaFS uima::CAS::createSofa ( const SofaID & sofaName,

const char * mimeType

)

Create a SofaFS.

Deprecated:
As of v2.0, use createView() instead.

SofaFS uima::CAS::getSofa ( const SofaID & sofaName )

Retrieve the SofaFS as identified by the SofaID.

Deprecated:
As of v2.0, use getView() instead. From the view you can access the Sofa data, or call getSofa() if you truly need to access the SofaFS object.

SofaFS uima::CAS::getSofa ( )

Get the Sofa feature structure associated with this CAS view.

Returns:
The SofaFS associated with this View.

CAS* uima::CAS::getView ( const icu::UnicodeString & localViewName )

Get the view for a Sofa (subject of analysis).
The view provides access to the Sofa data and the index repository that contains metadata (annotations and other feature structures) pertaining to that Sofa.

Parameters:

localViewName the local name, before any sofa name mapping is done, for this view (note: this is the same as the associated Sofa name).

Returns:
The view corresponding to this local name.

Exceptions:

CASException if no View with this name exists in this CAS

CAS* uima::CAS::getView ( SofaFS aSofa )

Get the view for a Sofa (subject of analysis).
The view provides access to the Sofa data and the index repository that contains metadata (annotations and other feature structures) pertaining to that Sofa.

Parameters:

aSofa a Sofa feature structure in the CAS

Returns:
The view for the given Sofa

CAS* uima::CAS::createView ( icu::UnicodeString const & localViewName )

Create a view and its underlying Sofa (subject of analysis).
The view provides access to the Sofa data and the index repository that contains metadata (annotations and other feature structures) pertaining to that Sofa.

Parameters:

localViewName the local name, before any sofa name mapping is done, for this view (note: this is the same as the associated Sofa name).

Returns:
The view corresponding to this local name.

Exceptions:

CASException if a View with this name already exists in this CAS

UnicodeStringRef uima::CAS::getViewName ( )

Get the view name.
The view name is the same as the name of the view's Sofa, retrieved by getSofa().getSofaID(), except for the initial View before its Sofa has been created.

Returns:
The name of the view

void uima::CAS::setDocumentText ( UnicodeStringRef const text )

Set the document text.
Once set, Sofa data is immutable, and cannot be set again until the CAS has been reset.

Parameters:

text The text to be analyzed.

Exceptions:

CASException If the Sofa data has already been set, or View is base CAS.

void uima::CAS::setDocumentText ( UChar const * cpBuffer,

size_t uiLength,

bool bCopyToCAS = false

)

Set the document text, old style.

Deprecated:
Use the new style

virtual void uima::CAS::setSofaDataString ( UnicodeStringRef const text,

icu::UnicodeString const & mimetype

) [virtual]

Set the document text.
Once set, Sofa data is immutable, and cannot be set again until the CAS has been reset.

Parameters:

text The text to be analyzed.

mimetype The mime type of the data

Exceptions:

CASException If the Sofa data has already been set, or View is base CAS.

virtual UnicodeStringRef uima::CAS::getDocumentText ( ) const [virtual]

Get the document text.

Returns:
The text being analyzed.

virtual DocumentFS const uima::CAS::getDocumentAnnotation ( ) const [virtual]

Returns the FeaturesStructure of type document annotation representing the current document.

virtual DocumentFS uima::CAS::getDocumentAnnotation ( ) [virtual]

virtual void uima::CAS::setSofaDataArray ( FeatureStructure array,

icu::UnicodeString const & mime

) [virtual]

Set the Sofa data as an ArrayFS.
Once set, Sofa data is immutable, and cannot be set again until the CAS has been reset.

Parameters:

array The ArrayFS to be analyzed.

mime The mime type of the data

Exceptions:

CASException If the Sofa data has already been set, or View is base CAS.

virtual FeatureStructure uima::CAS::getSofaDataArray ( ) [virtual]

Get the Sofa data array.

Returns:
The Sofa Data being analyzed.

virtual void uima::CAS::setSofaDataURI ( icu::UnicodeString const & uri,

icu::UnicodeString const & mime

) [virtual]

Set the Sofa data as a URI.
Once set, Sofa data is immutable, and cannot be set again until the CAS has been reset.

Parameters:

uri The URI of the data to be analyzed.

mime The mime type of the data

Exceptions:

CASException If the Sofa data has already been set, or View is base CAS.

virtual UnicodeStringRef uima::CAS::getSofaDataURI ( ) [virtual]

Get the Sofa data array.

Returns:
The Sofa Data being analyzed.

virtual SofaDataStream* uima::CAS::getSofaDataStream ( ) [virtual]

Get the Sofa data as a byte stream.

Returns:
a SofaDataStream.

void uima::CAS::setCurrentComponentInfo ( AnnotatorContext * info )

Informs the CAS of relevant information about the component that is currently procesing it.
This is called by the framework automatically; users do not need to call it.