tv.amwa.maj.integer (Media Authoring with Java API)
Date: 2016-02-05

# Package tv.amwa.maj.integer

Provides annotations to label that a value of a Java primitive type in the current context should be interpreted as a particular AAF integer data type.

See: Description

- Annotation Types Summary
  Annotation Type | Description
  --- | ---
  Int16 | Labels a 16-bit 2's complement signed integer value.
  Int16Array | Labels an array of 16-bit 2's complement signed integer values.
  Int32 | Labels a 32-bit 2's complement integer value.
  Int32Array | Labels an array of 32-bit 2's complement signed integer values.
  Int64 | Labels a 64-bit 2's complement integer value.
  Int64Array | Labels an array of 64-bit 2's complement signed integer values.
  Int8 | Labels an 8-bit 2's complement integer value.
  Int8Array | Labels an array of 8-bit 2's complement signed integer values.
  UInt16 | Labels an unsigned 16-bit integer value.
  UInt16Array | Labels an array of 16-bit unsigned integer values.
  UInt32 | Labels an unsigned 32-bit integer value.
  UInt32Array | Labels an array of 32-bit unsigned integer values.
  UInt32Set | Labels a set containing 8-bit 2's complement integer values.
  UInt64 | Labels an unsigned 64-bit integer value.
  UInt64Array | Labels an array of 64-bit unsigned integer values.
  UInt8 | Labels an unsigned 8-bit integer value.
  UInt8Array | Labels an array of 8-bit unsigned integer values.

## Package tv.amwa.maj.integer Description

Provides annotations to label that a value of a Java primitive type in the current context should be interpreted as a particular AAF integer data type. These annotations are provided to guide a developer as to the interpretation they should make of an AAF integer-type property. In particular, Java does not have unsigned integer data types and the AAF does. From this additional information, a developer may decide to add additional validation to prevent non-negative numbers from being stored in a signed value or to use bitwise operators for arithmetic operations.

## Integer annotation usage

To indicate that a method returns a value of AAF data type `UInt32`, the Java `int` keyword is annotated with `@UInt32`. For example:

        public @UInt32 int countPropertyDefinitions();

To indicate that a method expects a value of AAF data type `UInt8` as a parameter, the Java `byte` keyword is annotated with `@UInt8`. The following example shows how the annotation can also be applied to arrays:

        public void setUniversalLabel(@UInt8 byte[] label);

## AAF integer types in Java

In general, AAF primitive data types map well onto the Java primitive types. This is also the case for signed integer data types, such as `Int16` or `Int32`. However, as Java does not have the concept of an unsigned integer data type, issues may arise when mapping AAF unsigned integer types, such as `UInt8` or `UInt32`, onto equivalent Java types.

Without the annotations of this package, it would not be possible to discover the AAF data type of a value from its Java equivalent. This is illustrated in the following table that shows the mappings from AAF integer data types to Java types:

AAF type | Java type
`Int8` | `byte`
`Int16` | `short`
`Int32` | `int`
`Int64` | `long`
`UInt8` | `byte`
`UInt16` | `short`
`UInt32` | `int`
`UInt64` | `long`

All Java versions of AAF types use the same number of bits in their representation as specified for the AAF type. This provides an efficient on-disk and in memory representation of AAF values in Java applications based on this API. However, this efficiency comes at the cost of ambiguity arising from possible interpretations of the AAF unsigned integer data types. The choice to use an unsigned value for an AAF property may have been made to:

- indicate that a value should be non-negative, e.g. property `DisplayWidth` on class `DigitalImageDescriptor` with type `UInt32`;
- represent a bit field, such as the `data1` part of the `AUID` structure.

Wherever possible, the annotations provided in this package are used to indicate what the interpretation of a Java value as an AAF value should be. In the case of unsigned values, a developer should be aware that different interpretations of the signed bit may be important. In the `DisplayWidth` example given above, if a value of 232 provides enough head room for a scalar value then a value of 231, the Java maximum integer value, is also likely to be fine. However, if a particular application uses 232 as an AAF-legal application-specific flag, then this value may cause problems in the Java domain if left unchecked.

For bit fields, Java is capable of representing AAF values bit-for-bit and has bitwise operators that treat the sign bit of a 2's complement number as if it has no special significance (using right-shift '`>>>`'). Also, for any Java integer type, casting an unsigned value for a value larger than Java's maximum value preserves its bit pattern. For example, `UInt8` value `254` is represented by bit pattern `11111110`. The Java casting expression `(byte) 254` casts unsigned value `254` to `-2` as a signed Java byte, with corresponding bit pattern `11111110`. As long as care is taken over the use of bitwise operators, it is possible to store AAF unsigned integers for bit fields or byte sequences as Java primitive types.

It would be useful for future versions of the AAF specification to include an indication of the reason for using an unsigned data type for a particular property. This could take the form of informative notes in the specification or be more explicitly specified as facets as defined in the XML Schema Datatypes specification.

See Also:
  `TypeDefinitionInteger`

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