net.sf.ivmaidns.util
Class ObservedCore

java.lang.Object
  net.sf.ivmaidns.util.ObservedCore

All Implemented Interfaces:

MultiObservable, TrimToSizeable, Verifiable

Direct Known Subclasses:

ActivityCore, Storage, StorageEnumerator

public class ObservedCore
extends java.lang.Object
implements MultiObservable, TrimToSizeable, Verifiable

Root class for observable objects. This is an implementation of MultiObservable. An observable object (which class extends or includes a variable of this class) represents mutable 'data' in the model-view paradigm. Each time an observable object is changed, it must call notifyObservers(this, argument) to notify every registered observer agent (in an unspecified order) about the event, where argument describes the occurred changes (as it must be specified for a particular object). 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.

Version:

2.0

Author:

Ivan Maidanski

See Also:

Notifiable

Constructor Summary

ObservedCore()
Constructs an observable object.

Method Summary

void	addObserver(Notifiable agent) Registers one more observer.
protected java.lang.Object	clone() Creates and returns a copy of this object.
boolean	hasObservers() Tests whether this observable object has any observers.
void	integrityCheck() Verifies this object for its integrity.
void	notifyObservers(MultiObservable observed, java.lang.Object argument) Notifies each registered observer agent on the event that just occurred.
void	removeObserver(Notifiable agent) Unregisters a particular observer.
void	trimToSize() Frees extra memory.

Methods inherited from class java.lang.Object

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

Constructor Detail

ObservedCore

public ObservedCore()

Constructs an observable object.

See Also:

addObserver(net.sf.ivmaidns.util.Notifiable)

Method Detail

trimToSize

public void trimToSize()

Frees extra memory. This method re-allocates internal observers list, setting its length to the current possible minimum. Observer agents are not modified. Observers order is not changed. This method must be synchronized outside.

Specified by:

trimToSize in interface TrimToSizeable

See Also:

addObserver(net.sf.ivmaidns.util.Notifiable), removeObserver(net.sf.ivmaidns.util.Notifiable)

addObserver

public void addObserver(Notifiable agent)
                 throws java.lang.NullPointerException

Registers one more observer. An observer registration means that agent will be updated (notified) each time this observable object is changed somehow. If the specified agent is already registered here then the registration of this agent is not performed (no duplicate agents). Internal observers array may be re-allocated (to have at least enough space for holding all registered agents). If an exception is thrown then state of this object is not changed. This method must be synchronized outside. Important notes: registered observers are not accessible for other objects, not copied when this object is cloned, and not serialized.

Specified by:

addObserver in interface MultiObservable

Parameters:

agent - the observer agent (must be non-null) to be registered.

Throws:

java.lang.NullPointerException - if agent is null.

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

removeObserver(net.sf.ivmaidns.util.Notifiable), notifyObservers(net.sf.ivmaidns.util.MultiObservable, java.lang.Object)

removeObserver

public void removeObserver(Notifiable agent)

Unregisters a particular observer. If agent is null or equals(agent) is false for every registered agent then nothing is performed. Else the specified agent is removed from observers of this observable object (this action is just the opposite to the agent registration). Internal observers array is not re-allocated. This method must be synchronized outside.

Specified by:

removeObserver in interface MultiObservable

Parameters:

agent - the observer agent (may be null) to be unregistered.

See Also:

addObserver(net.sf.ivmaidns.util.Notifiable)

hasObservers

public final boolean hasObservers()

Tests whether this observable object has any observers. If the result is false then there is no observers which must be updated so at this moment it is useless to call notifyObservers(MultiObservable, Object) method.

Returns:

false only if no observer agents registered.

See Also:

addObserver(net.sf.ivmaidns.util.Notifiable), removeObserver(net.sf.ivmaidns.util.Notifiable), notifyObservers(net.sf.ivmaidns.util.MultiObservable, java.lang.Object)

notifyObservers

public void notifyObservers(MultiObservable observed,
                            java.lang.Object argument)
                     throws java.lang.RuntimeException

Notifies each registered observer agent on the event that just occurred. Agents notification means calling update(observed, argument) for every agent which is in observers list of this observable object. The order of notification is undefined. Important notes: notification should be done after committing of the occurred modification of observed; argument object should provide minimum yet enough information to effectively find out new state of the object; RuntimeException (and OutOfMemoryError) should be handled properly (since some of the agents may have already been notified before the exception is thrown); this method should be called only from the observable object (so, in subclasses this method should be overridden with a public dummy method).

Parameters:

observed - the observed object (may be null, but normally this).

argument - the argument (may be null), describing the occurred event.

Throws:

java.lang.RuntimeException - if the notification process for some registered agent has failed (a custom exception, not all of the agents may have been notified).

java.lang.OutOfMemoryError - if there is not enough memory to complete notification (not all of the agents may have been notified).

See Also:

addObserver(net.sf.ivmaidns.util.Notifiable)

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException

Creates and returns a copy of this object. This method overrides clone() of Object to prevent copying of observers list (it is set empty in the returned observable object). Of course, this method works only for subclasses which implement Cloneable interface. This method may be overridden and made public in the subclasses if needed.

Overrides:

clone in class java.lang.Object

Returns:

a copy (may be null) of this instance.

Throws:

java.lang.CloneNotSupportedException - if Cloneable interface is not implemented (in a subclass).

java.lang.OutOfMemoryError - if there is not enough memory.

Since:

1.1

integrityCheck

public void integrityCheck()

Verifies this object for its integrity. Observer agents of this observable are not checked. For debug purpose only.

Specified by:

integrityCheck in interface Verifiable

Throws:

java.lang.InternalError - if integrity violation is detected.

Since:

2.0