Package org.apache.uima.cas

# Interface SofaFS

All Superinterfaces:
  `Cloneable`, `FeatureStructure`

All Known Subinterfaces:
  `SofaFSImpl`

All Known Implementing Classes:
  `Sofa`

public interface SofaFS extends FeatureStructure
Interface for "Subject of Analysis" (Sofa) feature structures. A Sofa is implemented as a built-in CAS type uima.cas.Sofa. The features of the Sofa type include:

- SofaID: Every Sofa in a CAS must have a unique SofaID. SoaIDs are the primary handle or access.
- Mime type: This string feature can be used to describe the type of the data represented by the Sofa.
- Sofa Data: The data itself. This data can be resident in the CAS or it can be a reference to data outside the CAS.

SofaFS (the feature structure that represents a SofA) are created as a side effect of creating a new CAS view. To create a new CAS view, use `CAS.createView(string-view-name)`. From the returned CAS view, you can get the associated SofaFS instance, using `CAS.getSofa()`. The SofaFS interface provides methods to set the values of the features of the Sofa FS. Generic CAS APIs should never be used to create Sofas or set their features.

Sofa data can be contained locally in the CAS itself or it can be remote from CAS. To set the local Sofa data in the Sofa FS use: `SofaFS.setLocalSofaData()`. If the data is remote from the CAS use: `SofaFS.setRemoteSofaURI()`.

Once set, the Sofa data cannot be set again until the CAS has been reset. This is so that annotators cannot change the subject of analysis during processing.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FeatureStructure`
  `getLocalFSData()`
  Get the Local Subject of Analysis returns null if not previously set.
  `String`
  `getLocalStringData()`
  Get the Local Subject of Analysis returns null if not previously set.
  `InputStream`
  `getSofaDataStream()`
  Provides stream access to both local and remote Sofa data.
  `String`
  `getSofaID()`
  Get the Sofa globally unique name, after mapping.
  `String`
  `getSofaMime()`
  Get the Sofa mime type.
  `int`
  `getSofaNum()`
  Get the Sofa Ref value.
  `int`
  `getSofaRef()`
  Get the Sofa Ref value.
  `String`
  `getSofaURI()`
  Get the Sofa URI value.
  `void`
  `setLocalSofaData(String aString)`
  Set the Local Subject of Analysis to be a String.
  `void`
  `setLocalSofaData(FeatureStructure aFS)`
  Set the Local Subject of Analysis to be a predefined ArrayFS.
  `void`
  `setRemoteSofaURI(String aURI)`
  Set the URI for a Remote Subject of Analysis.

  ### Methods inherited from interface org.apache.uima.cas.FeatureStructure

  `_getTypeCode, _id, clone, equals, getAddress, getBooleanValue, getByteValue, getCAS, getDoubleValue, getFeatureValue, getFeatureValueAsString, getFloatValue, getIntValue, getJCas, getLongValue, getShortValue, getStringValue, getType, hashCode, setBooleanValue, setByteValue, setDoubleValue, setFeatureValue, setFeatureValueFromString, setFloatValue, setIntValue, setLongValue, setShortValue, setStringValue`

- ## Method Details

  - ### setRemoteSofaURI

    void setRemoteSofaURI(String aURI)
    Set the URI for a Remote Subject of Analysis. Once set, this URI may not be changed.
    Parameters:
      `aURI` - the URI for a remote Sofa
    Throws:
      `CASRuntimeException` - if the Sofa data has already been set

  - ### setLocalSofaData

    void setLocalSofaData(FeatureStructure aFS) throws CASRuntimeException
    Set the Local Subject of Analysis to be a predefined ArrayFS. Once set, the Sofa data cannot be changed.
    Parameters:
      `aFS` - the SofA
    Throws:
      `CASRuntimeException` - if given FS is not an ArrayFS, or if the Sofa data has already been set

  - ### setLocalSofaData

    void setLocalSofaData(String aString) throws CASRuntimeException
    Set the Local Subject of Analysis to be a String. Once set, the Sofa data cannot be changed.
    Parameters:
      `aString` - The subject of analysis
    Throws:
      `CASRuntimeException` - if the Sofa data has already been set

  - ### getLocalFSData

    FeatureStructure getLocalFSData()
    Get the Local Subject of Analysis returns null if not previously set.
    Returns:
      the local SofA

  - ### getLocalStringData

    String getLocalStringData()
    Get the Local Subject of Analysis returns null if not previously set.
    Returns:
      the SofA

  - ### getSofaMime

    String getSofaMime()
    Get the Sofa mime type.
    Returns:
      SofA mime type

  - ### getSofaID

    String getSofaID()
    Get the Sofa globally unique name, after mapping.
    Returns:
      Sofa globally unique name, after mapping

  - ### getSofaURI

    String getSofaURI()
    Get the Sofa URI value.
    Returns:
      Sofa URI or null if not valid

  - ### getSofaNum

    int getSofaNum()
    Get the Sofa Ref value. (same as getSofaRef())
    Returns:
      the Sofa Reference value

  - ### getSofaRef

    int getSofaRef()
    Get the Sofa Ref value.
    Returns:
      the Sofa Reference value

  - ### getSofaDataStream

    InputStream getSofaDataStream()
    Provides stream access to both local and remote Sofa data. For remote SofA data, a custom URLStreamHandler may be registered for a protocol via the java.protocol.handler.pkgs system property.
    Returns:
      an InputStream for reading Sofa data. null returned if there is no Sofa data.