com.sun.jini.example.basic.ex1.activation
Class ServiceDeactivator

java.lang.Object
  extended bycom.sun.jini.example.basic.ex1.activation.AbstractDeactivator
      extended bycom.sun.jini.example.basic.ex1.activation.ServiceDeactivator

public class ServiceDeactivator
extends AbstractDeactivator

Class which implements the criteria for deactivating an activatable object as defined by the abstract class AbstractDeactivator. An activatable object that wishes to be deactivated should instantiate this class in its constructor. This class determines whether or not an active object should be deactivated based on a measure of "busy-ness"; which any class that extends the AbstractDeactivator class must define. Because deactivation and reactivation are 'expensive' processes, this class will NOT deactivate an object if at least N remote methods of the object have been invoked, and un-processed, in the past T milliseconds; where the values of N and T are supplied by the activatable object that wishes to be deactivated.


Constructor Summary
ServiceDeactivator(java.rmi.activation.ActivationID activationID)
          Constructor invoked by an activatable object which supplies neither a wait interval nor a 'busy-ness' threshold; allowing both to revert to their default values.
ServiceDeactivator(java.rmi.activation.ActivationID activationID, int threshold)
          Constructor invoked by an activatable object which supplies only its own 'busy-ness' threshold; but lets the wait interval revert to the default value.
ServiceDeactivator(java.rmi.activation.ActivationID activationID, long waitMS)
          Constructor invoked by an activatable object which supplies only its own wait interval; but lets the 'busy-ness' threshold revert to the default value.
ServiceDeactivator(java.rmi.activation.ActivationID activationID, long waitMS, int threshold)
          Constructor invoked by an activatable object which supplies its own wait interval and 'busy-ness' threshold.
 
Method Summary
protected  boolean deactivateObject(java.rmi.activation.ActivationID activationID)
          This method will attempt to change the state of the object from active to inactive.
protected  void decreaseBusyMetric()
          This method 'decrements' the measure of how 'busy' an activatable object is.
protected  void handleException(java.lang.Exception e)
          This method handles any Exception in a manner that is appropriate for the operational environment of the object that wishes to be deactivated.
 void increaseBusyMetric()
          This method 'increments' the measure of how 'busy' an activatable object is.
protected  boolean objectIsBusy()
          This method measures how 'busy' the activatable object is and returns true if it is too busy to be deactivated; otherwise it returns false indicating deactivation may be safely attempted.
protected  boolean objectIsIdle()
          This method returns an indication of whether or not the object that wishes to be deactivated has entered a state in which it is appropriate to begin deactivation attempts.
protected  void waitBeforeDeactivation()
          This method will wait an amount of time before returning.
protected  void wakeDeactivatorThread()
          This method will wake this class' DeactivatorThread from its wait state.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ServiceDeactivator

public ServiceDeactivator(java.rmi.activation.ActivationID activationID,
                          long waitMS,
                          int threshold)
Constructor invoked by an activatable object which supplies its own wait interval and 'busy-ness' threshold. Deactivation will NOT be attempted if at least threshold remote methods of the object have been invoked, and un-processed, in the past waitMS milliseconds.

Parameters:
activationID - ActivationID of the activatable object
waitMS - milliseconds to wait before retrying deactivation
threshold - deactivation will NOT be attempted if at least this many remote methods have been invoked, and un-processed, in the past waitMS milliseconds.

ServiceDeactivator

public ServiceDeactivator(java.rmi.activation.ActivationID activationID,
                          long waitMS)
Constructor invoked by an activatable object which supplies only its own wait interval; but lets the 'busy-ness' threshold revert to the default value. Deactivation will NOT be attempted if at least DEFAULT_THRESHOLD remote methods of the object have been invoked, and un-processed, in the past waitMS milliseconds.

Parameters:
activationID - ActivationID of the activatable object
waitMS - milliseconds to wait before retrying deactivation

ServiceDeactivator

public ServiceDeactivator(java.rmi.activation.ActivationID activationID,
                          int threshold)
Constructor invoked by an activatable object which supplies only its own 'busy-ness' threshold; but lets the wait interval revert to the default value. Deactivation will NOT be attempted if at least threshold remote methods of the object have been invoked, and un-processed, in the past DEFAULT_WAIT_MS milliseconds.

Parameters:
activationID - ActivationID of the activatable object

ServiceDeactivator

public ServiceDeactivator(java.rmi.activation.ActivationID activationID)
Constructor invoked by an activatable object which supplies neither a wait interval nor a 'busy-ness' threshold; allowing both to revert to their default values. Deactivation will NOT be attempted if at least DEFAULT_THRESHOLD remote methods of the object have been invoked, and un-processed, in the past DEFAULT_WAIT_MS milliseconds.

Parameters:
activationID - ActivationID of the activatable object
Method Detail

increaseBusyMetric

public void increaseBusyMetric()
Description copied from class: AbstractDeactivator
This method 'increments' the measure of how 'busy' an activatable object is.

Although the definition of the measure of an object's 'busy-ness', as well as the method by which that measure is updated, are left to be defined by the concrete implementation of this method, invoking this method should always result in an increase in that measure in some manner that is meaningful for the activatable object.

Requirement: for any activatable object that employs this class to become inactive, every remote method of that object must invoke this method so as to increase the measure of how 'busy' the object is.

Specified by:
increaseBusyMetric in class AbstractDeactivator
See Also:
AbstractDeactivator.increaseBusyMetric()

decreaseBusyMetric

protected void decreaseBusyMetric()
Description copied from class: AbstractDeactivator
This method 'decrements' the measure of how 'busy' an activatable object is.

Although the definition of the measure of an object's 'busy-ness', as well as the method by which that measure is updated, are left for the concrete implementation of this method, invoking this method should always result in a decrease in that measure in some manner that is meaningful for the activatable object.

This method is only invoked by the DeactivatorThread inner class defined in this class.

Specified by:
decreaseBusyMetric in class AbstractDeactivator
See Also:
AbstractDeactivator.decreaseBusyMetric()

objectIsIdle

protected boolean objectIsIdle()
Description copied from class: AbstractDeactivator
This method returns an indication of whether or not the object that wishes to be deactivated has entered a state in which it is appropriate to begin deactivation attempts. For the purposes of deactivation, this method defines an object to be in an idle state if the busy measure of the object is zero.

This method is used to avoid attempting deactivation before the Activation System has had a chance to complete its activation of the object. Deactivation cannot safely occur if a previously inactive object is in the process of being activated.

Specified by:
objectIsIdle in class AbstractDeactivator
Returns:
boolean if the object that wishes to be deactivated has a busy measure of zero, return true; otherwise return false.
See Also:
AbstractDeactivator.objectIsIdle()

objectIsBusy

protected boolean objectIsBusy()
Description copied from class: AbstractDeactivator
This method measures how 'busy' the activatable object is and returns true if it is too busy to be deactivated; otherwise it returns false indicating deactivation may be safely attempted.

This method is used to determine when to attempt deactivation. The concrete implementation must define a measure of busy-ness as well as a criteria for deactivation that is appropriate for the needs of the object wishing to be deactivated.

Specified by:
objectIsBusy in class AbstractDeactivator
Returns:
boolean if the object that wishes to be deactivated has a busy measure that satisfies deactivation criteria, return true; otherwise return false.
See Also:
AbstractDeactivator.objectIsBusy()

handleException

protected void handleException(java.lang.Exception e)
Description copied from class: AbstractDeactivator
This method handles any Exception in a manner that is appropriate for the operational environment of the object that wishes to be deactivated.

This abstract method allows the concrete implementation of this class to define how an Exception should be handled. Since some objects will have access to a display screen, and some will not, it is important that this class make no assumptions about the mechanism an object will use to deal with such exceptions. Some implementations may decide to log the exception to a screen or to a file, some may ignore the exception, still others may handle the exception in manner that is unique to the application.

Specified by:
handleException in class AbstractDeactivator
See Also:
AbstractDeactivator.handleException(java.lang.Exception)

waitBeforeDeactivation

protected void waitBeforeDeactivation()
Description copied from class: AbstractDeactivator
This method will wait an amount of time before returning. This is used to insert a time delay between deactivation attempts.

If it is desirable to change the delay mechanism employed by this class, or to perform any processing in addition to the delay, then this method should be overridden by the concrete implementation of this class.

Overrides:
waitBeforeDeactivation in class AbstractDeactivator
See Also:
AbstractDeactivator.waitBeforeDeactivation()

wakeDeactivatorThread

protected void wakeDeactivatorThread()
Description copied from class: AbstractDeactivator
This method will wake this class' DeactivatorThread from its wait state. When that thread awakes, it will either attempt to deactivate the object, or it will decrement the busy measure of the object. If it is desirable to perform any processing prior to waking the DeactivatorThread, then this method should be overridden by the concrete implementation of this class.

Requirement: for every concrete implementation of this class, the implementation of the method increaseBusyMetric is required to invoke this method after the busy metric has been increased.

Requirement: if the concrete implementation of this class overrides this method, the overriding implementation is required to invoke super.wakeDeactivatorThread after any preprocessing is performed.

Overrides:
wakeDeactivatorThread in class AbstractDeactivator
See Also:
AbstractDeactivator.wakeDeactivatorThread()

deactivateObject

protected boolean deactivateObject(java.rmi.activation.ActivationID activationID)
                            throws java.rmi.RemoteException,
                                   java.rmi.activation.ActivationException,
                                   java.rmi.activation.UnknownObjectException
Description copied from class: AbstractDeactivator
This method will attempt to change the state of the object from active to inactive. If it is desirable to perform any preprocessing prior to attempting the deactivation of the object, then this method should be overridden by the concrete implementation of this class.

Requirement: if the concrete implementation of this class overrides this method, the overriding implementation is required to invoke super.deactivateObject after any preprocessing is performed.

Overrides:
deactivateObject in class AbstractDeactivator
Parameters:
activationID - id needed to deactivate the activatable object
Throws:
java.rmi.RemoteException
java.rmi.activation.ActivationException
java.rmi.activation.UnknownObjectException
See Also:
AbstractDeactivator.deactivateObject(java.rmi.activation.ActivationID)


Copyright © 2003 Sun Microsystems Corp. All Rights Reserved.