net.sf.okapi.common.resource

## Interface ITextUnit

- All Superinterfaces:
    INameable, IReferenceable, IResource
  All Known Implementing Classes:
    TextUnit

      public interface ITextUnit
      extends INameable, IReferenceable

  Interface for the basic unit of extraction from a filter and also the resource associated with the filter event TEXT_UNIT.

  The TextUnit object holds the extracted source text, all its properties and annotations, and any target corresponding data.

  If adjustments to the source are required for different target locales, these can be made using the `IVariantSources` interface, accessible through `getVariantSources()`

  Where adjusted sources exist, methods in this interface should have their effects on the default source, however a specific implementation may provide a method to select one of the variant sources that methods would then use. The main source should always be used before such a method is called.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `TYPE_CDATA` Resource type value for a cdata section.
    `static java.lang.String` | `TYPE_HEADER` Resource type value for a header.
    `static java.lang.String` | `TYPE_LIST_ELEMENT` Resource type value for a list.
    `static java.lang.String` | `TYPE_PARA` Resource type value for a paragraph.
    `static java.lang.String` | `TYPE_TITLE` Resource type value for a title.

    - ### Fields inherited from interface net.sf.okapi.common.IResource

      `COPY_ALL, COPY_CONTENT, COPY_PROPERTIES, COPY_SEGMENTATION, COPY_SEGMENTED_CONTENT, CREATE_EMPTY`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ITextUnit` | `clone()` Clones this TextUnit.
    `void` | `createSourceSegmentation(ISegmenter segmenter)` Segments the default source content based on the rules provided by a given ISegmenter.
    `TextContainer` | `createTarget(LocaleId locId, boolean overwriteExisting, int creationOptions)` Creates or get the target for this TextUnit.
    `void` | `createTargetSegmentation(ISegmenter segmenter, LocaleId targetLocale)` Segments the specified target content based on the rules provided by a given ISegmenter.
    `IAlignedSegments` | `getAlignedSegments()` Creates a new `IAlignedSegments` object to access and manipulate the segments of this text unit.
    `TextContainer` | `getSource()` Gets the source object for this text unit (a `TextContainer` object).
    `Segment` | `getSourceSegment(java.lang.String segId, boolean createIfNeeded)` Gets the source segment for a given segment id.
    `ISegments` | `getSourceSegments()` Gets the segments for the source.
    `TextContainer` | `getTarget(LocaleId locId)` Gets the target object for this text unit for a given locale.
    `Segment` | `getTargetSegment(LocaleId trgLoc, java.lang.String segId, boolean createIfNeeded)` Gets the segment for a given segment id in a given target.
    `ISegments` | `getTargetSegments(LocaleId trgLoc)` Get the segments for a given target.
    `IVariantSources` | `getVariantSources()` Returns the variant sources (an `IVariantSources` object) for this text unit.
    `boolean` | `hasTarget(LocaleId locId)` Indicates if there is a target object for a given locale for this text unit.
    `boolean` | `hasVariantSources()` Indicates whether there are any variant sources used in this text unit.
    `boolean` | `isEmpty()` Indicates if the source text of this TextUnit is empty.
    `void` | `removeAllSegmentations()` Removes all segmentations (source and targets) in this text unit.
    `void` | `removeTarget(LocaleId locId)` Removes a given target object from this text unit.
    `TextContainer` | `setSource(TextContainer textContainer)` Sets the source object for this TextUnit.
    `TextFragment` | `setSourceContent(TextFragment content)` Sets the content of the source for this TextUnit.
    `TextContainer` | `setTarget(LocaleId locId, TextContainer text)` Sets the target object for this text unit for a given locale.
    `TextFragment` | `setTargetContent(LocaleId locId, TextFragment content)` Sets the content of the target for a given locale for this TextUnit.

    - ### Methods inherited from interface net.sf.okapi.common.resource.INameable

      `createTargetProperty, getMimeType, getName, getProperty, getPropertyNames, getSourceProperty, getSourcePropertyNames, getTargetLocales, getTargetProperty, getTargetPropertyNames, getType, hasProperty, hasSourceProperty, hasTargetProperty, isTranslatable, preserveWhitespaces, removeProperty, removeSourceProperty, removeTargetProperty, setIsTranslatable, setMimeType, setName, setPreserveWhitespaces, setProperty, setSourceProperty, setTargetProperty, setType`

    - ### Methods inherited from interface net.sf.okapi.common.IResource

      `getAnnotation, getAnnotations, getId, getSkeleton, setAnnotation, setId, setSkeleton`

    - ### Methods inherited from interface net.sf.okapi.common.resource.IReferenceable

      `getReferenceCount, isReferent, setIsReferent, setReferenceCount`

- - ### Field Detail

    - #### TYPE_PARA

          static final java.lang.String TYPE_PARA

      Resource type value for a paragraph.
      See Also:
        Constant Field Values

    - #### TYPE_LIST_ELEMENT

          static final java.lang.String TYPE_LIST_ELEMENT

      Resource type value for a list.
      See Also:
        Constant Field Values

    - #### TYPE_TITLE

          static final java.lang.String TYPE_TITLE

      Resource type value for a title.
      See Also:
        Constant Field Values

    - #### TYPE_HEADER

          static final java.lang.String TYPE_HEADER

      Resource type value for a header.
      See Also:
        Constant Field Values

    - #### TYPE_CDATA

          static final java.lang.String TYPE_CDATA

      Resource type value for a cdata section.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### clone

          ITextUnit clone()

      Clones this TextUnit.
      Returns:
        A new TextUnit object that is a copy of this one.

    - #### isEmpty

          boolean isEmpty()

      Indicates if the source text of this TextUnit is empty.
      Returns:
        true if the source text of this TextUnit is empty, false otherwise.

    - #### getSource

          TextContainer getSource()

      Gets the source object for this text unit (a `TextContainer` object).
      Returns:
        the source object for this text unit.

    - #### setSource

          TextContainer setSource(TextContainer textContainer)

      Sets the source object for this TextUnit. Any existing source object is overwritten.
      Parameters:
        `textContainer` - the source object to set.
      Returns:
        the source object that has been set.

    - #### hasVariantSources

          boolean hasVariantSources()

      Indicates whether there are any variant sources used in this text unit.
      Returns:
        true if there are one or more variant sources, false if there are none

    - #### getVariantSources

          IVariantSources getVariantSources()

      Returns the variant sources (an `IVariantSources` object) for this text unit.
      Returns:
        the variant sources used in this text unit

    - #### getTarget

          TextContainer getTarget(LocaleId locId)

      Gets the target object for this text unit for a given locale. If the target does not exists a null is retruned.
      Parameters:
        `locId` - the locale to query.
      Returns:
        the target object for this text unit for the given locale, or null if the target does not exist.
      See Also:
        `createTarget(LocaleId, boolean, int)`

    - #### setTarget

          TextContainer setTarget(LocaleId locId,
                                TextContainer text)

      Sets the target object for this text unit for a given locale.

      If the target does not exists, one is created. Any existing content for the given locale is overwritten. To set a target object based on the source, use the `createTarget(LocaleId, boolean, int)` method.

      Parameters:
        `locId` - the target locale.
        `text` - the target content to set.
      Returns:
        the target content that has been set.

    - #### removeTarget

          void removeTarget(LocaleId locId)

      Removes a given target object from this text unit. If the given locale does not exist in this text unit nothing happens. Variant source for this target locale will not be affected.
      Parameters:
        `locId` - the target locale to remove.

    - #### hasTarget

          boolean hasTarget(LocaleId locId)

      Indicates if there is a target object for a given locale for this text unit.
      Parameters:
        `locId` - the locale to query.
      Returns:
        true if a target object exists for the given locale, false otherwise.

    - #### createTarget

          TextContainer createTarget(LocaleId locId,
                                   boolean overwriteExisting,
                                   int creationOptions)

      Creates or get the target for this TextUnit.

      If a variant source exists for the target locale, creationOptions apply to the variant source.

      Parameters:
        `locId` - the target locale.
        `overwriteExisting` - true to overwrite any existing target for the given locale. False to not create a new target object if one already exists for the given locale.
        `creationOptions` - creation options:
        - CREATE_EMPTY: Create an empty target object.
        - COPY_PROPERTIES: Copy the source properties.
        - COPY_CONTENT: Copy the text of the source (and any associated in-line code), but not the segmenation.
        - COPY_SEGMENTATION: Copy the source segmentation.
        - COPY_SEGMENTED_CONTENT: Same as (COPY_CONTENT|COPY_SEGMENTATION).
        - COPY_ALL: Same as (COPY_SEGMENTED_CONTENT|COPY_PROPERTIES).
      Returns:
        the target object that was created, or retrieved.

    - #### setSourceContent

          TextFragment setSourceContent(TextFragment content)

      Sets the content of the source for this TextUnit.
      Parameters:
        `content` - the new content to set.
      Returns:
        the new content of the source for this TextUnit.

    - #### setTargetContent

          TextFragment setTargetContent(LocaleId locId,
                                      TextFragment content)

      Sets the content of the target for a given locale for this TextUnit.

      If the target does not exists, one is created. Any existing content for the given locale is overwritten. To set a target object based on the source, use the `createTarget(LocaleId, boolean, int)` method.

      Parameters:
        `locId` - the locale to set.
        `content` - the new content to set.
      Returns:
        the new content for the given target locale for this text unit.

    - #### getAlignedSegments

          IAlignedSegments getAlignedSegments()

      Creates a new `IAlignedSegments` object to access and manipulate the segments of this text unit.
      Returns:
        a new `IAlignedSegments` object.

    - #### getSourceSegments

          ISegments getSourceSegments()

      Gets the segments for the source. Un-segmented content return a single segment.
      Returns:
        an object implementing ISegments for the source content.

    - #### getTargetSegments

          ISegments getTargetSegments(LocaleId trgLoc)

      Get the segments for a given target. Un-segmented content return a single segment. If the target does not exists, one is created, with the same segments as the source, but empty.
      Parameters:
        `trgLoc` - the locale of the target to retrieve.
      Returns:
        an object implementing ISegments for the given target content.

    - #### removeAllSegmentations

          void removeAllSegmentations()

      Removes all segmentations (source and targets) in this text unit. All entries are converted to non-segmented entries.

    - #### createSourceSegmentation

          void createSourceSegmentation(ISegmenter segmenter)

      Segments the default source content based on the rules provided by a given ISegmenter.
      Parameters:
        `segmenter` - the segmenter to use to create the segments.

    - #### createTargetSegmentation

          void createTargetSegmentation(ISegmenter segmenter,
                                      LocaleId targetLocale)

      Segments the specified target content based on the rules provided by a given ISegmenter.
      Parameters:
        `segmenter` - the segmenter to use to create the segments.
        `targetLocale` - `LocaleId` of the target we want to segment.

    - #### getSourceSegment

          Segment getSourceSegment(java.lang.String segId,
                                 boolean createIfNeeded)

      Gets the source segment for a given segment id.

      If the segment does not exists, one is created if `createIfNeeded` is true.

      Parameters:
        `segId` - the id of the segment to retrieve.
        `createIfNeeded` - true to append a segment at the end of the content and return it if the segment does not exist yet. False to return null when the segment does not exists.
      Returns:
        the found or created segment, or null.

    - #### getTargetSegment

          Segment getTargetSegment(LocaleId trgLoc,
                                 java.lang.String segId,
                                 boolean createIfNeeded)

      Gets the segment for a given segment id in a given target.

      If the target does not exists, one is created.

      If the segment does not exists, one is created if `createIfNeeded` is true.

      Parameters:
        `trgLoc` - the target locale to look up.
        `segId` - the id of the segment to retrieve.
        `createIfNeeded` - true to append a segment at the end of the target content and return it if the segment does not exist yet. False to return null when the segment does not exists.
      Returns:
        the found or created segment, or null.