Package de.iip_ecosphere.platform.services

Class ServicesAasClient

java.lang.Object
de.iip_ecosphere.platform.support.iip_aas.SubmodelClient
de.iip_ecosphere.platform.support.iip_aas.SubmodelElementsCollectionClient
de.iip_ecosphere.platform.services.ServicesAasClient
All Implemented Interfaces:
ServiceOperations, ServicesClient
public class ServicesAasClient extends de.iip_ecosphere.platform.support.iip_aas.SubmodelElementsCollectionClient implements ServicesClient
A client for ServicesAas for accessing the operations provided by a certain resource.
Author:
Holger Eichelberger, SSE

  • Field Details

    • appId

      private String appId

  • Constructor Details

    • ServicesAasClient

      public ServicesAasClient(String resourceId) throws IOException
      Creates a client instance based on a deployed IIP-AAS from AasPartRegistry based on a submodel with resources.
      Parameters:
      resourceId - the id used as key in ServicesAas.NAME_SUBMODEL_RESOURCES to denote the resource to operate on
      Throws:
      IOException - if retrieving the IIP-AAS or the respective submodel fails

    • ServicesAasClient

      public ServicesAasClient(String resourceId, String appId) throws IOException
      Creates a client instance based on a deployed IIP-AAS from AasPartRegistry based on a submodel with resources.
      Parameters:
      resourceId - the id used as key in ServicesAas.NAME_SUBMODEL_RESOURCES to denote the resource to operate on
      appId - optional app id to select the service manager to use, may be empty or null for the first/fallback manager
      Throws:
      IOException - if retrieving the IIP-AAS or the respective submodel fails

  • Method Details

    • getSubmodelElementCollection

      protected de.iip_ecosphere.platform.support.aas.SubmodelElementCollection getSubmodelElementCollection()
      Overrides:
      getSubmodelElementCollection in class de.iip_ecosphere.platform.support.iip_aas.SubmodelElementsCollectionClient

    • contains

      private static boolean contains(String[] array, String elt)
      Returns whether array contains elt.
      Parameters:
      array - the array to search
      elt - the element to search for
      Returns:
      true if contained, false else

    • addArtifact

      public String addArtifact(URI location) throws ExecutionException
      Description copied from interface: ServiceOperations
      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.
      Specified by:
      addArtifact in interface ServiceOperations
      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

    • addArtifactAsTask

      public String addArtifactAsTask(String taskId, URI location) throws ExecutionException
      Description copied from interface: ServicesClient
      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.
      Specified by:
      addArtifactAsTask in interface ServicesClient
      Parameters:
      taskId - the task id to report on (may be null, leads to ServiceOperations.addArtifact(URI))
      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

    • removeArtifact

      public void removeArtifact(String artifactId) throws ExecutionException
      Description copied from interface: ServiceOperations
      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.
      Specified by:
      removeArtifact in interface ServiceOperations
      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

    • removeArtifactAsTask

      public void removeArtifactAsTask(String taskId, String artifactId) throws ExecutionException
      Description copied from interface: ServicesClient
      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.
      Specified by:
      removeArtifactAsTask in interface ServicesClient
      Parameters:
      taskId - the task id to report on (may be null, leads to ServiceOperations.removeArtifact(String))
      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

      public void updateService(String serviceId, URI location) throws ExecutionException
      Description copied from interface: ServiceOperations
      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.
      Specified by:
      updateService in interface ServiceOperations
      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

      public void switchToService(String serviceId, String targetId) throws ExecutionException
      Description copied from interface: ServiceOperations
      Switches to an interface-compatible service. This method cares for stopping the old service, performing a handover if adequate, starting the target service. [adaptation]
      Specified by:
      switchToService in interface ServiceOperations
      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

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

    • passivateService

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

    • startService

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

    • startService

      public void startService(Map<String,String> options, String... serviceId) throws ExecutionException
      Description copied from interface: ServiceOperations
      Starts one or multiple service. The service implementation must be already within the management domain of this instance by ServiceOperations.addArtifact(URI). The service(s) shall after some time be in state ServiceState.STARTING, ServiceState.RUNNING or ServiceState.FAILED.
      Specified by:
      startService in interface ServiceOperations
      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 ServiceOperations.OPTION_ARGS, ServiceOperations.OPTION_ENSEMBLE, ServiceOperations.OPTION_PARAMS, ServiceOperations.OPTION_SERVERS, or ServiceOperations.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

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

    • migrateService

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

    • reconfigureService

      public void reconfigureService(String serviceId, Map<String,String> values) throws ExecutionException
      Description copied from interface: ServiceOperations
      Reconfigures the underlying service. [adaptation]
      Specified by:
      reconfigureService in interface ServiceOperations
      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

      public void setServiceState(String serviceId, de.iip_ecosphere.platform.services.environment.ServiceState state) throws ExecutionException
      Description copied from interface: ServiceOperations
      Sets the state of the service. [adaptation]
      Specified by:
      setServiceState in interface ServiceOperations
      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

      public de.iip_ecosphere.platform.services.environment.ServiceState getServiceState(String serviceId)
      Description copied from interface: ServiceOperations
      Returns the state of the service.
      Specified by:
      getServiceState in interface ServiceOperations
      Parameters:
      serviceId - the id of the running service
      Returns:
      the state of the service

    • streamLog

      public String streamLog(String serviceId, ServiceOperations.StreamLogMode mode) throws ExecutionException
      Description copied from interface: ServiceOperations
      Tries to attach the logs of serviceId to a sender determined by TransportConverterFactory.
      Specified by:
      streamLog in interface ServiceOperations
      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

    • getServices

      public String[] getServices(String artifactId, boolean topLevelOnly)
      Description copied from interface: ServicesClient
      Returns the services associated to a given artifactId.
      Specified by:
      getServices in interface ServicesClient
      Parameters:
      artifactId - the artifactId to search for
      topLevelOnly - whether only top-level services or all shall be returned
      Returns:
      the associated service ids, empty if none was found

    • getServices

      private void getServices(de.iip_ecosphere.platform.support.aas.SubmodelElementCollection coll, String artifactId, List<String> serviceIds, boolean topLevelOnly)
      Collects the services associated to a given artifactId.
      Parameters:
      coll - the collection containing the services
      artifactId - the artifactId to search for
      serviceIds - the service ids to be modified as a side effect
      topLevelOnly - whether only top-level services or all services shall be returned

    • getArtifacts

      public de.iip_ecosphere.platform.support.aas.SubmodelElementCollection getArtifacts()
      Description copied from interface: ServicesClient
      Returns the collection with all artifacts of the resources this client was created for.
      Specified by:
      getArtifacts in interface ServicesClient
      Returns:
      the artifacts collection, may be null for none

    • getServices

      public de.iip_ecosphere.platform.support.aas.SubmodelElementCollection getServices()
      Description copied from interface: ServicesClient
      Returns the collection with all services of the resources this client was created for.
      Specified by:
      getServices in interface ServicesClient
      Returns:
      the services collection, may be null for none

    • getRelations

      public de.iip_ecosphere.platform.support.aas.SubmodelElementCollection getRelations()
      Returns the collection with all relations of the resources this client was created for.
      Returns:
      the relations collection, may be null for none

    • startServiceAsTask

      public void startServiceAsTask(String taskId, String... serviceId) throws ExecutionException
      Description copied from interface: ServicesClient
      Like ServiceOperations.startService(String...) but reporting on the given taskId.
      Specified by:
      startServiceAsTask in interface ServicesClient
      Parameters:
      taskId - the task id to report on (may be null, leads to ServiceOperations.startService(String...))
      serviceId - the id(s) of the service(s)
      Throws:
      ExecutionException - in case that starting the service fails for some reason

    • startServiceAsTask

      public void startServiceAsTask(String taskId, Map<String,String> options, String... serviceId) throws ExecutionException
      Description copied from interface: ServicesClient
      Like ServiceOperations.startService(Map, String...) but reporting on the given taskId.
      Specified by:
      startServiceAsTask in interface ServicesClient
      Parameters:
      taskId - the task id to report on (may be null, leads to ServiceOperations.startService(Map, String...))
      options - optional map of optional options, see ServiceOperations.startService(Map, String...)
      serviceId - the id(s) of the service(s)
      Throws:
      ExecutionException - in case that starting the service fails for some reason

    • stopServiceAsTask

      public void stopServiceAsTask(String taskId, String... serviceId) throws ExecutionException
      Description copied from interface: ServicesClient
      Like ServiceOperations.stopService(String...) but reporting on the given taskId.
      Specified by:
      stopServiceAsTask in interface ServicesClient
      Parameters:
      taskId - the task id to report on (may be null, leads to ServiceOperations.stopService(String...))
      serviceId - the id(s) of the service(s) to stop
      Throws:
      ExecutionException - if stopping the service fails

    • getServiceStateCount

      private int getServiceStateCount(de.iip_ecosphere.platform.support.aas.SubmodelElementCollection resource, de.iip_ecosphere.platform.services.environment.ServiceState state)
      Requests the number of services in the given state on the service manager submodel elements collection resource.
      Parameters:
      resource - the submodel elements collection representing a service manager
      state - the state to query for
      Returns:
      the number of service instances

    • getServiceInstanceCount

      public int getServiceInstanceCount(String serviceId)
      Description copied from interface: ServiceOperations
      Returns the number of service instances of the same service in the same application.
      Specified by:
      getServiceInstanceCount in interface ServiceOperations
      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