org.xins.server
Class API

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

All Implemented Interfaces:

DefaultResultCodes

public abstract class API

extends Manageable

implements DefaultResultCodes

Base class for API implementation classes.

Since:

XINS 1.0.0

Version:

$Revision: 1.334 $ $Date: 2006/10/24 09:31:13 $

Author:

Ernst de Haan, Anthony Goubard, Tauseef Rehman

Nested Class Summary

Nested classes inherited from class org.xins.common.manageable.Manageable

Manageable.State

Field Summary

Fields inherited from class org.xins.common.manageable.Manageable

BOOTSTRAPPED, BOOTSTRAPPING, DEINITIALIZING, INITIALIZING, UNUSABLE, USABLE

Fields inherited from interface org.xins.server.DefaultResultCodes

_DISABLED_FUNCTION, _INTERNAL_ERROR, _INVALID_REQUEST, _INVALID_RESPONSE

Constructor Summary

protected

API(String name) Constructs a new API object.

Method Summary

protected void	add(Manageable m) Adds the specified manageable object.
boolean	allow(String ip, String functionName) Determines if the specified IP address is allowed to access the specified function, returning a boolean value.
protected void	bootstrapImpl(PropertyReader buildSettings) Bootstraps this API (wrapper method).
protected void	bootstrapImpl2(PropertyReader buildSettings) Bootstraps this API (implementation method).
protected void	deinitImpl() Performs shutdown of this XINS API.
APISpec	getAPISpecification() Get the specification of the API.
PropertyReader	getBootstrapProperties() Gets the bootstrap properties specified for the API.
List	getFunctionList() Gets the list of the functions of this API.
String	getName() Gets the name of this API.
RuntimeProperties	getProperties() Gets the runtime properties specified in the implementation.
long	getStartupTimestamp() Gets the timestamp that indicates when this API instance was created.
TimeZone	getTimeZone() Returns the applicable time zone.
protected void	initImpl(PropertyReader runtimeSettings) Initializes this API.
protected void	reinitializeImpl() Triggers re-initialization of this API.

Methods inherited from class org.xins.common.manageable.Manageable

assertUsable, bootstrap, deinit, getState, init, isBootstrapped, isUsable

Methods inherited from class java.lang.Object

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

Constructor Detail

API

protected API(String name)
       throws IllegalArgumentException

Constructs a new API object.

Parameters:

name - the name of the API, cannot be null nor can it be an empty string.

Throws:

IllegalArgumentException - if name == null || name.length() < 1.

Method Detail

getName

public final String getName()

Gets the name of this API.

Returns:

the name of this API, never null and never an empty string.

getFunctionList

public final List getFunctionList()

Gets the list of the functions of this API.

Returns:

the functions of this API as a List of Function objects, never null.

Since:

XINS 1.5.0.

getBootstrapProperties

public PropertyReader getBootstrapProperties()

Gets the bootstrap properties specified for the API.

Returns:

the bootstrap properties, cannot be null.

Since:

XINS 1.5.0.

getProperties

public RuntimeProperties getProperties()

Gets the runtime properties specified in the implementation.

Returns:

the runtime properties for the API, cannot be null.

getStartupTimestamp

public final long getStartupTimestamp()

Gets the timestamp that indicates when this API instance was created.

Returns:

the time this instance was constructed, as a number of milliseconds since the UNIX Epoch.

getTimeZone

public final TimeZone getTimeZone()

Returns the applicable time zone.

Returns:

the time zone, never null.

bootstrapImpl

protected final void bootstrapImpl(PropertyReader buildSettings)
                            throws IllegalStateException,
                                   MissingRequiredPropertyException,
                                   InvalidPropertyValueException,
                                   BootstrapException

Bootstraps this API (wrapper method). This method calls bootstrapImpl2(PropertyReader).

Overrides:

bootstrapImpl in class Manageable

Parameters:

buildSettings - the build-time configuration properties, not null.

Throws:

IllegalStateException - if this API is currently not bootstraping.

MissingRequiredPropertyException - if a required property is not given.

InvalidPropertyValueException - if a property has an invalid value.

BootstrapException - if the bootstrap fails.

bootstrapImpl2

protected void bootstrapImpl2(PropertyReader buildSettings)
                       throws MissingRequiredPropertyException,
                              InvalidPropertyValueException,
                              BootstrapException

Bootstraps this API (implementation method).

The implementation of this method in class API is empty. Custom subclasses can perform any necessary bootstrapping in this class.

Note that bootstrapping and initialization are different. Bootstrap includes only the one-time configuration of the API based on the build-time settings, while the initialization

The add(Manageable) may be called from this method, and from this method only.

Parameters:

buildSettings - the build-time properties, guaranteed not to be null.

Throws:

MissingRequiredPropertyException - if a required property is not given.

InvalidPropertyValueException - if a property has an invalid value.

BootstrapException - if the bootstrap fails.

reinitializeImpl

protected final void reinitializeImpl()

Triggers re-initialization of this API. This method is meant to be called by API function implementations when it is anticipated that the API should be re-initialized.

initImpl

protected final void initImpl(PropertyReader runtimeSettings)
                       throws MissingRequiredPropertyException,
                              InvalidPropertyValueException,
                              InitializationException,
                              IllegalStateException

Initializes this API.

Overrides:

initImpl in class Manageable

Parameters:

runtimeSettings - the runtime configuration settings, cannot be null.

Throws:

MissingRequiredPropertyException - if a required property is missing.

InvalidPropertyValueException - if a property has an invalid value.

InitializationException - if the initialization failed for some other reason.

IllegalStateException - if this API is currently not initializing.

add

protected final void add(Manageable m)
                  throws IllegalStateException,
                         IllegalArgumentException

Adds the specified manageable object. It will not immediately be bootstrapped and initialized.

Parameters:

m - the manageable object to add, not null.

Throws:

IllegalStateException - if this API is currently not bootstrapping.

IllegalArgumentException - if instance == null.

deinitImpl

protected final void deinitImpl()

Performs shutdown of this XINS API. This method will never throw any exception.

Overrides:

deinitImpl in class Manageable

getAPISpecification

public final APISpec getAPISpecification()
                                  throws InvalidSpecificationException

Get the specification of the API.

Returns:

the APISpec specification object, never null.

Throws:

InvalidSpecificationException - if the specification cannot be found or is invalid.

Since:

XINS 1.3.0

allow

public boolean allow(String ip,
                     String functionName)
              throws IllegalArgumentException

Determines if the specified IP address is allowed to access the specified function, returning a boolean value.

This method finds the first matching rule and then returns the allow property of that rule (see AccessRule.isAllowRule()). If there is no matching rule, then false is returned.

Parameters:

ip - the IP address, cannot be null.

functionName - the name of the function, cannot be null.

Returns:

true if the request is allowed, false if the request is denied.

Throws:

IllegalArgumentException - if ip == null || functionName == null.