TypeDefinitionString (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.meta

## Interface TypeDefinitionString

- All Superinterfaces:
    MetadataObject, MetaDefinition, TypeDefinition, WeakReferenceTarget
  All Known Implementing Classes:
    TypeDefinitionStringImpl

      public interface TypeDefinitionString
      extends TypeDefinition

  Specifies the definition of a property type that consists, effectively, of an array of the underlying character or integer type. In the MAJ API, all strings are represented as Java strings.

  String type definitions have an underlying element type that can be found be calling `getElementType()`. The element type can be either a character type or an integer type. The methods of this class allow the manipulation of string property values in a way that hides the underlying value type.

  For any conversion between arrays of integer values and Java strings or vice versa, the character set returned by `getCharacterSet()` is used. This character set can also be set using to a user-defined value with `setCharacterSet(String)` and the defined byte order of any buffer is respected. The default value for this property is "`UTF-16`", which is the same as the default character set for the Java platform.

  Due to the object-oriented representation of arrays in Java including a defined length, sequences of data are not expected to be terminated with null bytes.

  Property values containing `null` as the value for a string are acceptable.

  See Also:
    `TypeCategory.String`, `String`, `TypeDefinitionCharacter`, `TypeDefinitions.UTF16String`, `AAFString`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendElements(PropertyValue stringProperty, Buffer elements)` Append to the string value of the given property value using a data buffer.
    `void` | `appendElements(PropertyValue stringProperty, PropertyValue[] elements)` Append to the string value of the given property value using the array of property value elements.
    `void` | `appendString(PropertyValue stringProperty, Buffer extension)` Appends the given data buffer to the string of the given property value.
    `void` | `appendString(PropertyValue stringProperty, String extension)` Appends the given Java String to the string of the given property value.
    `TypeDefinitionString` | `clone()` Create a cloned copy of this string type definition.
    `PropertyValue` | `createValueFromString(Buffer initialData)` Create a new string type property value consistent with this type definition from the given data buffer.
    `PropertyValue` | `createValueFromString(String initialData)` Create a new string type property value consistent with this type definition from the given Java string.
    `String` | `getCharacterSet()` Returns the character set that will be used for conversion between a Java string and this string type definition.
    `int` | `getCount(PropertyValue stringProperty)` Returns the length of the string contained in the given string property value, measured in the number of characters.
    `Buffer` | `getElements(PropertyValue stringProperty)` Returns the value of the given string property as a data buffer consistent with the element type of this string type definition.
    `TypeDefinition` | `getElementType()` Returns the underlying AAF type used to represent characters of a string of this string type definition.
    `PropertyValue[]` | `getPropertyValues(PropertyValue stringProperty)` Returns the value of the given string property as an array of property values of a compatible type to the string type definition, as returned by `getElementType()`.
    `String` | `getString(PropertyValue stringProperty)` Returns the value of the given string property as a Java string.
    `void` | `setCharacterSet(String charSet)` Set the character set that will be used for conversion between a Java string and this string type definition.
    `void` | `setString(PropertyValue stringProperty, Buffer data)` Set the value of the string contained in the given string property value to the given data buffer.
    `void` | `setString(PropertyValue stringProperty, String data)` Set the value of the string contained in the given string property value to the given Java string value.

    - ### Methods inherited from interface tv.amwa.maj.meta.TypeDefinition

      `createFromBytes, createValue, getPropertyValue, getTypeCategory, lengthAsBytes, resolveReferences, setPropertyValue, writeAsBytes, writeAsStructuredStorageBytes`

    - ### Methods inherited from interface tv.amwa.maj.meta.MetaDefinition

      `appendMetadictXML, deepEquals, equals, getAAFNamesInUse, getAliases, getAUID, getDescription, getName, getNamespace, getPrefix, getSymbol, hashCode, setAAFNamesInUse, setDescription, setName, setNamespace, setPrefix, setSymbol, toString`

    - ### Methods inherited from interface tv.amwa.maj.industry.WeakReferenceTarget

      `getWeakTargetReference`

- - ### Method Detail

    - #### getElementType

          TypeDefinition getElementType()

      Returns the underlying AAF type used to represent characters of a string of this string type definition.

      Returns:
        Underlying type used to represent characters of a string of this string type definition.

    - #### getCount

          @UInt32
          int getCount(PropertyValue stringProperty)
                        throws NullPointerException,
                               IllegalPropertyValueException

      Returns the length of the string contained in the given string property value, measured in the number of characters.

      Parameters:
        `stringProperty` - Property value containing a string to determine the length of.
      Returns:
        Number of characters in the given string.
      Throws:
        `NullPointerException` - The given string property value is `null`.
        `IllegalPropertyValueException` - The given string property value type does not match this string type definition.
      See Also:
        `String.length()`

    - #### createValueFromString

          PropertyValue createValueFromString(String initialData)

      Create a new string type property value consistent with this type definition from the given Java string. Conversion to the underlying character type takes place according to the character set returned by `getCharacterSet()`. Setting a `null` value will result in the return of a property value with its internal string representation set to `null`.

      Parameters:
        `initialData` - Initial string data to create a new string property value.
      Returns:
        Newly created string property value from the given Java string.
      See Also:
        `createValueFromString(Buffer)`

    - #### createValueFromString

          PropertyValue createValueFromString(Buffer initialData)
                                       throws IllegalArgumentException

      Create a new string type property value consistent with this type definition from the given data buffer. Any character set conversion required takes place using the character set returned by `getCharacterSet()`. Setting a `null` value will result in the return of a property value with its internal string representation set to `null`.

      The buffer of data must be one of the following types:

      - `ByteBuffer`
      - `ShortBuffer`
      - `IntBuffer`
      - `LongBuffer`
      - `CharBuffer`

      Any other buffer types will result in an `IllegalArgumentException`.

      Parameters:
        `initialData` - Initial string data to use to create a new string property value.
      Returns:
        Newly created string property value from the given buffer.
      Throws:
        `IllegalArgumentException` - The given buffer must be of an appropriate type for conversion to the underlying element type for this string type definition.
      See Also:
        `createValueFromString(Buffer)`

    - #### setString

          void setString(PropertyValue stringProperty,
                         String data)
                  throws NullPointerException,
                         IllegalPropertyValueException

      Set the value of the string contained in the given string property value to the given Java string value. Any character set conversion required takes place using the character set returned by `getCharacterSet()`. Setting a `null` value will result in the return of a property value with its internal string representation set to `null`.

      Parameters:
        `stringProperty` - Property value to have its string value set.
        `data` - Value to set for the string type property value, represented as a Java String.
      Throws:
        `NullPointerException` - The given string property value is `null`.
        `IllegalPropertyValueException` - The given string property type does not match this string type definition.
      See Also:
        `getString(PropertyValue)`, `setString(PropertyValue, Buffer)`

    - #### setString

          void setString(PropertyValue stringProperty,
                         Buffer data)
                  throws NullPointerException,
                         IllegalPropertyValueException,
                         IllegalArgumentException

      Set the value of the string contained in the given string property value to the given data buffer. Any character set conversion required takes place using the character set returned by `getCharacterSet()`. Setting a `null` value will result in the return of a property value with its internal string representation set to `null`.

      The buffer of data must be one of the following types:

      - `ByteBuffer`
      - `ShortBuffer`
      - `IntBuffer`
      - `LongBuffer`
      - `CharBuffer`

      Any other buffer types will result in an `IllegalArgumentException`.

      Parameters:
        `stringProperty` - Property value to have its string value set.
        `data` - Value to set for the string type property value, represented as a data buffer.
      Throws:
        `NullPointerException` - The given string property is `null`.
        `IllegalPropertyValueException` - The given string property type does not match this string type definition.
        `IllegalArgumentException` - The given buffer must be of an appropriate type for conversion to the underlying element type for this string type definition.
      See Also:
        `getElements(PropertyValue)`, `setString(PropertyValue, String)`

    - #### appendElements

          void appendElements(PropertyValue stringProperty,
                              PropertyValue[] elements)
                       throws NullPointerException,
                              BadTypeException,
                              IllegalPropertyValueException,
                              BadSizeException

      Append to the string value of the given property value using the array of property value elements. Each element of the given array must match the type definition returned by `getElementType()`.

      Parameters:
        `stringProperty` - Property value containing a string to be extended.
        `elements` - Array of property value elements to use to extend the given string.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`, or one or more of the values of the given array is `null`.
        `BadTypeException` - One or more of the elements of the given array of property values is of an incompatible type.
        `IllegalPropertyValueException` - The given string property value is not of this string type definition.
        `BadSizeException` - The number of bytes per integer of the underlying element type of this string type definition is not supported by this implementation.
      See Also:
        `appendElements(PropertyValue, Buffer)`, `appendString(PropertyValue, String)`

    - #### appendElements

          void appendElements(PropertyValue stringProperty,
                              Buffer elements)
                       throws NullPointerException,
                              IllegalArgumentException,
                              IllegalPropertyValueException

      Append to the string value of the given property value using a data buffer. Any character set conversion required takes place using the character set returned by `getCharacterSet()`. An attempt to pass in a `null` buffer will result in no change to the property value and no error.

      The buffer of data must be one of the following types:

      - `ByteBuffer`
      - `ShortBuffer`
      - `IntBuffer`
      - `LongBuffer`
      - `CharBuffer`

      Any other buffer types will result in an `IllegalArgumentException`.

      This method has the same behaviour as `appendString(PropertyValue, Buffer)`.

      Parameters:
        `stringProperty` - Property value containing a string value to append the given elements to.
        `elements` - Buffer containing values to be appended to to the given property value.
      Throws:
        `NullPointerException` - The given string property argument is `null`.
        `IllegalArgumentException` - The given buffer must be of an appropriate type for conversion to the underlying element type for this string type definition.
        `IllegalPropertyValueException` - The given string property type does not match this type definition.
      See Also:
        `appendElements(PropertyValue, PropertyValue[])`, `appendString(PropertyValue, String)`

    - #### appendString

          void appendString(PropertyValue stringProperty,
                            String extension)
                     throws NullPointerException,
                            IllegalPropertyValueException

      Appends the given Java String to the string of the given property value. Any character set conversion required takes place using the character set returned by `getCharacterSet()`. An attempt to pass a `null` string will result in no change to the property value and no error.

      Parameters:
        `stringProperty` - Property value containing the string to extend.
        `extension` - String to append to the end of the given property value.
      Throws:
        `NullPointerException` - The given string property argument is `null`.
        `IllegalPropertyValueException` - The given string property value type does not match this string type definition.
      See Also:
        `appendString(PropertyValue, Buffer)`, `appendElements(PropertyValue, PropertyValue[])`

    - #### appendString

          void appendString(PropertyValue stringProperty,
                            Buffer extension)
                     throws NullPointerException,
                            IllegalArgumentException,
                            IllegalPropertyValueException

      Appends the given data buffer to the string of the given property value. Any character set conversion required takes place using the character set returned by `getCharacterSet()`. An attempt to pass a `null` buffer will result in no change to the property value and no error.

      The buffer of data must be one of the following types:

      - `ByteBuffer`
      - `ShortBuffer`
      - `IntBuffer`
      - `LongBuffer`
      - `CharBuffer`

      Any other buffer types will result in an `IllegalArgumentException`.

      This method has the same behaviour as `appendElements(PropertyValue, Buffer)`.

      Parameters:
        `stringProperty` - Property value containing the string to extend.
        `extension` - Buffer of string data to use to extend the given property value.
      Throws:
        `NullPointerException` - The given string property value is `null`.
        `IllegalArgumentException` - The given buffer must be of an appropriate type for conversion to the underlying element type for this string type definition.
        `IllegalPropertyValueException` - The given string property value type does not match this string type definition.
      See Also:
        `appendElements(PropertyValue, PropertyValue[])`, `appendString(PropertyValue, String)`

    - #### getElements

          Buffer getElements(PropertyValue stringProperty)
                      throws NullPointerException,
                             IllegalPropertyValueException,
                             BadSizeException

      Returns the value of the given string property as a data buffer consistent with the element type of this string type definition. Any character set conversion required takes place using the character set returned by `getCharacterSet()`. If the internal representation of the string property value is `null` then this method will return `null`.

      Note that a `null` character will not be inserted as the last byte of the buffer.

      Parameters:
        `stringProperty` - Property value containing the string to convert.
      Returns:
        Data buffer representation of the given value.
      Throws:
        `NullPointerException` - The given string property value is `null`.
        `IllegalPropertyValueException` - The given string property type does not match this string property value.
        `BadSizeException` - The number of bytes per integer of the underlying element type of this string type definition is not supported by this implementation.
      See Also:
        `setString(PropertyValue, Buffer)`, `getString(PropertyValue)`

    - #### getPropertyValues

          PropertyValue[] getPropertyValues(PropertyValue stringProperty)
                                     throws NullPointerException,
                                            IllegalPropertyValueException,
                                            BadSizeException

      Returns the value of the given string property as an array of property values of a compatible type to the string type definition, as returned by `getElementType()`.

      Parameters:
        `stringProperty` - Property value containing the string to convert.
      Returns:
        Java String representation of the given value.
      Throws:
        `NullPointerException` - The given string property value is `null`.
        `IllegalPropertyValueException` - The type of the given string property value does not match this string type definition.
        `BadSizeException` - The number of bytes per integer of the underlying element type of this string type definition is not supported by this implementation.
      See Also:
        `appendElements(PropertyValue, PropertyValue[])`

    - #### getString

          String getString(PropertyValue stringProperty)
                    throws NullPointerException,
                           IllegalPropertyValueException

      Returns the value of the given string property as a Java string.

      Parameters:
        `stringProperty` - Property value containing the string to convert.
      Returns:
        Java String representation of the given value, which could be a `null` string.
      Throws:
        `NullPointerException` - The given string property value is `null`.
        `IllegalPropertyValueException` - The given string property is not of this string type definition.

    - #### getCharacterSet

          String getCharacterSet()

      Returns the character set that will be used for conversion between a Java string and this string type definition. If a character set has not been provided by a user then the value returned will be the default Java character set of "`UTF-16`".

      Returns:
        Character set used for conversion between this string type and Java strings.
      See Also:
        `Charset`

    - #### setCharacterSet

          void setCharacterSet(String charSet)
                        throws NullPointerException,
                               UnsupportedCharsetException

      Set the character set that will be used for conversion between a Java string and this string type definition. For information on valid character set names, see the relevant Java API documentation.

      Parameters:
        `charSet` - Character set used for conversion between this string type and Java strings.
      Throws:
        `NullPointerException` - The given character set name is `null`.
        `UnsupportedCharsetException` - The named character set is not supported in the underlying implementation of Java.
      See Also:
        `Charset`

    - #### clone

          TypeDefinitionString clone()

      Create a cloned copy of this string type definition.

      Specified by:
        `clone` in interface `MetaDefinition`
      Specified by:
        `clone` in interface `TypeDefinition`
      Returns:
        Cloned copy of this string type definition.

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.