Media Authoring
with Java API

tv.amwa.maj.iface
Interface Sequence

All Superinterfaces:
Component, InterchangeObject, Segment
All Known Implementing Classes:
Sequence

public interface Sequence
extends Segment

Specifies the combination of an ordered list of segments and transitions. A sequence is the mechanism for combining sections of essence to be played in a sequential manner. If a sequence object has one segment followed by another segment, after the first segment is played, the following one begins immediately.

To be considered legal, sequences must satisfy a number of rules. The MAJ API supports the construction of sequences from start to finish, allowing a sequence to temporarily exist in an illegal state, for example with a trailing transition. The application must ensure that the rules for sequences are maintained. These rules are repeated from the AAF specification below:

  1. The first and last components in the ordered set shall be segments.
  2. A transition shall only appear in a sequence between two segments. The length of each of these segments shall be greater than or equal to the length of the transition.
  3. If a segment has a transition before it and after it, the sum of the lengths of the surrounding transitions shall be less than or equal to the length of the segment that they surround.
  4. The length of the sequence shall be equal to the sum of the length of all segments directly owned by the sequence minus the sum of the lengths of all transitions directly owned by the sequence.
  5. The data definition of each component in the sequence shall be the same as the data definition of the sequence itself.
  6. If a sequence has a transition, the last section of the segment that precedes the transition, the transition itself, and the first section of the segment that follows the transition are overlapped. The duration of the transition determines the duration of the section of the preceding and following segments that are overlapped.

Author:
Richard Cartwright
See Also:
makeSequence(), OperationGroup.isValidTransitionOperation()

Method Summary
 void appendComponent(Component component)
          Appends the given component to this sequence.
 int countComponents()
          Returns the number of components in this sequence.
 Component getComponentAt(int index)
          Returns the component at the given index through this sequence.
 List<? extends Component> getComponents()
          Returns a list of all the components of this sequence.
 void insertComponentAt(int index, Component component)
          Insert the given component into this sequence at the given index.
 void prependComponent(Component component)
          Prepends the given component to this sequence.
 void removeComponentAt(int index)
          Removes the component at the given index from this sequence.
 
Methods inherited from interface tv.amwa.maj.iface.Segment
segmentOffsetToTC, segmentTCToOffset
 
Methods inherited from interface tv.amwa.maj.iface.Component
appendAttribute, appendAttribute, appendComment, appendComment, appendKLVData, countAttributes, countComments, countKLVData, getAttributes, getComments, getDataDefinition, getKLVData, getLength, removeAttribute, removeComment, removeKLVData, setDataDefinition, setLength
 
Methods inherited from interface tv.amwa.maj.iface.InterchangeObject
countProperties, createOptionalPropertyValue, disableGenerationTracking, enableGenerationTracking, getDefinition, getGeneration, getGenerationAUID, getProperties, getPropertyValue, isGenerationTracked, isPropertyPresent, omitOpionalProperty, setPropertyValue
 

Method Detail

appendComponent

void appendComponent(Component component)
                     throws NullPointerException,
                            InvalidDataDefinitionException,
                            LeadingTransitionException,
                            EventSemanticsException,
                            BadPropertyException,
                            BadLengthException,
                            AdjacentTransitionException,
                            InsufficientTransitionMaterialException

Appends the given component to this sequence. The length of the sequence is incremented by the size of the component or transition.

If the component is to be the first in the sequence and is a transition, the method fails with a LeadingTransitionException as it is not acceptable to have a transition as the first element of a sequence. Note that this method supports the incremental creation of sequences from start to finish and so could be used to create a sequence that ends in a transition, which is an illegal state.

The method checks that the data definition of the appended component is compatible with that of the sequence.

Parameters:
component - Component to append to this sequence.
Throws:
NullPointerException - The given component is null.
InvalidDataDefinitionException - The kind of data of the component is not compatible with the data definition of the sequence.
LeadingTransitionException - A transition cannot be appended to a sequence so as to become its first component.
EventSemanticsException - The given component is an event that either: does not match the other kinds of event in the sequence; does not have the contextual position property set; does not follow on from the previous event.
BadPropertyException - The given non-event component does not have a length value set.
BadLengthException - The length of the given components is negative.
AdjacentTransitionException - Appending the given transition component would result in two adjacent transitions.
InsufficientTransitionMaterialException - Appending the given component or transition will result in insufficient material for the last transition in the sequence.
See Also:
Event

prependComponent

void prependComponent(Component component)
                      throws NullPointerException,
                             InvalidDataDefinitionException,
                             LeadingTransitionException

Prepends the given component to this sequence. The length of the sequence is incremented by the size of the component.

If the component is a transition, the method fails with a LeadingTransitionException as it is not acceptable to have a transition as the first element of a sequence. Use insertComponentAt(int, Component) instead.

The method checks that the data definition of the appended component is compatible with that of the sequence.

Parameters:
component - Component to prepend to this sequence.
Throws:
NullPointerException - The given component is null.
InvalidDataDefinitionException - The kind of data of the component is not compatible with the data definition of the sequence.
LeadingTransitionException - A transition cannot be appended to a sequence so as to become its first or last component.

insertComponentAt

void insertComponentAt(@UInt32
                       int index,
                       Component component)
                       throws NullPointerException,
                              IndexOutOfBoundsException,
                              InvalidDataDefinitionException,
                              LeadingTransitionException,
                              AdjacentTransitionException,
                              InsufficientTransitionMaterialException

Insert the given component into this sequence at the given index. The length of the sequence is incremented by the size of the component, unless the component is a transition. Indices of components higher than the given index will be increased by one to accommodate the new component.

If the component is a transition, the method checks that it is not the first object in the sequence, and that it is not neighbouring another transition. It also verifies that there is enough source material on either side of the transition. Note that this method supports the incremental creation of sequences from start to finish and so could be used to create a sequence that ends in a transition, which is an illegal state.

The method checks that the data definition of the appended component is compatible with that of the sequence.

Parameters:
index - 0-based index to insert the new component at.
component - Component to insert into the sequence.
Throws:
NullPointerException - The given component to insert is null.
IndexOutOfBoundsException - The index is outside the acceptable range for the sequence.
InvalidDataDefinitionException - The kind of data of the component is not compatible with the data definition of the sequence.
LeadingTransitionException - A transition component cannot be inserted as first element of the sequence.
AdjacentTransitionException - Inserting a transition and the given index will result in two neighbouring transitions, which is not permitted.
InsufficientTransitionMaterialException - Not enough source material exists either side of the given transition for the transition to work.

getComponentAt

Component getComponentAt(@UInt32
                         int index)
                         throws IndexOutOfBoundsException

Returns the component at the given index through this sequence.

Parameters:
index - Index of component through this sequence
Returns:
Component at the given index of this sequence.
Throws:
IndexOutOfBoundsException - The index is outside the acceptable range for this sequence.

removeComponentAt

void removeComponentAt(@UInt32
                       int index)
                       throws IndexOutOfBoundsException

Removes the component at the given index from this sequence. Components already existing at indices higher than the given index will be moved to the next lower index to accommodate.

Note that removal of a component from a sequence may result in the sequence being in an illegal state.

Parameters:
index - Index of component to be removed.
Throws:
IndexOutOfBoundsException - The index is outside the acceptable range for the sequence.

countComponents

@UInt32
int countComponents()

Returns the number of components in this sequence.

Returns:
Number of components in this sequence.

getComponents

List<? extends Component> getComponents()

Returns a list of all the components of this sequence.

Returns:
Shallow copy of the list containing all of the components of the sequence.

Media Authoring
with Java API

(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.