com.flagstone.transform.action
Class ExceptionHandler

java.lang.Object
  com.flagstone.transform.action.ExceptionHandler

All Implemented Interfaces:

Action, Copyable<Action>, SWFEncodeable

public final class ExceptionHandler
extends Object
implements Action

The ExceptionHandler class is used to represent try..catch blocks in Actionscript.

When an exception is thrown, the object can be assigned to either one of the Flash Player's 256 internal registers or to a variable in memory.

The ExceptionHandler class contains three lists of actions supporting the standard syntax for an exception with try, catch and finally blocks. Both the catch and finally blocks are optional when defining an exception, the corresponding arguments in constructors and methods may be set to empty.

Nested Class Summary

static class

ExceptionHandler.Builder The Builder class is used to generate a new ExceptionHandler object using a small set of convenience methods.

Constructor Summary

ExceptionHandler(ExceptionHandler.Builder builder)
Creates and initialises an ExceptionHandler using parameters defined in the Builder.

ExceptionHandler(ExceptionHandler object)
Creates and initialises an ExceptionHandler action using the values copied from another ExceptionHandler.

ExceptionHandler(int index, List<Action> tryArray, List<Action> catchArray, List<Action> finallyArray)
Constructs a new exception handler with the thrown object assigned to one of the Flash Player's internal registers.

ExceptionHandler(String name, List<Action> tryArray, List<Action> catchArray, List<Action> finallyArray)
Creates a new exception handler with the thrown object assigned to a local variable.

ExceptionHandler(SWFDecoder coder, Context context)
Creates and initialises an ExceptionHandler action using values encoded in the Flash binary format.

Method Summary

ExceptionHandler	copy() Creates a complete copy of this object.
void	encode(SWFEncoder coder, Context context) Encode an object to the Flash binary format.
List<Action>	getCatchActions() Returns the list of actions executed in the catch block.
List<Action>	getFinalActions() Returns the list of actions executed in the finally block.
int	getRegister() Returns the index of the register that the exception object is assigned to.
List<Action>	getTryActions() Returns the list of actions executed in the try block.
String	getVariable() Returns the name of the variable which the exception object is assigned to.
int	prepareToEncode(Context context) Prepare an object for encoding, returning the expected size of an object when it is encoded.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ExceptionHandler

public ExceptionHandler(ExceptionHandler.Builder builder)

Creates and initialises an ExceptionHandler using parameters defined in the Builder.

Parameters:

builder - a Builder object containing the parameters to generate the ExceptionHandler.

ExceptionHandler

public ExceptionHandler(SWFDecoder coder,
                        Context context)
                 throws IOException

Creates and initialises an ExceptionHandler action using values encoded in the Flash binary format.

Parameters:

coder - an SWFDecoder object that contains the encoded Flash data.

context - a Context object used to manage the decoders for different type of object and to pass information on how objects are decoded.

Throws:

IOException - if an error occurs while decoding the data.

ExceptionHandler

public ExceptionHandler(String name,
                        List<Action> tryArray,
                        List<Action> catchArray,
                        List<Action> finallyArray)

Creates a new exception handler with the thrown object assigned to a local variable.

Parameters:

name - the name of the variable that the thrown object will be assigned to. Must not be null.

tryArray - actions that will be executed in the try block of the exception. Must not be null.

catchArray - actions that will be executed in the catch block of the exception, if one is defined. This may be empty if no catch block is required - the exception will be handled by another catch block higher in the exception tree.

finallyArray - actions that will be executed in the finally block of the exception, if one is defined. This may be empty if no finally block is required.

ExceptionHandler

public ExceptionHandler(int index,
                        List<Action> tryArray,
                        List<Action> catchArray,
                        List<Action> finallyArray)

Constructs a new exception handler with the thrown object assigned to one of the Flash Player's internal registers.

Parameters:

index - the number of the register that the thrown object will be assigned to. Must be in the range 0..255.

tryArray - actions that will be executed in the try block of the exception. Must not be null.

catchArray - actions that will be executed in the catch block of the exception, if one is defined. This may be empty if no catch block is required - the exception will be handled by another catch block higher in the exception tree.

finallyArray - actions that will be executed in the finally block of the exception, if one is defined. This may be empty is no finally block is required.

ExceptionHandler

public ExceptionHandler(ExceptionHandler object)

Creates and initialises an ExceptionHandler action using the values copied from another ExceptionHandler.

Parameters:

object - an ExceptionHandler object from which the values will be copied. References to immutable objects will be shared.

Method Detail

getVariable

public String getVariable()

Returns the name of the variable which the exception object is assigned to.

Returns:

the name of the function. Returns null if the exception object will be assigned to a register.

getRegister

public int getRegister()

Returns the index of the register that the exception object is assigned to.

Returns:

the number of register. Returns 0 if the exception object will be assigned to a local variable.

getTryActions

public List<Action> getTryActions()

Returns the list of actions executed in the try block.

Returns:

the list of actions for the try block.

getCatchActions

public List<Action> getCatchActions()

Returns the list of actions executed in the catch block.

Returns:

the list of actions for the catch block.

getFinalActions

public List<Action> getFinalActions()

Returns the list of actions executed in the finally block.

Returns:

the list of actions for the finally block.

copy

public ExceptionHandler copy()

Creates a complete copy of this object.

Specified by:

copy in interface Copyable<Action>

Returns:

a deep-copy of this object. New instances of mutable objects are copied and immutable instances are shared.

toString

public String toString()

Overrides:

toString in class Object

prepareToEncode

public int prepareToEncode(Context context)

Prepare an object for encoding, returning the expected size of an object when it is encoded. This method also used to initialise variables, such as offsets and flags that will be used when the object is encoded. Generally the method returns the size in bytes, however when called on objects that use bit fields such as shapes the methods will return the size in bits.

Specified by:

prepareToEncode in interface SWFEncodeable

Parameters:

context - an Context that allows information to be passed between objects to control how they are initialised for encoding.

Returns:

the size of the object when it is encoded.

encode

public void encode(SWFEncoder coder,
                   Context context)
            throws IOException

Encode an object to the Flash binary format.

Specified by:

encode in interface SWFEncodeable

Parameters:

coder - an SWFEncoder object.

context - an Context that allows information to be passed between objects to control how they are initialised for encoding.

Throws:

IOException - if an error occurs while encoding the object.