org.systinet.wasp.webservice
Class ServiceInstance

java.lang.Object
  org.systinet.wasp.webservice.ServiceInstance

public abstract class ServiceInstance

extends java.lang.Object

ServiceInstance class represents handle for implementation of ServiceEndpoint. Typical usages are as following:

 ServiceInstance instance = ServiceInstance.create(HelloService.class);
 instance.setInstantiationMethod(ServiceInstance.INSTANTIATION_METHOD_PER_CLIENT);
 instance.set...;
 ...
 ServiceEndpoint endpoint = ServiceEndpoint.create("/HelloWorld", instance);
 Registry.publish(endpoint);

Another usage:

 ServiceEndpoint endpoint = Registry.getServiceEndpoint("/HelloWorld");
 ServiceInstance instance = endpoint.getServiceInstance();
 instance.disable();

Since:

4.5

Component:

Core

Field Summary

static int	INSTANTIATION_METHOD_PER_CLIENT New instance is created for each client.
static int	INSTANTIATION_METHOD_SHARED Clients share common instance.

Constructor Summary

protected

ServiceInstance()

Method Summary

static ServiceInstance	create(java.lang.Class implementationClass) Creates new service instance.
static ServiceInstance	create(java.lang.Object implementationObject) Creates new service instance.
static ServiceInstance	create(java.lang.String implementationClass) Creates new service instance.
abstract void	disable() Performs transition to the ServiceInstance.Disabled service state.
abstract void	enable() Performs transition from the Disabled or Offline states to Enabled state, thus allowing the service to process requests.
abstract Attributes	getAttributes() Retrieves attributes store bound to this service instance.
abstract Configurable	getConfigurable() Returns the custom configuration of the service instance.
abstract ServiceInstanceContext	getContext() Gets the ServiceInstanceContext object asociated to this service instance.
abstract java.lang.Class	getImplementationClass() Returns the class implementing this service instance.
abstract java.lang.String	getImplementationClassName() Returns the name of implememntation class.
abstract java.lang.Object	getImplementationObject() Returns the object implementing this service instance creating it, if it does not exist.
abstract int	getInstantiationMethod() Returns the instantiation method.
abstract int	getMaxInstances() Returns maximum count of instances allowed to exist simultaneously for this service.
abstract java.lang.String	getResource(java.lang.String path) Returns the resource with the given name or null if the resource could not be found.
abstract java.io.InputStream	getResourceAsStream(java.lang.String path) Returns an input stream for reading the specified resource.
abstract int	getState() Returns service state of this service instance.
abstract long	getTTL() This setting is valid only for per-client instantiated service.
abstract void	kill() Forces service instance in Active and Enabled states to go to Disabled without waiting for the active request to complete.
abstract void	log(java.lang.String msg) Logs a message.
abstract void	log(java.lang.String message, java.lang.Throwable throwable) Logs a message and exception.
abstract void	setConfigurable(Configurable serviceConfig) Sets the custom configuration of the service instance.
abstract void	setImplementationClass(java.lang.Class implementationClass) Sets implementation class.
abstract void	setImplementationObject(java.lang.Object implementationObject) Sets implementation object.
abstract void	setInstantiationMethod(int instantiationMethod) Sets the instantiation method.
abstract void	setMaxInstances(int maxInstances) This setting is valid only for per-client instantiated service.
abstract void	setTTL(long seconds) This setting is valid only for per-client instantiated service.
abstract void	waitForState(int states) Waits for the service instance to enter one of given state.
abstract boolean	waitForState(int states, long timeout) Waits for the service instance to enter one of s given states.

Methods inherited from class java.lang.Object

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

Field Detail

INSTANTIATION_METHOD_SHARED

public static final int INSTANTIATION_METHOD_SHARED

Clients share common instance. It's used by setInstantiationMethod(int) and getInstantiationMethod().

See Also:

Constant Field Values

INSTANTIATION_METHOD_PER_CLIENT

public static final int INSTANTIATION_METHOD_PER_CLIENT

New instance is created for each client. It's used by setInstantiationMethod(int) and getInstantiationMethod().

See Also:

Constant Field Values

Constructor Detail

ServiceInstance

protected ServiceInstance()

Method Detail

create

public static ServiceInstance create(java.lang.Object implementationObject)

Creates new service instance.

Parameters:

implementationObject - the object implementing the service

create

public static ServiceInstance create(java.lang.Class implementationClass)

Creates new service instance.

Parameters:

implementationClass - the class implementing the service

create

public static ServiceInstance create(java.lang.String implementationClass)

Creates new service instance. During creation process, all registered instantiation listeners are used to instatiate given instance. If no one is able to handle given string representation, instantiation process fails.

Parameters:

implementationClass - the class implementing the service. Can be in various formats such a fully qualified java class name, JNDI name etc. depending on existing instantiation listeners.

getConfigurable

public abstract Configurable getConfigurable()

Returns the custom configuration of the service instance.

Returns:

the configuration of the service

setConfigurable

public abstract void setConfigurable(Configurable serviceConfig)

Sets the custom configuration of the service instance.

Parameters:

serviceConfig - the configuration of the service

getContext

public abstract ServiceInstanceContext getContext()

Gets the ServiceInstanceContext object asociated to this service instance.

Returns:

ServiceInstanceContext object or null if it does not exist

getImplementationObject

public abstract java.lang.Object getImplementationObject()
                                                  throws java.lang.ClassNotFoundException,
                                                         java.lang.InstantiationException,
                                                         java.lang.IllegalAccessException

Returns the object implementing this service instance creating it, if it does not exist. Note that the service instance can be implemented either by particular object or by a class. One instance of the class is created in the later case and returned. When shared instantiation method is taking place, this is the real object used during service invocation. When per-client instantiation is used, this object acts as a template for per-client instances being created during invocation, so it doesn't really serve client requests.

Returns:

implementation object or one instance of implementation class

Throws:

java.lang.ClassNotFoundException - if implementationClassName was specified (i.e. for deployed services) and the class was not found

java.lang.InstantiationException - if implementationClassName was specified (i.e. for deployed services) or implementationClass was specified and there was a problem with instantiation

java.lang.IllegalAccessException - if implementationClassName was specified (i.e. for deployed services) and the class was not public

See Also:

getImplementationClass()

getImplementationClass

public abstract java.lang.Class getImplementationClass()
                                                throws java.lang.ClassNotFoundException

Returns the class implementing this service instance. Note that the service instance can be implemented either by an object or by a class which is then instantiated on demand.

Returns:

class implementing this service instance

Throws:

java.lang.ClassNotFoundException

See Also:

getImplementationObject()

getImplementationClassName

public abstract java.lang.String getImplementationClassName()

Returns the name of implememntation class. This name can be full package and class name, JNDI name, etc.

Returns:

class name

getInstantiationMethod

public abstract int getInstantiationMethod()

Returns the instantiation method. It can be either "per-client", where there is instance created for each client accessing the service, or "shared", where clients share instances from a pool.

Returns:

INSTANTIATION_METHOD_PER_CLIENT or INSTANTIATION_METHOD_SHARED

setInstantiationMethod

public abstract void setInstantiationMethod(int instantiationMethod)
                                     throws java.lang.IllegalStateException

Sets the instantiation method. It can be either "per-client", where there is instance created for each client accessing the service, or "shared", where clients share instances from a pool.

Parameters:

instantiationMethod - set to INSTANTIATION_METHOD_PER_CLIENT or INSTANTIATION_METHOD_SHARED

Throws:

java.lang.IllegalStateException - when service instance is already initialized(service endpoint was published)

getTTL

public abstract long getTTL()

This setting is valid only for per-client instantiated service. Returns default time-to-live of per-client created instances in seconds. For further details about TTL setting see setTTL(long). After last request,if no further request comes in speciefed amount of time, created instance is disposed. For setting instantiation method see setInstantiationMethod(int).

Returns:

the default time-to-live in seconds, negative value = live forever

setTTL

public abstract void setTTL(long seconds)

This setting is valid only for per-client instantiated service. Sets default time-to-live of per-client created instances in seconds. After last request is processed and no further request comes in specified amount of time, created instance is disposed, so the server resources can be freed. For setting instantiation method see setInstantiationMethod(int).

Parameters:

seconds - the default time-to-live in seconds, negative value = live forever

getMaxInstances

public abstract int getMaxInstances()

Returns maximum count of instances allowed to exist simultaneously for this service. This setting is valid only for per-client instantiated service.

Returns:

maximum count of instances allowed, 0 = no limit

See Also:

for further details.

setMaxInstances

public abstract void setMaxInstances(int maxInstances)

This setting is valid only for per-client instantiated service. Sets maximum count of instances allowed to exist simultaneously for this service. In other words it limits the number of concurrently processed service clients.

Parameters:

maxInstances - maximum count of instances allowed, 0 = no limit

getState

public abstract int getState()

Returns service state of this service instance.

Returns:

service state

See Also:

ServiceState

disable

public abstract void disable()
                      throws java.lang.IllegalStateException,
                             InvalidStateTransitionException

Performs transition to the ServiceInstance.Disabled service state. For more information see documentation about service states and their transition diagram.

This method is non-blocking. Use waitForState(ServiceState.DISABLED) to wait for the disabled state.

Throws:

java.lang.IllegalStateException - when this service instance is not registrated( is not referenced by already published service endpoint)

InvalidStateTransitionException - when this service instance transition is not possible

enable

public abstract void enable()
                     throws java.lang.IllegalStateException,
                            InvalidStateTransitionException

Performs transition from the Disabled or Offline states to Enabled state, thus allowing the service to process requests.

This method is non-blocking. Use waitForState(ServiceState.ENABLED | ServiceState.ACTIVE) to wait for the enabled state.

Throws:

java.lang.IllegalStateException - when this service instance is not registrated( is not referenced by already published service endpoint)

InvalidStateTransitionException - when this service instance transition is not possible

kill

public abstract void kill()
                   throws java.lang.IllegalStateException,
                          InvalidStateTransitionException

Forces service instance in Active and Enabled states to go to Disabled without waiting for the active request to complete. The active connections are abandoned. Furthermore, if service instance implements Initializable, destroy is NOT processed.

If service instance is already in Initializing or Destroying states and either init() or destroy() is taking place, this method causes interrupting of these methods and transition to Disabled state.

Note: use with care - this method is unsafe and does not terminate active connections properly. It can thus lead to unpredictable behavior. This method is blocking.

Throws:

java.lang.IllegalStateException - when this service instance is not registrated( is not referenced by already published service endpoint)

InvalidStateTransitionException - when this service instance transition is not possible

waitForState

public abstract void waitForState(int states)
                           throws java.lang.InterruptedException

Waits for the service instance to enter one of given state. This method returns when the service instance enters one of a given states.

Parameters:

states - bitwise mask of service states to wait for. See ServiceState

Throws:

java.lang.InterruptedException

waitForState

public abstract boolean waitForState(int states,
                                     long timeout)
                              throws java.lang.InterruptedException

Waits for the service instance to enter one of s given states. This method returns when the service instance enters one of a given states or when the given timeout expires.

Parameters:

states - bitwise mask of service states to wait for

timeout - upper bound of time in milliseconds to wait for service instance to enter required state

Returns:

false when timeout interval expires without the service instance entering given state, true otherwise

Throws:

java.lang.InterruptedException

getResource

public abstract java.lang.String getResource(java.lang.String path)

Returns the resource with the given name or null if the resource could not be found. The name of a resource is a "/"-separated path name that identifies the resource. For the path name "/" returns absolute path of the root directory of the web service context represented by this instance. Note, that The "/" path returns valid data only for persistently deployed services.

Parameters:

path - path of the resource

Returns:

the string representation of the resource's URL

getResourceAsStream

public abstract java.io.InputStream getResourceAsStream(java.lang.String path)
                                                 throws java.io.IOException

Returns an input stream for reading the specified resource. or null if the resource could not be found.

Parameters:

path - path of the resource

Returns:

the input stream of the resource

Throws:

java.io.IOException - if something goes wrong

log

public abstract void log(java.lang.String msg)

Logs a message.

Parameters:

msg - message to be logged

log

public abstract void log(java.lang.String message,
                         java.lang.Throwable throwable)

Logs a message and exception.

Parameters:

message - the message to be logged

throwable - the exception to be logged

setImplementationClass

public abstract void setImplementationClass(java.lang.Class implementationClass)
                                     throws java.lang.IllegalStateException

Sets implementation class.

Parameters:

implementationClass - implementation class

Throws:

java.lang.IllegalStateException - when this service instance is already registrated( is referenced by already published service endpoint)

setImplementationObject

public abstract void setImplementationObject(java.lang.Object implementationObject)
                                      throws java.lang.IllegalStateException

Sets implementation object.

Parameters:

implementationObject - implementation object

Throws:

java.lang.IllegalStateException - when this service instance is already registrated( is referenced by already published service endpoint)

getAttributes

public abstract Attributes getAttributes()

Retrieves attributes store bound to this service instance.

Returns:

attributes store