Package tv.amwa.maj.constant

Defines constant values used throughout the MAJ API and defined by external specifications.

See:
Description

Interface Summary

CodecConstant	Implement this interface to access unique identifiers for codecs, such as WAVE or JPEG.
CodecFlavour	Implement this interface to access unique identifiers for flavours of codec.
CodingEquationsType	Implement this interface to access unique identifiers for coding equations used to convert RGB image components to component color difference image components.
ColorPrimariesType	Implement this interface to access unique identifiers for the color primaries used in the representation of images.
CommonConstants	Implement this interface to access constant values used across the MAJ API.
ContainerConstant	Implement this interface to access unique identifiers for mechanisms used to store essence in files.
DataDefinitionConstant	Implement this interface to access unique identifiers for data definitions that specify the kind of data that can be stored in a component.
InterpolationConstant	Implement this interface to access unique identifiers for the definition of an interpolation function, which specifies the mechanism used to calculate the values produced by a varying value.
OperationalPatternConstant	Implement this interface to access unique identifiers for operational patterns or AAF protocols, such as as the AAF edit protocol.
OperationCategoryType	Implement this interface to access unique identifiers for categories of operations.
OperationConstant	Implement this interface to access unique identifiers for operations, such as the video and audio effects defined by the AAF edit protocol.
ParameterConstant	Implement this interface to access unique identifiers for parameters to operations, such as the video and audio effects defined by the AAF edit protocol.
PluginCategoryType	Implement this interface to access unique identifiers describing the categories of plugin definitions.
PluginIdentifiers	Implement this interface to access some standard constants used to define plugins.
PropertyDefinitions	Implement this interface to access unique identifiers for property definitions not available elsewhere in the MAJ API through the AAFProperty annotation.
TransferCharacteristicType	Implement this interface to access unique identifiers for kinds of opto-electronic transfer characteristics.
UsageType	Implement this interface to access unique identifiers describing the way that a mob is used.

Annotation Types Summary

CodecDescription	Labels an AUID that is a unique identifier for a codec.
ContainerDescription	Labels an AUID that is a unique identifier for a kind of essence container.
DataDefinitionDescription	Labels an AUID that is a unique identifier for a data definition that specifies the kind of data that can be stored in a component.
InterpolationDescription	Labels an AUID that is a unique identifier for a kind of interpolation function that specifies the mechanism used to calculate the values produced by a varying value.
OperationalPatternDescription	Labels an AUID that is a unqiue identifier for an operational pattern.
OperationDescription	Labels an AUID that is a unique identifier for an operation.
ParameterDescription	Labels an AUID that is a unique identifier for a parameter to an operation.

Package tv.amwa.maj.constant Description

Defines constant values used throughout the MAJ API and defined by external specifications. Typically, these are unique identifiers defined by an AUID that fall into two categories:

1. Unique identifiers for defined objects that can appear in the AAF dictionary. These definitions are annotated and managed as described below.
2. Unique identifiers used as enumeration items in extendible enumerations.

The constants are all implemented within interfaces in useful groupings. For example, all the constants uniquely identifying container types are public final static fields within the ContainerConstant interface. To make these constants available within a class, simply implement the interface. None of the interfaces in this package have methods so no requirement is placed on the implementor to write implementations for additional methods.

Heritage

Due to package and interface names providing a scope for constant names in Java, the preceding scope part of a definition's name in the MAJ API has been removed from the equivalent C name. For example, the codec definition identified as "CodecDef_JPEG" in the C-based AAF SDK (file "CodecDefs.h") is represented in the MAJ API by "CodecConstant.JPEG". However, forName() methods of the various definition classes will accept both the MAJ API name and the C name.

Managing definitions dynamically

Every AAF file contains a dictionary holding a number of definitions for items used to specify instances of AAF classes. A number of definitions are specified by the SMPTE registries, other SMPTE specifications and more proprietary definitions. The interfaces of this package contain many of the specified or soon to be specified definitions. This section describes how the specified definitions can be turned into definition object instances and how extension definitions can be specified in the same way.

From this point onwards, codec definitions will be discussed as an example. However, everything said here about codec definitions applies equally to other kinds of definition objects. The table below shows the relationship between: the interface describing a classification of definition type; the interface containing unique identifiers for that class of definition; the annotation that provides additional metadata that is used to instantiate a definition.

definition interface	unique identifiers	metadata annotation
CodecDefinition	CodecConstant	CodecDescription
ContainerDefinition	ContainerConstant	ContainerDescription
DataDefinition	DataDefinitionConstant	DataDefinitionDescription
InterpolationDefinition	InterpolationConstant	InterpolationDescription
OperationDefinition	OperationConstant	OperationDescription
ParameterDefinition	ParameterConstant	ParameterDescription

Creating definition instances

Definition instances can be created using Java constructors in the normal way, or through the AAFFactory. For example:

    CodecDefinition JPEG = new CodecDefinition(
        CodecConstant.JPEG,
        "JPEG",
        ClassDefinition.forName("CDCIDescriptor"),
        pictureDataDefs);

or

    CodecDefinition JPEG = aafFactory.makeCodecDefinition(
        CodecConstant.JPEG,
        "JPEG",
        ClassDefinition.forName("CDCIDescriptor"),
        pictureDataDefs);

Registering a definition instance

With each definition implementation, static methods are provided to lookup definitions by name or identification, such as CodecDefinition.forName(String). To register a definition with the static lookup table defined in for each definition type, use the registerXDefinition() method, replacing X with the name of the definition kind. For example, to register the codec definition in the previous example:

    CodecDefinition.registerCodecDefinition(JPEG);

The registration takes place at runtime so that the range of definitions supported can be dynamically extended. Note that such a registration remains local within a virtual machine.

Registering a group of definition instances

All of the unique identifiers of this package related to definitions are annotated with additional metadata so that they can be used to instaciate definitions. For example, the JPEG codec is defined with a codec description annotation as follows:

    @CodecDescription(fileDescriptorClass = "CDCIDescriptor",
        dataDefinitions = { "DataDef_Picture", "DataDef_LegacyPicture" },
        description = "Supports a constrained form of ISO/IEC 10918-1 JPEG images ...")
    public final static AUID JPEG = new tv.amwa.maj.embeddable.AUID(
            0x18634f8c, (short) 0x3bab, (short) 0x11d3, 
            new byte[] { (byte) 0xbf, (byte) 0xd6, 0x00, 0x10, 0x4b, (byte) 0xc9, 0x15, 0x6d} );

The annotation has all the additional parameters required to construct a codec definition over and above just its name and unique identifier. To avoid duplication, the name and identifier are not repeated in the annotation

To register all the annotated constants defined in any interface or class, the Java class of an interface containing such annotated constants is passed to the registerXFromClass() method of a definitions implementation, replacing X with the name of the definition kind. For example, to register all of the codec definitions with unique identifiers in CodecDefinition:

    CodecDefinition.registerCodecsFromClass(CodecConstant.class);

In fact, any class containing an AUID constant annotated with a definition description can be passed to the appropriate registration method. The registration method looks through the class for the relevant annotations and registers any constants that it finds. There should never be a need to use the exact line above as it is executed automatically when the codec definition implementation class is loaded. This registration process is provided to enable dynamic runtime extension of the supported range of definitions.

Extending the range of definitions

The range of supported definitions can be extended beyond those provided as part of the MAJ API. To do this:

1. Create an interface (or class) containing public static final fields of AUID values, with the name of the Java static field being the same as the name of the required definition. Take care to define an AUID so that it does not conflict with an existing SMPTE UL or UUID scheme used on your systems.
2. Annotate the fields with the appropriate description, such as CodecDescription. Some elements of the annotation are required and so values must be provided.
3. Compile the interface (or class) and make sure it is available in the same classpath as the MAJ API.
4. Register all of the definitions in your interface (or class) by calling the appropriate registerXFromClass() methods. For example:
   

       CodecDefinition.registerCodecsFromClass(my_package.MyCodecs.class);
    

New definitions can be registered dynamically at runtime. Once registered, the definition can be looked up using the appropriate "forName()" or "forIdentification()" methods of the definition types implementing class. For example:

    CodecDefinition myCodec = tv.amwa.maj.entity.CodecDefinition.forName("MyOwnCodec");

Note that registering a definition within a Java local machine has no direct impact on the creation or management of dictionaries. The calls of the MAJ API described here are provided to help with dictionary management and to ensure consistent representation of definitions across dictionaries. The way that a dictionary is managed and interpreted is an application-specific issue.

Author:

Richard Cartwright