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

tv.amwa.maj.meta.impl

## Class TypeDefinitionIntegerImpl

- java.lang.Object
- - tv.amwa.maj.meta.impl.MetaDefinitionImpl
  - - tv.amwa.maj.meta.impl.TypeDefinitionImpl
    - - tv.amwa.maj.meta.impl.SingletonTypeDefinitionImpl
      - - tv.amwa.maj.meta.impl.TypeDefinitionIntegerImpl

- All Implemented Interfaces:
    Serializable, Cloneable, CommonConstants, MetadataObject, WeakReferenceTarget, MetaDefinition, TypeDefinition, TypeDefinitionInteger, DefinitionType

      @MediaClass(uuid1=218169601,
                  uuid2=516,
                  uuid3=0,
                  uuid4={6,14,43,52,2,6,1,1},
                  definedName="TypeDefinitionInteger",
                  description="The TypeDefinitionInteger class defines a property type that is an integer with the specified number of bytes.",
                  symbol="TypeDefinitionInteger")
      public final class TypeDefinitionIntegerImpl
      extends SingletonTypeDefinitionImpl
      implements TypeDefinitionInteger, Serializable, CommonConstants, Cloneable

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

  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TypeDefinitionIntegerImpl.BaseIntegerValue`
    `static class` | `TypeDefinitionIntegerImpl.ByteValue`
    `static class` | `TypeDefinitionIntegerImpl.IntegerValue`
    `static class` | `TypeDefinitionIntegerImpl.LongValue`
    `static class` | `TypeDefinitionIntegerImpl.ShortValue`

    - ### Nested classes/interfaces inherited from class tv.amwa.maj.meta.impl.SingletonTypeDefinitionImpl

      `SingletonTypeDefinitionImpl.SingletonMethodBag`

    - ### Nested classes/interfaces inherited from class tv.amwa.maj.meta.impl.TypeDefinitionImpl

      `TypeDefinitionImpl.PropertyValueImpl`

  - ### Field Summary

    - ### Fields inherited from interface tv.amwa.maj.meta.TypeDefinitionInteger

      `BYTE, INT, LONG, SHORT`

    - ### Fields inherited from interface tv.amwa.maj.constant.CommonConstants

      `AAF_METADICT_NAMESPACE, AAF_METADICT_PREFIX, AAF_XML_NAMESPACE, AAF_XML_PREFIX, ApplicationPluginObjectID, ApplicationPluginsID, MAX_NUM_RGBA_COMPS, MemberOfID, ObjectClassID, ParentClassID, PropertiesID, XMLClassIDAsAttributeName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TypeDefinitionIntegerImpl(AUID identification, String typeName, byte intSize, boolean isSigned)` Creates and initializes the integer type definition, which defines a property type that is a signed or an unsigned integer with the specified number of bytes.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendMetadictXML(Node metadict, String namespace, String prefix)` Append an XML representation of this meta definition to the given XML node.
    `TypeDefinitionInteger` | `clone()` Create a cloned copy of this meta definition.
    `PropertyValue` | `createFromBytes(ByteBuffer buffer)` Create a value of this type by reading the bytes in the given byte buffer.
    `PropertyValue` | `createValue(Object javaValue)` Create a property value from the given Java object.
    `PropertyValue` | `createValueFromNumber(Number value)` Creates a property value as defined by this integer type definition using the given number.
    `boolean` | `deepEquals(Object o)` Determines whether this definition is equal to the given object by comparing each property.
    `Number` | `getInteger(PropertyValue integerProperty)` Returns the value of the given integer property value as a `Number`.
    `boolean` | `getIsSigned()`
    `byte` | `getSize()` Returns the size of integral value of the integer type definition, measured in number of bytes.
    `TypeCategory` | `getTypeCategory()` Returns the type category to which this type definition belongs, which corresponds to its sub interface.
    `static boolean` | `initializeIsSigned()`
    `static byte` | `initializeSize()`
    `boolean` | `isSigned()` Returns `true` if the integer type definition defines signed integer values; otherwise `false`.
    `long` | `lengthAsBytes(PropertyValue value)` Returns the number of bytes that the given value of this type is serialized as a sequence of bytes.
    `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.
    `void` | `setIsSigned(boolean isSigned)`
    `void` | `setSize(byte intSize)`
    `List<PropertyValue>` | `writeAsBytes(PropertyValue value, ByteBuffer buffer)` Write the given property value of this type to the given byte stream.

    - ### Methods inherited from class tv.amwa.maj.meta.impl.SingletonTypeDefinitionImpl

      `setPropertyValue`

    - ### Methods inherited from class tv.amwa.maj.meta.impl.TypeDefinitionImpl

      `getNamespace, getPrefix, getPropertyValue, initalizeTypeNameMap, nameToAAFName, resolveReferences, writeAsStructuredStorageBytes`

    - ### Methods inherited from class tv.amwa.maj.meta.impl.MetaDefinitionImpl

      `aafNameToName, appendXMLChildren, equals, getAAFNamesInUse, getAliases, getAUID, getComment, getDescription, getIdentification, getName, getSymbol, getWeakTargetReference, hashCode, initializeMetaDefinitionIdentification, initializeMetaDefinitionName, setAAFNamesInUse, setAliases, setDescription, setIdentification, setName, setNamespace, setPrefix, setSymbol, toString`

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

      `getClass, notify, notifyAll, wait, wait, wait`

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

      `getPropertyValue, resolveReferences, setPropertyValue, writeAsStructuredStorageBytes`

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

      `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`

- - ### Constructor Detail

    - #### TypeDefinitionIntegerImpl

          public TypeDefinitionIntegerImpl(AUID identification,
                                           @AAFString
                                           String typeName,
                                           @UInt8
                                           byte intSize,
                                           @Bool
                                           boolean isSigned)
                                    throws NullPointerException,
                                           IllegalArgumentException

      Creates and initializes the integer type definition, which defines a property type that is a signed or an unsigned integer with the specified number of bytes.

      The implementation of this method may only allow certain values for the `intSize`. It will allow at least 1, 2, 4, and 8-byte integers; some implementations may allow more than that.

      Creating new and unregistered type definitions is not recommended as this may cause interoperability issues with other systems. The official registry of type definitions is available from SMPTE at SMPTE Metadata Registries And Related Items. The full range of data types documented in the AAF 1.1 object specification can be accessed by name and identification using either `Warehouse.lookForType(String)` or `Warehouse.lookForType(tv.amwa.maj.record.AUID)` respectively.

      Parameters:
        `identification` - AUID to use to identify this type.
        `typeName` - Friendly name for the integer type definition.
        `intSize` - Number of bytes used to represent a value.
        `isSigned` - Is the integer type signed?
      Throws:
        `NullPointerException` - The identification argument is `null`.
        `IllegalArgumentException` - The implementation does not support the given number of bytes per integer value.

  - ### Method Detail

    - #### createValueFromNumber

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

      Description copied from interface: `TypeDefinitionInteger`

      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 `TypeDefinitionInteger.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.

      Specified by:
        `createValueFromNumber` in interface `TypeDefinitionInteger`
      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:
        `TypeDefinitionInteger.setInteger(PropertyValue, Number)`

    - #### getInteger

          public Number getInteger(PropertyValue integerProperty)
                            throws NullPointerException,
                                   IllegalPropertyValueException

      Description copied from interface: `TypeDefinitionInteger`

      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..

      Specified by:
        `getInteger` in interface `TypeDefinitionInteger`
      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.

    - #### getSize

          @MediaProperty(uuid1=50397699,
                         uuid2=256,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,2},
                         definedName="Size",
                         typeName="UInt8",
                         optional=false,
                         uniqueIdentifier=false,
                         pid=15,
                         symbol="Size")
          public byte getSize()

      Description copied from interface: `TypeDefinitionInteger`

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

      Specified by:
        `getSize` in interface `TypeDefinitionInteger`
      Returns:
        Size of integral value of the integer type definition, measured in number of bytes.

    - #### setSize

          @MediaPropertySetter(value="Size")
          public void setSize(byte intSize)
                                                          throws IllegalArgumentException

      Throws:
        `IllegalArgumentException`

    - #### initializeSize

          public static final byte initializeSize()

    - #### isSigned

          public boolean isSigned()

      Description copied from interface: `TypeDefinitionInteger`

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

      Specified by:
        `isSigned` in interface `TypeDefinitionInteger`
      Returns:
        Does the integer type definition define signed integer values?

    - #### getIsSigned

          @MediaProperty(uuid1=50397699,
                         uuid2=512,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,2},
                         definedName="IsSigned",
                         typeName="Boolean",
                         optional=false,
                         uniqueIdentifier=false,
                         pid=16,
                         symbol="IsSigned")
          public boolean getIsSigned()

    - #### setIsSigned

          @MediaPropertySetter(value="IsSigned")
          public void setIsSigned(boolean isSigned)

    - #### initializeIsSigned

          public static final boolean initializeIsSigned()

    - #### setInteger

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

      Description copied from interface: `TypeDefinitionInteger`

      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 `TypeDefinitionInteger.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.

      Specified by:
        `setInteger` in interface `TypeDefinitionInteger`
      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:
        `TypeDefinitionInteger.createValueFromNumber(Number)`

    - #### getTypeCategory

          public TypeCategory getTypeCategory()

      Description copied from interface: `TypeDefinition`

      Returns the type category to which this type definition belongs, which corresponds to its sub interface. For example, TypeCategory.Int is returned for a `TypeDefinitionInteger`.

      Specified by:
        `getTypeCategory` in interface `TypeDefinition`
      Specified by:
        `getTypeCategory` in class `TypeDefinitionImpl`
      Returns:
        Type category to which the type definition belongs.
      See Also:
        `TypeCategory`

    - #### createValue

          public PropertyValue createValue(Object javaValue)
                                    throws ClassCastException

      Description copied from class: `TypeDefinitionImpl`

      Create a property value from the given Java object. If the type of the object is not compatible with this type definition, a `ClassCastException` is thrown.

      Specified by:
        `createValue` in interface `TypeDefinition`
      Specified by:
        `createValue` in class `TypeDefinitionImpl`
      Parameters:
        `javaValue` - Java object to use to create a property value of this type.
      Returns:
        Property value representing the given value.
      Throws:
        `ClassCastException` - The given object cannot be cast to a property value with this type definition.

    - #### deepEquals

          public final boolean deepEquals(Object o)

      Description copied from interface: `MetaDefinition`

      Determines whether this definition is equal to the given object by comparing each property. The `MetaDefinition.equals(Object)` method only checks that the identities of two definitions are equal, relying on the uniqueness ensured by identity registration. This method is provided for debugging and validation purposes.

      Specified by:
        `deepEquals` in interface `MetaDefinition`
      Overrides:
        `deepEquals` in class `MetaDefinitionImpl`
      Parameters:
        `o` - Object to compare to this meta definition.
      Returns:
        Is the given object a meta definition with all of its properties equal to this meta definition?
      See Also:
        `MetaDefinition.equals(Object)`

    - #### createFromBytes

          public PropertyValue createFromBytes(ByteBuffer buffer)
                                        throws NullPointerException,
                                               EndOfDataException

      Description copied from interface: `TypeDefinition`

      Create a value of this type by reading the bytes in the given byte buffer. The buffer is assumed to have exactly the number of bytes that represent the value. For example, the length of a string value will be determined by the length (remaining bytes) in the buffer and not by reading a length value from the buffer.

      This method is able to read values written by the `TypeDefinition.writeAsBytes(PropertyValue, ByteBuffer)` method.

      Specified by:
        `createFromBytes` in interface `TypeDefinition`
      Overrides:
        `createFromBytes` in class `TypeDefinitionImpl`
      Parameters:
        `buffer` - Buffer to create a value from.
      Returns:
        Value of this type created from the given byte array.
      Throws:
        `NullPointerException` - Cannot read values from a `null` buffer.
        `EndOfDataException` - Insufficient bytes remaining in the given buffer to create a value of this type.
      See Also:
        `TypeDefinition.writeAsBytes(PropertyValue, ByteBuffer)`, `TypeDefinition.lengthAsBytes(PropertyValue)`

    - #### writeAsBytes

          public List<PropertyValue> writeAsBytes(PropertyValue value,
                                                  ByteBuffer buffer)
                                           throws NullPointerException,
                                                  IllegalPropertyValueException,
                                                  InsufficientSpaceException

      Description copied from interface: `TypeDefinition`

      Write the given property value of this type to the given byte stream. This version is most appropriate for writing KLV streams (MXF files).

      The format used to serialize the value with be compatible with the `TypeDefinition.createFromBytes(ByteBuffer)` method. The number of bytes written to the byte buffer will be the same as returned by `TypeDefinition.lengthAsBytes(PropertyValue)`.

      Specified by:
        `writeAsBytes` in interface `TypeDefinition`
      Overrides:
        `writeAsBytes` in class `TypeDefinitionImpl`
      Parameters:
        `value` - Value to write to the given buffer.
        `buffer` - Buffer to write the value to.
      Returns:
        List of any strongly referenced property values referenced from the new structure of bytes. Elements of this list will require separate serialization to the stream if the reference if to be resolved.
      Throws:
        `NullPointerException` - Cannot write from a `null` property value and/or to a `null` value.
        `IllegalPropertyValueException` - The given property value is not of this type.
        `InsufficientSpaceException` - Insufficient space to write the given value into the given buffer.
      See Also:
        `TypeDefinition.writeAsStructuredStorageBytes(PropertyValue, ByteBuffer)`, `TypeDefinition.createFromBytes(ByteBuffer)`, `TypeDefinition.lengthAsBytes(PropertyValue)`

    - #### lengthAsBytes

          public long lengthAsBytes(PropertyValue value)
                             throws NullPointerException,
                                    IllegalPropertyValueException

      Description copied from interface: `TypeDefinition`

      Returns the number of bytes that the given value of this type is serialized as a sequence of bytes.

      The number returned by this method is the same as the number of bytes written to a byte buffer by the `TypeDefinition.writeAsBytes(PropertyValue, ByteBuffer)` method.

      Specified by:
        `lengthAsBytes` in interface `TypeDefinition`
      Overrides:
        `lengthAsBytes` in class `TypeDefinitionImpl`
      Parameters:
        `value` - Value to find the length of when serialized to bytes.
      Returns:
        Number of bytes used to represent the given value when serialized.
      Throws:
        `NullPointerException` - Cannot compute the serialized length of a `null` value.
        `IllegalPropertyValueException` - The given property value is not of this type.
      See Also:
        `TypeDefinition.writeAsBytes(PropertyValue, ByteBuffer)`, `TypeDefinition.createFromBytes(ByteBuffer)`

    - #### appendMetadictXML

          public void appendMetadictXML(Node metadict,
                                        String namespace,
                                        String prefix)

      Description copied from interface: `MetaDefinition`

      Append an XML representation of this meta definition to the given XML node.

      Specified by:
        `appendMetadictXML` in interface `MetaDefinition`
      Overrides:
        `appendMetadictXML` in class `MetaDefinitionImpl`
      Parameters:
        `metadict` - Meta dictionary node to append a description of this node to.
      See Also:
        `CommonConstants.AAF_METADICT_NAMESPACE`

    - #### clone

          public TypeDefinitionInteger clone()

      Description copied from interface: `MetaDefinition`

      Create a cloned copy of this meta definition.

      Specified by:
        `clone` in interface `MetaDefinition`
      Specified by:
        `clone` in interface `TypeDefinition`
      Specified by:
        `clone` in interface `TypeDefinitionInteger`
      Overrides:
        `clone` in class `TypeDefinitionImpl`
      Returns:
        Cloned copy of this meta definition.

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