Package tv.amwa.maj.exception

Specific exceptions thrown due to exceptional behaviour during the execution of method calls from the MAJ API.

See:
Description

Interface Summary

MAJException	Interface implemented by all exceptions that are specific to the MAJ API.
NewForMAJ	This interfaces labels new exceptions introduced for this Java implementation of the AAF class model.

Exception Summary

AdjacentTransitionException	Thrown when an operation on a sequence would result in two adjacent transitions within that sequence.
AlreadyOpenException	Thrown when an attempt is made to open an AAF file that is already open.
AlreadyUniquelyIdentifiedException	Thrown when an attempt is made to add a property to a class definition described as a unique identifier when the class already has a registered property that is a unique identifier.
BadCloseException	Thrown when an attempt is made to open a file that has not yet been closed.
BadLengthException	Thrown when an out of range length value is set for a component or fade in the current context.
BadOpenException	Thrown when an attempt is made to perform an operation on a random access file that is not currently open.
BadParameterException	Thrown when a lookup operation fails because the given parameter cannot be found in a known collection of values.
BadPropertyException	Thrown when an optional property should be omitted in the current context.
BadRateException	Thrown if an unacceptable edit rate is set for a source mob's slot.
BadSampleOffsetException	Thrown when an offset into a segment or some file-based essence, specified by timecode or frames, is out of range.
BadSizeException	Thrown when an array is not of the required number of elements.
BadTypeException	Thrown when a method call on an object in the meta dictionary passes in the wrong type of property value as a parameter.
ContainerWriteException	Thrown when writing to a data container fails.
DataSizeException	Thrown when it has not been possible to allocate the requested or necessary amount of space for data storage.
DuplicateEssenceKindException	Thrown when an attempt is made to add an essence kind to that supported by a codec definition that is already listed as supported by that codec.
DuplicateException	Thrown when an attempt is made to add an element to a set that is already contained in that set.
DuplicateMobIDException	Thrown when an attempt is made to add essence or metadata to content storage when information with the same mob id is already stored.
DuplicateParameterException	Thrown when an attempt is made to add a parameter to an operation group that is already a parameter for that group.
EndOfDataException	Thrown when an attempt is made to read beyond the end of a data stream.
EssenceNotFoundException	Thrown when an attempt is made to remove some data from content storage that is not contained within that storage.
EventSemanticsException	Thrown when an event is used in the wrong context.
FilmDescriptorOnlyException	Thrown when an attempt is made to add an edgecode slot to a source mob that does not reference film essence.
GenerationMethodNotSupportedException	Thrown when the generation of a mob id is requested with a kind of generation method that is not supported.
IllegalPropertyException	Thrown when a given property definition is illegal within the context of an interchange object.
IllegalPropertyValueException	Thrown when a parameter to a method call of an object is outside the acceptable range or of the wrong type for that object in its current state.
InconsistancyException	Thrown when an inconsistency occurs when searching an essence group.
InstanceOverflowException	Thrown when the instance generator of a mob id overflows.
InsufficientSpaceException	Thrown when not enough space is available on the filing system to save data to a file.
InsufficientTransitionMaterialException	Thrown when appending or inserting a given component to a sequence will result in insufficient material for the adjacent transition.
InvalidDataDefinitionException	Thrown when an inappropriate data definition is used within the context of a method call.
InvalidLinkageException	Thrown when traversal of the content in an essence group is not possible due to an invalid link.
InvalidMobTypeException	Thrown if the given mob kind is not appropriate for a search operation.
InvalidParameterException	Thrown whenever a method call parameter contains a value that is invalid in the current context.
LeadingTransitionException	Thrown when the result of an operation would make the first component of a sequence a transition.
MobNotFoundException	Thrown when a given mob identified with a mob id cannot be found.
NoHeaderException	Thrown when a file does not contain a header object.
NoMoreObjectsException	Thrown when a given parent of a tagged value definition is not known and so cannot be removed from its list of parent properties.
NotAnInterfaceException	Thrown when an interface, represented by a Class instance, to be implemented by a new class instance is not a Java interface.
NotImplementedException	Thrown when a method is called that is not implemented in the MAJ API.
NotOpenException	Thrown when an operation on a file cannot take place because the file is not in an opened state.
NotReadableException	Thrown when a raw stream is not open and/or available for reading.
NotSourceClipException	Thrown when adding a pulldown reference to a source mob that does not contain a source clip.
NotTapeMobException	Thrown when a request is made to find the name of a tape associated with a master mob which is not describing tape-based material
NotValidKeyException	Thrown when creating a KLV data key that does not map to a built-in type.
NotWriteableException	Thrown when it is not possible to write to a file on the filing system.
ObjectAlreadyAttachedException	Thrown when an attempt is made to attach an item to a collection that it already contains.
ObjectNotAttachedException	Thrown when an interchange object is not attached to a header object.
ObjectNotFoundException	Thrown when a given object cannot be found in a collection, such as when a request is made to remove the item from the collection.
OffsetSizeException	Thrown when a given offset exceeds the size of a file or the available space to extend storage for a file.
ParameterNotFoundException	Thrown when a parameter to an operation cannot be found from its parameter id.
PositionOutOfRangeException	Thrown when a given position, specified by frame count or timecode, is outside the the length of the referenced stream.
PropertyAlreadyPresentException	Thrown when an attempt is made to create an optional property for an interchange object when a property with the same definition already exists for that object.
PropertyNotPresentException	Thrown when an attempt is made to read the value of a property that is omitted from an interchange object.
PulldownDirectionException	Thrown when an invalid pulldown direction is specified in the context of a source mob.
RationalRangeException	Thrown when a rational value is outside of the acceptable range in a given context.
SegmentNotFoundException	Thrown when a given segment cannot be found within the segments of a selector.
SingleChannelOpException	Thrown when an attempt is made to write samples into an essence stream that contains interleaved data.
SlotExistsException	Thrown when an attempt is made to add a slot to a master mob where the given slot id already exists.
SlotNotFoundException	Thrown when a mob slot cannot be found within a mob.
StreamFullException	Thrown when a stream has insufficient capacity to complete the requested write operation.
TapeDescriptorOnlyException	Thrown if an operation relating to tape-based material is called on a source mob that does not describe tape-based material.
TimecodeNotFoundException	Thrown when a given timecode or offset is not available within a segment or mob.
TraversalNotPossibleException	Thrown when a search operation cannot proceed.
TypeNotFoundException	Thrown when a key cannot be resolved to a type definition.
WrongOpenModeException	Thrown when an attempt is made to save data to a file that was not opened for writing or other modification.

Package tv.amwa.maj.exception Description

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.

Design approach

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:

• In cases where the C-based AAF SDK would return result code AAFRESULT_SUCCESS, a value is returned as the method output.
• In all other cases, a Java exception is thrown.

The following sections describe the approach taken to implementing result codes in a Java style in the MAJ API.

Reuse of Java exceptions

Wherever possible in this API, Java's built in exceptions are used, such as those defined in the 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 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, BadLengthException extends IllegalArgumentException as it represents the unexpected state where a given length value is illegal for a particular method call.

AAF-specific exceptions

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 Exception or RuntimeException. All such exceptions implement the MAJException interface. The choice for whether the exceptions are runtime exceptions or not is made as follows:

• Extends Exception: Exceptions that an application using this API should be expected to catch, e.g. to handle a case where searching for an item finds nothing or a file operation fails. An application or API is required by the Java compiler to provide code to catch these exceptions or throw them to a higher level API.
• Extends RuntimeException: Exceptions that occur during normal operation of a Java Virtual Machine at runtime, such as a call to a method with an illegal value. An application may catch these exceptions but is not required to do so by the Java compiler. Failure to catch these exceptions may result in the termination of the current thread.

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.

MAJ-specific exceptions

Certain exceptions have been introduced for behaviour specific to the MAJ API. These exceptions implement the NewForMAJ interface.

Separate package for exceptions

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.

Author:

Richard Cartwright