| #ifndef UIMA_FEATURESTRUCTURE_HPP |
| #define UIMA_FEATURESTRUCTURE_HPP |
| /** \file featurestructure.hpp . |
| ----------------------------------------------------------------------------- |
| |
| |
| |
| |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| |
| ----------------------------------------------------------------------------- |
| |
| \brief Contains class uima::FeatureStructure |
| |
| Description: |
| |
| ----------------------------------------------------------------------------- |
| |
| |
| -------------------------------------------------------------------------- */ |
| |
| |
| /* ----------------------------------------------------------------------- */ |
| /* Include dependencies */ |
| /* ----------------------------------------------------------------------- */ |
| |
| #include "uima/pragmas.hpp" |
| |
| #include "uima/lowlevel_typedefs.hpp" |
| #include "uima/typesystem.hpp" |
| #include "uima/casexception.hpp" |
| #include "uima/unistrref.hpp" |
| |
| #include "unicode/utf.h" |
| /* ----------------------------------------------------------------------- */ |
| /* Constants */ |
| /* ----------------------------------------------------------------------- */ |
| |
| /* ----------------------------------------------------------------------- */ |
| /* Forward declarations */ |
| /* ----------------------------------------------------------------------- */ |
| |
| |
| namespace uima { |
| class ListFS; |
| class FloatListFS; |
| class IntListFS; |
| class StringListFS; |
| class ArrayFS; |
| class FloatArrayFS; |
| class IntArrayFS; |
| class StringArrayFS; |
| class StringFilter; |
| class ByteArrayFS; |
| class BooleanArrayFS; |
| class ShortArrayFS; |
| class LongArrayFS; |
| class DoubleArrayFS; |
| |
| namespace internal { |
| class IndexCompWrapper; |
| class FSFilterWrapper; |
| class FSPromoter; |
| } |
| namespace lowlevel { |
| class FSHeap; |
| } |
| } |
| |
| /* ----------------------------------------------------------------------- */ |
| /* Types / Classes */ |
| /* ----------------------------------------------------------------------- */ |
| |
| |
| |
| namespace uima { |
| // exceptions |
| UIMA_EXC_CLASSDECLARE(InvalidFSObjectException, CASException); |
| UIMA_EXC_CLASSDECLARE(FeatureNotAppropriateException, CASException); |
| UIMA_EXC_CLASSDECLARE(IncompatibleValueTypeException, CASException); |
| UIMA_EXC_CLASSDECLARE(FSIsNotStringException, CASException); |
| UIMA_EXC_CLASSDECLARE(WrongStringValueException, CASException); |
| |
| |
| /** |
| * Our feature structure. |
| * All methods may throw an <code>InvalidFSObjectException</code> if the |
| * feature structure object is not valid. |
| */ |
| class UIMA_LINK_IMPORTSPEC FeatureStructure { |
| friend class uima::internal::FSPromoter; |
| friend class uima::ListFS; |
| friend class uima::ArrayFS; |
| friend class uima::StringFilter; |
| friend class uima::CAS; |
| friend class RemoteSofaDataStream; |
| friend class LocalSofaDataStream; |
| friend class XCASDeserializerHandler; |
| friend class XmiDeserializerHandler; |
| |
| protected: |
| lowlevel::TyFS iv_tyFS; |
| CAS * iv_cas; |
| |
| //FeatureStructure(lowlevel::TyFS anFS, uima::lowlevel::FSHeap &); |
| FeatureStructure(lowlevel::TyFS anFS, uima::CAS &); |
| |
| void checkValidity(TyMessageId) const; |
| void checkFeature(Feature const & f, TyMessageId) const; |
| void checkNonBuiltinFeature(Feature const & f, TyMessageId) const; |
| void checkAppropFeature(Feature const & f, lowlevel::TyFSType aType, TyMessageId) const; |
| void checkAppropFeature(Feature const & f, FeatureStructure const & anFS, TyMessageId) const; |
| |
| void checkRangeIsString(Feature const & fList, TyMessageId) const; |
| |
| public: |
| typedef lowlevel::TyHeapCell TyArrayElement; |
| |
| /** |
| * Default constructor: Creates an invalid FS. |
| */ |
| FeatureStructure(); |
| |
| /** |
| * Returns the CAS object in which this feature structure lives. |
| */ |
| CAS & getCAS(); |
| CAS const & getCAS() const; |
| |
| /** |
| * Check if this FS object is valid, i.e., properly initialized. |
| */ |
| bool isValid() const; |
| |
| /** |
| * @return the type of this FS. |
| * @throws InvalidFSObjectException |
| */ |
| Type getType() const; |
| |
| |
| /** |
| * Creates a copy of this feature structure. |
| * The returned feature structure is a new and separate object but |
| * all features of the feature structure which are not of builtin |
| * types (integer, float, string) will be shared between the clone |
| * and it's source FS. |
| * @return the cloned copy of this object. |
| * @throws InvalidFSObjectException |
| */ |
| FeatureStructure clone(); |
| |
| /** |
| * creates a feature structure of type t and copies all |
| * "common" features of t and this->getType(). |
| * A feature is common to two types t1 and t2 if it is defined on the |
| * most specific common supertype of t1 and t2. |
| */ |
| FeatureStructure clone(Type const & t); |
| |
| /** |
| * Check if the value of <code>crFeature</code> was already used via |
| * a call to <code>getFSValue()</code> or <code>setFSValue()</code>. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| */ |
| bool isUntouchedFSValue(Feature const & crFeature) const; |
| |
| /** |
| * Get the value of feature <code>crFeature</code> of this feature structure |
| * (must not be a builtin type). |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| */ |
| FeatureStructure getFSValue(Feature const & crFeature) const; |
| |
| /** |
| * Get the value of feature <code>crFeature</code> of this feature structure |
| * (must not be a builtin type). |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| */ |
| FeatureStructure getFeatureValue(Feature const & crFeature) const; |
| |
| /** |
| * set the value of feature <code>crFeature</code> of this feature structure |
| * (must not be a builtin type). |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| void setFSValue(Feature const & crFeature, FeatureStructure const & anFS); |
| |
| /** |
| * set the value of feature <code>crFeature</code> of this feature structure |
| * (must not be a builtin type). |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| void setFeatureValue(Feature const & crFeature, FeatureStructure const & anFS); |
| |
| /** |
| * Get the value of feature <code>crFeature</code>, must be builtin type integer. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| int getIntValue(Feature const & crFeature) const; |
| |
| /** |
| * Set the value of feature <code>crFeature</code>, must be builtin type integer. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| void setIntValue(Feature const & crFeature, int i); |
| |
| /** |
| * Get the value of feature <code>crFeature</code>, must be builtin type float. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| float getFloatValue(Feature const & crFeature) const; |
| |
| /** |
| * Set the value of feature <code>crFeature</code>, must be builtin type float. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| void setFloatValue(Feature const & crFeature, float ); |
| |
| /** |
| * Get the value of feature <code>crFeature</code>, must be of type string. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotAStringException |
| */ |
| UnicodeStringRef getStringValue(Feature const & crFeature) const; |
| |
| /** |
| * sets the value of feature <code>crFeature</code> of this feature structure |
| * to a new string on the heap. |
| * Precondition: getFSValue(crFeature) must be of type string. |
| * The string is copied to the heap and the string value will point |
| * to the copy on the heap and not to <code>cuStr</code>. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotAStringException |
| */ |
| void setStringValue(Feature const & crFeature, UnicodeStringRef cuStr); |
| void setStringValue(Feature const & crFeature, UChar const * cuStr, size_t uiLen ); |
| void setStringValue(Feature const & crFeature, icu::UnicodeString const & crustr ); |
| |
| /** |
| * sets the value of feature <code>crFeature</code> of this feature structure |
| * to a new string outside of the heap. |
| * Precondition: FS must be of type string. |
| * The string is <strong>not</strong> copied to the heap, |
| * so the string value will point to <code>cuStr</code>. |
| * The caller must make sure that the characters in <code>cuStr</code> |
| * have an appropriate live time. |
| * For persistency of the CAS to be consistent and complete the caller |
| * must make sure that all the string data lives somewhere on the heap. |
| * |
| * @throws InvalidFSObjectException |
| * @throws FSIsNotAStringException |
| */ |
| void setStringValueExternal(Feature const & crFeature, UnicodeStringRef cuStr); |
| void setStringValueExternal(Feature const & crFeature, UChar const * cuStr, size_t uiLen ); |
| void setStringValueExternal(Feature const & crFeature, icu::UnicodeString const & crustr ); |
| |
| |
| /** |
| * Return feature structure of type array stored at feature fArray. |
| * The return value is guaranteed to be a properly terminated array. |
| * Each element in the array is a FeatureStructure. |
| * |
| * @param fArray The feature referencing the array to return. |
| * fArray must be valid. |
| * fArray must be appropriate for this feature strucutre. |
| * fArray must be subsumed by type array. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotArrayException |
| */ |
| ArrayFS getArrayFSValue(Feature const & fArray) const; |
| |
| /** |
| * Return feature structure of type array stored at feature fArray. |
| * The return value is guaranteed to be a properly terminated array. |
| * Each element in the array is a float. |
| * |
| * @param fArray The feature referencing the array to return. |
| * fArray must be valid. |
| * fArray must be appropriate for this feature strucutre. |
| * fArray must be subsumed by type array. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotArrayException |
| */ |
| FloatArrayFS getFloatArrayFSValue( Feature const & fArray ) const; |
| |
| /** |
| * Return feature structure of type array stored at feature fArray. |
| * The return value is guaranteed to be a properly terminated array. |
| * Each element in the array is a int. |
| * |
| * @param fArray The feature referencing the array to return. |
| * fArray must be valid. |
| * fArray must be appropriate for this feature strucutre. |
| * fArray must be subsumed by type array. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotArrayException |
| */ |
| IntArrayFS getIntArrayFSValue( Feature const & fArray ) const; |
| |
| /** |
| * Return feature structure of type array stored at feature fArray. |
| * The return value is guaranteed to be a properly terminated array. |
| * Each element in the array is a string. |
| * |
| * @param fArray The feature referencing the array to return. |
| * fArray must be valid. |
| * fArray must be appropriate for this feature strucutre. |
| * fArray must be subsumed by type array. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotArrayException |
| */ |
| StringArrayFS getStringArrayFSValue( Feature const & fArray ) const; |
| |
| /** |
| * Returns true if the list stored at feature fList has elements. |
| * |
| * @param fList The feature to check. |
| * fList must be of type list |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotListException |
| */ |
| bool hasListElements(Feature const & fList) const; |
| |
| /** |
| * Return feature structure of type list stored at feature fList. |
| * The return value is guaranteed to be a properly terminated list. |
| * Each element of the list is a feature structure. |
| * |
| * @param fList The feature referencing the list to return. |
| * fList must be valid. |
| * fList must be appropriate for this feature strucutre. |
| * fList must be subsumed by type list. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotListException |
| */ |
| ListFS getListFSValue(Feature const & fList) const; |
| |
| /** |
| * Return feature structure of type list stored at feature fList. |
| * The return value is guaranteed to be a properly terminated list. |
| * Each element of the list is a float. |
| * |
| * @param f The feature referencing the list to return. |
| * f must be valid. |
| * f must be appropriate for this feature strucutre. |
| * f must be subsumed by type list. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotListException |
| */ |
| FloatListFS getFloatListFSValue( Feature const & f ) const; |
| |
| /** |
| * Return feature structure of type list stored at feature fList. |
| * The return value is guaranteed to be a properly terminated list. |
| * Each element of the list is a int. |
| * |
| * @param f The feature referencing the list to return. |
| * f must be valid. |
| * f must be appropriate for this feature strucutre. |
| * f must be subsumed by type list. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotListException |
| */ |
| IntListFS getIntListFSValue( Feature const & f ) const; |
| |
| /** |
| * Return feature structure of type list stored at feature fList. |
| * The return value is guaranteed to be a properly terminated list. |
| * Each element of the list is a string. |
| * |
| * @param f The feature referencing the list to return. |
| * f must be valid. |
| * f must be appropriate for this feature strucutre. |
| * f must be subsumed by type list. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotListException |
| */ |
| StringListFS getStringListFSValue( Feature const & f ) const; |
| |
| |
| /** |
| * Get the value of feature <code>crFeature</code>, must be builtin type byte. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| bool getBooleanValue(Feature const & crFeature) const; |
| |
| /** |
| * Set the value of feature <code>crFeature</code>, must be builtin type byte. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| void setBooleanValue(Feature const & crFeature, bool ); |
| |
| /** |
| * Get the value of feature <code>crFeature</code>, must be builtin type byte. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| char getByteValue(Feature const & crFeature) const; |
| |
| /** |
| * Set the value of feature <code>crFeature</code>, must be builtin type byte. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| void setByteValue(Feature const & crFeature, char ); |
| |
| /** |
| * Get the value of feature <code>crFeature</code>, must be builtin type short. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| short getShortValue(Feature const & crFeature) const; |
| |
| /** |
| * Set the value of feature <code>crFeature</code>, must be builtin type short. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| void setShortValue(Feature const & crFeature, short ); |
| |
| |
| /** |
| * Get the value of feature <code>crFeature</code>, must be builtin type short. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| INT64 getLongValue(Feature const & crFeature) const; |
| |
| /** |
| * Set the value of feature <code>crFeature</code>, must be builtin type short. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| void setLongValue(Feature const & crFeature, INT64 ); |
| |
| /** |
| * Set the value of feature <code>crFeature</code>, must be builtin type short. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| void setDoubleValue(Feature const & crFeature, double ); |
| |
| /** |
| * Get the value of feature <code>crFeature</code>, must be builtin type short. |
| * @throws InvalidFSObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws IncompatibleValueTypeException |
| */ |
| double getDoubleValue(Feature const & crFeature) const; |
| |
| |
| |
| |
| |
| /** Return feature structure of type array stored at feature fArray. |
| * The return value is guaranteed to be a properly terminated array. |
| * Each element in the array is a byte. |
| * |
| * @param fArray The feature referencing the array to return. |
| * fArray must be valid. |
| * fArray must be appropriate for this feature strucutre. |
| * fArray must be subsumed by type array. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotArrayException |
| */ |
| BooleanArrayFS getBooleanArrayFSValue( Feature const & fArray ) const; |
| |
| /** Return feature structure of type array stored at feature fArray. |
| * The return value is guaranteed to be a properly terminated array. |
| * Each element in the array is a byte. |
| * |
| * @param fArray The feature referencing the array to return. |
| * fArray must be valid. |
| * fArray must be appropriate for this feature strucutre. |
| * fArray must be subsumed by type array. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotArrayException |
| */ |
| ByteArrayFS getByteArrayFSValue( Feature const & fArray ) const; |
| |
| |
| /** Return feature structure of type array stored at feature fArray. |
| * The return value is guaranteed to be a properly terminated array. |
| * Each element in the array is a short. |
| * |
| * @param fArray The feature referencing the array to return. |
| * fArray must be valid. |
| * fArray must be appropriate for this feature strucutre. |
| * fArray must be subsumed by type array. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotArrayException |
| */ |
| ShortArrayFS getShortArrayFSValue( Feature const & fArray ) const; |
| |
| /** Return feature structure of type array stored at feature fArray. |
| * The return value is guaranteed to be a properly terminated array. |
| * Each element in the array is a lomg (INT64). |
| * |
| * @param fArray The feature referencing the array to return. |
| * fArray must be valid. |
| * fArray must be appropriate for this feature strucutre. |
| * fArray must be subsumed by type array. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotArrayException |
| */ |
| LongArrayFS getLongArrayFSValue( Feature const & fArray ) const; |
| |
| /** Return feature structure of type array stored at feature fArray. |
| * The return value is guaranteed to be a properly terminated array. |
| * Each element in the array is a double (INT64). |
| * |
| * @param fArray The feature referencing the array to return. |
| * fArray must be valid. |
| * fArray must be appropriate for this feature strucutre. |
| * fArray must be subsumed by type array. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotArrayException |
| */ |
| DoubleArrayFS getDoubleArrayFSValue( Feature const & fArray ) const; |
| |
| bool operator==(FeatureStructure const & ) const; |
| bool operator!=(FeatureStructure const & crFS) const; |
| bool operator<(FeatureStructure const & crFS) const; |
| }; |
| |
| |
| |
| } // namespace uima |
| |
| /* ----------------------------------------------------------------------- */ |
| /* Implementation */ |
| /* ----------------------------------------------------------------------- */ |
| |
| namespace uima { |
| inline bool FeatureStructure::operator!=(FeatureStructure const & crFS) const { |
| return ! (*this == crFS); |
| } |
| inline void FeatureStructure::setStringValue(Feature const & crFeature, UChar const * cpuc, size_t uiLen) { |
| setStringValue(crFeature, UnicodeStringRef(cpuc, uiLen)); |
| } |
| inline void FeatureStructure::setStringValue(Feature const & crFeature, icu::UnicodeString const & crustr ) { |
| setStringValue(crFeature, UnicodeStringRef(crustr.getBuffer(), crustr.length())); |
| } |
| inline void FeatureStructure::setStringValueExternal(Feature const & crFeature, UChar const * cpuc, size_t uiLen) { |
| setStringValueExternal(crFeature, UnicodeStringRef(cpuc, uiLen)); |
| } |
| inline void FeatureStructure::setStringValueExternal(Feature const & crFeature, icu::UnicodeString const & crustr ) { |
| setStringValueExternal(crFeature, UnicodeStringRef(crustr.getBuffer(), crustr.length())); |
| } |
| } |
| |
| /* ----------------------------------------------------------------------- */ |
| /* Implementation */ |
| /* ----------------------------------------------------------------------- */ |
| |
| /* ----------------------------------------------------------------------- */ |
| |
| |
| #endif |
| /* <EOF> */ |
| |
| |
