net.sf.ivmaidns.util
Interface Notifiable

All Superinterfaces:
Verifiable

public interface Notifiable
extends Verifiable

Interface for custom observer agents. A class should implement (or should have a private class which implements) this interface when it wants to be informed of changes in the observable object. Normally, observer agent serves as an intermediate entity between one or more observed entities and the application entity which wants to be notified (with details) only on the events in these observed objects. Verifiable interface is extended to allow integrity checking for typical agent objects. Important notes: agents must not modify observed object anyhow; notification should be performed just after changes; this notification mechanism has nothing to do with threads and is completely separate from the 'wait-notify' mechanism of Object. Here is the usage example of an observer agent:

 final class MyAgent // hidden helper class
 implements Notifiable
 {
 private final MyClass myClass; // myClass != null
 protected MyAgent(MyClass myClass)
 throws NullPointerException
 {
 myClass.equals(myClass);
 this.myClass = myClass;
 }
 public void update(MultiObservable observed, Object argument)
 {
 MyClass myClass = this.myClass;
 if (argument instanceof MyEvent && myClass.observed == observed)
 // safe (private) actions on myClass
 }
 public void integrityCheck()
 {
 if (myClass == null)
 throw new InternalError("myClass: null");
 }
 }
 private transient Notifiable agent = new MyAgent(this);
 . . .
 observed.addObserver(agent);
 . . .
 observed.removeObserver(agent); // stop observing
 

Version:
2.0
Author:
Ivan Maidanski
See Also:
MultiObservable

Method Summary
 void update(MultiObservable observed, java.lang.Object argument)
          Notifies this observer agent on a particular event that just occurred.
 
Methods inherited from interface net.sf.ivmaidns.util.Verifiable
integrityCheck
 

Method Detail

update

void update(MultiObservable observed,
            java.lang.Object argument)
Notifies this observer agent on a particular event that just occurred. This method is called whenever observed object is changed. Important notes: observed object should not be modified during the notification; types of observed and argument should be checked inside; no access should be provided to the instance of this interface (since this method is public) outside hidden notifyObservers method of observed object; RuntimeException (and OutOfMemoryError) may be thrown if a notification failure has occurred.

Parameters:
observed - the observed object (may be null, should be checked inside).
argument - the argument (may be null, should be checked inside) describing the occurred event.
Throws:
java.lang.RuntimeException - if the notification process has failed (a custom exception).
java.lang.OutOfMemoryError - if there is not enough memory (to perform notification).