Class ServiceConfiguration

java.lang.Object
eu.cloudnetservice.driver.service.ServiceConfigurationBase
eu.cloudnetservice.driver.service.ServiceConfiguration
All Implemented Interfaces:
DefaultedDocPropertyHolder, DocPropertyHolder, Cloneable
public class ServiceConfiguration extends ServiceConfigurationBase implements Cloneable
The configuration based on which a service gets created. This configuration is completely lose from any service task or group configuration and only softly includes them. This means that creating a service without having to create a task first is completely possible and supported. One example use case are private servers which don't require a task to be created.

Example usage to create a service based on a task: 

 
  public final class ServiceCreateHelper {
    public void createService() {
      ServiceTask task = serviceTaskProvider.serviceTask("Lobby");
      ServiceConfiguration config = ServiceConfiguration.builder(task).build();
      ServiceCreateResult createResult = config.createNewService();

      if (createResult.state() == ServiceCreateResult.State.CREATED) {
        // the service was created
        // prints for example "Lobby-1"
        System.out.println(createResult.serviceInfo().name());
      } else {
        // service creation failed or was deferred
        System.out.println("Unable to create service: " + createResult.state());
      }
    }
  }

Example of changing the task name of the service, this change will show up in the service name: 

 
  public final class ServiceCreateHelper {
    public void createService() {
      ServiceTask task = serviceTaskProvider.serviceTask("Lobby");
      ServiceConfiguration config = ServiceConfiguration.builder(task)
        .taskName("HelloWorld")
        .build();
      ServiceCreateResult createResult = config.createNewService();

      if (createResult.state() == ServiceCreateResult.State.CREATED) {
        // the service was created
        // prints for example "HelloWorld-1" because we changed the name of the task
        System.out.println(createResult.serviceInfo().name());
      } else {
        // service creation failed or was deferred
        // for example not enough heap memory was free to start the service
        System.out.println("Unable to create service: " + createResult.state());
      }
    }
  }

But you can also create a service without any task, configured as we want it to be. It's required to set the task and environment name to create a service that way. Example: 

 
  public final class ServiceCreateHelper {
    public void createService() {
      ServiceConfiguration config = ServiceConfiguration.builder()
        .nameSplitter("#")
        .maxHeapMemory(1024)
        .taskName("HelloWorld")
        .environment("MINECRAFT_SERVER")
        .build();
      ServiceCreateResult createResult = config.createNewService();

      if (createResult.state() == ServiceCreateResult.State.CREATED) {
        // the service was created
        // prints for example "HelloWorld#1" because
        // we set the task name and name splitter to these values
        System.out.println(createResult.serviceInfo().name());
      } else {
        // service creation failed or was deferred
        // for example not enough heap memory was free to start the service
        System.out.println("Unable to create service: " + createResult.state());
      }
    }
  }
Since:
4.0

  • Field Details

    • serviceId

      protected final ServiceId serviceId

    • processConfig

      protected final ProcessConfiguration processConfig

    • retryConfiguration

      protected final ServiceCreateRetryConfiguration retryConfiguration

    • port

      protected final int port

    • runtime

      protected final String runtime

    • hostAddress

      protected final String hostAddress

    • javaCommand

      protected final String javaCommand

    • autoDeleteOnStop

      protected final boolean autoDeleteOnStop

    • staticService

      protected final boolean staticService

    • groups

      protected final Set<String> groups

    • deletedFilesAfterStop

      protected final Set<String> deletedFilesAfterStop

  • Constructor Details

    • ServiceConfiguration

      protected ServiceConfiguration(@NonNull @NonNull ServiceId serviceId, @NonNull @NonNull ProcessConfiguration processConfig, @NonNull @NonNull ServiceCreateRetryConfiguration retryConfiguration, int port, @NonNull @NonNull String runtime, @Nullable @Nullable String hostAddress, @Nullable @Nullable String javaCommand, boolean autoDeleteOnStop, boolean staticService, @NonNull @NonNull Set<String> groups, @NonNull @NonNull Set<String> deletedFilesAfterStop, @NonNull @NonNull Set<ServiceTemplate> templates, @NonNull @NonNull Set<ServiceDeployment> deployments, @NonNull @NonNull Set<ServiceRemoteInclusion> includes, @NonNull @NonNull Document properties)
      Constructs a new service configuration instance.
      Parameters:
      serviceId - the id of the service to create based on the configuration.
      processConfig - the process configuration of the service which gets created.
      retryConfiguration - the service create retry configuration to apply if the initial service create fails.
      port - the port of the service to start with, might get increased when already taken.
      runtime - the runtime of the service to create it based on, for example jvm.
      hostAddress - the host address the service based on this configuration is bound to.
      javaCommand - the java command to use when starting a service.
      autoDeleteOnStop - if the service should get deleted when stopping.
      staticService - if the service which gets created should be static (no file deletion when stopping).
      groups - the names of the group configurations to include before starting the service.
      deletedFilesAfterStop - all files which should get deleted when stopping a service based on this config.
      templates - the templates to include before starting a service based on this config.
      deployments - the deployments to execute when stopping a service based on this config.
      includes - the inclusions to include before starting a service based on this configuration.
      properties - the properties which should get copied onto the service before starting.
      Throws:
      NullPointerException - if one of the given parameters is null.

  • Method Details

    • builder

      @NonNull public static @NonNull ServiceConfiguration.Builder builder()
      Constructs a new builder instance for a service configuration.
      Returns:
      a new service configuration builder.

    • builder

      @NonNull public static @NonNull ServiceConfiguration.Builder builder(@NonNull @NonNull ServiceTask task)
      Creates a new builder instance for a service configuration which has the same options set as the given service task. Note: the properties of the task will not get copied into the configuration as they don't explicitly belong to the service. If you do want the properties in the task anyway, make sure to set them manually in the builder.

      Changes made to the given service task will not reflect into the created builder and vice-versa.

      Parameters:
      task - the task to copy the options of.
      Returns:
      a new builder instance initialized with the options set in the given task.
      Throws:
      NullPointerException - if the given task is null.

    • builder

      @NonNull public static @NonNull ServiceConfiguration.Builder builder(@NonNull @NonNull ServiceConfiguration configuration)
      Creates a new service configuration builder which has the same options set as the given service configuration. Changes made to the given configuration will not reflect into the new builder and vice-versa.

      When calling build directly after creating the builder based on the given service configuration it will return a service configuration which is equal to the given one, but not identical.

      Parameters:
      configuration - the configuration to copy the set options of.
      Returns:
      a new builder instance which has the same options set as the given configuration.
      Throws:
      NullPointerException - if the given configuration is null.

    • serviceId

      @NonNull public @NonNull ServiceId serviceId()
      Get the base service id all services created based on this configuration will use. However, pre-create checks might change the configuration if needed, for example increasing the service id if it is already taken or setting the node on which the service will start when it is not set already. These changes will not reflect into the service id object returned by this object.
      Returns:
      the base service id for services created using this configuration.

    • retryConfiguration

      @NonNull public @NonNull ServiceCreateRetryConfiguration retryConfiguration()
      Get the creation retry configuration that will be applied to all services which are created based on the configuration. If the configuration is enabled and a service cannot get created, then the configuration will be used to retry the service creation.
      Returns:
      the retry configuration for services created using this configuration.

    • autoDeleteOnStop

      public boolean autoDeleteOnStop()
      Get if services should be deleted when stopping the service. This does only mean that the service gets unregistered and is no longer available for starting, but does not mean that all service files get deleted when the service is static.

      If this option is false the service will be stopped and then go back to the prepared state, ready to get started again.

      Returns:
      if the service should get unregistered when stopping it.

    • staticService

      public boolean staticService()
      Get if services which get created based on this configuration are static. Files of static services will not get deleted when deleting the service. That means that starting the exact service after it was deleted, will result in the same service files to be present.

      NOTE: static services are not automatically synced between nodes, therefore a specific node to start the service on should be present, else it might result in a different configuration (or world) than expected.

      Returns:
      if services created based on this configuration should be static.

    • javaCommand

      @Nullable public @Nullable String javaCommand()
      Get the java command to use when starting a service. This can for example be used to use different java distros or versions on services. If no java command is set the java command configured in the node that is picking up the service will be used.
      Returns:
      the java command to use when starting services based on this configuration.

    • runtime

      @NonNull public @NonNull String runtime()
      Get the runtime to use when services gets created based on this configuration. Runtimes are there to allow different types of configuration for running in different environments, for example inside a docker container. The given runtime must be registered on the node which picks up the service, if not it will result in an error.
      Returns:
      the runtime to use when creating a service based on this configuration.

    • hostAddress

      public @UnknownNullability String hostAddress()
      Get the host address that all services based on this configuration are bound to. The host address is not required to be an ip address, it is possible that the host address is just an ip alias which needs to be resolved using the configuration of the node. The host address might be null, in that case the fallback host of the node is used.

      Note: Might be null until the host address was resolved during the preparation of a service based on this configuration. The resolved host address is not reflected into the original configuration, only into the configuration which is available through the service information snapshot.

      Returns:
      the host address that all services based on this configuration are bound to, null if not resolved yet.

    • groups

      @NonNull public @Unmodifiable @NonNull Set<String> groups()
      Get the names of the groups whose configuration should get included when starting a service based on this configuration. Each configuration is only included when it is present on the node starting the service, if not it will silently be ignored. Note that groups targeting the same environment as this configuration will get included automatically.
      Returns:
      the names of the group configurations to include their configurations before starting.

    • deletedFilesAfterStop

      @NonNull public @Unmodifiable @NonNull Set<String> deletedFilesAfterStop()
      Get the files (or directories) which should get deleted when stopping the service (before deployments are executed). Trying to delete files outside the service directory will result in an exception.
      Returns:
      a set of path to files/directories which should get deleted when stopping a service based on this config.

    • processConfig

      @NonNull public @NonNull ProcessConfiguration processConfig()
      Get the process configuration to apply to all services which get created based on this configuration.
      Returns:
      the process configuration to apply to all services.

    • port

      public @Range(from=0L,to=65535L) int port()
      The port of the service to start on. If the given port is already taken it will be counted up until it reaches the port limit (65535) or one of the ports in between is free to be taken. Port changes because of counting up will not be reflected into this configuration and vice-versa.
      Returns:
      the port number to start the service on, might be counted up when the port is already taken.

    • jvmOptions

      @NonNull public @Unmodifiable @NonNull Collection<String> jvmOptions()
      Get the jvm options which should get applied to the service command line. JVM options are there to configure the behaviour of the jvm, for example the garbage collector.
      Specified by:
      jvmOptions in class ServiceConfigurationBase
      Returns:
      the jvm options to set for services created based on this configuration.

    • processParameters

      @NonNull public @Unmodifiable @NonNull Collection<String> processParameters()
      Get the process parameters which should get appended to the command line. Process parameters are there to configure the application, for example setting an option like --online-mode=true.
      Specified by:
      processParameters in class ServiceConfigurationBase
      Returns:
      the process parameters to set for services created based on this configuration.

    • environmentVariables

      @NonNull public @Unmodifiable @NonNull Map<String,String> environmentVariables()
      Get the environment variables which should get appended to all environments of services which are created based on this configuration.
      Specified by:
      environmentVariables in class ServiceConfigurationBase
      Returns:
      the environment variables to set for services created based on this configuration.

    • createNewService

      @NonNull public @NonNull ServiceCreateResult createNewService()
      Creates and prepares a service based on this configuration using the default cloud service factory.
      Returns:
      a result representing the state of the service creation.
      See Also:

    • createNewServiceAsync

      @NonNull public @NonNull CompletableFuture<ServiceCreateResult> createNewServiceAsync()
      Creates and prepares a service based on this configuration using the default cloud service factory.
      Returns:
      a task completed with a result representing the state of the service creation.
      See Also:

    • clone

      @NonNull public @NonNull ServiceConfiguration clone()
      Overrides:
      clone in class Object