MediaEngine (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.industry

## Class MediaEngine

- java.lang.Object
- - tv.amwa.maj.industry.MediaEngine

- All Implemented Interfaces:
    CommonConstants

      public final class MediaEngine
      extends Object
      implements CommonConstants

  An engine to allow the manipulation of metadata objects. The engine provides a means to be able to:

  - get and set property values by name and with a variety of different value representations;
  - test if two objects are equal, both shallow and deep;
  - generate a hash code;
  - create a string representation.

  The utilities of this class depend on the given metadata objects being instances of Java classes that provide `@MediaClass`, `@MediaProperty` and associated annotations. To create an extension to the specified classes or to implement your own media data model, use these annotations.

  To read, write or manipulate Advanced Authoring Format (AAF) data, including AAF, MXF or Reg-XML files, call `initializeAAF()` first. Values of these types can then be made using the make methods of the forge: `Forge.make(Class, Object...)`, `Forge.make(Class, boolean, Object...)`, `Forge.makeAAF(String, Object...)` etc..

  All the methods of this class are static.

  See Also:
    `Forge`, `MediaClass`, `MediaProperty`, `ClassDefinition`

- - ### Field Summary

    - ### Fields inherited from interface tv.amwa.maj.constant.CommonConstants

      `AAF_METADICT_NAMESPACE, AAF_METADICT_PREFIX, AAF_XML_NAMESPACE, AAF_XML_PREFIX, ApplicationPluginObjectID, ApplicationPluginsID, MAX_NUM_RGBA_COMPS, MemberOfID, ObjectClassID, ParentClassID, PropertiesID, XMLClassIDAsAttributeName`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `changeStreamResolver(StreamResolver newResolver)` Change the stream resolver currently in use by this media engine.
    `static boolean` | `deepEquals(MetadataObject first, Object second)` Test to see if a metadata object is equal to another object by comparing the properties of each object.
    `static boolean` | `equals(MetadataObject first, Object second)` Test to see if the first metadata object is equal to the second object, accepting equality of unique identifiers where available.
    `static ClassDefinition` | `getClassDefinition(MetadataObject target)` Returns the class definition that defines the type of the given metadata object.
    `static PropertyDefinition` | `getPropertyDefinition(MetadataObject target, String propertyName)` Returns the property definition of the named property from given metadata object.
    `static <T> T` | `getPropertyValue(MetadataObject target, String propertyName)` Returns the value of the named property from the given metadata object.
    `static StreamResolver` | `getStreamResolver()` Returns the stream resolver currently in use by this media engine for resolving stream idenfiers into stream values.
    `static PropertyValue` | `getWrappedPropertyValue(MetadataObject target, String propertyName)` Returns the value of the named property from the given metadata object, wrapped up with its type in a property value.
    `static int` | `hashCode(MetadataObject value)` Create a hash code value for a metadata object using its present properties.
    `static void` | `initializeAAF()` Initializes the warehouse with all the class definitions of the AAF specified classes, along with all associated types.
    `static boolean` | `isBaseline(AUID metaDefinitionID)` Determines if the given identifier identifies a class, property or type definition that is part of the AAF baseline set.
    `static boolean` | `isBaseline(MetaDefinition metaDefinition)` Determines if the given class, property or type definition that is part of the AAF baseline set.
    `static boolean` | `isPropertyPresent(MetadataObject target, String propertyName)` Checks whether a property of the given name is present or omitted for the given metadata object.
    `static <T extends MetadataObject> T` | `make(Class<T> type, boolean strict, Object... properties)` Deprecated. Use `Forge.make(Class, boolean, Object...)` instead
    `static <T extends MetadataObject> T` | `make(Class<T> type, Object... properties)` Deprecated. Use `Forge.make(Class, Object...)` instead
    `static <T extends MetadataObject> T` | `makeAAF(String typeName, Object... properties)` Deprecated. Use `Forge.makeAAF(String,Object...)` instead
    `static <T extends MetadataObject> T` | `makeByName(String namespace, String typeName, boolean strict, Object... properties)` Deprecated. Use `Forge.makeByName(String,String,boolean,Object...)` instead
    `static <T extends MetadataObject> T` | `makeByName(String namespace, String typeName, Object... properties)` Deprecated. Use `Forge.makeByName(String,String,Object...)` instead
    `static URI` | `makeSpecific(URI streamReference, String accept)` Make a canonical URI both local and file-type specific by using the registered mappings of the resolver and the HTTP-like accept criteria provided.
    `static void` | `omitOptionalProperty(MetadataObject target, String propertyName)` Omits an optional property of the given name from the given metadata object if it is currently present.
    `static void` | `registerMapping(URI canonicalForm, URI location)` Register a mapping between the canonical form of a URI for a stream and a location and file-type specific form.
    `static boolean` | `removeLocation(URI identifier)` Remove a canonical identifier or a specific location identifier as a possible stream resolution source.
    `static Stream` | `resolveStream(URI streamReference)` Resolve the given URI to a stream that can be used to access the data at that URI according to resolver policy.
    `static Stream` | `resolveStream(URI streamReference, String accept)` Resolve the given URI to a stream that can be used to access the data at the URI in a form that matches the given HTTP-like accept criteria.
    `static void` | `setPropertyValue(MetadataObject target, String propertyName, Object propertyValue)` Sets the value of the named property from the given metadata object to the given value.
    `static void` | `setPropertyValue(MetadataObject target, String propertyName, PropertyValue propertyValue)` Sets the value of the named property from the given metadata object to the given wrapped property value.
    `static String` | `toString(MetadataObject metadataOject)` Create a string representation of the given metadata object.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### initializeAAF

          public static final void initializeAAF()

      Initializes the warehouse with all the class definitions of the AAF specified classes, along with all associated types. Call this before any code that needs to create, read, write or otherwise manipulate AAF data, including AAF files, MXF files and Reg XML documents.

      Note that the first call to this method may take same time as a few hundred classes have to be loaded by the Java virtual machine and registered with this engine.

      See Also:
        `AAFSpecifiedClasses`

    - #### isBaseline

          public static final boolean isBaseline(MetaDefinition metaDefinition)

      Determines if the given class, property or type definition that is part of the AAF baseline set. All baseline types are registered by calling `initializeAAF()`. If it is not part of the baseline set, the definition is considered as an extension.

      Note that this method only returns a correct result after calling `initializeAAF()`.

      Parameters:
        `metaDefinition` - Meta definition to test to see if it is part of the AAF baseline.
      Returns:
        Is the given definition part of the AAF baseline set (returns `true`) or an extension (returns `false`)?
      Throws:
        `NullPointerException` - The given meta definition is `null`.
      See Also:
        `isBaseline(AUID)`, `MetaDefinition`

    - #### isBaseline

          public static final boolean isBaseline(AUID metaDefinitionID)
                                          throws NullPointerException

      Determines if the given identifier identifies a class, property or type definition that is part of the AAF baseline set. All baseline types are registered by calling `initializeAAF()`. If it is not part of the baseline set, the definition is considered as an extension.

      Note that this method only returns a correct result after calling `initializeAAF()`.

      Parameters:
        `metaDefinitionID` - Meta definition to test to see if it is part of the AAF baseline.
      Returns:
        Is the given definition part of the AAF baseline set (returns `true`) or an extension (returns `false`)?
      Throws:
        `NullPointerException` - The given identifier is `null`.
      See Also:
        `isBaseline(MetaDefinition)`, `MetaDefinition`

    - #### equals

          public static boolean equals(MetadataObject first,
                                       Object second)

      Test to see if the first metadata object is equal to the second object, accepting equality of unique identifiers where available. Equality is defined by the following rules:

      - Two `null` values are always equal.
      - If only one of the values is `null`, the values are not equal.
      - For non-null values, the class definitions of the values are the same or one is an ancestor of the other in the class hierarchy.
      - For non-null values and for values that both have a unique identifier property, the value of that identifier property is equal in both objects.
      - For non-null values with no unique identifiers:
        - every required property must be equal according to the property value's equals method;
        - The same optional property values must be present and of equal value according to the property value's equals method.

      For media classes, developer's can use this method to provide an equality test in their own classes without having to write their own code. An example of how to do this is:

               @Override
               public boolean equals(
                       Object o) {

                   return MetaEngine.equals(this, o);
               }

      The equality test of this method is compatible with the media engines hash code method.

      Parameters:
        `first` - First object to test the equality of.
        `second` - Second object to test the equality of.
      Returns:
        Are the two objects of equals value?
      See Also:
        `deepEquals(MetadataObject, Object)`, `Object.equals(Object)`

    - #### deepEquals

          public static final boolean deepEquals(MetadataObject first,
                                                 Object second)

      Test to see if a metadata object is equal to another object by comparing the properties of each object. Equality is defined by the following rules:

      - Two `null` values are always equal.
      - If only one of the values is `null`, the values are not equal.
      - For non-null values, the class definitions of the values are the same or one is an ancestor of the other in the class hierarchy.
      - For non-null values:
        - every required property must be equal according to the property value's equals method;
        - The same optional property values must be present and of equal value according to the property value's equals method.

      Note that deep equals is only one level deep. Any comparison of child values that have unique identifiers will use those identifiers.

      For media classes, developer's can use this method to provide an equality test in their own classes without having to write their own code. An example of how to do this is:

               public boolean deepEquals(
                       Object o) {

                   return MetaEngine.equals(this, o);
               }

      Parameters:
        `first` - First object to test the equality of.
        `second` - Second object to test the equality of.
      Returns:
        Are the two objects of equals value?
      See Also:
        `equals(MetadataObject, Object)`, `Object.equals(Object)`

    - #### hashCode

          public static final int hashCode(MetadataObject value)

      Create a hash code value for a metadata object using its present properties.

      If two objects have equal value, they should have the same hash code. Objects that are not equal values should have different hash codes but may occasionally clash.

      Calling this method as a delegate within a metadata object's hashCode() method, overriding the default, will enable efficient storage and reference to metadata objects in hash sets and hash maps. By using the media metadata associated with a class to create the hash code, a developer does not have to implement their own hash code calculation. An example of using this method is:

               @Override
               public int hashCode() {

                   MediaEngine.hashCode(this);
               }

      Note that `null` values produce a `0` hash code rather than throwing an exception.

      Parameters:
        `value` - Hashcode value for a metadata object using its present properties.
      Returns:
        Hashcode value for a metadata object using its present properties.
      See Also:
        `Object.hashCode()`

    - #### getPropertyValue

          public static final <T> T getPropertyValue(MetadataObject target,
                                                     String propertyName)
                                              throws NullPointerException,
                                                     IllegalPropertyException,
                                                     ClassCastException,
                                                     PropertyNotPresentException

      Returns the value of the named property from the given metadata object.

      The type of the value that is returned will depend on the data type of the property. See the type mapping table in the package documentation to determine the expected type of the return value.

      Type Parameters:
        `T` - Default Java type for the property to retrieve.
      Parameters:
        `target` - Metadata object instance to retrieve a property value from.
        `propertyName` - Name of the property value to retrieve.
      Returns:
        Unwrapped value of the property.
      Throws:
        `NullPointerException` - Cannot get a property value from a `null` value.
        `IllegalPropertyException` - The given property name does not match a property defined for the class of the given metadata object.
        `ClassCastException` - Class cast exception when trying to cast the returned value to the required type.
        `PropertyNotPresentException` - An optional property is not present for the given metadata object.
      See Also:
        `getWrappedPropertyValue(MetadataObject, String)`, `setPropertyValue(MetadataObject, String, Object)`, `PropertyDefinition.getPropertyValue(MetadataObject)`

    - #### getWrappedPropertyValue

          public static final PropertyValue getWrappedPropertyValue(MetadataObject target,
                                                                    String propertyName)
                                                             throws NullPointerException,
                                                                    IllegalPropertyException,
                                                                    PropertyNotPresentException

      Returns the value of the named property from the given metadata object, wrapped up with its type in a property value.

      Parameters:
        `target` - Metadata object instance to retrieve a property value from.
        `propertyName` - Name of the property value to retrieve.
      Returns:
        Wrapped value of the property.
      Throws:
        `NullPointerException` - Cannot get a property value from a `null` value.
        `IllegalPropertyException` - Cannot get a property value from the given metadata object using a `null` value.
        `PropertyNotPresentException` - An optional property is not present for the given metadata object.
      See Also:
        `getPropertyValue(MetadataObject, String)`, `setPropertyValue(MetadataObject, String, PropertyValue)`

    - #### getClassDefinition

          public static final ClassDefinition getClassDefinition(MetadataObject target)
                                                          throws NullPointerException,
                                                                 IllegalArgumentException

      Returns the class definition that defines the type of the given metadata object.

      Parameters:
        `target` - Object to retrieve the class definition for.
      Returns:
        Class definition defining the type of the given object.
      Throws:
        `NullPointerException` - Cannot retrieve a class definition for a `null` value.
        `IllegalArgumentException` - The given object is not annotated as a media class.
      See Also:
        `getPropertyDefinition(MetadataObject, String)`, `MediaClass`, `ClassDefinition`, `InterchangeObject.getObjectClass()`

    - #### getPropertyDefinition

          public static final PropertyDefinition getPropertyDefinition(MetadataObject target,
                                                                       String propertyName)
                                                                throws NullPointerException,
                                                                       IllegalPropertyException,
                                                                       IllegalArgumentException

      Returns the property definition of the named property from given metadata object.

      Parameters:
        `target` - Object to retrieve the property definition for.
        `propertyName` - Name of the property.
      Returns:
        Property definition of the given name in the class defining the type of the given metadata object.
      Throws:
        `NullPointerException` - Cannot retrieve a property definition from a `null` object or with a `null` name.
        `IllegalPropertyException` - The given metadata object does not have a property of the given name.
        `IllegalArgumentException` - The given metadata object is not annotated as a media class.
      See Also:
        `getClassDefinition(MetadataObject)`, `ClassDefinition.lookupPropertyDefinition(String)`, `MediaProperty`, `PropertyDefinition`, `getPropertyValue(MetadataObject, String)`

    - #### setPropertyValue

          public static final void setPropertyValue(MetadataObject target,
                                                    String propertyName,
                                                    Object propertyValue)
                                             throws NullPointerException,
                                                    IllegalPropertyException,
                                                    IllegalArgumentException

      Sets the value of the named property from the given metadata object to the given value. The type of the value to set must match that of the property's type definition as shown in the type mapping table.

      All values will be set through the relevant set method of the metadata object, meaning that any semantic checks implemented in that set method will be carried out.

      Note that it is possible to set a `null` value to omit an optional property. Setting a `null` value for a required property will result in an exception.

      Parameters:
        `target` - Metadata object to set the value of a property for.
        `propertyName` - Name of the property value to set.
        `propertyValue` - Value to set for the property.
      Throws:
        `NullPointerException` - Cannot set a property value on a `null` value or find a property using a `null` name.
        `IllegalPropertyException` - The given metadata object does not have a property of the given name.
        `IllegalArgumentException` - An error occurred when trying to convert the value to the required type or when calling the underlying classes set method.
      See Also:
        `setPropertyValue(MetadataObject, String, PropertyValue)`, `getPropertyValue(MetadataObject, String)`, `getPropertyDefinition(MetadataObject, String)`, `PropertyDefinition.setPropertyValue(MetadataObject, PropertyValue)`, `TypeDefinition.createValue(Object)`

    - #### setPropertyValue

          public static final void setPropertyValue(MetadataObject target,
                                                    String propertyName,
                                                    PropertyValue propertyValue)
                                             throws NullPointerException,
                                                    IllegalPropertyException,
                                                    IllegalArgumentException

      Sets the value of the named property from the given metadata object to the given wrapped property value.

      All values will be set through the relevant set method of the metadata object, meaning that any semantic checks implemented in that set method will be carried out.

      Note that it is possible to set a `null` value to omit an optional property. Setting a `null` value for a required property will result in an exception.

      Parameters:
        `target` - Metadata object to set the value of a property for.
        `propertyName` - Name of the property value to set.
        `propertyValue` - Value to set for the property.
      Throws:
        `NullPointerException` - Cannot set a property value on a `null` value or find a property using a `null` name.
        `IllegalPropertyException` - The given metadata object does not have a property of the given name.
        `IllegalArgumentException` - An error occurred when trying to convert the value to the required type or when calling the underlying classes set method.
      See Also:
        `setPropertyValue(MetadataObject, String, Object)`, `getWrappedPropertyValue(MetadataObject, String)`, `getPropertyDefinition(MetadataObject, String)`, `PropertyDefinition.setPropertyValue(MetadataObject, PropertyValue)`, `TypeDefinition.createValue(Object)`

    - #### toString

          public static final String toString(MetadataObject metadataOject)

      Create a string representation of the given metadata object. The string representation will be in an XML format similar to the one used for SMPTE Reg-XML. The symbol names of the object's defining class and the properties will be used as XML element names.

      Developer's can use this as a delegate method in a method that overrides `the default to string method` in any class. This means they can get a XML form of a value at any time and this is often useful in debugging. An example of how to do this is:

               @Override
               public String toString() {

                   return MetaEngine.toString(this);
               }

      Parameters:
        `metadataOject` - Metadata object to create a string representation of.
      Returns:
        String representation of the given metadata object.
      See Also:
        `Object.toString()`, `XMLBuilder.toXML(MetadataObject)`

    - #### make

          public static final <T extends MetadataObject> T make(Class<T> type,
                                                                boolean strict,
                                                                Object... properties)
                                                         throws NullPointerException,
                                                                IllegalArgumentException

      Deprecated. Use `Forge.make(Class, boolean, Object...)` instead

      Create new instances of metadata objects using the definition of its primary interface and its initial property values. Property values must be provided for all required properties and may also be provided for optional values. This is with the exception of required sets and arrays that are initialized to empty and will require at least one element to be added to become initialized.

      The type of object to create is provided by its defining Java interface or class. The property values are provided by a list of property identifier and value pairs, where each identifier is followed by its value. The property identifier can by a name, AUID or property definition. The values are either instances of the `PropertyValue` interface or Java values compatible with the type definition, as defined in the type mapping table.

      Here is an example of how to use this method:

                  TimelineTrack videoTrack = MediaEngine.make(
                    TimelineTrack.class,
                    "TrackID", 1,
                    "EditRate", "25/1",
                    "Origin", 0l,
                    "TrackSegment", videoSequence);

      In the example, an instance of the timeline track type is created. Its track identifier is initialized to 1, edit rate to 25/1 using a string representation of the value, origin to 0 and track to a variable called `videoSequence`.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `type` - Java class representing the type to return.
        `strict` - Should the method be strict about required properties or use defaults provided by the implementation?
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, Object...)`, `makeByName(String, String, boolean, Object...)`, `makeByName(String, String, Object...)`, `makeAAF(String, Object...)`, `ClassDefinition.createInstance()`

    - #### make

          public static final <T extends MetadataObject> T make(Class<T> type,
                                                                Object... properties)
                                                         throws NullPointerException,
                                                                IllegalArgumentException

      Deprecated. Use `Forge.make(Class, Object...)` instead

      Create new instances of metadata objects using the definition of its primary interface and its initial property values without being strict about required properties. See the description of `make(Class, boolean, Object...)` for more details.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `type` - Java class representing the type to return.
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, boolean, Object...)`, `makeByName(String, String, Object...)`, `ClassDefinition.createInstance()`

    - #### makeByName

          public static final <T extends MetadataObject> T makeByName(String namespace,
                                                                      String typeName,
                                                                      boolean strict,
                                                                      Object... properties)
                                                               throws NullPointerException,
                                                                      IllegalArgumentException

      Deprecated. Use `Forge.makeByName(String,String,boolean,Object...)` instead

      Create new instances of metadata objects using a fully qualified XML namespace name for the type and its initial property values. Property values must be provided for all required properties and may also be provided for optional values. This is with the exception of required sets and arrays that are initialized to empty and will require at least one element to be added to become initialized.

      The type of object to create is provided by its defining Java interface or class. The property values are provided by a list of property identifier and value pairs, where each identifier is followed by its value. The property identifier can by a name, AUID or property definition. The values are either instances of the `PropertyValue` interface or Java values compatible with the type definition, as defined in the type mapping table.

      Here is an example of how to use this method:

                  TimelineTrack videoTrack = MediaEngine.make(
                    "http://www.smpte-ra.org/schemas/2001-2/2007/aaf", "TimelineTrack",
                    "TrackID", 1,
                    "EditRate", "25/1",
                    "Origin", 0l,
                    "TrackSegment", videoSequence);

      In the example, an instance of the timeline track type is created. Its track identifier is initialized to 1, edit rate to 25/1 using a string representation of the value, origin to 0 and track to a variable called `videoSequence`. Note that the default AAF XML namespace is set as static string `CommonConstants.AAF_XML_NAMESPACE`.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `namespace` - Namespace in which the type for the new instance is defined.
        `typeName` - Name of the type of instance to create within the given namespace.
        `strict` - Should the method be strict about required properties or use defaults provided by the implementation?
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, Object...)`, `ClassDefinition.createInstance()`, `MediaClass.namespace()`, `CommonConstants.AAF_XML_NAMESPACE`

    - #### makeByName

          public static final <T extends MetadataObject> T makeByName(String namespace,
                                                                      String typeName,
                                                                      Object... properties)
                                                               throws NullPointerException,
                                                                      IllegalArgumentException

      Deprecated. Use `Forge.makeByName(String,String,Object...)` instead

      Create new instances of metadata objects using a fully qualified XML namespace name for the type and its initial property values, and also without being strict about required properties. For more details about this method, see the documentation for the `makeByName(String, String, boolean, Object...)` method.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `namespace` - Namespace in which the type for the new instance is defined.
        `typeName` - Name of the type of instance to create within the given namespace.
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, Object...)`, `make(Class, boolean, Object...)`, `makeByName(String, String, boolean, Object...)`, `makeAAF(String, Object...)`, `ClassDefinition.createInstance()`, `MediaClass.namespace()`, `CommonConstants.AAF_XML_NAMESPACE`

    - #### makeAAF

          public static final <T extends MetadataObject> T makeAAF(String typeName,
                                                                   Object... properties)
                                                            throws NullPointerException,
                                                                   IllegalArgumentException

      Deprecated. Use `Forge.makeAAF(String,Object...)` instead

      Create new instances of AAF baseline metadata objects using the name of the type and its initial property values, and also without being strict about required properties.

      For more details about this method, see the documentation for the `makeByName(String, String, boolean, Object...)` method. This method is the same as calling that method with the namespace set to the AAF namespace.

      Type Parameters:
        `T` - Type of value to make and return.
      Parameters:
        `typeName` - Name of the AAF baseline type of instance to create.
        `properties` - List of pairs of property identifiers and property values to use to initialize the newly made value.
      Returns:
        New instance of the specified type initialized with the given property values.
      Throws:
        `NullPointerException` - Cannot make a new value for a null class specification.
        `IllegalArgumentException` - The list of properties must be a list of property identifier and property value pairs, ie. divisible by 2, or a summary of other errors encountered during object creation.
      See Also:
        `make(Class, Object...)`, `make(Class, boolean, Object...)`, `makeByName(String, String, boolean, Object...)`, `makeByName(String, String, Object...)`, `ClassDefinition.createInstance()`, `MediaClass.namespace()`, `CommonConstants.AAF_XML_NAMESPACE`

    - #### isPropertyPresent

          public static final boolean isPropertyPresent(MetadataObject target,
                                                        String propertyName)
                                                 throws NullPointerException,
                                                        IllegalPropertyException

      Checks whether a property of the given name is present or omitted for the given metadata object. Optional properties may be present or omitted, whereas required (non-optional) properties must always be present.

      Parameters:
        `target` - Metadata object to check for the presence of a property.
        `propertyName` - Name of the property to check for.
      Returns:
        Is the property present for the given object (`true`) of omitted (`false`)?
      Throws:
        `NullPointerException` - One of both of the metadata object and/or property name is/are `null`.
        `IllegalPropertyException` - The given property name is not known as a property of the given metadata object.
      See Also:
        `omitOptionalProperty(MetadataObject, String)`, `getPropertyValue(MetadataObject, String)`, `PropertyDefinition.getIsOptional()`, `PropertyDefinition.isPropertyPresent(MetadataObject)`

    - #### omitOptionalProperty

          public static final void omitOptionalProperty(MetadataObject target,
                                                        String propertyName)
                                                 throws NullPointerException,
                                                        IllegalPropertyException,
                                                        IllegalArgumentException

      Omits an optional property of the given name from the given metadata object if it is currently present. If the property is already omitted, this method does nothing. Required (non-optional) properties cannot be omitted.

      Parameters:
        `target` - Metadata object instance to omit the property from.
        `propertyName` - Name of the proeprty to omit.
      Throws:
        `NullPointerException` - One or both of the obect and/or property name is/are `null`.
        `IllegalPropertyException` - A property with the given name is not a known property of the given metadata object or the property is not optional.
        `IllegalArgumentException` - An error occurred when trying to omit the property.
      See Also:
        `isPropertyPresent(MetadataObject, String)`, `getPropertyValue(MetadataObject, String)`, `PropertyNotPresentException`, `PropertyDefinition.omitOptionalProperty(MetadataObject)`

    - #### resolveStream

          public static final Stream resolveStream(URI streamReference)
                                            throws NullPointerException

      Resolve the given URI to a stream that can be used to access the data at that URI according to resolver policy. The URI may be location and file-type specific, or it may be a canonical identifier for which a specific location has already been registered. If a canonical identifier, the resolver uses a local policy to determine which location to return as a stream.

      Parameters:
        `streamReference` - Identifier for the stream to resolve.
      Returns:
        Stream that can be used to read and write data, or `null` if the given URI cannot be resolved.
      Throws:
        `NullPointerException` - Cannot resolve a `null` URI.
      See Also:
        `resolveStream(URI)`, `getStreamResolver()`, `StreamResolver.resolveStream(URI)`, `URI.create(String)`

    - #### resolveStream

          public static final Stream resolveStream(URI streamReference,
                                                   String accept)
                                            throws NullPointerException,
                                                   IllegalArgumentException

      Resolve the given URI to a stream that can be used to access the data at the URI in a form that matches the given HTTP-like accept criteria. The accept criteria provide a list of MIME types and quality parameters that indicate types of data acceptable to the caller, in order of preference. The resolver may choose to use the accept criteria when selecting a stream to access, according to local resolver policy. The format of an HTTP accept criteria is defined to be the same as an HTTP accept header, which can be found in section 14 of HTTP 1.1.

      The calling client should look at the URI of the stream returned using Stream.getStreamURI() to see if their accept request has been observed. Note that two calls to this method with the same identifier may resolve to different streams according to the policy of the local resolved, for example to handle network routing failures.

      Parameters:
        `streamReference` - Identifier for the stream to resolve.
        `accept` - Hint for the resolver as to the acceptable kinds of stream for the calling client. An accept header must be provided and should be set to "`*/*`" to get the same behaviour as for `resolveStream(URI)`.
      Returns:
        Stream that can be used to read and write data, or `null` if the given URI cannot be resolved.
      Throws:
        `NullPointerException`
        `IllegalArgumentException`
      See Also:
        `Cannot resolve a `null` URI and/or deal with a `null` accept header.`, `The given accept header is not valid.`, `resolveStream(URI)`, `makeSpecific(URI, String)`, `StreamResolver.resolveStream(URI, String)`, `URI.create(String)`

    - #### makeSpecific

          public static final URI makeSpecific(URI streamReference,
                                               String accept)
                                        throws NullPointerException,
                                               IllegalArgumentException

      Make a canonical URI both local and file-type specific by using the registered mappings of the resolver and the HTTP-like accept criteria provided. This method is similar to `resolveStream(URI, String)` except that it does not carry out the final step of resolving the provided URI to a stream. Instead, it provides the specific URI that would be used to provide access to the stream.

      URIs that are already specific should be passed straight through.

      Parameters:
        `streamReference` - Identifier for the stream to resolve.
        `accept` - Hint for the resolver as to the acceptable kinds of stream for the calling client.
      Returns:
        Location and file-type specific URI for accessing the stream.
      Throws:
        `NullPointerException`
        `IllegalArgumentException`
      See Also:
        `Cannot resolve a `null` URI and/or deal with a `null` accept header.`, `The given accept header is not valid.`, `resolveStream(URI, String)`, `StreamResolver.makeSpecific(URI, String)`, `URI.create(String)`

    - #### registerMapping

          public static final void registerMapping(URI canonicalForm,
                                                   URI location)
                                            throws NullPointerException,
                                                   IllegalArgumentException

      Register a mapping between the canonical form of a URI for a stream and a location and file-type specific form. This mapping may be used by future resolutions from identifier to streams made by this resolver.

      Parameters:
        `canonicalForm` - Canonical representation of an identifier for a stream.
        `location` - One possible location and file-type specific identifier for the stream.
      Throws:
        `NullPointerException` - One or both is the arguments is/are `null`.
        `IllegalArgumentException` - The given canonical identifier is location specific and/or the given location identifier is not specific enough.
      See Also:
        `resolveStream(URI)`, `resolveStream(URI, String)`, `makeSpecific(URI, String)`, `StreamResolver.registerMapping(URI, URI)`, `URI.create(String)`

    - #### removeLocation

          public static final boolean removeLocation(URI identifier)
                                              throws NullPointerException

      Remove a canonical identifier or a specific location identifier as a possible stream resolution source. If the location is canonical, all location-specific identifiers for that identifier may also be removed.

      Parameters:
        `identifier` - Identifier to remove from this resolved.
      Returns:
        Has the identifier been successfully removed? Note that `false` is returned if the identifier is not known to this resolver.
      Throws:
        `NullPointerException` - Cannot remove a `null` identifier.
      See Also:
        `StreamResolver.removeLocation(URI)`, `changeStreamResolver(StreamResolver)`

    - #### getStreamResolver

          public static final StreamResolver getStreamResolver()

      Returns the stream resolver currently in use by this media engine for resolving stream idenfiers into stream values. The default resolver is the local file resolver.

      Returns:
        Stream resolver in use by this media engine.
      See Also:
        `changeStreamResolver(StreamResolver)`, `resolveStream(URI)`

    - #### changeStreamResolver

          public static final void changeStreamResolver(StreamResolver newResolver)
                                                 throws NullPointerException

      Change the stream resolver currently in use by this media engine. The first call to this method will replace the default local file resolver.

      Care should be taken as mappings are not preserved between the current stream resolver and the replacement stream resolver.

      Parameters:
        `newResolver` - Resolver to use instead of the current resolver.
      Throws:
        `NullPointerException` - Cannot set a `null` stream resolver.
      See Also:
        `getStreamResolver()`

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