net.sf.okapi.common.resource

## Interface IVariantSources

- All Superinterfaces:
    java.lang.Iterable<TextContainer>
  All Known Implementing Classes:
    VariantSources

      public interface IVariantSources
      extends java.lang.Iterable<TextContainer>

  EXPERIMENTAL interface, do not use yet, Provides methods to allow the creation and manipulation of different source versions for different locales of an `ITextUnit` object.

  To create an instance of this interface, use the method `ITextUnit.getVariantSources()`.

  Author:
    David Mason, dr.d.mason@gmail.com

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `count()` Indicates the number of variant sources stored in this variant source object
    `TextContainer` | `create(LocaleId targetLocale, boolean overwriteExisting, int creationOptions)` Creates a variant source for a given target locale, using the content of the default source according to the specified options.
    `TextContainer` | `create(TextContainer sourceText, LocaleId targetLocale, boolean overwriteExisting)` Creates a variant source for a given locale, using the provided `TextContainer`.
    `TextContainer` | `get(LocaleId targetLocale)` Gets the source object (a `TextContainer` object) used for the given target locale.
    `java.util.Set<LocaleId>` | `getLocales()` Lists all target locales for which there is a variant source Does not include a locale for the default source.
    `Property` | `getProperty(LocaleId targetLocale, java.lang.String name)` Gets the source property for a given name and target locale.
    `java.util.Set<java.lang.String>` | `getPropertyNames(LocaleId targetLocale)` Gets the names of all the source properties for this resource.
    `Segment` | `getSegment(LocaleId targetLocale, java.lang.String segId, boolean createIfNeeded)` Gets the source segment for a given target locale and segment id.
    `ISegments` | `getSegments(LocaleId targetLocale)` Gets the segments for the source used for the given target locale.
    `boolean` | `hasProperty(LocaleId targetLocale, java.lang.String name)` Indicates if a source property exists for a given name.
    `boolean` | `hasVariant(LocaleId targetLocale)` Indicates whether there is a variant source for the given locale
    `boolean` | `isEmpty()` Indicates whether this variant source object contains any variant sources.
    `boolean` | `isEmpty(LocaleId targetLocale)` Indicates if the source text for the given target locale is isEmpty.
    `void` | `propagateAllAnnotations(LocaleId from, boolean overwriteExisting)` Copies all annotations from one source version to all other source versions.
    `void` | `propagateAllAnnotations(LocaleId from, LocaleId to, boolean overwriteExisting)` Copies all annotations from one source version to another source version.
    `void` | `propagateAllProperties(LocaleId from, boolean overwriteExisting)` Copies all properties from one source version to all other source versions.
    `void` | `propagateAllProperties(LocaleId from, LocaleId to, boolean overwriteExisting)` Copies all properties from one source version to another source version.
    `<A extends IAnnotation> void` | `propagateAnnotation(LocaleId from, java.lang.Class<A> type, boolean overwriteExisting)` Copies a single annotation from one source version to all other source versions.
    `<A extends IAnnotation> void` | `propagateAnnotation(LocaleId from, LocaleId to, java.lang.Class<A> type, boolean overwriteExisting)` Copies a single annotation from one source version to another source version.
    `void` | `propagateProperty(LocaleId from, LocaleId to, java.lang.String propertyName, boolean overwriteExisting)` Copies a single property from one source version to another source version.
    `void` | `propagateProperty(LocaleId from, java.lang.String propertyName, boolean overwriteExisting)` Copies a single property from one source version to all other source versions.
    `void` | `remove(LocaleId targetLocale)` Removes any variant source used for the given target locale.
    `void` | `removeProperty(LocaleId targetLocale, java.lang.String name)` Removes a source property of a given name.
    `TextContainer` | `set(LocaleId targetLocale, TextContainer textContainer)` Sets the source object to use for the given target locale.
    `TextFragment` | `setContent(LocaleId targetLocale, TextFragment content)` Sets the content of the variant source for the given target locale.
    `Property` | `setProperty(LocaleId targetLocale, Property property)` Sets a source property.

    - ### Methods inherited from interface java.lang.Iterable

      `iterator`

- - ### Method Detail

    - #### isEmpty

          boolean isEmpty(LocaleId targetLocale)

      Indicates if the source text for the given target locale is isEmpty. Result will be for the default source if there is no variant source for the given locale, or if the given locale is null.
      Parameters:
        `targetLocale` - the target locale for the source to check
      Returns:
        true if the source text (may be the default source) for the given locale is isEmpty, false otherwise

    - #### create

          TextContainer create(LocaleId targetLocale,
                             boolean overwriteExisting,
                             int creationOptions)

      Creates a variant source for a given target locale, using the content of the default source according to the specified options.
      Parameters:
        `targetLocale` - the target locale that uses the new source
        `overwriteExisting` - overwrites any existing source associated with the locale if true
        `creationOptions` - creation options:
        - CREATE_EMPTY: Create an isEmpty source object.
        - COPY_CONTENT: Copy the text of the default source (and any associated in-line code).
        - COPY_PROPERTIES: Copy the default source properties.
        - COPY_SEGMENTS: Copy the default source segmentation.
        - COPY_ALL: Same as (COPY_CONTENT|COPY_PROPERTIES|COPY_SEGMENTS).
      Returns:
        the source object that was created or retrieved, or null if the

    - #### create

          TextContainer create(TextContainer sourceText,
                             LocaleId targetLocale,
                             boolean overwriteExisting)

      Creates a variant source for a given locale, using the provided `TextContainer`.
      Parameters:
        `sourceText` - the text to include in this source
        `targetLocale` - the target locale that uses the new source
        `overwriteExisting` - overwrites any existing source associated with the locale if true
      Returns:
        the source object that was created or retrieved

    - #### get

          TextContainer get(LocaleId targetLocale)

      Gets the source object (a `TextContainer` object) used for the given target locale. Returns the default source object if the target locale has no variant source.
      Parameters:
        `targetLocale` - the target locale used by the source.
      Returns:
        the source used by the given locale. May be the default source.

    - #### set

          TextContainer set(LocaleId targetLocale,
                          TextContainer textContainer)
                            throws java.lang.IllegalArgumentException

      Sets the source object to use for the given target locale. Any existing variant source object for the target locale will be overwritten.
      Parameters:
        `targetLocale` - the target locale that will use the given source object
        `textContainer` - the source object to use for the given target locale
      Returns:
        the source object that has been set
      Throws:
        `java.lang.IllegalArgumentException` - if the target locale is null

    - #### remove

          void remove(LocaleId targetLocale)
                      throws java.lang.IllegalArgumentException

      Removes any variant source used for the given target locale. Any associated targets will be associated with the default source, which may lead to misalignment of segments between some targets and the default source.
      Parameters:
        `targetLocale` - the locale for which to remove variant source
      Throws:
        `java.lang.IllegalArgumentException` - if the target locale is null

    - #### count

          int count()

      Indicates the number of variant sources stored in this variant source object
      Returns:
        the number of variant sources stored in this VariantSources object

    - #### isEmpty

          boolean isEmpty()

      Indicates whether this variant source object contains any variant sources.
      Returns:
        true if there are no variant sources in this variant sources object

    - #### hasVariant

          boolean hasVariant(LocaleId targetLocale)
                             throws java.lang.IllegalArgumentException

      Indicates whether there is a variant source for the given locale
      Parameters:
        `targetLocale` - the locale to check for variant sources
      Returns:
        true if there is a variant source object for the given locale, false otherwise. Returns false if null target locale is given.
      Throws:
        `java.lang.IllegalArgumentException` - if targetLocale is null

    - #### setContent

          TextFragment setContent(LocaleId targetLocale,
                                TextFragment content)
                                  throws java.lang.IllegalArgumentException

      Sets the content of the variant source for the given target locale. Creates a variant source if one does not exist for the given locale. Replaces any existing content for the source of the given locale.

      TODO consider adding an overwriteExisting flag

      Parameters:
        `targetLocale` - the locale for which to set the source content null to set for default source
        `content` - the content to use for the source of the given locale
      Returns:
        the source content that was set.
      Throws:
        `java.lang.IllegalArgumentException` - if targetLocale is null

    - #### getSegments

          ISegments getSegments(LocaleId targetLocale)

      Gets the segments for the source used for the given target locale. Un-segmented content return a single segment.
      Parameters:
        `targetLocale` - the target locale for which to return source segments
      Returns:
        an object implementing ISegments for the source content.

    - #### getSegment

          Segment getSegment(LocaleId targetLocale,
                           java.lang.String segId,
                           boolean createIfNeeded)

      Gets the source segment for a given target locale and segment id.

      If the segment does not exists, one is created if `createIfNeeded` is true. TODO discuss how to handle target locales that use the default source.

      Parameters:
        `targetLocale` - the target locale for which to return a source segment
        `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 retrieved or created segment, or null if none was found or created.

    - #### getLocales

          java.util.Set<LocaleId> getLocales()

      Lists all target locales for which there is a variant source Does not include a locale for the default source.
      Returns:
        a set of all target locales that use a variant source.

    - #### propagateProperty

          void propagateProperty(LocaleId from,
                               LocaleId to,
                               java.lang.String propertyName,
                               boolean overwriteExisting)

      Copies a single property from one source version to another source version.
      Parameters:
        `from` - the target locale of the source in which the property is located, null to use the default source
        `to` - the target locale of the source to which the property will be copied, null to use the default source
        `propertyName` - the name of the property to copy
        `overwriteExisting` - true to overwrite an existing property if present

    - #### propagateProperty

          void propagateProperty(LocaleId from,
                               java.lang.String propertyName,
                               boolean overwriteExisting)

      Copies a single property from one source version to all other source versions.
      Parameters:
        `from` - the target locale of the source in which the property is located, null to use the default source
        `propertyName` - the name of the property to copy
        `overwriteExisting` - true to overwrite an existing property if present

    - #### propagateAllProperties

          void propagateAllProperties(LocaleId from,
                                    LocaleId to,
                                    boolean overwriteExisting)

      Copies all properties from one source version to another source version.
      Parameters:
        `from` - the target locale of the source to copy properties from, null to use the default source
        `to` - the target locale of the source to copy properties to, null to use the default source
        `overwriteExisting` - true to overwrite any existing properties if present

    - #### propagateAllProperties

          void propagateAllProperties(LocaleId from,
                                    boolean overwriteExisting)

      Copies all properties from one source version to all other source versions.
      Parameters:
        `from` - the target locale of the source to copy properties from, null to use the default source
        `overwriteExisting` - true to overwrite any existing properties if present

    - #### propagateAnnotation

          <A extends IAnnotation> void propagateAnnotation(LocaleId from,
                                                         LocaleId to,
                                                         java.lang.Class<A> type,
                                                         boolean overwriteExisting)

      Copies a single annotation from one source version to another source version.
      Type Parameters:
        `A` - the class type.
      Parameters:
        `from` - the target locale of the source in which the annotation is located, null to use the default source
        `to` - the target locale of the source to which the annotation will be copied, null to use the default source
        `type` - the type of the annotation to copy
        `overwriteExisting` - true to overwrite an existing annotation if present

    - #### propagateAnnotation

          <A extends IAnnotation> void propagateAnnotation(LocaleId from,
                                                         java.lang.Class<A> type,
                                                         boolean overwriteExisting)

      Copies a single annotation from one source version to all other source versions.
      Type Parameters:
        `A` - the class type.
      Parameters:
        `from` - the target locale of the source in which the annotation is located, null to use the default source
        `type` - the type of the annotation to copy
        `overwriteExisting` - true to overwrite an existing annotation if present

    - #### propagateAllAnnotations

          void propagateAllAnnotations(LocaleId from,
                                     LocaleId to,
                                     boolean overwriteExisting)

      Copies all annotations from one source version to another source version.
      Parameters:
        `from` - the target locale of the source to copy annotations from, null to use the default source
        `to` - the target locale of the source to which annotations will be copied, null to use the default source
        `overwriteExisting` - true to overwrite any existing annotation if present

    - #### propagateAllAnnotations

          void propagateAllAnnotations(LocaleId from,
                                     boolean overwriteExisting)

      Copies all annotations from one source version to all other source versions.
      Parameters:
        `from` - the target locale of the source to copy annotations from, null to use the default source
        `overwriteExisting` - true to overwrite any existing annotation if present

    - #### getProperty

          Property getProperty(LocaleId targetLocale,
                             java.lang.String name)

      Gets the source property for a given name and target locale.
      Parameters:
        `targetLocale` - the target locale of the source
        `name` - The name of the source property to retrieve.
      Returns:
        The property or null if it does not exist.

    - #### setProperty

          Property setProperty(LocaleId targetLocale,
                             Property property)

      Sets a source property. If a property already exists it is overwritten.
      Parameters:
        `targetLocale` - the target locale of the source
        `property` - The new property to set.
      Returns:
        The property that has been set.

    - #### removeProperty

          void removeProperty(LocaleId targetLocale,
                            java.lang.String name)

      Removes a source property of a given name. If the property does not exists nothing happens.
      Parameters:
        `targetLocale` - the target locale of the source
        `name` - The name of the property to remove.

    - #### getPropertyNames

          java.util.Set<java.lang.String> getPropertyNames(LocaleId targetLocale)

      Gets the names of all the source properties for this resource.
      Parameters:
        `targetLocale` - the target locale of the source
      Returns:
        All the names of the source properties for this resource.

    - #### hasProperty

          boolean hasProperty(LocaleId targetLocale,
                            java.lang.String name)

      Indicates if a source property exists for a given name.
      Parameters:
        `targetLocale` - the target locale of the source
        `name` - The name of the source property to query.
      Returns:
        True if a source property exists, false otherwise.