Specific exceptions thrown due to exceptional behaviour during the execution of method calls from the MAJ API. These exceptions are loosely based on the result codes in the C-based AAF SDK.
This API is designed to provide AAF support using a design similar to that used by other Java APIs.
The methods in the MAJ API interfaces package are designed
to be similar to the methods in the C-based AAF SDK COM interfaces, as specified in file
"AAF.idl
". Rather than using in and out arguments
with methods returning a result code, as defined in the COM interfaces, the MAJ API treats all method
arguments as inputs:
AAFRESULT_SUCCESS
, a value is returned as the method output.The following sections describe the approach taken to implementing result codes in a Java style in the MAJ API.
Wherever possible in this API, Java's built in exceptions are used, such
as those defined in the {@link java.lang} package. For example, instead of an AAF_NULL_PARAM
result code being returned when an error due to a null pointer occurs within the execution of a method, the
MAJ API throws a {@link java.lang.NullPointerException} instead.
Where an AAF result code is a special kind of an existing built in Java exception, an exception is included in this package that extends the built in exception. For example, {@link tv.amwa.maj.exception.BadLengthException} extends {@link java.lang.IllegalArgumentException} as it represents the unexpected state where a given length value is illegal for a particular method call.
If no direct link to an Java built in exception can be identified, an AAF-specific exception is provided in this package that either directly extends {@link java.lang.Exception} or {@link java.lang.RuntimeException}. All such exceptions implement the {@link tv.amwa.maj.exception.MAJException} interface. The choice for whether the exceptions are runtime exceptions or not is made as follows:
Many of these exceptions can be linked to AAF SDK result codes, as listed in
"AAFResult.h
". Where this is the case, the description of the exception
includes the equivalent result code.
Certain exceptions have been introduced for behaviour specific to the MAJ API. These exceptions implement the {@link tv.amwa.maj.exception.NewForMAJ} interface.
A separate package has been used for the exceptions of this API as they are class implementations rather than interfaces. At the same time, these exceptions form a core part of the implementation-independent interfaces in the interfaces package. So that the interfaces can be distributed and managed separately from the implementations provided in this API, this separate exceptions package has been created.