net.sf.ivmaidns.util
Class ActivityCore

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

All Implemented Interfaces:

java.lang.Runnable, MultiObservable, SafeRunnable, TrimToSizeable, Verifiable

public abstract class ActivityCore
extends ObservedCore
implements SafeRunnable, java.lang.Runnable

Class for active observable entities. This is a basis implementation of SafeRunnable interface, which also extends ObservedCore class, providing an easy way to create a custom active observable object, which starts running on its creation and stops when done or when safe stop is requested by the user of the object (or when Java Virtual Machine terminates). Active objects may be also interrupted, suspended and resumed. The activity of such object is implemented through the encapsulation of Thread instance. Created thread is not daemon (unless current thread is a daemon). Important notes: the Java Virtual Machine exits when the only threads running are all daemons or if exit(int) method of Runtime class is called; Runnable interface is implemented here entirely for the internal purpose.

Version:

2.0

Author:

Ivan Maidanski

Field Summary

protected static int

IDLE_SLEEP_MILLIS Represents the default idle sleep time in milliseconds.

Constructor Summary

ActivityCore(java.lang.String name)
Constructs an active observable object with the specified thread name.

Method Summary

protected java.lang.Object	clone() Creates and returns a copy of this object.
protected void	done() Custom clean-up method which is executed before normal termination of this active object.
protected void	init() Custom initialization method which is executed just at the beginning of the execution of this active object.
void	integrityCheck() Verifies this object for its integrity.
void	interrupt() Interrupts sleeping or waiting inside active object.
boolean	isAlive() Tests whether this active object is still alive.
boolean	isSuspended() Tests whether this active object is suspended.
void	join() Waits while active object is alive.
protected abstract boolean	loop() Custom action main method which is executed in this active object as many times as needed.
void	resume() Resumes running after suspend.
void	run() The thread execution body (an internal method).
void	stop() Initiates safe stop operation.
void	suspend() Initiates safe suspend operation.
void	trimToSize() Frees extra memory.
void	waitSuspend() Initiates and waits for safe suspend.

Methods inherited from class net.sf.ivmaidns.util.ObservedCore

addObserver, hasObservers, notifyObservers, removeObserver

Methods inherited from class java.lang.Object

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

Field Detail

IDLE_SLEEP_MILLIS

protected static final int IDLE_SLEEP_MILLIS

Represents the default idle sleep time in milliseconds. This int (positive) value is used as a default argument for wait(long) of Object class and for sleep(long) of Thread class when infinitely waiting for a particular event.

Since:

2.0

See Also:

Constant Field Values

Constructor Detail

ActivityCore

public ActivityCore(java.lang.String name)
             throws java.lang.NullPointerException

Constructs an active observable object with the specified thread name. Created thread is marked as a daemon only if current thread is a daemon. The thread is started (activated) just after its creation. The user of this constructed object may safely suspend/resume or stop its activity at any time (while it is running). name is entirely used to identify the thread in the computer system (for the purpose of the system performance monitoring).

Parameters:

name - the name (must be non-null) of created thread.

Throws:

java.lang.NullPointerException - if name is null.

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

java.lang.InternalError - if Java VM internal error occurs or if the security manager prohibits the creation of a new thread.

See Also:

run(), stop(), join(), isAlive()

Method Detail

init

protected void init()

Custom initialization method which is executed just at the beginning of the execution of this active object. This method is only called internally once (in the encapsulated thread, not in the constructor) before calling loop(). If OutOfMemoryError is thrown then loop() is skipped and done() is called. This method should be protected final in the subclasses if overridden (if not overridden then it is dummy).

Throws:

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

See Also:

ActivityCore(java.lang.String), loop(), done(), run()

loop

protected abstract boolean loop()

Custom action main method which is executed in this active object as many times as needed. This method is only called internally (in the encapsulated thread) many times (may be none) while soft stop is not requested and result is true. If OutOfMemoryError is thrown then loop() is not called anymore and done() is called. This method should be protected final in the subclasses.

Returns:

true only if this method requests to be called again.

Throws:

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

See Also:

init(), done(), run(), stop()

done

protected void done()

Custom clean-up method which is executed before normal termination of this active object. This method is called internally once (in the encapsulated thread) at the end after calling loop() method. This method is called even if soft stop operation is being performed or even if loop() (or init()) method has just thrown OutOfMemoryError. If this method throws OutOfMemoryError then it is caught silently. This method should be protected final in the subclasses if overridden (if not overridden then it is dummy).

Throws:

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

See Also:

init(), loop(), run(), stop()

run

public final void run()

The thread execution body (an internal method). This method is called internally (only once) by Thread object when thread of this is initialized (when this active object is constructed). This method first calls init() method then calls loop() many times while it returns true, then calls done() (semantics of all these three methods is defined by the subclass), and returns. Each time, before calling loop(), this method analyses the state of suspending and stopping to perform safe suspend/resume and stop operations whenever they are requested by the user of this active object. If suspending is set then this method waits (before calling loop()) while suspending remains set. Setting of stopping would stop looping, this method calls done() and returns. If OutOfMemoryError is thrown during execution of these 'init/loop/done' methods then it is silently ignored and has the same effect as if stopping is true. Important notes: on return of this method thread is terminated; if this method is called outside Thread then it does nothing.

Specified by:

run in interface java.lang.Runnable

See Also:

ActivityCore(java.lang.String), suspend(), waitSuspend(), resume(), stop()

trimToSize

public void trimToSize()

Frees extra memory. This method re-allocates internal structures (of the object) releasing unused memory occupied by them. This method must be synchronized outside.

Specified by:

trimToSize in interface TrimToSizeable

Overrides:

trimToSize in class ObservedCore

See Also:

ActivityCore(java.lang.String)

interrupt

public void interrupt()

Interrupts sleeping or waiting inside active object. Interruption means sending a special interrupt signal to each thread of active object (resulting in throwing of InterruptedException inside thread when it is waiting or sleeping). This method returns immediately. This method may be overridden in the subclasses. Important notes: current thread interruption status may be cleared via sleep(0) of Thread class.

Specified by:

interrupt in interface SafeRunnable

See Also:

isAlive()

suspend

public void suspend()

Initiates safe suspend operation. This method just sets suspending flag which signals active object that all its threads (only which are alive) must be safely suspended (turned to sleeping state) as soon as possible. This method returns immediately. This method may be overridden in the subclasses.

Specified by:

suspend in interface SafeRunnable

See Also:

waitSuspend(), resume(), isSuspended(), stop()

waitSuspend

public void waitSuspend()

Initiates and waits for safe suspend. This method sets suspending flag which signals active object that all its threads (only which are alive) must be safely suspended (turned to sleeping state) as soon as possible. This method returns just after all threads of active object have been suspended (or died). This method may be overridden in the subclasses.

Specified by:

waitSuspend in interface SafeRunnable

See Also:

suspend(), resume(), isSuspended()

resume

public final void resume()

Resumes running after suspend. This method clears suspending flag, thus telling active object to resume normal running (stop sleeping) after safe suspend for all its still alive threads. This method returns immediately.

Specified by:

resume in interface SafeRunnable

See Also:

suspend(), waitSuspend(), isSuspended()

stop

public void stop()

Initiates safe stop operation. This method just sets stopping flag which signals active object that all its threads (only which are alive) must be safely terminated (stopped) as soon as possible. This method returns immediately. If active object is suspended then safe stop operation begins just when resuming. This method may be overridden in the subclasses.

Specified by:

stop in interface SafeRunnable

See Also:

suspend(), resume(), join(), isSuspended(), isAlive()

join

public final void join()

Waits while active object is alive. This method infinitely waits for the death (termination) of all threads inside this active object.

Specified by:

join in interface SafeRunnable

See Also:

stop(), isAlive(), waitSuspend()

isSuspended

public final boolean isSuspended()

Tests whether this active object is suspended. This method just immediately returns suspended flag which is true only when active object is in safe-suspend state (and alive).

Specified by:

isSuspended in interface SafeRunnable

Returns:

true if and only if active object is suspended.

See Also:

suspend(), waitSuspend(), resume(), isAlive()

isAlive

public final boolean isAlive()

Tests whether this active object is still alive. This method just immediately returns the flag indicating that one or more threads (inside this active object) have not died yet.

Specified by:

isAlive in interface SafeRunnable

Returns:

true if and only if active object is alive.

See Also:

stop(), join(), isSuspended()

clone

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

Creates and returns a copy of this object. The implementation of this method prohibits (since thread object is not cloneable) the usage of standard clone() method of Object (even in the subclasses) by throwing CloneNotSupportedException. But, if needed, this method may be overridden (and made public) in the subclasses, providing 'pseudo-cloning' (through the constructor of a subclass).

Overrides:

clone in class ObservedCore

Returns:

a copy (not null and != this) of this instance.

Throws:

java.lang.CloneNotSupportedException - if cloning is not implemented.

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

Since:

1.1

integrityCheck

public void integrityCheck()

Verifies this object for its integrity. For debug purpose only.

Specified by:

integrityCheck in interface Verifiable

Overrides:

integrityCheck in class ObservedCore

Throws:

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

Since:

2.0