public final class Warehouse extends Object
Warehouse with a dynamic inventory of classes, types, definitions and extendible enumeration items. The warehouse is the place to come looking for any weak referenced item, by name or identification, known to the virtual machine containing the class. Also, new items can be added to the inventory of the warehouse at runtime, enabling dynamic and loosely-coupled use of the API.
The warehouse is not the place to come to make new values or instantiate objects, or to manipulate and test values. Use the forge to make new things and the media engine to change them.
To find something in the inventory of the warehouse, use:
lookForClass(Class) / lookForClass(String) /
lookForClass(AUID). Note that property
definitions are accessible as part of the class that they are a member of.lookForType(String) /
lookForType(AUID).lookup(Class, String) / lookup(Class, AUID) /
lookup(String, String) / lookup(String, AUID).lookupExtendibleEnumeration(String) or
use other methods to query details of the elements of an extendible enumeration:
extendibleEnumerationName(AUID), extendibleEnumerationElementName(AUID),
extendibleEnumerationElementValue(String), extendibleEnumerationFullName(AUID).To register to items onto the inventory of the warehouse, use:
lookForClass(Class)
and lookForClass(String) methods will automatically register an unknown class specified
using an appropriately annotated Java class.register(TypeDefinition, String, String)
or add a collection of type definitions from static values of a class using
registerTypes(Class, String, String).register(DefinitionObject).registerExtendibleEnumerationElement(String, String, AUID) or from static values of a
class with extendible enumeration item annotations
using registerExtendibleEnumerationElements(Class).To query the current inventory of the warehouse, lists and counts of the various names and types of item are provided:
getClassInventory()
and countClassDefinitions().getTypeInventory(),
getTypeDefinitions() and countTypeDefinitions().count(Class) and inventory(Class).getExtendibleEnumerationInventory() and countExtendibleEnumerations().| Modifier and Type | Method and Description |
|---|---|
static void |
clear() |
static <T extends DefinitionObject> |
count(Class<T> definitionType)
Counts the number of definitions in the inventory of the given definition type.
|
static int |
countClassDefinitions()
Count of the number of different kinds of class in this warehouse.
|
static int |
countExtendibleEnumerations()
Returns the number of extendible enumerations known in the inventory of this
warehouse.
|
static int |
countTypeDefinitions()
Count of the number of different type definitions in this warehouse.
|
static String |
extendibleEnumerationElementName(AUID elementValue)
Returns the element name of an extendible enumeration item from its element value.
|
static AUID |
extendibleEnumerationElementValue(String fullElementName)
Looks up the full name of an enumeration element value in the warehouse inventory by
its full name, including enumeration name and element name.
|
static String |
extendibleEnumerationFullName(AUID elementValue)
Looks up the full name of an enumeration element in the warehouse inventory by its
element value identifications.
|
static String |
extendibleEnumerationName(AUID elementValue)
Returns the enumeration name of an extendible enumeration item from its element value.
|
static Collection<ClassDefinition> |
getClassDefinitions() |
static Collection<String> |
getClassInventory()
Returns a collection of all classes known in this warehouse, by name.
|
static Collection<String> |
getExtendibleEnumerationInventory()
Returns a collection of all extendible enumerations known in the inventory for this
warehouse, by name.
|
static Collection<TypeDefinition> |
getTypeDefinitions()
Returns a collection containing all the different kinds of type definitions in this
warehouse.
|
static Collection<String> |
getTypeInventory()
Returns a collection of all types in the
inventory of this warehouse, by name.
|
static <T extends DefinitionObject> |
inventory(Class<T> definitionType)
Returns a collection of the names of the definitions of the given definition type.
|
static boolean |
isKnownProperty(PropertyDefinition property) |
static String |
javaClassAlias(String aafName)
Transform an AAF class name into its Java equivalent name.
|
static ClassDefinition |
lookForClass(AUID identification)
Looks up and returns the class definition in this warehouse
with the given identification.
|
static ClassDefinition |
lookForClass(Class<?> mediaClass)
For any given Java class, this method finds the corresponding media class definition or
creates it if it does not yet exist within the current Java virtual machine.
|
static ClassDefinition |
lookForClass(String name)
Finds and returns a class definition for the given media class name.
|
static PropertyDefinition |
lookForProperty(AUID propertyID)
Look for a property in the warehouse
by its unique identifier.
|
static TypeDefinition |
lookForType(AUID identification)
Finds the type definition with the given AUID identification
from the warehouse inventory.
|
static TypeDefinition |
lookForType(String typeName)
Finds the type definition for the given name from the warehouse inventory.
|
static <T extends DefinitionObject> |
lookup(Class<T> definitionType,
AUID definitionID)
Looks up a definition by its type and its identification
in the inventory of the warehouse.
|
static <T extends DefinitionObject> |
lookup(Class<T> definitionType,
String definitionName)
Looks up a definition by its type and its name
in the inventory of the warehouse.
|
static <T extends DefinitionObject> |
lookup(String definitionTypeName,
AUID definitionID)
Looks up a definition by its type name and its
identification in the inventory of the warehouse.
|
static <T extends DefinitionObject> |
lookup(String definitionTypeName,
String definitionName)
Looks up a definition by its type name and its name
in the inventory of the warehouse.
|
static SortedMap<String,AUID> |
lookupExtendibleEnumeration(String extendibleEnumerationName)
Returns a sorted map representation of an extendible enumeration from the name of
an extendible enumeration in the inventory of this warehouse.
|
static ExtensionScheme |
lookupExtensionScheme(AUID extensionSchemeID) |
static ExtensionScheme |
lookupExtensionScheme(String extensionSchemeIdentifier) |
static void |
register(ClassDefinition classDefinition) |
static Boolean |
register(DefinitionObject definition)
Registers the given definition with the inventory of this
warehouse.
|
static void |
register(ExtensionScheme extensionScheme) |
static void |
register(PropertyDefinition propertyDefinition) |
static void |
register(TypeDefinition typeDefinition,
String namespace,
String prefix)
Add or replace a given type definition in this warehouse.
|
static boolean |
registerExtendibleEnumerationElement(String extendibleEnumerationName,
String elementName,
AUID elementValue)
Add an element to an extendible
enumeration in the inventory of this warehouse.
|
static int |
registerExtendibleEnumerationElements(Class<?> extendibleEnumerationClass)
Scan the given class for AUID values annotated
as the definitions of extendible enumeration values.
|
static void |
registerTypes(Class<?> typeClass,
String namespace,
String prefix)
Looks through the given class for public static fields of
type definitions
and adds these to the warehouse inventory. |
public static final void clear()
public static final ClassDefinition lookForClass(Class<?> mediaClass) throws NullPointerException, IllegalArgumentException
For any given Java class, this method finds the corresponding media class definition or creates it if it does not yet exist within the current Java virtual machine. The creation of class definitions is done by lazy evaluation as required using Java reflection and annotations. All generated values are stored in the warehouse inventory, a static hashtable, so that once generated the work is not repeated.
The values returned by this method are only as good as the annotations provided with
the sourcecode, as labelled using MediaClass and MediaProperty.
If an MediaClass annotation is not present in the given class, an IllegalArgumentException is thrown. Any
problems found with the MediaProperty annotations, such as two properties having the same
name, will also result in an IllegalArgumentException.
mediaClass - Java class to find the media class definition of.NullPointerException - The given Java class is null.IllegalArgumentException - The given Java class is not annotated with MediaClass or
the MediaProperty annotations contain errors.MediaClass,
MediaProperty,
MediaEngine.initializeAAF(),
MediaEngine.getClassDefinition(MetadataObject)public static final void register(ClassDefinition classDefinition) throws NullPointerException
NullPointerExceptionpublic static final ClassDefinition lookForClass(String name) throws NullPointerException, IllegalArgumentException
Finds and returns a class definition for the given media class name. Firstly, the search takes place using the class name specified in the AAF object specification and then by using a Java class name.
The search order used by this method is:
Class.forName(String) followed by
lookForClass(Class) with the result. If the given class name represents an interface,
an attempt is made to find the implementation by naming convention. Return the value.Class.forName(String) followed by
lookForClass(Class) with the result. Return the value.Once the class has been located and linked into the running virtual machine, the lookForClass(Class)
method is called.
name - Name of the class definition to find, specified using a name from the AAF object specification,
a MAJ API class name or a fully qualified java class name.NullPointerException - The given class name is null.IllegalArgumentException - The given class name could not be resolved to an AAF class.Class.forName(java.lang.String)public static final Collection<String> getClassInventory()
Returns a collection of all classes known in this warehouse, by name.
Note this methods excludes some classes registered only for the mechanics of reading and writing MXF files.
countClassDefinitions()public static final Collection<ClassDefinition> getClassDefinitions()
public static final int countClassDefinitions()
Count of the number of different kinds of class in this warehouse.
Note that this method includes a count of classes registered for the mechanics of reading and writing MXF files. To exclude these from the count, use:
getClassInventory().size()getClassInventory()public static final ClassDefinition lookForClass(AUID identification) throws NullPointerException
Looks up and returns the class definition in this warehouse
with the given identification. If no class definition with the given identification can be
found, a value of null is returned.
identification - Identifier for the class.NullPointerException - Cannot resolve a registered class definition using a null
value.public static final <T extends DefinitionObject> T lookup(Class<T> definitionType, String definitionName) throws NullPointerException
Looks up a definition by its type and its name in the inventory of the warehouse. The definition only has to be known to the Java local machine and is not necessarily stored in an AAF dictionary.
For example, to find the correct kind of data definition for a picture, call:
DataDefinition pictureData = Warehouse.lookup(DataDefinition.class, "Picture");
T - All kinds of definition objects.definitionType - Specific kind of definition required.definitionName - Name of the definition of the given kind to find.null if the
definition name is not known for the given type.NullPointerException - One or both of the given definition type or definition name
is/are null.lookup(Class, AUID),
lookup(String, AUID),
lookup(String, String),
WeakReference,
Dictionarypublic static final <T extends DefinitionObject> T lookup(Class<T> definitionType, AUID definitionID) throws NullPointerException
Looks up a definition by its type and its identification in the inventory of the warehouse. The definition only has to be known to the Java local machine and is not necessarily stored in an AAF dictionary.
For example, to find the correct kind of data definition for a picture, call:
DataDefinition pictureData = Warehouse.lookup(
tv.amwa.maj.model.DataDefinition.class,
Forge.parseAUID("urn:smpte:ul:060x0e2b34.04010101.01030202.01000000"));T - All kinds of definition objects.definitionType - Specific kind of definition required.definitionID - Identification of the definition of the given kind to find.null if the
definition name is not known for the given type.NullPointerException - One or both of the given definition type or definition name
is/are null.lookup(Class, String),
lookup(String, AUID),
lookup(String, String),
WeakReference,
Dictionarypublic static final <T extends DefinitionObject> T lookup(String definitionTypeName, String definitionName) throws NullPointerException, IllegalArgumentException
Looks up a definition by its type name and its name in the inventory of the warehouse. The definition only has to be known to the Java local machine and is not necessarily stored in an AAF dictionary.
For example, to find the correct kind of data definition for a picture, call:
DataDefinition pictureData = Warehouse.lookup("DataDefinition", "Picture");
T - All kinds of definition objects.definitionTypeName - Name of the specific kind of definition required.definitionName - Name of the definition of the given kind to find.null if the
definition name is not known for the given type.NullPointerException - One or both of the given definition type or definition name
is/are null.IllegalArgumentException - The given type name does not match one knwon in the class inventory
or is not a kind of definition.lookup(Class, AUID),
lookup(String, AUID),
lookup(Class, String),
WeakReference,
Dictionarypublic static final <T extends DefinitionObject> T lookup(String definitionTypeName, AUID definitionID) throws NullPointerException, IllegalArgumentException
Looks up a definition by its type name and its identification in the inventory of the warehouse. The definition only has to be known to the Java local machine and is not necessarily stored in an AAF dictionary.
For example, to find the correct kind of data definition for a picture, call:
DataDefinition pictureData = Warehouse.lookup(
"DataDefinition",
Forge.parseAUID("urn:smpte:ul:060x0e2b34.04010101.01030202.01000000"));T - All kinds of definition objects.definitionTypeName - Name of the specific kind of definition required.definitionID - Identification of the definition of the given kind to find.null if the
definition name is not known for the given type.NullPointerException - One or both of the given definition type name or definition identification
is/are null.IllegalArgumentExceptionlookup(Class, String),
lookup(Class, AUID),
lookup(String, String),
WeakReference,
Dictionarypublic static final Boolean register(DefinitionObject definition) throws NullPointerException
Registers the given definition with the inventory of this warehouse.
definition - Definition to be placed onto the warehouse inventory.true if the registration is successful, false if the
definition is already registered and null if an error occurred and the
registration failed.NullPointerException - The given definition is null.lookup(Class, String),
lookup(Class, AUID)public static final <T extends DefinitionObject> int count(Class<T> definitionType) throws NullPointerException
Counts the number of definitions in the inventory of the given definition type.
T - All kinds of definition types.definitionType - Definition type to count the number of known definitions for.NullPointerException - The given definition type is null.countClassDefinitions(),
countTypeDefinitions(),
countExtendibleEnumerations(),
inventory(Class)public static final <T extends DefinitionObject> Collection<String> inventory(Class<T> definitionType) throws NullPointerException
Returns a collection of the names of the definitions of the given definition type.
T - All kinds of definition types.definitionType - Definition type to list the elements of.null if the type is not known.NullPointerException - The given definition type is null.getTypeInventory(),
getClassInventory(),
getExtendibleEnumerationInventory(),
count(Class)public static final void registerTypes(Class<?> typeClass, String namespace, String prefix) throws NullPointerException
Looks through the given class for public static fields of type definitions
and adds these to the warehouse inventory.
This method picks out static fields in the given class and adds them to the cache of known types in this class. Here is an example of the declaration of a UInt8 value:
public final static TypeDefinitionInteger UInt8 = new TypeDefinitionInteger(
new AUID(0x01010100, (short) 0x0000, (short) 0x0000,
new byte[] { 0x06, 0x0e, 0x2b, 0x34, 0x01, 0x04, 0x01, 0x01 } ),
"UInt8", (byte) 1, false);
typeClass - Class to check for static type definition instances.namespace - Namespace in which the type definition is defined.prefix - Preferred prefix for symbols in the given namespace.NullPointerException - The given class is null.register(TypeDefinition, String, String),
lookForType(AUID),
lookForType(String),
MetaDefinition.getNamespace(),
MetaDefinition.getPrefix()public static final TypeDefinition lookForType(String typeName) throws NullPointerException
Finds the type definition for the given name from the warehouse inventory. Type definition names are the same as used in the AAF specification, reference implementation meta dictionary or SMPTE type dictionary, for example:
UInt32 is a unique name;Int8Array is a unique name;TypeDefinitionWeakReferenceVector returns the same type as:
WeakReferenceVector of TypeDefinition andWeakReferenceVector<TypeDefinition>;CompositionPackageStrongReference returns the same type as:
StrongReference to CompositionPackage andStrongReference<CompositionPackage>If a corresponding type cannot be found, this method returns null.
typeName - Name of the type definition to check for.NullPointerException - The given type name is null.lookForClass(AUID),
getTypeInventory()public static final TypeDefinition lookForType(AUID identification) throws NullPointerException
Finds the type definition with the given AUID identification
from the warehouse inventory. If a type definition matching the given identification cannot be found,
null is returned.
identification - AUID to use to lookup a type definition.NullPointerException - The given type identifier is null.lookForType(String),
getTypeInventory()public static int countTypeDefinitions()
Count of the number of different type definitions in this warehouse.
getTypeDefinitions(),
getTypeInventory(),
countClassDefinitions()public static final void register(TypeDefinition typeDefinition, String namespace, String prefix) throws NullPointerException
Add or replace a given type definition in this warehouse.
typeDefinition - Type definition to add to the warehouse.namespace - Namespace in which the type definition is defined.prefix - Preferred prefix for symbols in the given namespace.NullPointerException - Cannot add a type to the warehouse
using a null value.registerTypes(Class, String, String),
MetaDefinition.getNamespace(),
MetaDefinition.getPrefix()public static final Collection<String> getTypeInventory()
Returns a collection of all types in the inventory of this warehouse, by name.
getClassInventory(),
getExtendibleEnumerationInventory(),
getTypeDefinitions(),
countTypeDefinitions()public static final Collection<TypeDefinition> getTypeDefinitions()
Returns a collection containing all the different kinds of type definitions in this warehouse.
countTypeDefinitions(),
getTypeInventory()public static final int registerExtendibleEnumerationElements(Class<?> extendibleEnumerationClass) throws NullPointerException, IllegalArgumentException
Scan the given class for AUID values annotated as the definitions of extendible enumeration values. Any values find are added to the inventory of the warehouse for use by applications sharing the same Java virtual machine.
To create an extendible enumeration element in MAJ, you can write an interface with a set of static AUID values and annotate these as follows:
@ExtendibleEnumerationItem(target = "OperationCategory")
public final static AUID Effect = Forge.makeAUID(
0x0d010102, (short) 0x0101, (short) 0x0100,
new byte[] { 0x06, 0x0e, 0x2b, 0x34, 0x04, 0x01, 0x01, 0x01 });
extendibleEnumerationClass - Class or interface containing extendible enumeration
element definitions.NullPointerException - The given class to add extendible enumeration values from is
null.IllegalArgumentException - Unable to access the annotations of the given class.ExtendibleEnumerationItem,
TypeDefinitionExtendibleEnumeration,
OperationCategoryType,
registerExtendibleEnumerationElement(String, String, AUID),
lookupExtendibleEnumeration(String)public static final boolean registerExtendibleEnumerationElement(String extendibleEnumerationName, String elementName, AUID elementValue) throws NullPointerException, IllegalArgumentException
Add an element to an extendible enumeration in the inventory of this warehouse. The element is added by the name of the extendible enumeration to which it is to be added, the element's name and the element's identification.
The value will overwrite previous values known in the inventory. The behaviour will be to degrade gracefully, with the possibility of two names resolving to one identification.
extendibleEnumerationName - Name of the extendible enumeration to which the element is to be
added. If no such enumeration is known, one will be created.elementName - Name of the new element to add to the inventory.elementValue - Identification of the new element to add to the inventory.true indicates a replacement and may result in an undesirable side effect.NullPointerException - One or more of the arguments in null.IllegalArgumentException - The given element value is already in use for a different
extendible enumeration.TypeDefinitionExtendibleEnumeration,
registerExtendibleEnumerationElements(Class),
ExtendibleEnumerationItempublic static final SortedMap<String,AUID> lookupExtendibleEnumeration(String extendibleEnumerationName) throws NullPointerException
Returns a sorted map representation of an extendible enumeration from the name of an extendible enumeration in the inventory of this warehouse.
extendibleEnumerationName - Name of an extendible enumeration that should be in the inventory of this
warehouse.null if no such extendible enumeration is found in the inventory.NullPointerException - The given extendible enumeration name is null.registerExtendibleEnumerationElements(Class),
registerExtendibleEnumerationElement(String, String, AUID),
extendibleEnumerationElementName(AUID),
extendibleEnumerationFullName(AUID),
extendibleEnumerationElementValue(String),
extendibleEnumerationName(AUID)public static final String extendibleEnumerationFullName(AUID elementValue) throws NullPointerException
Looks up the full name of an enumeration element in the warehouse inventory by its element value identifications. The name is of the form:
>_<element_name>This form is commonly used by XML representation of AAF and can be converted back
to an element value using extendibleEnumerationElementValue(String).
elementValue - Value of the extendible enumeration full name to lookup in the inventory.null if the element value is not in the inventory.NullPointerException - The given element value is null.extendibleEnumerationElementValue(String),
lookupExtendibleEnumeration(String)public static final AUID extendibleEnumerationElementValue(String fullElementName) throws NullPointerException
Looks up the full name of an enumeration element value in the warehouse inventory by its full name, including enumeration name and element name. The name should be of the form:
>_<element_name>This full name form is commonly use by XML representations of AAF and can be converted
back to a string form using extendibleEnumerationFullName(AUID).
fullElementName - Full name of the element value to look up in the inventory.null if
the name is not known in the inventory.NullPointerException - The given full element name is null.extendibleEnumerationElementValue(String),
lookupExtendibleEnumeration(String)public static final String extendibleEnumerationName(AUID elementValue) throws NullPointerException
Returns the enumeration name of an extendible enumeration item from its element value. The element name part is not included.
elementValue - Element value identification to find the corresponding enumeration name
for.null if no element of the
given element identification is known in the inventory.NullPointerException - Cannot find an extendible enumeration name from a null element value.extendibleEnumerationFullName(AUID),
extendibleEnumerationElementName(AUID)public static final String extendibleEnumerationElementName(AUID elementValue) throws NullPointerException
Returns the element name of an extendible enumeration item from its element value. The enumeration name part is not included.
elementValue - Element value identification to find the corresponding element name
for.null if no element of the
given element identification is known in the inventory.NullPointerException - Cannot find an element name from a null element value.extendibleEnumerationName(AUID),
extendibleEnumerationFullName(AUID)public static final Collection<String> getExtendibleEnumerationInventory()
Returns a collection of all extendible enumerations known in the inventory for this warehouse, by name.
getClassInventory(),
getTypeInventory(),
lookupExtendibleEnumeration(String),
countExtendibleEnumerations()public static final int countExtendibleEnumerations()
Returns the number of extendible enumerations known in the inventory of this warehouse.
getExtendibleEnumerationInventory(),
countClassDefinitions(),
countTypeDefinitions()public static final String javaClassAlias(String aafName)
Transform an AAF class name into its Java equivalent name. For example, the
AAF class called FileDescriptor is known as
AAFFileDescriptor in
Java. Most names are the same and passed through this method unchanged, as
are null values.
aafName - Name of the class to check for an alias of.MetaDefinition.getName()public static final PropertyDefinition lookForProperty(AUID propertyID) throws NullPointerException
Look for a property in the warehouse by its unique identifier.
To look for a property by its name or local identification number, use
ClassDefinition.lookupPropertyDefinition(String) and
ClassDefinition.lookupPropertyDefinition(short) respectively.
propertyID - Unique identifier of a property to check for in the warehouse.null if the property
cannot be found.NullPointerException - Cannot look for a property using a null identifier.ClassDefinition.lookupPropertyDefinition(AUID),
lookForClass(AUID),
lookForClass(Class),
lookForClass(String)public static final void register(PropertyDefinition propertyDefinition) throws NullPointerException
NullPointerExceptionpublic static final boolean isKnownProperty(PropertyDefinition property)
public static final void register(ExtensionScheme extensionScheme) throws NullPointerException
NullPointerExceptionpublic static final ExtensionScheme lookupExtensionScheme(AUID extensionSchemeID) throws NullPointerException
NullPointerExceptionpublic static final ExtensionScheme lookupExtensionScheme(String extensionSchemeIdentifier) throws NullPointerException
NullPointerException(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.