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

# Package tv.amwa.maj.union

Provides interfaces to a union type representing values which may contain one of many different sub-types.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  DefaultFade | Specifies the optional default audio fade properties of a composition package, which are either all present or all omitted.
  DefinitionCriteria | Specifies a criteria for matching a definition as determined by class, kind, name etc..
  DefinitionCriteriaByClass | Specifies a criteria for matching a definition determined by reference to the unique identifier of a class definition.
  DefinitionCriteriaByKind | Specifies a criteria for matching a definition determined by its kind, such as data definition, property definition etc..
  DefinitionCriteriaByName | Criteria for matching a definition by its name.
  DefinitionCriteriaNoSearch | Specifies a criteria for matching a definition that matches nothing.
  Fade | Specifies a value that describes an audio fade operation associated with a source clip in terms of its fade in and out lengths and types.
  IdentificationCriteria | Specifies a criteria for matching an identification.
  IdentificationCriteriaByIdGeneration | Specifies a criteria for matching an identification by its generation id.
  IdentificationCriteriaByIdProductID | Specifies a criteria for matching an identification by its product id.
  IdentificationCriteriaByIdRefImplVersion | Specifies a criteria for matching an identification by its reference implementation version, also known as its toolkit version.
  IdentificationCriteriaNoIdSearch | Specifies a criteria for matching an identification that matches nothing.
  MultiCreateItem | Specifies an element of an array used to create interleaved audio and video essence.
  MultiResultItem | Specifies an element of an array containing multiple result values from an operation to read one or more channels from an interleaved data stream.
  MultiXferItem | Specifies an element of a transfer array that is used when reading one or more channels from an interlaced data stream.
  SearchByAUID | Specifies a search criteria for matching packages defined by an AUID value.
  SearchByMediaCriteria | Specifies a search criteria for matching packages defined by media criteria.
  SearchByName | Specifies a search criteria for matching packages defined by package name.
  SearchByPackageID | Specifies a search criteria for matching packages defined by a package id.
  SearchByPackageKind | Specifies a search criteria for matching packages defined by a kind of package.
  SearchCriteria | Specifies a search criteria for matching packages specified in a number of different ways.
  SearchForNothing | Specifies a search criteria for matching packages that does not match anything.
  SourceReferenceValue | Specifies a reference to a clip of source material, by material identifier, track number and start time offset.

- Enum Summary
  Enum | Description
  --- | ---
  DefinitionCriteriaType | Defines the type of the associated criteria for matching a definition.
  IdentificationCriteriaType | Defines the type of the associated criteria for matching an identification.
  SearchTag | Specifies the type of criteria used to match packages in a search criteria.

## Package tv.amwa.maj.union Description

Provides interfaces to a union type representing values which may contain one of many different sub-types. These are useful for specifying search criteria and composite return values.

The value of searches specified using the criteria of this package when the MAJ API is used in conjunction with a persistence entity manager is not clear. In this case, it is far better to define queries using an expressive query language that make use of the optimised search algorithms of the underlying store (database). However, searching using criteria is implemented in for searching for packages and essence data in the MAJ API in a way that can be used by a standalone application. These methods use the search criteria defined in this package.

The identification criteria and definition criteria defined in this package are not currently used in the MAJ API and may be deprecated in the near future.

## Heritage

The original versions of the interfaces of this package were derived from the `union` type definitions in the existing C-based AAF reference implementation, from file "`AAFTypes.h`". Java does not have a union type definition so abstract interfaces are used instead, with each sub-interface representing an element of the union. This is a little bit cumbersome as it requires several files Java for a concept that can be expressed so simply in C. However, it achieves the same result as each search criteria only takes the memory required to represent that criteria.

An example of the union type definition a set of criteria were derived from is:

        typedef struct _aafDefinitionCrit_t
        {
            aafDefinitionCritType_t type;
            union
            {
                aafDefinitionKind_t    defKind;
                aafString_t            name;
                aafClassID_t           objClass;
            } tags;
        } aafDefinitionCrit_t;

This converts into the Java abstract interface `DefinitionCriteria` with sub-interfaces `DefinitionCriteriaByKind`, `DefinitionCriteriaByName` and `DefinitionCriteriaByClass`. The type of the definition criteria is specified by enumeration `DefinitionCriteriaType`.

See Also:
  `ContentStorage.getPackages(SearchCriteria)`, `Preface.getPackages(SearchCriteria)`

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