|
Media Authoring with Java API |
|||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
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. |
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.
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);
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:
DisplayWidth
on class DigitalImageDescriptor
with type UInt32
;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.
TypeDefinitionInteger
|
Media Authoring with Java API |
|||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |