Media Authoring
with Java API

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
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 typeJava type
Int8byte
Int16short
Int32int
Int64long
UInt8byte
UInt16short
UInt32int
UInt64long

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:

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.

Author:
Richard Cartwright
See Also:
TypeDefinitionInteger

Media Authoring
with Java API

(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.