org.graffiti.plugin.algorithm.animation
Class AbstractAnimation

java.lang.Object
  extended by org.graffiti.plugin.algorithm.animation.AbstractAnimation
All Implemented Interfaces:
Animation
Direct Known Subclasses:
BidirectionalAnimation, ForwardAnimation

public abstract class AbstractAnimation
extends Object
implements Animation

Partial implementation of a forward animation (i.e. an animation that does not support steps to previous states). All a client has to do to implement a forward animation is to extend this class and provide implementations for the performClear, isReady, hasNextStep and performNextStep methods. The resulting animation will provide only steps forward and will clear itself when modifications of the underlying graph occur.

As the implementation of GraphModificationPolicy given here relies on the implementation of clear, clients that do not support clear must implement another graph modification policy. Otherwise any attempt to modify a graph while an animation is running will result in an UnsupportedOperationException being thrown.

As any reasonable algorithm will modifiy attributes of the underlying graph, an animation's graph modification policy can be temporarily disabled. This is done by calling the respective methods disableGraphModificationPolicy and enableGraphModificationPolicy. Actually the implementations of clear, nextStep and previousStep given by this class are template methods. The methods doing the actual work are those prefixed with "perform". The template methods disable notifications of graph modifications before any call to the actual worker methods and re-enable them afterwards. So the worker methods are the natural extension points of this class for subclassing clients.

The default implementations of the worker methods all throw UnsupportedOperationException.

A final word of caution: Make sure two and more instances of the same animation can operate on one graph simultaneously. Suppose your implementation of nextStep has the side effect of removing all unnecessary attributes after the last step has been completed. Without further precautions this will violate the principle from above. Suppose one instance of your animation is in the middle of processing when the other instance finished. The first instance will rely on all attributes being present. As the second instance removed some attributes a runtime exception (or worse a weird bug) will occur.

A possible solution to this problem is to track all created instances in a list. Make sure their graph modification policies are all enabled and disabled at the same time and clear them as soon as another instance is created.

Version:
$Revision$ $Date$
Author:
Harald Frankenberger

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.graffiti.plugin.algorithm.animation.Animation
Animation.GraphModificationPolicy
 
Field Summary
protected  Animation.GraphModificationPolicy graphModificationPolicy
          The graph modification policy of this animation.
 
Fields inherited from interface org.graffiti.plugin.algorithm.animation.Animation
EMPTY_ANIMATION
 
Constructor Summary
protected AbstractAnimation()
          Sole constructor for subclass invocation.
 
Method Summary
 void clear()
          Resets this animation to its initial state.
protected  void disableGraphModificationPolicy()
          Disables the graph modification policy of this animation.
protected  void enableGraphModificationPolicy()
          Enables the graph modification policy of this animation.
 Animation.GraphModificationPolicy getGraphModificationPolicy()
          Returns the graph modification policy of this animation.
 String getName()
          Returns the name of this animation.
abstract  boolean hasNextStep()
          Returns true if this animation has a next step.
 boolean hasPreviousStep()
          Returns true if this animation has a previous step.
 boolean isCleared()
          Returns true if this animation is cleared; i.e.
abstract  boolean isReady()
          Returns true if the preconditions of the underlying algorithm are satisfied.
 void nextStep()
          Computes the next state of the underlying algorithm; i.e.
 void performClear()
          Worker method called by the template implementation of clear.
protected  void performNextStep()
          Worker method called by the template implementation of nextStep.
protected  void performPreviousStep()
          Worker method called by the template implementation of previousStep.
 void previousStep()
          Computes the previous state of the underlying algorithm; i.e.
 boolean supportsClear()
          Returns true if this animation supports clearing; i.e.
 boolean supportsPreviousStep()
          Returns true if this animation supports steps to previous states of the underlying algorithm.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

graphModificationPolicy

protected Animation.GraphModificationPolicy graphModificationPolicy
The graph modification policy of this animation.

Constructor Detail

AbstractAnimation

protected AbstractAnimation()
Sole constructor for subclass invocation.

Method Detail

isReady

public abstract boolean isReady()
Returns true if the preconditions of the underlying algorithm are satisfied.

Specified by:
isReady in interface Animation
Returns:
true if the preconditions of the underlying algorithm are satisfied.

supportsClear

public boolean supportsClear()
Returns true if this animation supports clearing; i.e. a call to clear or isCleared will not throw UnsupportedOperationException.

Specified by:
supportsClear in interface Animation
Returns:
true if this animation supports clearing.
See Also:
clear(), isCleared()

isCleared

public boolean isCleared()
Returns true if this animation is cleared; i.e. it is newly created or clear has been called and no change of state has occured yet.

Specified by:
isCleared in interface Animation
Returns:
true if this animation is cleared.
Throws:
UnsupportedOperationException - if this animation does not support clear.
See Also:
supportsClear(), clear()

clear

public void clear()
Resets this animation to its initial state. A call to clear is the only means of resetting this animation if steps to previous states are not supported.

On completion of a call to clear, this animation's state is equivalent to its state immediately after constructor invocation. Note that this implies, that all modifications to this animation's data are undone, too; i.e. data structures are cleared, changes to the underlying graph are undone, etc.

Specified by:
clear in interface Animation

performClear

public void performClear()
Worker method called by the template implementation of clear.

See Also:
clear()

hasNextStep

public abstract boolean hasNextStep()
Returns true if this animation has a next step.

Specified by:
hasNextStep in interface Animation
Returns:
true if this animation has a next step.

supportsPreviousStep

public boolean supportsPreviousStep()
Returns true if this animation supports steps to previous states of the underlying algorithm.

This implementation always returns false.

Specified by:
supportsPreviousStep in interface Animation
Returns:
true if this animation supports steps to previous states of the underlying algorithm.

hasPreviousStep

public boolean hasPreviousStep()
Returns true if this animation has a previous step. Throws UnsupportedOperationException if this animation does not support steps to previous states.

This implementation always throws UnsupportedOperationException.

Specified by:
hasPreviousStep in interface Animation
Returns:
true if this animation has a previous step.
Throws:
UnsupportedOperationException - if this animation does not support steps to previous states.
See Also:
Animation.previousStep(), Animation.supportsPreviousStep()

nextStep

public void nextStep()
Computes the next state of the underlying algorithm; i.e. moves the animation one step forward.

Specified by:
nextStep in interface Animation
Throws:
IllegalStateException - if this animation does not have a next step.
IllegalStateException - if this animation is not ready.
See Also:
Animation.hasNextStep(), Animation.isReady()

performNextStep

protected void performNextStep()
Worker method called by the template implementation of nextStep.

See Also:
nextStep()

previousStep

public void previousStep()
Computes the previous state of the underlying algorithm; i.e. moves this animation one step backwards.

This implementation always throws UnsupportedOperationException.

Specified by:
previousStep in interface Animation
Throws:
IllegalStateException - if this animation does not have a previous step or does not support steps to previous states at all.
IllegalStateException - if this animation is not ready.
UnsupportedOperationException - if this animation does not support steps to previous states.
See Also:
Animation.supportsPreviousStep(), Animation.hasPreviousStep(), Animation.isReady()

performPreviousStep

protected void performPreviousStep()
Worker method called by the template implementation of previousStep.

See Also:
previousStep()

enableGraphModificationPolicy

protected void enableGraphModificationPolicy()
Enables the graph modification policy of this animation.

See Also:
graphModificationPolicy

disableGraphModificationPolicy

protected void disableGraphModificationPolicy()
Disables the graph modification policy of this animation.

See Also:
graphModificationPolicy

getName

public String getName()
Returns the name of this animation.

This implementation returns getClass().getSimpleName().

Specified by:
getName in interface Animation
Returns:
the name of this animation.

getGraphModificationPolicy

public Animation.GraphModificationPolicy getGraphModificationPolicy()
Returns the graph modification policy of this animation.

The returned graph modification policy will clear this animation whenever the underlying graph is modified.

Specified by:
getGraphModificationPolicy in interface Animation
Returns:
the graph modification policy of this animation.
See Also:
Animation.GraphModificationPolicy


Generated at 2012-05-30 11:00:36 PM CEST