org.apache.uima.jcas
Interface JCas

All Superinterfaces:

AbstractCas

public interface JCas
extends AbstractCas

Java Cover Classes based Object-oriented CAS (Common Analysis System) API.

A JCas object provides the starting point for working with the CAS using Java Cover Classes for each type, generated by the utility JCasGen.

This interface extends the CAS Interface, providing all the same functionality, plus some specific to the JCas.

It supports the creation of new instances of CAS types, using the normal Java "new" operator.

You can create a JCas object from a CAS object by calling the getJCas() method on the CAS object.

Field Summary

static int

INVALID_FEATURE_CODE (internal use)

Method Summary

void	addFsToIndexes(FeatureStructure fs) Add a feature structure to all appropriate indexes in the repository associated with this CAS View.
void	checkArrayBounds(int fsRef, int pos) Internal Use.
FeaturePath	createFeaturePath() Create a feature path.
FeatureValuePath	createFeatureValuePath(String featureValuePath) Create a feature-value path from a string.
<T extends FeatureStructure> FSIterator<T>	createFilteredIterator(FSIterator<T> it, FSMatchConstraint cons) Create an iterator over structures satisfying a given constraint.
SofaFS	createSofa(SofaID sofaID, String mimeType) Deprecated. As of v2.0, use createView(String) instead.
JCas	createView(String sofaID) Create a view and its underlying Sofa (subject of analysis).
<T extends FeatureStructure> ListIterator<T>	fs2listIterator(FSIterator<T> it) Wrap a standard Java ListIterator around an FSListIterator.
AnnotationIndex<Annotation>	getAnnotationIndex() Get the standard annotation index.
AnnotationIndex<Annotation>	getAnnotationIndex(int type) Get the standard annotation index restricted to a specific annotation type.
AnnotationIndex<Annotation>	getAnnotationIndex(Type type) Get the standard annotation index restricted to a specific annotation type.
CAS	getCas() return the Cas object for this JCas instantiation
org.apache.uima.cas.impl.CASImpl	getCasImpl() internal use
Type	getCasType(int i) Given Foo.type, return the corresponding CAS Type object.
ConstraintFactory	getConstraintFactory() Get a constraint factory.
TOP	getDocumentAnnotationFs() Gets the document annotation.
String	getDocumentLanguage() Gets the language code for this document from the language feature of the special instance of the DocumentationAnnotation associated with this CAS.
String	getDocumentText() Get the document text.
FloatArray	getFloatArray0L() A constant for each cas which holds a 0-length instance.
FSArray	getFSArray0L() A constant for each cas which holds a 0-length instance.
FSIndexRepository	getFSIndexRepository() return the FSIndexRepository object for this Cas.
FSIndexRepository	getIndexRepository() Get the index repository.
IntegerArray	getIntegerArray0L() A constant for each cas which holds a 0-length instance.
JCas	getJCas(Sofa sofa) Create a JCas view for a Sofa.
TOP	getJfsFromCaddr(int casAddr) Internal Use - sets the corresponding Java instance for a Cas instance
JFSIndexRepository	getJFSIndexRepository() Gets the JCas-based interface to the Index Repository.
org.apache.uima.cas.impl.LowLevelCAS	getLowLevelCas() internal use
org.apache.uima.cas.impl.LowLevelIndexRepository	getLowLevelIndexRepository()
Feature	getRequiredFeature(Type t, String s) Internal use - look up a feature-name-string in the CAS type system and returns the Cas Feature object.
Feature	getRequiredFeatureDE(Type t, String s, String rangeName, boolean featOkTst) Internal Use - look up a feature-name-string in the CAS type system and returns the Cas Feature object.
Type	getRequiredType(String s) Internal use - looks up a type-name-string in the CAS type system and returns the Cas Type object.
Sofa	getSofa() Get the Sofa feature structure associated with this JCas view.
Sofa	getSofa(SofaID sofaID) Deprecated. As of v2.0, use {#getView(String)}. From the view you can access the Sofa data, or call getSofa() if you truly need to access the SofaFS object.
FeatureStructure	getSofaDataArray() Get the Sofa data array.
InputStream	getSofaDataStream() Get the Sofa data as a byte stream.
String	getSofaDataString() Get the Sofa Data String (a.k.a.
String	getSofaDataURI() Get the Sofa data array.
FSIterator<SofaFS>	getSofaIterator() Get iterator for all SofaFS in the CAS.
String	getSofaMimeType() Get the mime type of the Sofa data being analyzed.
StringArray	getStringArray0L() A constant for each cas which holds a 0-length instance.
TOP_Type	getType(int i) get the JCas _Type instance for a particular CAS type constant
TOP_Type	getType(TOP instance) Deprecated. use instance.jcasType instead - faster
TypeSystem	getTypeSystem() Return the type system of this CAS instance.
JCas	getView(SofaFS aSofa) Get the view for a Sofa (subject of analysis).
JCas	getView(String localViewName) Get the view for a Sofa (subject of analysis).
Iterator<JCas>	getViewIterator() Get iterator over all views in this JCas.
Iterator<JCas>	getViewIterator(String localViewNamePrefix) Get iterator over all views with the given name prefix.
String	getViewName() Get the view name.
void	processInit() Deprecated. not required, does nothing
void	putJfsFromCaddr(int casAddr, FeatureStructure fs) Internal Use - sets the corresponding Java instance for a Cas instance
void	removeFsFromIndexes(FeatureStructure fs) Remove a feature structure from all indexes in the repository associated with this CAS View.
void	reset() Reset the CAS, emptying it of all content.
void	setDocumentLanguage(String languageCode) Sets the language for this document.
void	setDocumentText(String text) Set the document text.
void	setSofaDataArray(FeatureStructure array, String mime) Set the Sofa data as an ArrayFS.
void	setSofaDataString(String text, String mimetype) Set the document text.
void	setSofaDataURI(String uri, String mime) Set the Sofa data as a URI.
int	size() Estimate the memory consumption of this CAS instance (in bytes).
void	throwFeatMissing(String feat, String type) Internal Use - throw missing feature exception at runtime.

Methods inherited from interface org.apache.uima.cas.AbstractCas

release

Field Detail

INVALID_FEATURE_CODE

static final int INVALID_FEATURE_CODE

(internal use)

See Also:

Constant Field Values

Method Detail

getFSIndexRepository

FSIndexRepository getFSIndexRepository()

return the FSIndexRepository object for this Cas.

getLowLevelIndexRepository

org.apache.uima.cas.impl.LowLevelIndexRepository getLowLevelIndexRepository()

getCas

CAS getCas()

return the Cas object for this JCas instantiation

getCasImpl

org.apache.uima.cas.impl.CASImpl getCasImpl()

internal use

getLowLevelCas

org.apache.uima.cas.impl.LowLevelCAS getLowLevelCas()

internal use

getType

TOP_Type getType(int i)

get the JCas _Type instance for a particular CAS type constant

Parameters:

i - the CAS type constant, written as Foo.type

Returns:

the instance of the JCas xxx_Type object for the specified type

getCasType

Type getCasType(int i)

Given Foo.type, return the corresponding CAS Type object. This is useful in the methods which require a CAS Type, for instance iterator creation.

Parameters:

i - - index returned by Foo.type

Returns:

the CAS Java Type object for this CAS Type.

getType

@Deprecated
TOP_Type getType(TOP instance)

Deprecated. use instance.jcasType instead - faster

get the JCas x_Type instance for a particular Java instance of a type

Parameters:

instance -

Returns:

the associated xxx_Type instance

getRequiredType

Type getRequiredType(String s)
                     throws CASException

Internal use - looks up a type-name-string in the CAS type system and returns the Cas Type object. Throws CASException if the type isn't found

Throws:

CASException

getRequiredFeature

Feature getRequiredFeature(Type t,
                           String s)
                           throws CASException

Internal use - look up a feature-name-string in the CAS type system and returns the Cas Feature object. Throws CASException if the feature isn't found

Throws:

CASException

getRequiredFeatureDE

Feature getRequiredFeatureDE(Type t,
                             String s,
                             String rangeName,
                             boolean featOkTst)

Internal Use - look up a feature-name-string in the CAS type system and returns the Cas Feature object. If the feature isn't found, adds an exception to the errorSet but doesn't throw

putJfsFromCaddr

void putJfsFromCaddr(int casAddr,
                     FeatureStructure fs)

Internal Use - sets the corresponding Java instance for a Cas instance

getJfsFromCaddr

TOP getJfsFromCaddr(int casAddr)

Internal Use - sets the corresponding Java instance for a Cas instance

checkArrayBounds

void checkArrayBounds(int fsRef,
                      int pos)

Internal Use.

throwFeatMissing

void throwFeatMissing(String feat,
                      String type)

Internal Use - throw missing feature exception at runtime.

getSofa

@Deprecated
Sofa getSofa(SofaID sofaID)

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

getSofa

Sofa getSofa()

Get the Sofa feature structure associated with this JCas view.

Returns:

The SofaFS associated with this JCas view.

createView

JCas createView(String sofaID)
                throws CASException

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.

This method creates the underlying Sofa feature structure, but does not set the Sofa data. Setting ths Sofa data must be done by calling setSofaDataArray(FeatureStructure, String), setSofaDataString(String, String) or setSofaDataURI(String, String) on the JCas view returned by this method.

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.

Throws:

CASRuntimeException - if a View with this name already exists in this CAS

CASException

getJCas

JCas getJCas(Sofa sofa)
             throws CASException

Create a JCas view for a Sofa.

Parameters:

aSofa - a Sofa feature structure in this CAS.

Returns:

The JCas view for the given Sofa.

Throws:

CASException

getJFSIndexRepository

JFSIndexRepository getJFSIndexRepository()

Gets the JCas-based interface to the Index Repository. Provides the same functionality as getFSIndexRepository() except that the methods that take a "type" argument take type arguments obtainable easily from the JCas type.

Returns:

the JCas-based interface to the index repository

getDocumentAnnotationFs

TOP getDocumentAnnotationFs()

Gets the document annotation. The object returned from this method can be typecast to DocumentAnnotation.

The reason that the return type of this method is not DocumentAnnotation is because of problems that arise when using the UIMA Extension ClassLoader to load annotator classes. The DocumentAnnotation type may be defined in the UIMA extension ClassLoader, differently than in the framework ClassLoader.

Returns:

The one instance of the DocumentAnnotation annotation.

See Also:

CAS.getDocumentAnnotation()

getStringArray0L

StringArray getStringArray0L()

A constant for each cas which holds a 0-length instance. Since this can be a common value, we avoid creating multiple copies of it. All uses can use the same valuee because it is not updatable (it has no subfields). This is initialized lazily on first reference, and reset when the CAS is reset.

getIntegerArray0L

IntegerArray getIntegerArray0L()

A constant for each cas which holds a 0-length instance. Since this can be a common value, we avoid creating multiple copies of it. All uses can use the same valuee because it is not updatable (it has no subfields). This is initialized lazily on first reference, and reset when the CAS is reset.

getFloatArray0L

FloatArray getFloatArray0L()

A constant for each cas which holds a 0-length instance. Since this can be a common value, we avoid creating multiple copies of it. All uses can use the same valuee because it is not updatable (it has no subfields). This is initialized lazily on first reference, and reset when the CAS is reset.

getFSArray0L

FSArray getFSArray0L()

A constant for each cas which holds a 0-length instance. Since this can be a common value, we avoid creating multiple copies of it. All uses can use the same valuee because it is not updatable (it has no subfields). This is initialized lazily on first reference, and reset when the CAS is reset.

processInit

@Deprecated
void processInit()

Deprecated. not required, does nothing

initialize the JCas for new Cas content. Not used, does nothing.

getView

JCas getView(String localViewName)
             throws CASException

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.

Throws:

CASException

getView

JCas getView(SofaFS aSofa)
             throws CASException

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

Throws:

CASException

getTypeSystem

TypeSystem getTypeSystem()
                         throws CASRuntimeException

Return the type system of this CAS instance.

Returns:

The type system, or null if none is available.

Throws:

CASRuntimeException - If the type system has not been committed.

createSofa

@Deprecated
SofaFS createSofa(SofaID sofaID,
                             String mimeType)

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

Create a Subject of Analysis. The new sofaFS is automatically added to the SofaIndex.

Returns:

The sofaFS.

getSofaIterator

FSIterator<SofaFS> getSofaIterator()

Get iterator for all SofaFS in the CAS.

Returns:

an iterator over SofaFS.

createFilteredIterator

<T extends FeatureStructure> FSIterator<T> createFilteredIterator(FSIterator<T> it,
                                                                  FSMatchConstraint cons)

Create an iterator over structures satisfying a given constraint. Constraints are described in the javadocs for ConstraintFactory and related classes.

Parameters:

it - The input iterator.

cons - The constraint specifying what structures should be returned.

Returns:

An iterator over FSs.

getConstraintFactory

ConstraintFactory getConstraintFactory()

Get a constraint factory. A constraint factory is a simple way of creating FSMatchConstraints.

Returns:

A constraint factory to create new FS constraints.

createFeaturePath

FeaturePath createFeaturePath()

Create a feature path. This is mainly useful for creating FSMatchConstraints.

Returns:

A new, empty feature path.

getIndexRepository

FSIndexRepository getIndexRepository()

Get the index repository.

Returns:

The index repository, or null if none is available.

fs2listIterator

<T extends FeatureStructure> ListIterator<T> fs2listIterator(FSIterator<T> it)

Wrap a standard Java ListIterator around an FSListIterator. Use if you feel more comfortable with java style iterators.

Parameters:

it - The FSListIterator to be wrapped.

Returns:

An equivalent ListIterator.

reset

void reset()
           throws CASAdminException

Reset the CAS, emptying it of all content. Feature structures and iterators will no longer be valid. Note: this method may only be called from an application. Calling it from an annotator will trigger a runtime exception.

Throws:

CASRuntimeException - When called out of sequence.

CASAdminException

See Also:

CASMgr

getViewName

String 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

size

int size()

Estimate the memory consumption of this CAS instance (in bytes).

Returns:

The estimated memory used by this CAS instance.

createFeatureValuePath

FeatureValuePath createFeatureValuePath(String featureValuePath)
                                        throws CASRuntimeException

Create a feature-value path from a string.

Parameters:

featureValuePath - String representation of the feature-value path.

Returns:

Feature-value path object.

Throws:

CASRuntimeException - If the input string is not well-formed.

setDocumentText

void setDocumentText(String text)
                     throws CASRuntimeException

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.

Throws:

CASRuntimeException - If the Sofa data has already been set.

setSofaDataString

void setSofaDataString(String text,
                       String mimetype)
                       throws CASRuntimeException

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.

mime - The mime type of the data

Throws:

CASRuntimeException - If the Sofa data has already been set.

getDocumentText

String getDocumentText()

Get the document text.

Returns:

The text being analyzed.

getSofaDataString

String getSofaDataString()

Get the Sofa Data String (a.k.a. the document text).

Returns:

The Sofa data string.

setDocumentLanguage

void setDocumentLanguage(String languageCode)
                         throws CASRuntimeException

Sets the language for this document. This value sets the language feature of the special instance of DocumentAnnotation associated with this CAS.

Parameters:

languageCode -

Throws:

CASRuntimeException

getDocumentLanguage

String getDocumentLanguage()

Gets the language code for this document from the language feature of the special instance of the DocumentationAnnotation associated with this CAS.

Returns:

language identifier

setSofaDataArray

void setSofaDataArray(FeatureStructure array,
                      String mime)
                      throws CASRuntimeException

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

Throws:

CASRuntimeException - If the Sofa data has already been set.

getSofaDataArray

FeatureStructure getSofaDataArray()

Get the Sofa data array.

Returns:

The Sofa Data being analyzed.

setSofaDataURI

void setSofaDataURI(String uri,
                    String mime)
                    throws CASRuntimeException

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

Throws:

CASRuntimeException - If the Sofa data has already been set.

getSofaDataURI

String getSofaDataURI()

Get the Sofa data array.

Returns:

The Sofa Data being analyzed.

getSofaDataStream

InputStream getSofaDataStream()

Get the Sofa data as a byte stream.

Returns:

A stream handle to the Sofa Data.

getSofaMimeType

String getSofaMimeType()

Get the mime type of the Sofa data being analyzed.

Returns:

the mime type of the Sofa

addFsToIndexes

void addFsToIndexes(FeatureStructure fs)

Add a feature structure to all appropriate indexes in the repository associated with this CAS View.

Important: after you have called addFsToIndexes(...) on a FS, do not change the values of any features used for indexing. If you do, the index will become corrupted and may be unusable. If you need to change an index feature value, first call removeFsFromIndexes(...) on the FS, change the feature values, then call addFsToIndexes(...) again.

Parameters:

fs - The Feature Structure to be added.

Throws:

NullPointerException - If the fs parameter is null.

removeFsFromIndexes

void removeFsFromIndexes(FeatureStructure fs)

Remove a feature structure from all indexes in the repository associated with this CAS View.

Parameters:

fs - The Feature Structure to be removed.

Throws:

NullPointerException - If the fs parameter is null.

getAnnotationIndex

AnnotationIndex<Annotation> getAnnotationIndex()

Get the standard annotation index.

Returns:

The standard annotation index.

getAnnotationIndex

AnnotationIndex<Annotation> getAnnotationIndex(Type type)
                                               throws CASRuntimeException

Get the standard annotation index restricted to a specific annotation type.

Parameters:

type - The annotation type the index is restricted to.

Returns:

The standard annotation index, restricted to type.

Throws:

CASRuntimeException

getAnnotationIndex

AnnotationIndex<Annotation> getAnnotationIndex(int type)
                                               throws CASRuntimeException

Get the standard annotation index restricted to a specific annotation type.

Parameters:

type - The annotation type the index is restricted to, passed as an integer using the form MyAnnotationType.type

Returns:

The standard annotation index, restricted to type.

Throws:

CASRuntimeException

getViewIterator

Iterator<JCas> getViewIterator()
                               throws CASException

Get iterator over all views in this JCas. Each view provides access to Sofa data and the index repository that contains metadata (annotations and other feature structures) pertaining to that Sofa.

Returns:

an iterator which returns all views. Each object returned by the iterator is of type JCas.

Throws:

CASException

getViewIterator

Iterator<JCas> getViewIterator(String localViewNamePrefix)
                               throws CASException

Get iterator over all views with the given name prefix. Each view provides access to Sofa data and the index repository that contains metadata (annotations and other feature structures) pertaining to that Sofa.

When passed the prefix namePrefix, the iterator will return all views who name is either exactly equal to namePrefix or is of the form namePrefix.suffix, where suffix can be any String.

Parameters:

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

Returns:

an iterator which returns all views with the given name prefix. Each object returned by the iterator is of type JCas.

Throws:

CASException