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, MultiConnectorServiceWrapper, TraceToAasService
public abstract class AbstractService extends 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 single 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 Details

    • loader

      private static ClassLoader loader

    • id

      private String id

    • name

      private String name

    • version

      private de.iip_ecosphere.platform.support.Version version

    • description

      private 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

    • typeCreators

      private Map<Class<?>,AbstractService.TypeCreator<?>> typeCreators

  • Constructor Details

    • AbstractService

      protected AbstractService(ServiceKind kind)
      Fallback constructor setting most fields to "empty" default values.
      Parameters:
      kind - the service kind

    • AbstractService

      protected AbstractService(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(String id, String name, de.iip_ecosphere.platform.support.Version version, 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:

    • AbstractService

      protected AbstractService(String serviceId, 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 Details

    • 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(URL[] jars)
      Sets shared jar libraries for the services.
      Parameters:
      jars - the libraries, ignored if null

    • createInstance

      public static <S extends Service> S createInstance(String className, 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(String className, Class<S> cls, String serviceId, 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 InputStream getResourceAsStream(ClassLoader loader, 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(ClassLoader loader, String className, Class<S> cls, String serviceId, 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)

    • createInstanceByPlugin

      public static <S extends Service> S createInstanceByPlugin(String pluginId, boolean log, String serviceId, String deploymentDescFile)
      Creates a service instance from a plugin.
      Type Parameters:
      S - the service type
      Parameters:
      pluginId - the plugin id
      log - emit log information when the plugin is not registered
      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:
      a new service instance or null if the service cannot be created/the plugin is not registered

    • getArg

      public static Object getArg(int index, Object[] args, Object dflt)
      Returns the i-th argument.
      Parameters:
      index - the index of the argument to return
      args - the arguments
      dflt - the default value if accessing the argument fails
      Returns:
      the argument or dflt

    • getStringArg

      public static String getStringArg(int index, Object[] args, String dflt)
      Returns the i-th argument as String.
      Parameters:
      index - the index of the argument to return
      args - the arguments
      dflt - the default value if accessing the argument fails
      Returns:
      the argument as String or dflt

    • createGenericMultiInstance

      public static <S extends Service> S createGenericMultiInstance(ClassLoader loader, String className, Class<S> cls, YamlService yaml, Object... args)
      Creates a service instance from a plugin via the AbstractDelegatingMultiService(YamlService) or the extended constructor with second parameter String... args.
      Type Parameters:
      S - the service type
      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
      yaml - the service description
      args - the optional service creation arguments
      Returns:
      a new service instance or null if the service cannot be created

    • createGenericMultiInstanceByPlugin

      public static <S extends Service> S createGenericMultiInstanceByPlugin(String pluginId, boolean log, YamlService yaml, Object... args)
      Creates a generic service instance from a plugin via ServiceDescriptor.createService(YamlService, Object...).
      Type Parameters:
      S - the service type
      Parameters:
      pluginId - the plugin id
      log - emit log information when the plugin is not registered
      yaml - the service description
      args - the optional service creation arguments
      Returns:
      a new service instance or null if the service cannot be created/the plugin is not registered

    • createGenericInstance

      public static <S extends Service, I, O> S createGenericInstance(ClassLoader loader, String className, Class<S> cls, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<I,String> inTrans, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<String,O> outTrans, de.iip_ecosphere.platform.transport.connectors.ReceptionCallback<O> callback, YamlService yaml, Object... args)
      Creates a service instance from a plugin via the AbstractDelegatingMultiService(YamlService) or the extended constructor with second parameter String... args.
      Type Parameters:
      S - the service type
      I - input type
      O - output type
      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
      inTrans - the input translator
      outTrans - the output translator
      callback - called when a processed item is received from the service
      yaml - the service description
      args - the optional service creation arguments
      Returns:
      a new service instance or null if the service cannot be created

    • createGenericInstanceByPlugin

      public static <S extends Service, I, O> S createGenericInstanceByPlugin(String pluginId, boolean log, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<I,String> inTrans, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<String,O> outTrans, de.iip_ecosphere.platform.transport.connectors.ReceptionCallback<O> callback, YamlService yaml, Object... args)
      Creates a generic service instance from a plugin via ServiceDescriptor.createService(YamlService, Object...).
      Type Parameters:
      S - the service type
      I - input type
      O - output type
      Parameters:
      pluginId - the plugin id
      log - emit log information when the plugin is not registered
      inTrans - the input translator
      outTrans - the output translator
      callback - called when a processed item is received from the service
      yaml - the service description
      args - the optional service creation arguments
      Returns:
      a new service instance or null if the service cannot be created/the plugin is not registered

    • getId

      public 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 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.Version getVersion()
      Description copied from interface: Service
      The version of the service.
      Specified by:
      getVersion in interface Service
      Returns:
      the version

    • getDescription

      public 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 ExecutionException
      Changes the state. [R133c]
      Specified by:
      setState in interface ServiceBase
      Parameters:
      state - the new state
      Throws:
      ExecutionException - if changing the state fails for some reason
      See Also:

    • start

      protected ServiceState start() throws ExecutionException
      Starts the service and the background process.
      Returns:
      the state to transition to, may be null for none
      Throws:
      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 ExecutionException
      Description copied from interface: Service
      Activates the service. [adaptation]
      Specified by:
      activate in interface Service
      Throws:
      ExecutionException - in case that activating fails, e.g., because the service is already active

    • passivate

      public void passivate() throws ExecutionException
      Description copied from interface: Service
      Passivates the service. [adaptation]
      Specified by:
      passivate in interface Service
      Throws:
      ExecutionException - in case that passivating fails, e.g., because the service is already passive

    • addConfigurer

      public static <T> void addConfigurer(Map<String,ParameterConfigurer<?>> configurers, String name, Class<T> cls, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<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(Map<String,ParameterConfigurer<?>> configurers, String name, Class<T> cls, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<String,T> trans, ValueConfigurer<T> cfg, 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(Map<String,ParameterConfigurer<?>> configurers, String name, Class<T> cls, de.iip_ecosphere.platform.transport.serialization.TypeTranslator<String,T> trans, ValueConfigurer<T> cfg, Supplier<T> getter, 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(Map<String,String> values, ParameterConfigurerProvider provider, boolean rollback, ServiceState state) throws 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:
      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, String name, String value, Map<String,String> rollbackMap) throws 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:
      ExecutionException - if the re-configuration fails

    • reconfigure

      public void reconfigure(Map<String,String> values) throws 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:
      ExecutionException - if reconfiguration fails

    • notifyReconfigured

      protected void notifyReconfigured(String paramName, 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:

    • transferData

      protected void transferData(Object source, Object target)
      Transfers all fields from the source object to the target object. The caller is responsible that the objects are sufficiently compatible.
      Parameters:
      source - the source object (may be null)
      target - the target object (may be null)

    • addTypeSubstitution

      public <T> void addTypeSubstitution(Class<? super T> cls, Class<T> actCls, Supplier<T> creator)
      Description copied from interface: Service
      Sets a type mapping, usually a substitution of more generic to more specific output types.
      Specified by:
      addTypeSubstitution in interface Service
      Type Parameters:
      T - the actual type
      Parameters:
      cls - the original class to apply the mapping for
      actCls - the actual class that the supplier will create an instance of
      creator - the creator supplier that creates an instance of the substitute

    • getSubstitutedType

      public <T> Class<? extends T> getSubstitutedType(Class<T> cls)
      Description copied from interface: Service
      Returns the actual (output) type, may be a substitute.
      Specified by:
      getSubstitutedType in interface Service
      Type Parameters:
      T - the actual type
      Parameters:
      cls - the original class to return the creator for
      Returns:
      the type, may be cls
      See Also:

    • getTypeCreator

      public <T> Supplier<T> getTypeCreator(Class<T> cls, Supplier<T> creator)
      Description copied from interface: Service
      Returns the creator for a certain (output) type, may be a substitute.
      Specified by:
      getTypeCreator in interface Service
      Type Parameters:
      T - the actual type
      Parameters:
      cls - the original class to return the creator for
      creator - the default creator supplier if none is registered
      Returns:
      a constructor supplier or creator if there is none
      See Also:

    • getTypeSubstitutions

      public Map<Class<?>,Class<?>> getTypeSubstitutions()
      Description copied from interface: Service
      Returns the actual (output) type substitutions.
      Specified by:
      getTypeSubstitutions in interface Service
      Returns:
      the type substitutions
      See Also: