Package de.iip_ecosphere.platform.services.environment

Class AbstractService

java.lang.Object

de.iip_ecosphere.platform.services.environment.AbstractService

All Implemented Interfaces:

ParameterConfigurerProvider, Service, ServiceBase

Direct Known Subclasses:

AbstractRunnablesService, ConnectorServiceWrapper, DefaultServiceImpl, TraceToAasService

public abstract class AbstractService
extends java.lang.Object
implements Service

Basic implementation of the service interface (aligned with Python). Implementing classes shall at least either have a no-arg constructor setting up the full/fallback service information, a signle string argument constructor taking the service id or a constructor like AbstractService(String, InputStream). The three types of constructors are recognized by createInstance(String, Class, String, String) or createInstance(ClassLoader, String, Class, String, String) to be used from generated service code. reconfigure(Map) is generically implemented via Service.getParameterConfigurer(String) (shall be overwritten), rollbackReconfigurationOnFailure() and reconfigure(Map, ParameterConfigurerProvider, boolean, ServiceState).

Author:

Holger Eichelberger, SSE

Field Summary

Fields

Modifier and Type	Field	Description
private java.lang.String	description
private java.lang.String	id
private boolean	isDeployable
private boolean	isTopLevel
private ServiceKind	kind
private static java.lang.ClassLoader	loader
private java.lang.String	name
private de.iip_ecosphere.platform.support.net.ManagedServerAddress	netKeyMgtAddress
private ServiceState	state
private de.iip_ecosphere.platform.support.iip_aas.Version	version

Fields inherited from interface de.iip_ecosphere.platform.services.environment.switching.ServiceBase

APPLICATION_SEPARATOR, DEFAULT_APPLICATION_INSTANCE_ID

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractService(ServiceKind kind)	Fallback constructor setting most fields to "empty" default values.
protected	AbstractService(YamlService yaml)	Creates an abstract service from YAML information.
protected	AbstractService(java.lang.String id, ServiceKind kind)	Fallback constructor setting most fields to "empty" default values.
protected	AbstractService(java.lang.String serviceId, java.io.InputStream ymlFile)	Creates an abstract service from a service id and a YAML artifact.
protected	AbstractService(java.lang.String id, java.lang.String name, de.iip_ecosphere.platform.support.iip_aas.Version version, java.lang.String description, boolean isDeployable, boolean isTopLevel, ServiceKind kind)	Creates an abstract service.

Method Summary

Modifier and Type	Method	Description
void	activate()	Activates the service.
static <T> void	addConfigurer(java.util.Map<java.lang.String,ParameterConfigurer<?>> configurers, java.lang.String name, java.lang.Class<T> cls, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<java.lang.String,T> trans, ValueConfigurer<T> cfg)	Helper method to add parameter configurers to configurers (without getter for rollback).
static <T> void	addConfigurer(java.util.Map<java.lang.String,ParameterConfigurer<?>> configurers, java.lang.String name, java.lang.Class<T> cls, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<java.lang.String,T> trans, ValueConfigurer<T> cfg, java.util.function.Supplier<T> getter)	Helper method to add parameter configurers to configurers without binding to a system property.
static <T> void	addConfigurer(java.util.Map<java.lang.String,ParameterConfigurer<?>> configurers, java.lang.String name, java.lang.Class<T> cls, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<java.lang.String,T> trans, ValueConfigurer<T> cfg, java.util.function.Supplier<T> getter, java.lang.String systemProperty)	Helper method to add parameter configurers to configurers without binding to a system property.
static <S extends Service> S	createInstance(java.lang.ClassLoader loader, java.lang.String className, java.lang.Class<S> cls, java.lang.String serviceId, java.lang.String deploymentDescFile)	Convenience method for creating service instances.
static <S extends Service> S	createInstance(java.lang.String className, java.lang.Class<S> cls)	Convenience method for creating service instances via the default constructor using the class loader of this class.
static <S extends Service> S	createInstance(java.lang.String className, java.lang.Class<S> cls, java.lang.String serviceId, java.lang.String deploymentDescFile)	Convenience method for creating service instances using the class loader of this class.
java.lang.String	getDescription()	The description of the service.
java.lang.String	getId()	Returns the unique id of the service.
ServiceKind	getKind()	Returns the service kind.
java.lang.String	getName()	The name of the service.
de.iip_ecosphere.platform.support.ServerAddress	getNetMgtKeyAddress()	Returns the resolved network address of the netMgtKey specified in the service descriptor.
static java.io.InputStream	getResourceAsStream(java.lang.ClassLoader loader, java.lang.String resource)	Loads a resource as stream from loader, first with given name, as fallback using resource without leading slashes (may be present after ZIP unpacking), else as file (may be present after ZIP unpacking).
ServiceState	getState()	Returns the state the service is currently in.
de.iip_ecosphere.platform.support.iip_aas.Version	getVersion()	The version of the service.
protected void	initializeFrom(YamlService yaml)	Does further initialization of this instance from the given YAML information.
boolean	isDeployable()	Returns whether the service is deployable in distributable manner or fixed in deployment location.
boolean	isTopLevel()	Returns whether the service is a top-level service.
protected void	notifyReconfigured(java.lang.String paramName, java.lang.String value)	Called to notify values have been reconfigured.
void	passivate()	Passivates the service.
protected static <T> void	reconf(ParameterConfigurer<T> configurer, java.lang.String name, java.lang.String value, java.util.Map<java.lang.String,java.lang.String> rollbackMap)	Reconfigures an individual parameter.
void	reconfigure(java.util.Map<java.lang.String,java.lang.String> values)	Reconfigures the service.
static void	reconfigure(java.util.Map<java.lang.String,java.lang.String> values, ParameterConfigurerProvider provider, boolean rollback, ServiceState state)	Generic service reconfiguration via values that may be passed in through reconfigure(Map).
protected boolean	rollbackReconfigurationOnFailure()	Returns whether the configuration shall be rolled by on failures.
static void	setLibJars(java.net.URL[] jars)	Sets shared jar libraries for the services.
void	setState(ServiceState state)	Changes the state.
protected ServiceState	start()	Starts the service and the background process.
protected ServiceState	stop()	Stops the service and the background process.

Methods inherited from class java.lang.Object

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

Methods inherited from interface de.iip_ecosphere.platform.services.environment.Service

getParameterConfigurer, getParameterNames, migrate, switchTo, update

Field Detail

loader

private static java.lang.ClassLoader loader

id

private java.lang.String id

name

private java.lang.String name

version

private de.iip_ecosphere.platform.support.iip_aas.Version version

description

private java.lang.String description

isDeployable

private boolean isDeployable

isTopLevel

private boolean isTopLevel

kind

private ServiceKind kind

state

private ServiceState state

netKeyMgtAddress

private de.iip_ecosphere.platform.support.net.ManagedServerAddress netKeyMgtAddress

Constructor Detail

AbstractService

protected AbstractService(ServiceKind kind)

Fallback constructor setting most fields to "empty" default values.

Parameters:

kind - the service kind

AbstractService

protected AbstractService(java.lang.String id,
                          ServiceKind kind)

Fallback constructor setting most fields to "empty" default values.

Parameters:

id - the id of the service

kind - the service kind

AbstractService

protected AbstractService(java.lang.String id,
                          java.lang.String name,
                          de.iip_ecosphere.platform.support.iip_aas.Version version,
                          java.lang.String description,
                          boolean isDeployable,
                          boolean isTopLevel,
                          ServiceKind kind)

Creates an abstract service.

Parameters:

id - the id of the service

name - the name of the service

version - the version of the service

description - a description of the service, may be empty

isDeployable - whether the service is decentrally deployable

isTopLevel - whether the service is a top-level (non-nested) service

kind - the service kind

AbstractService

protected AbstractService(YamlService yaml)

Creates an abstract service from YAML information.

Parameters:

yaml - the service information as read from YAML

See Also:

initializeFrom(YamlService)

AbstractService

protected AbstractService(java.lang.String serviceId,
                          java.io.InputStream ymlFile)

Creates an abstract service from a service id and a YAML artifact.

Parameters:

serviceId - the service id

ymlFile - the YML file containing the YAML artifact with the service descriptor

Method Detail

initializeFrom

protected void initializeFrom(YamlService yaml)

Does further initialization of this instance from the given YAML information.

Parameters:

yaml - the service information as read from YAML

setLibJars

public static void setLibJars(java.net.URL[] jars)

Sets shared jar libraries for the services.

Parameters:

jars - the libraries, ignored if null

createInstance

public static <S extends Service> S createInstance(java.lang.String className,
                                                   java.lang.Class<S> cls)

Convenience method for creating service instances via the default constructor using the class loader of this class.

Type Parameters:

S - the service type (parent interface of className)

Parameters:

className - the name of the service class (must implement Service and provide a no-argument constructor)

cls - the class to cast to

Returns:

the service instance (null if the service cannot be found/initialized)

createInstance

public static <S extends Service> S createInstance(java.lang.String className,
                                                   java.lang.Class<S> cls,
                                                   java.lang.String serviceId,
                                                   java.lang.String deploymentDescFile)

Convenience method for creating service instances using the class loader of this class.

Type Parameters:

S - the service type (parent interface of className)

Parameters:

className - the name of the service class (must implement Service and provide a no-argument constructor)

cls - the class to cast to

serviceId - the id of the service as given in deploymentDescFile (may be null, then the default constructor is invoked)

deploymentDescFile - the resource name of the deployment descriptor containing a YAML artifact with the service description (may be null, then the default constructor is invoked)

Returns:

the service instance (null if the service cannot be found/initialized)

getResourceAsStream

public static java.io.InputStream getResourceAsStream(java.lang.ClassLoader loader,
                                                      java.lang.String resource)

Loads a resource as stream from loader, first with given name, as fallback using resource without leading slashes (may be present after ZIP unpacking), else as file (may be present after ZIP unpacking).

Parameters:

loader - the class loader to load the class with

resource - the resource name/path

Returns:

the input stream if the resource was found, null else

createInstance

public static <S extends Service> S createInstance(java.lang.ClassLoader loader,
                                                   java.lang.String className,
                                                   java.lang.Class<S> cls,
                                                   java.lang.String serviceId,
                                                   java.lang.String deploymentDescFile)

Convenience method for creating service instances.

Type Parameters:

S - the service type (parent interface of className)

Parameters:

loader - the class loader to load the class with

className - the name of the service class (must implement Service and provide a no-argument constructor)

cls - the class to cast to

serviceId - the id of the service as given in deploymentDescFile (may be null, then the default constructor is invoked)

deploymentDescFile - the resource name of the deployment descriptor containing a YAML artifact with the service description (may be null, then the default constructor is invoked)

Returns:

the service instance (null if the service cannot be found/initialized)

getId

public java.lang.String getId()

Description copied from interface: ServiceBase

Returns the unique id of the service. May be a single service id, a service id and a postfixed application id (after ServiceBase.APPLICATION_SEPARATOR) or a service id with application id and postfixed application instance id (after ServiceBase.APPLICATION_SEPARATOR)

Specified by:

getId in interface ServiceBase

Returns:

the unique id

getName

public java.lang.String getName()

Description copied from interface: Service

The name of the service.

Specified by:

getName in interface Service

Returns:

the name

getVersion

public de.iip_ecosphere.platform.support.iip_aas.Version getVersion()

Description copied from interface: Service

The version of the service.

Specified by:

getVersion in interface Service

Returns:

the version

getDescription

public java.lang.String getDescription()

Description copied from interface: Service

The description of the service.

Specified by:

getDescription in interface Service

Returns:

the description, may be empty

getState

public ServiceState getState()

Description copied from interface: ServiceBase

Returns the state the service is currently in. [R4c]

Specified by:

getState in interface ServiceBase

Returns:

the state

setState

public void setState(ServiceState state)
              throws java.util.concurrent.ExecutionException

Changes the state. [R133c]

Specified by:

setState in interface ServiceBase

Parameters:

state - the new state

Throws:

java.util.concurrent.ExecutionException - if changing the state fails for some reason

See Also:

start(), stop()

start

protected ServiceState start()
                      throws java.util.concurrent.ExecutionException

Starts the service and the background process.

Returns:

the state to transition to, may be null for none

Throws:

java.util.concurrent.ExecutionException - if starting the process fails

stop

protected ServiceState stop()

Stops the service and the background process.

Returns:

the state to transition to, may be null for none

isDeployable

public boolean isDeployable()

Description copied from interface: Service

Returns whether the service is deployable in distributable manner or fixed in deployment location.

Specified by:

isDeployable in interface Service

Returns:

true for deployable, false for fixed

isTopLevel

public boolean isTopLevel()

Description copied from interface: Service

Returns whether the service is a top-level service.

Specified by:

isTopLevel in interface Service

Returns:

true for top-level, false for nested

getKind

public ServiceKind getKind()

Description copied from interface: Service

Returns the service kind.

Specified by:

getKind in interface Service

Returns:

the service kind

getNetMgtKeyAddress

public de.iip_ecosphere.platform.support.ServerAddress getNetMgtKeyAddress()

Description copied from interface: Service

Returns the resolved network address of the netMgtKey specified in the service descriptor.

Specified by:

getNetMgtKeyAddress in interface Service

Returns:

the resolved address, may be null in particular if no key was specified in the service descriptor

activate

public void activate()
              throws java.util.concurrent.ExecutionException

Description copied from interface: Service

Activates the service. [adaptation]

Specified by:

activate in interface Service

Throws:

java.util.concurrent.ExecutionException - in case that activating fails, e.g., because the service is already active

passivate

public void passivate()
               throws java.util.concurrent.ExecutionException

Description copied from interface: Service

Passivates the service. [adaptation]

Specified by:

passivate in interface Service

Throws:

java.util.concurrent.ExecutionException - in case that passivating fails, e.g., because the service is already passive

addConfigurer

public static <T> void addConfigurer(java.util.Map<java.lang.String,ParameterConfigurer<?>> configurers,
                                     java.lang.String name,
                                     java.lang.Class<T> cls,
                                     de.iip_ecosphere.platform.transport.serialization.TypeTranslator<java.lang.String,T> trans,
                                     ValueConfigurer<T> cfg)

Helper method to add parameter configurers to configurers (without getter for rollback).

Type Parameters:

T - the parameter type

Parameters:

configurers - the configurers map to be modified

name - the name of the parameter

cls - the class representing the parameter type

trans - the type translator to turn initial string values into internal values

cfg - the value configurer that may change the value / throw exceptions

addConfigurer

public static <T> void addConfigurer(java.util.Map<java.lang.String,ParameterConfigurer<?>> configurers,
                                     java.lang.String name,
                                     java.lang.Class<T> cls,
                                     de.iip_ecosphere.platform.transport.serialization.TypeTranslator<java.lang.String,T> trans,
                                     ValueConfigurer<T> cfg,
                                     java.util.function.Supplier<T> getter)

Helper method to add parameter configurers to configurers without binding to a system property.

Type Parameters:

T - the parameter type

Parameters:

configurers - the configurers map to be modified

name - the name of the parameter

cls - the class representing the parameter type

trans - the type translator to turn initial string values into internal values

cfg - the value configurer that may change the value / throw exceptions

getter - the getter for the value (may be null for none, prevents rollback)

addConfigurer

public static <T> void addConfigurer(java.util.Map<java.lang.String,ParameterConfigurer<?>> configurers,
                                     java.lang.String name,
                                     java.lang.Class<T> cls,
                                     de.iip_ecosphere.platform.transport.serialization.TypeTranslator<java.lang.String,T> trans,
                                     ValueConfigurer<T> cfg,
                                     java.util.function.Supplier<T> getter,
                                     java.lang.String systemProperty)

Helper method to add parameter configurers to configurers without binding to a system property.

Type Parameters:

T - the parameter type

Parameters:

configurers - the configurers map to be modified

name - the name of the parameter

cls - the class representing the parameter type

trans - the type translator to turn initial string values into internal values

cfg - the value configurer that may change the value / throw exceptions

getter - the getter for the value (may be null for none, prevents rollback)

systemProperty - optional system property to take the higher precedence initial/default value for the parameter from, may be empty or null for none

reconfigure

public static void reconfigure(java.util.Map<java.lang.String,java.lang.String> values,
                               ParameterConfigurerProvider provider,
                               boolean rollback,
                               ServiceState state)
                        throws java.util.concurrent.ExecutionException

Generic service reconfiguration via values that may be passed in through reconfigure(Map). Prepared that code generation can hook in any parameter attributes.

Parameters:

values - the values to reconfigure in the encoding requested by reconfigure(Map). The specified configurers must provide appropriate serializers to turn individual values into compatible objects

provider - access to the parameter configurers (may be null, then nothing happens)

rollback - whether a rollback shall be performed if reconfiguration leads to exceptions on individual parameters

state - the state of the service. Currently unused, but may be used to filter out parameter reconfigurations

Throws:

java.util.concurrent.ExecutionException - if the reconfiguration cannot be carried out; if rollback is true and getters for individual parameters are available in the ParameterConfigurer, a rollback of the values set before will be carried out

reconf

protected static <T> void reconf(ParameterConfigurer<T> configurer,
                                 java.lang.String name,
                                 java.lang.String value,
                                 java.util.Map<java.lang.String,java.lang.String> rollbackMap)
                          throws java.util.concurrent.ExecutionException

Reconfigures an individual parameter.

Type Parameters:

T - the parameter type

Parameters:

configurer - the configurer to use

name - the name of the parameter to reconfigure

value - the value, may be null

rollbackMap - the rollback

Throws:

java.util.concurrent.ExecutionException - if the re-configuration fails

reconfigure

public void reconfigure(java.util.Map<java.lang.String,java.lang.String> values)
                 throws java.util.concurrent.ExecutionException

Description copied from interface: Service

Reconfigures the service. [adaptation]

Specified by:

reconfigure in interface Service

Parameters:

values - the (service-specific) name-value mapping that shall lead to a reconfiguration of the service; values come either as primitive values or as JSON structures complying with the parameter descriptor. The service is responsible for correct JSON de-serialization according to the respective descriptor.

Throws:

java.util.concurrent.ExecutionException - if reconfiguration fails

notifyReconfigured

protected void notifyReconfigured(java.lang.String paramName,
                                  java.lang.String value)

Called to notify values have been reconfigured.

Parameters:

paramName - the name of the parameter

value - the serialized value (JSON)

rollbackReconfigurationOnFailure

protected boolean rollbackReconfigurationOnFailure()

Returns whether the configuration shall be rolled by on failures.

Returns:

true

See Also:

reconfigure(Map), reconfigure(Map, ParameterConfigurerProvider, boolean, ServiceState)