Interface SpecificCloudServiceProvider

public interface SpecificCloudServiceProvider
An instance of this class represents a manageable service in the cluster which is stateless. This is the main difference to a service snapshot. While the snapshot holds the service information in a specific moment, the provider of the service will always be ready to execute actions on a service (unless the provider is no longer valid).

The provider for a service could possibly target other services which were created with the same name or unique id this provider was created for. Therefore, acquiring a new provider for a service when you're unsure if the old service still exists is recommended.

Since:
4.0

  • Method Details

    • serviceInfo

      @Nullable @Nullable ServiceInfoSnapshot serviceInfo()
      Get the last reported service info snapshot of the service. This snapshot is updated on an event basis, therefore this method will not always return a snapshot which is brand-new. More specifically, for example the bridge will cause a service info update each time a player joins/leaves the current server. This leads to unexpected information when for example querying the process snapshot or the creation time, as these data can be very old.

      This information is null when either the underlying service of this provider was unregistered from the system or when creating the provider the service didn't yet exist.

      If you need an update-to-date version of the snapshot, use forceUpdateServiceInfo() instead.

      Returns:
      the last reported information snapshot of the service, can be null as described above.

    • valid

      boolean valid()
      Get if this provider is still valid. A provider which is valid
      1. targets a service which still exists.
      2. targets a service which is not marked as deleted.
      Returns:
      true if this provider is still valid, false otherwise.

    • forceUpdateServiceInfo

      @Nullable @Nullable ServiceInfoSnapshot forceUpdateServiceInfo()
      Forces the service to update its service info and always returns a newly created snapshot of the service (other than returning the last reported snapshot what serviceInfo() does). This method returns null when the underlying service
      1. doesn't exist anymore.
      2. is not started and therefore not connected to a node.
      Returns:
      a newly created service snapshot, can be null as described above.

    • addServiceTemplate

      void addServiceTemplate(@NonNull @NonNull ServiceTemplate serviceTemplate)
      Adds the given service template to the inclusion queue. This does not mean that the given template will be copied directly onto the service. The template will be copied when
      1. the service gets prepared, for example when restarting the service.
      2. the templates get included via the associated method in this provider.
      Parameters:
      serviceTemplate - the service template to enqueue.
      Throws:
      NullPointerException - if the given service template is null.

    • addServiceRemoteInclusion

      void addServiceRemoteInclusion(@NonNull @NonNull ServiceRemoteInclusion serviceRemoteInclusion)
      Adds the given service remote inclusion to the queue. This does not mean that the inclusion gets copied directly onto the service. The inclusion will be included when:
      1. the service gets prepared, for example when restarting the service.
      2. the inclusions get included via the associated methods in this provider.
      Parameters:
      serviceRemoteInclusion - the inclusion to enqueue.
      Throws:
      NullPointerException - if the given inclusion is null.

    • addServiceDeployment

      void addServiceDeployment(@NonNull @NonNull ServiceDeployment serviceDeployment)
      Adds the given service deployment to the queue. This does not mean that the deployment gets executed directly. It will be executed when:
      1. the service stops, for example when deleting it.
      2. the deployments get executed via the associated methods in this provider.
      Parameters:
      serviceDeployment - the deployment to enqueue.
      Throws:
      NullPointerException - if the given deployment is null.

    • cachedLogMessages

      @NonNull @NonNull Queue<String> cachedLogMessages()
      Get all log messages which are currently cached on the node this service is running on. Modifications to the returned queue might be possible. The size of the returned collection is always not bigger than configured in the node configuration the associated service is running on.

      This method never return null but can return an empty queue if the underlying service does not exist.

      Returns:
      all cached log messages of the service on the node the service is running on.

    • toggleScreenEvents

      boolean toggleScreenEvents(@NonNull @NonNull ChannelMessageSender channelMessageSender, @NonNull @NonNull String channel)
      Enables or disabled the screen event handling. When the log events get enabled an event will be called on the given sender of the request holding information about the log line. The provided channel represents the event channel to which the listener need to listen in order to receive the events, set this to * to call all event listeners.
      Parameters:
      channelMessageSender - the sender who should receive the log events.
      channel - the event channel to call the log entry event in.
      Returns:
      true if the log events were enabled for the sender, false if they got disabled.
      Throws:
      NullPointerException - if either the given message sender or channel is null.

    • stop

      default void stop()
      Sets the service lifecycle to stopped and executes the appropriate actions to change to the stopped state.

    • start

      default void start()
      Sets the service lifecycle to started and executes the appropriate actions to change to the started state.

    • delete

      default void delete()
      Sets the service lifecycle to deleted and executes the appropriate actions to change to the deleted state.

    • restart

      void restart()
      Stops this service and then tries to start it again. Note that this method will stop and delete the service, but not start the service again when auto delete on stop is active for the service.

    • updateLifecycle

      void updateLifecycle(@NonNull @NonNull ServiceLifeCycle lifeCycle)
      Requests a change of the service lifecycle to the given one. This method has no effect if to the given lifecycle cannot be switched from the current lifecycle of the service.
      Parameters:
      lifeCycle - the service lifecycle to switch to.
      Throws:
      NullPointerException - if the given lifecycle is null.

    • deleteFiles

      void deleteFiles()
      Stops the service if it is currently running marks it as deleted. Other than the delete method, in this case all files associated with the service will get deleted permanently even if the service is static. If you just want to stop and delete all files of the service when it is non-static use delete() instead.

      Deployments added to the service will get executed before the files get deleted.

    • runCommand

      void runCommand(@NonNull @NonNull String command)
      Executes the given command on the service if it is running. The given command line will be sent to stdin directly.
      Parameters:
      command - the command line to execute.
      Throws:
      NullPointerException - if the given command line is null.

    • installedTemplates

      @NonNull @NonNull Collection<ServiceTemplate> installedTemplates()
      Gets the templates that actually are installed on the service. If a template is present in the configuration ServiceConfiguration but wasn't pulled onto the service it won't appear in this collection.
      Returns:
      all installed templates of the service.

    • installedInclusions

      @NonNull @NonNull Collection<ServiceRemoteInclusion> installedInclusions()
      Gets the inclusions that actually are installed on the service. If an inclusion is present in the configuration ServiceConfiguration but wasn't pulled onto the service it won't appear in this collection.
      Returns:
      all installed inclusions of the service.

    • installedDeployments

      @NonNull @NonNull Collection<ServiceDeployment> installedDeployments()
      Gets the deployments that were actually executed for this service. If a deployment is present in the configuration ServiceConfiguration but wasn't executed until now it won't appear in this collection.
      Returns:
      all executed deployments of the service.

    • includeWaitingServiceTemplates

      void includeWaitingServiceTemplates()
      Copies all queued templates onto the service without further checks. Note that this can lead to errors if you try to override locked files or files which are in use (for example the application jar file).

      This method forces the inclusion of all templates, see includeWaitingServiceTemplates(boolean) for more information.

    • includeWaitingServiceTemplates

      void includeWaitingServiceTemplates(boolean force)
      Copies all queued templates onto the service without further checks. Note that this can lead to errors if you try to override locked files or files which are in use (for example the application jar file).

      This method only copies all templates to a service if the force option is set to true. If disabled the normal checks are made before trying to copy a template (for example if a template should be copied to a static service).

      Parameters:
      force - if the inclusions of the templates should be forced.

    • includeWaitingServiceInclusions

      void includeWaitingServiceInclusions()
      Downloads and copies all waiting inclusions onto the service without further checks. Note that this can lead to errors if you try to override locked files or files which are in use (for example the application jar file).

    • deployResources

      void deployResources(boolean removeDeployments)
      Executes all deployments which were previously added to the associated service and optionally removes them once they were executed successfully.
      Parameters:
      removeDeployments - if the deployments should get removed after executing them.

    • removeAndExecuteDeployments

      default void removeAndExecuteDeployments()
      Executes all deployments which were previously added to the associated service and removes them once they were executed. This method call is identical to provider.deployResources(true).

    • updateProperties

      void updateProperties(@NonNull @NonNull Document properties)
      Updates the properties of the current service info to include all properties set in the given document. All existing properties will be overridden when using this method. If the associated service is currently running, a request will be sent to update the current service information to use the given properties. Plugins on the service can decide to ignore values set in the given document and override them.

      Example use in an async context might look like this: 

       
 public void updateCustomProperties(@NonNull SpecificCloudServiceProvider provider) {
   provider.serviceInfoAsync().thenAcceptAsync(info -> {
     var properties = info.properties();
     properties.append("hello", "world");
     properties.append("world", 123);
     provider.updateProperties(properties);
   });
 }
      The difference to using the updatePropertiesAsync(Document) method is that the update operation is executed in the same async context as the service info retrieval, rather than moving the update (without a need) into a separate thread.

      Update request of the properties might not reflect instantly into new service snapshots produced by the service.

      Parameters:
      properties - the new properties of the service to cleanly set.
      Throws:
      NullPointerException - if the given properties document is null.

    • serviceInfoAsync

      @NonNull @NonNull CompletableFuture<ServiceInfoSnapshot> serviceInfoAsync()
      Get the last reported service info snapshot of the service. This snapshot is updated on an event basis, therefore this method will not always return a snapshot which is brand-new. More specifically, for example the bridge will cause a service info update each time a player joins/leaves the current server. This leads to unexpected information when for example querying the process snapshot or the creation time, as these data can be very old.

      This information is null when either the underlying service of this provider was unregistered from the system or when creating the provider the service didn't yet exist.

      If you need an update-to-date version of the snapshot, use forceUpdateServiceInfo() instead.

      Returns:
      a task completed with the last reported snapshot of the service, can be null as described above.

    • validAsync

      @NonNull @NonNull CompletableFuture<Boolean> validAsync()
      Get if this provider is still valid. A provider which is valid
      1. targets a service which still exists.
      2. targets a service which is not marked as deleted.
      Returns:
      a task completed with true if this provider is still valid, false otherwise.

    • forceUpdateServiceInfoAsync

      @NonNull @NonNull CompletableFuture<ServiceInfoSnapshot> forceUpdateServiceInfoAsync()
      Forces the service to update its service info and always returns a newly created snapshot of the service (other than returning the last reported snapshot what serviceInfo() does). This method returns null when the underlying service
      1. doesn't exist anymore.
      2. is not started and therefore not connected to a node.
      Returns:
      a task completed with a newly created service snapshot, can be null as described above.

    • addServiceTemplateAsync

      @NonNull @NonNull CompletableFuture<Void> addServiceTemplateAsync(@NonNull @NonNull ServiceTemplate serviceTemplate)
      Adds the given service template to the inclusion queue. This does not mean that the given template will be copied directly onto the service. The template will be copied when
      1. the service gets prepared, for example when restarting the service.
      2. the templates get included via the associated method in this provider.
      Parameters:
      serviceTemplate - the service template to enqueue.
      Returns:
      a task completed when the given service template was enqueued.
      Throws:
      NullPointerException - if the given service template is null.

    • addServiceRemoteInclusionAsync

      @NonNull @NonNull CompletableFuture<Void> addServiceRemoteInclusionAsync(@NonNull @NonNull ServiceRemoteInclusion serviceRemoteInclusion)
      Adds the given service remote inclusion to the queue. This does not mean that the inclusion gets copied directly onto the service. The inclusion will be included when:
      1. the service gets prepared, for example when restarting the service.
      2. the inclusions get included via the associated methods in this provider.
      Parameters:
      serviceRemoteInclusion - the inclusion to enqueue.
      Returns:
      a task completed when the given service remote inclusion was enqueued.
      Throws:
      NullPointerException - if the given inclusion is null.

    • addServiceDeploymentAsync

      @NonNull @NonNull CompletableFuture<Void> addServiceDeploymentAsync(@NonNull @NonNull ServiceDeployment serviceDeployment)
      Adds the given service deployment to the queue. This does not mean that the deployment gets executed directly. It wil be executed when:
      1. the service stops, for example when deleting it.
      2. the deployments get executed via the associated methods in this provider.
      Parameters:
      serviceDeployment - the deployment to enqueue.
      Returns:
      a task completed when the given service deployment was enqueued.
      Throws:
      NullPointerException - if the given deployment is null.

    • cachedLogMessagesAsync

      @NonNull @NonNull CompletableFuture<Queue<String>> cachedLogMessagesAsync()
      Get all log messages which are currently cached on the node this service is running on. Modifications to the returned queue might be possible. The size of the returned collection is always not bigger than configured in the node configuration the associated service is running on.

      This method never return null but can return an empty queue if the underlying service does not exist.

      Returns:
      a task completed with all cached service log messages on the node the service is running on.

    • toggleScreenEventsAsync

      @NonNull @NonNull CompletableFuture<Boolean> toggleScreenEventsAsync(@NonNull @NonNull ChannelMessageSender sender, @NonNull @NonNull String channel)
      Enables or disabled the screen event handling. When the log events get enabled an event will be called on the given sender of the request holding information about the log line. The provided channel represents the event channel to which the listener need to listen in order to receive the events, set this to * to call all event listeners.
      Parameters:
      sender - the sender who should receive the log events.
      channel - the event channel to call the log entry event in.
      Returns:
      a task completed with true if the log events were enabled for the sender, false if they got disabled.
      Throws:
      NullPointerException - if either the given message sender or channel is null.

    • stopAsync

      @NonNull default @NonNull CompletableFuture<Void> stopAsync()
      Sets the service lifecycle to stopped and executes the appropriate actions to change to the stopped state.
      Returns:
      a task completed when the service lifecycle changed to stopped.

    • startAsync

      @NonNull default @NonNull CompletableFuture<Void> startAsync()
      Sets the service lifecycle to started and executes the appropriate actions to change to the started state.
      Returns:
      a task completed when the service lifecycle changed to running.

    • deleteAsync

      @NonNull default @NonNull CompletableFuture<Void> deleteAsync()
      Sets the service lifecycle to deleted and executes the appropriate actions to change to the deleted state.
      Returns:
      a task completed when the service state changed to deleted.

    • restartAsync

      @NonNull @NonNull CompletableFuture<Void> restartAsync()
      Stops this service and then tries to start it again. Note that this method will stop and delete the service, but not start the service again when auto delete on stop is active for the service.
      Returns:
      a task completed when the service was restarted.

    • updateLifecycleAsync

      @NonNull @NonNull CompletableFuture<Void> updateLifecycleAsync(@NonNull @NonNull ServiceLifeCycle lifeCycle)
      Requests a change of the service lifecycle to the given one. This method has no effect if to the given lifecycle cannot be switched from the current lifecycle of the service.
      Parameters:
      lifeCycle - the service lifecycle to switch to.
      Returns:
      a task completed when the lifecycle change was tried.
      Throws:
      NullPointerException - if the given lifecycle is null.

    • deleteFilesAsync

      @NonNull @NonNull CompletableFuture<Void> deleteFilesAsync()
      Stops the service if it is currently running marks it as deleted. Other than the delete method, in this case all files associated with the service will get deleted permanently even if the service is static. If you just want to stop and delete all files of the service when it is non-static use delete() instead.

      Deployments added to the service will get executed before the files get deleted.

      Returns:
      a task completed when the service files were deleted.

    • runCommandAsync

      @NonNull @NonNull CompletableFuture<Void> runCommandAsync(@NonNull @NonNull String command)
      Executes the given command on the service if it is running. The given command line will be sent to stdin directly.
      Parameters:
      command - the command line to execute.
      Returns:
      a task completed when the command was send to the service.
      Throws:
      NullPointerException - if the given command line is null.

    • includeWaitingServiceTemplatesAsync

      @NonNull @NonNull CompletableFuture<Void> includeWaitingServiceTemplatesAsync()
      Copies all queued templates onto the service without further checks. Note that this can lead to errors if you try to override locked files or files which are in use (for example the application jar file).

      This method forces the inclusion of all templates, see includeWaitingServiceTemplates(boolean) for more information.

      Returns:
      a task completed when the waiting service templates were included.

    • includeWaitingServiceTemplatesAsync

      @NonNull @NonNull CompletableFuture<Void> includeWaitingServiceTemplatesAsync(boolean force)
      Copies all queued templates onto the service without further checks. Note that this can lead to errors if you try to override locked files or files which are in use (for example the application jar file).

      This method only copies all templates to a service if the force option is set to true. If disabled the normal checks are made before trying to copy a template (for example if a template should be copied to a static service).

      Parameters:
      force - if the inclusions of the templates should be forced.
      Returns:
      a task completed when the waiting service templates were included.

    • includeWaitingServiceInclusionsAsync

      @NonNull @NonNull CompletableFuture<Void> includeWaitingServiceInclusionsAsync()
      Downloads and copies all waiting inclusions onto the service without further checks. Note that this can lead to errors if you try to override locked files or files which are in use (for example the application jar file).
      Returns:
      a task completed when the waiting service inclusions were included.

    • deployResourcesAsync

      @NonNull @NonNull CompletableFuture<Void> deployResourcesAsync(boolean removeDeployments)
      Executes all deployments which were previously added to the associated service and optionally removes them once they were executed successfully.
      Parameters:
      removeDeployments - if the deployments should get removed after executing them.
      Returns:
      a task completed when all waiting service deployments were executed.

    • removeAndExecuteDeploymentsAsync

      @NonNull @NonNull CompletableFuture<Void> removeAndExecuteDeploymentsAsync()
      Executes all deployments which were previously added to the associated service and removes them once they were executed. This method call is identical to provider.deployResourcesAsync(true).
      Returns:
      a task completed when all waiting service deployments were executed.

    • updatePropertiesAsync

      @NonNull @NonNull CompletableFuture<Void> updatePropertiesAsync(@NonNull @NonNull Document properties)
      Updates the properties of the current service info to include all properties set in the given document. All existing properties will be overridden when using this method. If the associated service is currently running, a request will be sent to update the current service information to use the given properties. Plugins on the service can decide to ignore values set in the given document and override them.

      Update request of the properties might not reflect instantly into new service snapshots produced by the service.

      Parameters:
      properties - the new properties of the service to cleanly set.
      Returns:
      a task completed when the update request was received and processed by the node the service runs on.
      Throws:
      NullPointerException - if the given properties document is null.