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

tv.amwa.maj.meta

## Interface TypeDefinitionInteger

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

      public interface TypeDefinitionInteger
      extends TypeDefinition

  Specifies the definition of a property type that is an integer with the specified number of bytes.

  The representation of integers in the MAJ API is explained in the description of the integer package. The methods of this class cast values of subclasses of `Number` to values of Java type used to represent an integer value, as described in the type mapping table. The methods here are specified in such a way that rounding or truncations errors should be avoidable

  See Also:
    `TypeCategory.Int`, `Int32`, `UInt8`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BYTE` Number of bytes used to represent a Java `byte` value.
    `static int` | `INT` Number of bytes used to represent a Java `int` value.
    `static int` | `LONG` Number of bytes used to represent a Java `long` value.
    `static int` | `SHORT` Number of bytes used to represent a Java `short` value.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `TypeDefinitionInteger` | `clone()` Create a cloned copy of this integer type definition.
    `PropertyValue` | `createValueFromNumber(Number value)` Creates a property value as defined by this integer type definition using the given number.
    `Number` | `getInteger(PropertyValue integerProperty)` Returns the value of the given integer property value as a `Number`.
    `byte` | `getSize()` Returns the size of integral value of the integer type definition, measured in number of bytes.
    `boolean` | `isSigned()` Returns `true` if the integer type definition defines signed integer values; otherwise `false`.
    `void` | `setInteger(PropertyValue integerProperty, Number value)` Convert the given number value to one appropriate for this integer type definition and set the value of the given integer property value to be the converted 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`

- - ### Field Detail

    - #### BYTE

          static final int BYTE

      Number of bytes used to represent a Java `byte` value.

      See Also:
        Constant Field Values

    - #### SHORT

          static final int SHORT

      Number of bytes used to represent a Java `short` value.

      See Also:
        Constant Field Values

    - #### INT

          static final int INT

      Number of bytes used to represent a Java `int` value.

      See Also:
        Constant Field Values

    - #### LONG

          static final int LONG

      Number of bytes used to represent a Java `long` value.

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### createValueFromNumber

          PropertyValue createValueFromNumber(Number value)
                                       throws NullPointerException,
                                              BadSizeException,
                                              IllegalArgumentException

      Creates a property value as defined by this integer type definition using the given number. The given number will he cast to a value that fits with this integer type definition.

      It is possible that the given Java value cannot be converted to a value compatible with this integer type definition. If this is the case, an `IllegalArgumentException` is thrown. Conversion may not be possible for the following reasons:

      - The given value is a `float`, `double` or `BigDecimal` that includes decimal part to its value that would require rounding as part of the conversion.
      - The given value uses more bytes to represent an integer value than the integer type definition, as returned by `getSize()`. Conversion will require truncation of the value.
      - The given value is negative and the integer type definition is not signed.

      To specifically cause truncation or rounding to take place, perform an appropriate cast before calling this method.

      A `BadSizeException` may also be thrown if the given value is a `BigInteger` or `BigDecimal` value as an implementation is not required to support values greater than 8-bytes in length.

      Parameters:
        `value` - Value to create a new integer property value from.
      Returns:
        New integer property value consistent with this integer type definition and set to the given value.
      Throws:
        `NullPointerException` - The given number value is `null`.
        `IllegalArgumentException` - Due to its value, the given value cannot be converted to a property value defined by this integer type definition.
        `BadSizeException`
      See Also:
        `setInteger(PropertyValue, Number)`

    - #### getInteger

          Number getInteger(PropertyValue integerProperty)
                     throws NullPointerException,
                            IllegalPropertyValueException

      Returns the value of the given integer property value as a `Number`. This value can then be converted to the required type by calling `Number.intValue()`, `Number.byteValue()` etc..

      Parameters:
        `integerProperty` - Property value of integer type.
      Returns:
        Integer value represented by an appropriate wrapper type from the `java.lang` package, e.g. `Byte`, `Integer` etc..
      Throws:
        `NullPointerException` - The given integer property value is `null`.
        `IllegalPropertyValueException` - The given integer property value is not as defined by this integer type definition.

    - #### setInteger

          void setInteger(PropertyValue integerProperty,
                          Number value)
                   throws NullPointerException,
                          BadSizeException,
                          IllegalPropertyValueException,
                          IllegalArgumentException

      Convert the given number value to one appropriate for this integer type definition and set the value of the given integer property value to be the converted value. This method can make use of Java's autoboxing features.

      It is possible that the given Java value cannot be converted to a value compatible with the integer type definition. If this is the case, an `IllegalArgumentException` is thrown. Conversion may not be possible for the following reasons:

      - The given value is a `float`, `double` or `BigDecimal` that includes decimal part to its value that would require rounding as part of the conversion.
      - The given value uses more bytes to represent an integer value than the integer type definition, as returned by `getSize()`. Conversion will require truncation of the value.
      - The given value is negative and the integer type definition is not signed.

      To specifically cause truncation or rounding to take place, perform an appropriate cast before calling this method.

      Parameters:
        `integerProperty` - Property value to set the value of.
        `value` - Value to set for the given integer property value to.
      Throws:
        `NullPointerException` - One or both of the integer property value and/or number value arguments is/are `null`.
        `IllegalPropertyValueException` - The given property value is not compatible with this integer type definition.
        `IllegalArgumentException` - Due to its value, the given value cannot be converted to a property value defined by the integer type definition.
        `BadSizeException`
      See Also:
        `createValueFromNumber(Number)`

    - #### getSize

          @UInt8
          byte getSize()

      Returns the size of integral value of the integer type definition, measured in number of bytes.

      Returns:
        Size of integral value of the integer type definition, measured in number of bytes.

    - #### isSigned

          @Bool
          boolean isSigned()

      Returns `true` if the integer type definition defines signed integer values; otherwise `false`.

      Returns:
        Does the integer type definition define signed integer values?

    - #### clone

          TypeDefinitionInteger clone()

      Create a cloned copy of this integer type definition.

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

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