org.xins.common.manageable
Class Manageable

java.lang.Object
  org.xins.common.manageable.Manageable

Direct Known Subclasses:

API, org.xins.server.CallingConvention, Function, SessionManager

public abstract class Manageable

extends Object

Abstraction of a manageable object. Abstract base class for classes that support bootstrap, initialization and deinitialization functions.

In environments where Manageable instances are constructed dynamically, they are typically expected to have a public no-argument constructor.

Initially the state of a manageable object is UNUSABLE. In this state, the object should be considered unusable. To change to the USABLE state, the bootstrap(PropertyReader) and init(PropertyReader) methods should be called first, as described below.

The bootstrap(PropertyReader) method can only be called if the state of this object is UNUSABLE. If it finishes successfully, the state then changes to BOOTSTRAPPED.

After that the init(PropertyReader) method should be called to initialize or re-initialize this object. This method can only be called successfully if the current state is either BOOTSTRAPPED or even USABLE.

The deinit() method is called when this object is no longer needed. That changes the state back to UNUSABLE. After that, bootstrap(PropertyReader) could be called again, though.

Since:

XINS 1.0.0

Version:

$Revision: 1.34 $ $Date: 2008/07/04 10:22:41 $

Author:

Ernst de Haan

Nested Class Summary

static class

Manageable.State State of a Manageable object.

Field Summary

static Manageable.State	BOOTSTRAPPED The BOOTSTRAPPED state.
static Manageable.State	BOOTSTRAPPING The BOOTSTRAPPING state.
static Manageable.State	DEINITIALIZING The DEINITIALIZING state.
static Manageable.State	INITIALIZING The INITIALIZING state.
static Manageable.State	UNUSABLE The UNUSABLE state.
static Manageable.State	USABLE The USABLE state.

Constructor Summary

protected

Manageable() Constructs a new Manageable.

Method Summary

protected void	assertUsable() Asserts that this object is currently usable.
void	bootstrap(PropertyReader properties) Performs the bootstrap procedure (wrapper method).
protected void	bootstrapImpl(PropertyReader properties) Performs the bootstrap procedure (actual implementation).
void	deinit() Deinitializes this instance (wrapper method).
protected void	deinitImpl() Deinitializes this instance (actual implementation).
Manageable.State	getState() Gets the current state of this object.
void	init(PropertyReader properties) Performs the initialization procedure (wrapper method).
protected void	initImpl(PropertyReader properties) Performs the initialization procedure (actual implementation).
boolean	isBootstrapped() Determines if this object is currently bootstrapped.
boolean	isUsable() Determines if this object is currently usable.

Methods inherited from class java.lang.Object

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

Field Detail

UNUSABLE

public static final Manageable.State UNUSABLE

The UNUSABLE state.

BOOTSTRAPPING

public static final Manageable.State BOOTSTRAPPING

The BOOTSTRAPPING state.

BOOTSTRAPPED

public static final Manageable.State BOOTSTRAPPED

The BOOTSTRAPPED state.

INITIALIZING

public static final Manageable.State INITIALIZING

The INITIALIZING state.

USABLE

public static final Manageable.State USABLE

The USABLE state.

DEINITIALIZING

public static final Manageable.State DEINITIALIZING

The DEINITIALIZING state.

Constructor Detail

Manageable

protected Manageable()

Constructs a new Manageable.

Method Detail

getState

public final Manageable.State getState()

Gets the current state of this object.

Returns:

the current state, never null.

bootstrap

public final void bootstrap(PropertyReader properties)
                     throws IllegalStateException,
                            MissingRequiredPropertyException,
                            InvalidPropertyValueException,
                            BootstrapException

Performs the bootstrap procedure (wrapper method).

If the state of this object is valid (it must be UNUSABLE) and the argument is not null, then bootstrapImpl(PropertyReader) will be called. If that method succeeds, then this object will be left in the BOOTSTRAPPED state.

If bootstrapImpl(PropertyReader) throws any exception (even Errors), it is wrapped in an BootstrapException and then the latter is thrown instead.

Parameters:

properties - the bootstrap properties, can be null.

Throws:

IllegalStateException - if the current state is not UNUSABLE.

MissingRequiredPropertyException - if a required property is not given.

InvalidPropertyValueException - if the value of a certain property is invalid.

BootstrapException - if the bootstrapping failed for any other reason.

bootstrapImpl

protected void bootstrapImpl(PropertyReader properties)
                      throws MissingRequiredPropertyException,
                             InvalidPropertyValueException,
                             BootstrapException

Performs the bootstrap procedure (actual implementation). When this method is called from bootstrap(PropertyReader), the state and the argument will have been checked and the state will have been set to BOOTSTRAPPING.

The implementation of this method in class Manageable is empty.

Parameters:

properties - the bootstrap properties, not null.

Throws:

MissingRequiredPropertyException - if a required property is not given.

InvalidPropertyValueException - if the value of a certain property is invalid.

BootstrapException - if the bootstrapping failed for any other reason.

init

public final void init(PropertyReader properties)
                throws IllegalStateException,
                       MissingRequiredPropertyException,
                       InvalidPropertyValueException,
                       InitializationException

Performs the initialization procedure (wrapper method).

If the state of this object is valid (it must be either BOOTSTRAPPED or USABLE) and the argument is not null, then initImpl(PropertyReader) will be called. If that method succeeds, then this object will be left in the USABLE state. If an exception is thrown, then this object will be left in the BOOTSTRAPPED state instead.

If initImpl(PropertyReader) throws any exception (even Errors), it is wrapped in an InitializationException and then the latter is thrown instead.

Parameters:

properties - the initialization properties, can be null.

Throws:

IllegalStateException - if the current state is not BOOTSTRAPPED or USABLE.

MissingRequiredPropertyException - if a required property is not given.

InvalidPropertyValueException - if the value of a certain property is invalid.

InitializationException - if the initialization failed for any other reason.

initImpl

protected void initImpl(PropertyReader properties)
                 throws MissingRequiredPropertyException,
                        InvalidPropertyValueException,
                        InitializationException

Performs the initialization procedure (actual implementation). When this method is called from init(PropertyReader), the state and the argument will have been checked and the state will have been set to INITIALIZING.

The implementation of this method in class Manageable is empty.

Parameters:

properties - the initialization properties, not null.

Throws:

MissingRequiredPropertyException - if a required property is not given.

InvalidPropertyValueException - if the value of a certain property is invalid.

InitializationException - if the initialization failed, for any other reason.

deinit

public final void deinit()
                  throws IllegalStateException,
                         DeinitializationException

Deinitializes this instance (wrapper method). This method relies on deinitImpl() to actually perform the deinitialization.

The current state of this object must be either BOOTSTRAPPED or USABLE.

When this method returns, the state has been set to UNUSABLE, even if deinitImpl() threw an exception.

If deinitImpl() throws any exception, it is wrapped in a DeinitializationException and then the latter is thrown instead.

Throws:

IllegalStateException - if the state is not BOOTSTRAPPED nor USABLE.

DeinitializationException - if the deinitialization caused an exception in deinitImpl().

deinitImpl

protected void deinitImpl()
                   throws Throwable

Deinitializes this instance (actual implementation). This method will be called from deinit() each time the latter is called and it finds that the state is correct. The state will have been set to DEINITIALIZING.

Throws:

Throwable - if the deinitialization caused an exception.

isBootstrapped

public final boolean isBootstrapped()

Determines if this object is currently bootstrapped. Even if this object is already initialized, then it is still considered bootstrapped.

Returns:

true if this object is bootstrapped, false if it is not.

Since:

XINS 1.5.0

isUsable

public final boolean isUsable()

Determines if this object is currently usable.

Returns:

true if this object is usable, false if it is not.

assertUsable

protected final void assertUsable()
                           throws IllegalStateException

Asserts that this object is currently usable. If it is not, then an IllegalStateException is thrown.

Throws:

IllegalStateException - if this object is not in the USABLE state.