org.ascape.model.event
Class DefaultScapeListener

java.lang.Object
  org.ascape.model.event.DefaultScapeListener

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.EventListener, ScapeListener, HasName

Direct Known Subclasses:

NonGraphicView, Query, RuntimeEnvironment, ScapeListenerDelegate, ScapeTransitionListener

public abstract class DefaultScapeListener
extends java.lang.Object
implements ScapeListener, java.io.Serializable

A listener to an agent scape. When a scape is updated, it is the listener's responsility to update itself, and then inform the scape that updating is finished, so that the scape can continue iterating through its rules. DefaultScapeListener provides a good reference implementation of the listener contract. By default, this is assumed to be a nongrphic view. Overide isGraphic to return true if you are implementing a graphic view.

Since:

1.0

Version:

2.9.1

Author:

Miles Parker

See Also:

Serialized Form

Field Summary

protected boolean	listeningToScape Is this scape view delegate currently listening to a scape? Seperated from wether scape is null, becuase we want to be able to save old scape.
protected java.lang.String	name The name of the view.
Scape	scape The scape being listened to.

Constructor Summary

DefaultScapeListener()
Constructs a default listener.

DefaultScapeListener(java.lang.String name)
Constructs a default listener.

Method Summary

java.lang.Object	clone() Clones this object.
void	environmentQuiting(ScapeEvent scapeEvent) Method called as the scape is about to be closed.
java.lang.String	getName() Returns a name for the view as defined by set name.
Scape	getScape() Returns the scape the listner is listening to.
boolean	isGraphic() Is this a grpahic view? By default, returns false.
boolean	isLifeOfScape() Returns true (default) if the listener is intended to be used only for the current scape; typical of all but control related listeners.
boolean	isNotifyScapeAutomatically() Should the scape be notified automatically? Default is true.
void	notifyScapeUpdated() Calls the observed scape and notifies it that the view has finished updating its state.
void	scapeAdded(ScapeEvent scapeEvent) Add the view to the scape, registering it as a listener, and ensuring that it hasn't been added to any other scapes.
void	scapeClosing(ScapeEvent scapeEvent) Method called as the scape is about to be closed.
void	scapeDeserialized(ScapeEvent scapeEvent) Method called immediatly after a model is deserialized.
void	scapeInitialized(ScapeEvent scapeEvent) Called immediatly after the scape is initialized.
void	scapeIterated(ScapeEvent scapeEvent) Called immediatly after scape is iterated.
void	scapeNotification(ScapeEvent scapeEvent) Notifies the delegating view that something has happened on the scape.
void	scapeRemoved(ScapeEvent scapeEvent) Notifies the listener that the scape has removed it.
void	scapeSetup(ScapeEvent scapeEvent) Method called when the scape is ready for setup.
void	scapeStarted(ScapeEvent scapeEvent) Called immediatly after the scape is started.
void	scapeStopped(ScapeEvent scapeEvent) Called immediatly after the scape is stopped.
void	setName(java.lang.String name) Sets the name of this view.
void	setNotifyScapeAutomatically(boolean notifyScapeAutomatically) Sets wether the scape is notified automatically.
java.lang.String	toString() Returns a short description of this view.

Methods inherited from class java.lang.Object

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

Field Detail

scape

public Scape scape

The scape being listened to.

listeningToScape

protected boolean listeningToScape

Is this scape view delegate currently listening to a scape? Seperated from wether scape is null, becuase we want to be able to save old scape.

name

protected java.lang.String name

The name of the view.

Constructor Detail

DefaultScapeListener

public DefaultScapeListener()

Constructs a default listener.

DefaultScapeListener

public DefaultScapeListener(java.lang.String name)

Constructs a default listener.

Parameters:

name - a user relevant name for this view

Method Detail

scapeInitialized

public void scapeInitialized(ScapeEvent scapeEvent)

Called immediatly after the scape is initialized.

Specified by:

scapeInitialized in interface ScapeListener

Parameters:

scapeEvent - the scape event

scapeStarted

public void scapeStarted(ScapeEvent scapeEvent)

Called immediatly after the scape is started.

Specified by:

scapeStarted in interface ScapeListener

Parameters:

scapeEvent - the scape event

scapeStopped

public void scapeStopped(ScapeEvent scapeEvent)

Called immediatly after the scape is stopped.

Specified by:

scapeStopped in interface ScapeListener

Parameters:

scapeEvent - the scape event

scapeIterated

public void scapeIterated(ScapeEvent scapeEvent)

Called immediatly after scape is iterated.

Specified by:

scapeIterated in interface ScapeListener

Parameters:

scapeEvent - the scape event

scapeSetup

public void scapeSetup(ScapeEvent scapeEvent)

Method called when the scape is ready for setup. That is, the scape has been created (or it has just finished its previous run) but it has not yet been initialized. This is an appropriate place to change model paramters, persent user's with options, etc.

Specified by:

scapeSetup in interface ScapeListener

Parameters:

scapeEvent - the scape event

scapeClosing

public void scapeClosing(ScapeEvent scapeEvent)

Method called as the scape is about to be closed. Allows any final view cleanup.

Specified by:

scapeClosing in interface ScapeListener

Parameters:

scapeEvent - the scape event

environmentQuiting

public void environmentQuiting(ScapeEvent scapeEvent)

Method called as the scape is about to be closed. Allows any final view cleanup.

Specified by:

environmentQuiting in interface ScapeListener

Parameters:

scapeEvent - the scape event

scapeDeserialized

public void scapeDeserialized(ScapeEvent scapeEvent)

Method called immediatly after a model is deserialized.

Specified by:

scapeDeserialized in interface ScapeListener

Parameters:

scapeEvent - the scape event

scapeAdded

public void scapeAdded(ScapeEvent scapeEvent)
                throws java.util.TooManyListenersException

Add the view to the scape, registering it as a listener, and ensuring that it hasn't been added to any other scapes.

Specified by:

scapeAdded in interface ScapeListener

Parameters:

scapeEvent - the event for this scape to make this view the observer of

Throws:

java.util.TooManyListenersException - the too many listeners exception

java.util.TooManyListenersException - on attempt to add a scape when one is allready added

scapeRemoved

public void scapeRemoved(ScapeEvent scapeEvent)

Notifies the listener that the scape has removed it. The scape event event must be from the scape that this listener is listening to.

Specified by:

scapeRemoved in interface ScapeListener

Parameters:

scapeEvent - the scape removed notification event

See Also:

scapeAdded

scapeNotification

public void scapeNotification(ScapeEvent scapeEvent)

Notifies the delegating view that something has happened on the scape. Calls the scapeIterated, setup, started, stoped, closing, or onDeserialized methods as appropriate. Calls notifyScapeUpdated, so you will need to overide this method if you do not want to notify the scape immediatly upon the scape... methods returning.

Specified by:

scapeNotification in interface ScapeListener

Parameters:

scapeEvent - a scape event update

notifyScapeUpdated

public void notifyScapeUpdated()

Calls the observed scape and notifies it that the view has finished updating its state. This method must be called after receiving any scapeNotification event or the model will stall.

isGraphic

public boolean isGraphic()

Is this a grpahic view? By default, returns false. Overide to return true if this is a graphic view.

Specified by:

isGraphic in interface ScapeListener

Returns:

true, if is graphic

isLifeOfScape

public boolean isLifeOfScape()

Returns true (default) if the listener is intended to be used only for the current scape; typical of all but control related listeners.

Specified by:

isLifeOfScape in interface ScapeListener

Returns:

true, if is life of scape

getScape

public Scape getScape()

Returns the scape the listner is listening to.

Specified by:

getScape in interface ScapeListener

Returns:

the scape

isNotifyScapeAutomatically

public boolean isNotifyScapeAutomatically()

Should the scape be notified automatically? Default is true.

Returns:

true, if is notify scape automatically

setNotifyScapeAutomatically

public void setNotifyScapeAutomatically(boolean notifyScapeAutomatically)

Sets wether the scape is notified automatically. That is, when the listener methods finish, should the scape be notified? Normally this should be true - anytime everything needed to update from the current scape state is known when the methods exit. But in some cases the sacape should not continue iterating until something else happens. The most obvious example is in a graphics view, where we need to be sure that the actual graphics are updated before the scape moves on. But other cases where you might want to wait might also happen; for example, you may want to wait for some other state to change first, you may need to wait for a process (like a database write) to occur in another thread, etc.

Parameters:

notifyScapeAutomatically - true to send a respond update event back immediatly, false to wait

getName

public java.lang.String getName()

Returns a name for the view as defined by set name.

Specified by:

getName in interface HasName

Returns:

the name

setName

public final void setName(java.lang.String name)

Sets the name of this view.

Parameters:

name - a user relevant name for this view

clone

public java.lang.Object clone()

Clones this object.

Specified by:

clone in interface ScapeListener

Overrides:

clone in class java.lang.Object

Returns:

the object

toString

public java.lang.String toString()

Returns a short description of this view. Sames as name unless overridden.

Overrides:

toString in class java.lang.Object

Returns:

the string