org.xins.server

Class API

java.lang.Object

org.xins.common.manageable.Manageable

org.xins.server.API

public abstract class API
extends Manageable

Base class for API implementation classes.

Since:

XINS 1.0.0

Version:

$Revision: 1.388 $ $Date: 2013/01/18 14:26:45 $

Author:

Ernst de Haan, Anthony Goubard, Tauseef Rehman

Nested Class Summary

Nested classes/interfaces 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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	API(String name) Constructs a new API object.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	add(Manageable m) Adds the specified manageable object.
boolean	allow(String ip, String functionName, String conventionName) Determines if the specified IP address is allowed to access the specified function, returning a boolean value.
protected void	bootstrapImpl(Map<String,String> buildSettings) Bootstraps this API (wrapper method).
protected void	bootstrapImpl2(Map<String,String> buildSettings) Bootstraps this API (implementation method).
protected void	deinitImpl() Performs shutdown of this XINS API.
APISpec	getAPISpecification() Get the specification of the API.
Map<String,String>	getBootstrapProperties() Gets the bootstrap properties specified for the API.
List<Function>	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.
InputStream	getResourceAsStream(String path) Gets the resource in the WAR file.
long	getStartupTimestamp() Gets the timestamp that indicates when this API instance was created.
TimeZone	getTimeZone() Returns the applicable time zone.
protected void	initImpl(Map<String,String> 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<Function> 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 Map<String,String> 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.

getResourceAsStream

public final InputStream getResourceAsStream(String path)
                                      throws IllegalArgumentException

Gets the resource in the WAR file.

Parameters:

path - the path for the resource, cannot be null and should start with /.

Returns:

the InputStream to use to read this resource or null if the resource cannot be found.

Throws:

IllegalArgumentException - if path == null or if the path doesn't start with /.

Since:

XINS 2.0.

bootstrapImpl

protected final void bootstrapImpl(Map<String,String> buildSettings)
                            throws IllegalStateException,
                                   MissingRequiredPropertyException,
                                   InvalidPropertyValueException,
                                   BootstrapException

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

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(Map<String,String> 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(Map<String,String> 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,
            String conventionName)
              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.

conventionName - the name of the calling convention, can be null.

Returns:

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

Throws:

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

Since:

XINS 2.1.