Package de.iip_ecosphere.platform.services

Interface ServiceOperations

All Known Subinterfaces:
ServiceManager, ServicesClient
All Known Implementing Classes:
AbstractServiceManager, ServicesAasClient
public interface ServiceOperations
Basic service operations that shall also be available via an AAS.
Author:
Holger Eichelberger, SSE

  • Field Details

    • EXC_ALREADY_KNOWN

      static final String EXC_ALREADY_KNOWN
      See Also:

    • OPTION_ENSEMBLE

      static final String OPTION_ENSEMBLE
      Service start option, ensemble mapping (member-leader mapping), given as JSON map (string).
      See Also:

    • OPTION_ARGS

      static final String OPTION_ARGS
      Service start option, command line options, usually -D<key>=<value>, given as JSON list (string).
      See Also:

    • OPTION_SERVERS

      static final String OPTION_SERVERS
      Service start option, mapping of service ids to server IP addresses JSON map (string).
      See Also:

    • OPTION_PARAMS

      static final String OPTION_PARAMS
      Service start option, mapping of service ids to maps of name-value for re-configuring the service parameters directly after start.
      See Also:

    • OPTION_MEMLIMITS

      static final String OPTION_MEMLIMITS
      Service start option, mapping of service ids to memory limits in MBytes given as JSON map.
      See Also:

  • Method Details

    • addArtifact

      String addArtifact(URI location) throws ExecutionException
      Adds an artifact (and transitively the contained services) to the management domain of this instance, e.g., by downloading it from an artifact/service store. This defines the id of the service within the management domain of this instance. After a successful execution, the artifact id is returned, artifact and service(s) shall be available and the service(s) shall be in state ServiceState.AVAILABLE.
      Parameters:
      location - the location from where to download the service, e.g., an URL
      Returns:
      the id of the artifact
      Throws:
      ExecutionException - in case that adding the service fails for some reason

    • startService

      void startService(String... serviceId) throws ExecutionException
      Starts one or multiple service. The service implementation must be already within the management domain of this instance by addArtifact(URI). The service(s) shall after some time be in state ServiceState.STARTING, ServiceState.RUNNING or ServiceState.FAILED.
      Parameters:
      serviceId - the id(s) of the service(s)
      Throws:
      ExecutionException - in case that starting the service fails for some reason

    • startService

      void startService(Map<String,String> options, String... serviceId) throws ExecutionException
      Starts one or multiple service. The service implementation must be already within the management domain of this instance by addArtifact(URI). The service(s) shall after some time be in state ServiceState.STARTING, ServiceState.RUNNING or ServiceState.FAILED.
      Parameters:
      options - optional map of optional options to be passed to the service manager, may modify the service descriptors, e.g., to change services to be started together on demand, may be empty for none; options are a name-value mapping with values that come either as primitive values or as JSON structures. For pre-defined names, see OPTION_ARGS, OPTION_ENSEMBLE, OPTION_PARAMS, OPTION_SERVERS, or OPTION_MEMLIMITS. The service manager is responsible for correct JSON de-serialization.
      serviceId - the id(s) of the service(s)
      Throws:
      ExecutionException - in case that starting the service fails for some reason
      See Also:

    • stopService

      void stopService(String... serviceId) throws ExecutionException
      Stops one or multiple services. The service shall afterwards be in state ServiceState.STOPPED.
      Parameters:
      serviceId - the id(s) of the service(s) to stop
      Throws:
      ExecutionException - if stopping the service fails

    • migrateService

      void migrateService(String serviceId, String resourceId) throws ExecutionException
      Migrates a service. However, it may be required to migrate/move the containing artifact. [adaptation]
      Parameters:
      serviceId - the id of the service
      resourceId - the target resource id, e.g., a device
      Throws:
      ExecutionException - if migration fails

    • removeArtifact

      void removeArtifact(String artifactId) throws ExecutionException
      Removes the artifact (and transitively its services) from the management domain of this instance. This operation shall only remove the implementation of non-operational services and, thus, perform a state transition to ServiceState.UNDEPLOYING and ultimately the service(s) shall be removed and their descriptors (including the artifact descriptor) shall not be available anymore.
      Parameters:
      artifactId - the id of the artifact to remove, or as fallback the canonical URI of the artifact
      Throws:
      ExecutionException - if removing the service fails, e.g., because it is still running

    • updateService

      void updateService(String serviceId, URI location) throws ExecutionException
      Updates the service by the service in the given location. This operation is responsible for stopping the running service (if needed), replacing it, starting the new service.
      Parameters:
      serviceId - the id of the service to be updated
      location - the location of the new service, e.g., an URL
      Throws:
      ExecutionException - if the given service cannot be updated for some reason, e.g., because the replacement service is not an evolved version of the running service

    • switchToService

      void switchToService(String serviceId, String targetId) throws ExecutionException
      Switches to an interface-compatible service. This method cares for stopping the old service, performing a handover if adequate, starting the target service. [adaptation]
      Parameters:
      serviceId - the id of the running service
      targetId - the id of the target service
      Throws:
      ExecutionException - if switching the service cannot be performed for some reason

    • activateService

      void activateService(String serviceId) throws ExecutionException
      Activates the service. [adaptation]
      Parameters:
      serviceId - the id of the running service
      Throws:
      ExecutionException - in case that activating fails, e.g., because the service is already active

    • passivateService

      void passivateService(String serviceId) throws ExecutionException
      Passivates the service. [adaptation]
      Parameters:
      serviceId - the id of the running service
      Throws:
      ExecutionException - in case that passivating fails, e.g., because the service is already passive

    • reconfigureService

      void reconfigureService(String serviceId, Map<String,String> values) throws ExecutionException
      Reconfigures the underlying service. [adaptation]
      Parameters:
      serviceId - the serviceId of the running service
      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

    • setServiceState

      void setServiceState(String serviceId, de.iip_ecosphere.platform.services.environment.ServiceState state) throws ExecutionException
      Sets the state of the service. [adaptation]
      Parameters:
      serviceId - the id of the running service
      state - the new state of the service
      Throws:
      ExecutionException - if changing to the target state is not possible

    • getServiceState

      de.iip_ecosphere.platform.services.environment.ServiceState getServiceState(String serviceId)
      Returns the state of the service.
      Parameters:
      serviceId - the id of the running service
      Returns:
      the state of the service

    • getServiceInstanceCount

      int getServiceInstanceCount(String serviceId)
      Returns the number of service instances of the same service in the same application.
      Parameters:
      serviceId - the service id, application instance id is ignored if not given
      Returns:
      0 if there is no other service instance, 1 if no applicationId is given in serviceId but there is a service with the same id, the number of instances otherwise

    • toMode

      static ServiceOperations.StreamLogMode toMode(String value)
      Turns a string value to a ServiceOperations.StreamLogMode.
      Parameters:
      value - the string value
      Returns:
      the mode, fallback is ServiceOperations.StreamLogMode.NONE.

    • streamLog

      default String streamLog(String serviceId, ServiceOperations.StreamLogMode mode) throws ExecutionException
      Tries to attach the logs of serviceId to a sender determined by TransportConverterFactory.
      Parameters:
      serviceId - the service id
      mode - the mode
      Returns:
      the URIs where to find the (streamed) log as JSON list or empty
      Throws:
      ExecutionException - if attaching fails