net.sf.okapi.common.resource

## Class VariantSources

- java.lang.Object
- - net.sf.okapi.common.resource.VariantSources

- All Implemented Interfaces:
    java.lang.Iterable<TextContainer>, IVariantSources

      public class VariantSources
      extends java.lang.Object
      implements IVariantSources

  EXPERIMENTAL implementation, do not use yet. Provides a standard implementation of the IVariantSources interface
  Author:
    David Mason, dr.d.mason@gmail.com

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `VariantSources(TextContainer sourceContainer)`
    `VariantSources(TextContainer sourceContainer, VariantSources original)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `VariantSources` | `clone()`
    `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.
    `java.util.Iterator<TextContainer>` | `iterator()`
    `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.
    `void` | `setDefaultSource(TextContainer sourceContainer)`
    `Property` | `setProperty(LocaleId targetLocale, Property property)` Sets a source property.

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### VariantSources

          public VariantSources(TextContainer sourceContainer)

    - #### VariantSources

          public VariantSources(TextContainer sourceContainer,
                        VariantSources original)

  - ### Method Detail

    - #### setDefaultSource

          public void setDefaultSource(TextContainer sourceContainer)

    - #### clone

          public VariantSources clone()

      Overrides:
        `clone` in class `java.lang.Object`

    - #### isEmpty

          public boolean isEmpty(LocaleId targetLocale)

      Description copied from interface: `IVariantSources`
      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.
      Specified by:
        `isEmpty` in interface `IVariantSources`
      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

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

      Description copied from interface: `IVariantSources`
      Creates a variant source for a given target locale, using the content of the default source according to the specified options.
      Specified by:
        `create` in interface `IVariantSources`
      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

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

      Description copied from interface: `IVariantSources`
      Creates a variant source for a given locale, using the provided `TextContainer`.
      Specified by:
        `create` in interface `IVariantSources`
      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

          public TextContainer get(LocaleId targetLocale)

      Description copied from interface: `IVariantSources`
      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.
      Specified by:
        `get` in interface `IVariantSources`
      Parameters:
        `targetLocale` - the target locale used by the source.
      Returns:
        the source used by the given locale. May be the default source.

    - #### set

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

      Description copied from interface: `IVariantSources`
      Sets the source object to use for the given target locale. Any existing variant source object for the target locale will be overwritten.
      Specified by:
        `set` in interface `IVariantSources`
      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

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

      Description copied from interface: `IVariantSources`
      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.
      Specified by:
        `remove` in interface `IVariantSources`
      Parameters:
        `targetLocale` - the locale for which to remove variant source
      Throws:
        `java.lang.IllegalArgumentException` - if the target locale is null

    - #### hasVariant

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

      Description copied from interface: `IVariantSources`
      Indicates whether there is a variant source for the given locale
      Specified by:
        `hasVariant` in interface `IVariantSources`
      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

    - #### count

          public int count()

      Description copied from interface: `IVariantSources`
      Indicates the number of variant sources stored in this variant source object
      Specified by:
        `count` in interface `IVariantSources`
      Returns:
        the number of variant sources stored in this VariantSources object

    - #### isEmpty

          public boolean isEmpty()

      Description copied from interface: `IVariantSources`
      Indicates whether this variant source object contains any variant sources.
      Specified by:
        `isEmpty` in interface `IVariantSources`
      Returns:
        true if there are no variant sources in this variant sources object

    - #### setContent

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

      Description copied from interface: `IVariantSources`
      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

      Specified by:
        `setContent` in interface `IVariantSources`
      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

          public ISegments getSegments(LocaleId targetLocale)

      Description copied from interface: `IVariantSources`
      Gets the segments for the source used for the given target locale. Un-segmented content return a single segment.
      Specified by:
        `getSegments` in interface `IVariantSources`
      Parameters:
        `targetLocale` - the target locale for which to return source segments
      Returns:
        an object implementing ISegments for the source content.

    - #### getSegment

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

      Description copied from interface: `IVariantSources`
      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.

      Specified by:
        `getSegment` in interface `IVariantSources`
      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

          public java.util.Set<LocaleId> getLocales()

      Description copied from interface: `IVariantSources`
      Lists all target locales for which there is a variant source Does not include a locale for the default source.
      Specified by:
        `getLocales` in interface `IVariantSources`
      Returns:
        a set of all target locales that use a variant source.

    - #### getProperty

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

      Description copied from interface: `IVariantSources`
      Gets the source property for a given name and target locale.
      Specified by:
        `getProperty` in interface `IVariantSources`
      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

          public Property setProperty(LocaleId targetLocale,
                             Property property)

      Description copied from interface: `IVariantSources`
      Sets a source property. If a property already exists it is overwritten.
      Specified by:
        `setProperty` in interface `IVariantSources`
      Parameters:
        `targetLocale` - the target locale of the source
        `property` - The new property to set.
      Returns:
        The property that has been set.

    - #### removeProperty

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

      Description copied from interface: `IVariantSources`
      Removes a source property of a given name. If the property does not exists nothing happens.
      Specified by:
        `removeProperty` in interface `IVariantSources`
      Parameters:
        `targetLocale` - the target locale of the source
        `name` - The name of the property to remove.

    - #### getPropertyNames

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

      Description copied from interface: `IVariantSources`
      Gets the names of all the source properties for this resource.
      Specified by:
        `getPropertyNames` in interface `IVariantSources`
      Parameters:
        `targetLocale` - the target locale of the source
      Returns:
        All the names of the source properties for this resource.

    - #### hasProperty

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

      Description copied from interface: `IVariantSources`
      Indicates if a source property exists for a given name.
      Specified by:
        `hasProperty` in interface `IVariantSources`
      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.

    - #### propagateProperty

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

      Description copied from interface: `IVariantSources`
      Copies a single property from one source version to all other source versions.
      Specified by:
        `propagateProperty` in interface `IVariantSources`
      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

    - #### propagateProperty

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

      Description copied from interface: `IVariantSources`
      Copies a single property from one source version to another source version.
      Specified by:
        `propagateProperty` in interface `IVariantSources`
      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

    - #### propagateAllProperties

          public void propagateAllProperties(LocaleId from,
                                    boolean overwriteExisting)

      Description copied from interface: `IVariantSources`
      Copies all properties from one source version to all other source versions.
      Specified by:
        `propagateAllProperties` in interface `IVariantSources`
      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

    - #### propagateAllProperties

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

      Description copied from interface: `IVariantSources`
      Copies all properties from one source version to another source version.
      Specified by:
        `propagateAllProperties` in interface `IVariantSources`
      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

    - #### propagateAnnotation

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

      Description copied from interface: `IVariantSources`
      Copies a single annotation from one source version to all other source versions.
      Specified by:
        `propagateAnnotation` in interface `IVariantSources`
      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

    - #### propagateAnnotation

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

      Description copied from interface: `IVariantSources`
      Copies a single annotation from one source version to another source version.
      Specified by:
        `propagateAnnotation` in interface `IVariantSources`
      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

    - #### propagateAllAnnotations

          public void propagateAllAnnotations(LocaleId from,
                                     boolean overwriteExisting)

      Description copied from interface: `IVariantSources`
      Copies all annotations from one source version to all other source versions.
      Specified by:
        `propagateAllAnnotations` in interface `IVariantSources`
      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

    - #### propagateAllAnnotations

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

      Description copied from interface: `IVariantSources`
      Copies all annotations from one source version to another source version.
      Specified by:
        `propagateAllAnnotations` in interface `IVariantSources`
      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

    - #### iterator

          public java.util.Iterator<TextContainer> iterator()

      Specified by:
        `iterator` in interface `java.lang.Iterable<TextContainer>`