Class ServiceConfiguration.Builder

java.lang.Object
eu.cloudnetservice.driver.service.ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
eu.cloudnetservice.driver.service.ServiceConfiguration.Builder
All Implemented Interfaces:
DefaultedDocPropertyHolder, DefaultedDocPropertyHolder.Mutable<ServiceConfiguration.Builder>, DefaultedDocPropertyHolder.Mutable.WithDirectModifier<ServiceConfiguration.Builder>, DocPropertyHolder, DocPropertyHolder.Mutable<ServiceConfiguration.Builder>
Enclosing class:
ServiceConfiguration
public static class ServiceConfiguration.Builder extends ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
Represents a builder for a service configuration.
Since:
4.0

  • Field Details

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • serviceId

      @NonNull public @NonNull ServiceConfiguration.Builder serviceId(@NonNull ServiceId.Builder serviceId)
      Sets the service id builder of this builder. Further calls might overwrite changes in the given builder, for example when setting the environment of the configuration via this builder.
      Parameters:
      serviceId - the new service id builder to use.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given service id builder is null.

    • processConfig

      @NonNull public @NonNull ServiceConfiguration.Builder processConfig(@NonNull ProcessConfiguration.Builder processConfig)
      Sets the process configuration builder of this builder. Further calls might overwrite changes in the given builder, for example when setting the max heap memory services are allowed to use.
      Parameters:
      processConfig - the new process configuration to use.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given process configuration builder is null.

    • retryConfiguration

      @NonNull public @NonNull ServiceConfiguration.Builder retryConfiguration(@NonNull @NonNull ServiceCreateRetryConfiguration retryConfiguration)
      Sets 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.
      Parameters:
      retryConfiguration - the retry configuration to use.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given retry configuration is null.

    • taskName

      @NonNull public @NonNull ServiceConfiguration.Builder taskName(@NonNull @NonNull String taskName)
      Sets the task name to use for the created services. This method will not change any other option than the task name, so if a task with the given name exists it has no effect when calling this method as nothing will be copied from that task into this builder.

      NOTE: the given task name must still match the defined pattern for a task name.

      Parameters:
      taskName - a task name, no task with that name must exist.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given task name is null.
      IllegalArgumentException - if the given task name doesn't follow the task naming policy.

    • environment

      @NonNull public @NonNull ServiceConfiguration.Builder environment(@NonNull @NonNull String environment)
      Sets the name of the environment to use for services created based on the service configuration. The environment will be resolved when creating the service and decides for example which application file gets used and which configuration files are updated for the environment.
      Parameters:
      environment - the name of the environment to use for services created based on the service configuration.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given environment name is null.

    • environment

      @NonNull public @NonNull ServiceConfiguration.Builder environment(@NonNull @NonNull ServiceEnvironmentType environment)
      Sets the environment to use for services created based on the service configuration. The environment decides for example which application file gets used and which configuration files are updated for the environment.
      Parameters:
      environment - the environment to use for services created based on the service configuration.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given environment is null.

    • taskId

      @NonNull public @NonNull ServiceConfiguration.Builder taskId(int taskId)
      Sets the base task id for services created based on the service configuration. Services which have the same task name will never have the same task id twice. If the given task id is already taken it will get counted up until either it finds a free task id or the integer limit is reached.

      Note: the given task id must be either

      1. -1 for automatic detection of the lowest free task id.
      2. positive (excluding 0) to start counting at the given task id.
      Parameters:
      taskId - the base task id to count up from when creating services based on the configuration.
      Returns:
      the same instance as used to call the method, for chaining.

    • uniqueId

      @NonNull public @NonNull ServiceConfiguration.Builder uniqueId(@NonNull @NonNull UUID uniqueId)
      Sets the unique id of any service created based on the service configuration. A random uuid will be chosen if the set unique id is already taken by any other service.
      Parameters:
      uniqueId - the base unique id for services created based on the service configuration.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given unique id is null.

    • javaCommand

      @NonNull public @NonNull ServiceConfiguration.Builder javaCommand(@Nullable @Nullable String javaCommand)
      Sets the java command to use when starting a service based on the service configuration. If no java command is set in the configuration, the configured command from the node which picked up the service will be used.
      Parameters:
      javaCommand - the java command to use when starting service based on the service configuration.
      Returns:
      the same instance as used to call the method, for chaining.

    • nameSplitter

      @NonNull public @NonNull ServiceConfiguration.Builder nameSplitter(@NonNull @NonNull String nameSplitter)
      Sets the name splitter for services based on the service configuration. The name splitter will be set between the task name and the service name. For example if the name splitter is set to #, the task name to Lobby and the task id is 1, the full service name will be Lobby#1.
      Parameters:
      nameSplitter - the name splitter to use for services created based on the service configuration.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given name splitter is null.
      IllegalArgumentException - if the given name splitter does not follow the naming pattern.

    • node

      @NonNull public @NonNull ServiceConfiguration.Builder node(@Nullable @Nullable String nodeUniqueId)
      Sets the node on which services based on the service configuration should get created and started. If the given node is either unknown or unable to start services, service creation requests will not work and there will be no tries to move the service onto another node.

      Note: this configuration option is most likely needed when trying to start a previously stored static service as they are not synced in the cluster automatically.

      Parameters:
      nodeUniqueId - the unique id of the node which should pick up the services.
      Returns:
      the same instance as used to call the method, for chaining.

    • allowedNodes

      @NonNull public @NonNull ServiceConfiguration.Builder allowedNodes(@NonNull @NonNull Collection<String> allowedNodes)
      Sets the names of the nodes which are allowed to pick up services created based on the service configuration. If an empty collection is given all nodes are allowed to start the service. If specific nodes are selected the one with the lowest resource usage (in percent) will be chosen to start the service. This setting has no effect if one specific node was selected to start the services.
      Parameters:
      allowedNodes - the nodes which are allowed to start the services, an empty collection for all nodes.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given node name collection is null.

    • runtime

      @NonNull public @NonNull ServiceConfiguration.Builder runtime(@NonNull @NonNull String runtime)
      Sets the runtime to use for the service. The runtime decides which factory is used for the service to be started and in which way. An example for an external runtime (other than the default, build-in jvm runtime) is the docker-jvm runtime which starts services in a docker container.

      Note: if no runtime with the given name exists on the node which is picking up the service it will result in an error.

      Parameters:
      runtime - the runtime to use for services based on the service configuration.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given runtime is null.

    • hostAddress

      @NonNull public @NonNull ServiceConfiguration.Builder hostAddress(@Nullable @Nullable String hostAddress)
      Sets the host address which all services based on this configuration are bound to. The host address is required to be assignable on every node a service can be started on. In order to ensure that the host address is assignable on every node, ip aliases can be used. Ip aliases can be defined in the config of each node. To use them set the host address to the name of the alias. If null is supplied the fallback address of the node is used.

      Note: if the host address is not assignable or the alias is not resolvable on the node which is picking up the service it will result in an error.

      Parameters:
      hostAddress - the host address all services based on this configuration should get bound to.
      Returns:
      the same instance as used to call the method, for chaining.

    • autoDeleteOnStop

      @NonNull public @NonNull ServiceConfiguration.Builder autoDeleteOnStop(boolean autoDeleteOnStop)
      Sets whether services created based on the service configuration should get deleted after being stopped. 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.

      Parameters:
      autoDeleteOnStop - if services should get deleted (unregistered) when stopping them.
      Returns:
      the same instance as used to call the method, for chaining.

    • staticService

      @NonNull public @NonNull ServiceConfiguration.Builder staticService(boolean staticService)
      Sets whether services created based on the service configuration should be static or not. Static services will never be deleted, meaning that when stopping the service the same state can be launched again without any need to deploy the current service state to a template.

      Note: static services are not automatically synced between nodes, you should take care of starting the service either always on the same node or ensure that the service state gets synced when it's being stopped.

      Parameters:
      staticService - if services created based on the configuration should be static or dynamic.
      Returns:
      the same instance as used to call the method, for chaining.

    • groups

      @NonNull public @NonNull ServiceConfiguration.Builder groups(@NonNull @NonNull Collection<String> groups)
      Sets the names of the groups which should get included onto any service created based on the service configuration. All groups targeting the environment of the builder will automatically get included onto all services without the need of explicitly defining them. If a group gets specified which is not known to the node picking up the service it will silently be ignored.

      This method overrides all previously added groups. The given collection will get copied into this builder, meaning that changes made to the collection after the method call will not reflect into the builder and vice-versa.

      Parameters:
      groups - the names of the groups to include on all services.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given group name collection is null.

    • modifyGroups

      @NonNull public @NonNull ServiceConfiguration.Builder modifyGroups(@NonNull @NonNull Consumer<Collection<String>> modifier)
      Modifies the names of the groups which should get included onto any service created based on the service configuration. All groups targeting the environment of the builder will automatically get included onto all services without the need of explicitly defining them. If a group gets specified which is not known to the node picking up the service it will silently be ignored.
      Parameters:
      modifier - the modifier to be applied to the already added groups of this builder.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given group name collection is null.

    • deletedFilesAfterStop

      @NonNull public @NonNull ServiceConfiguration.Builder deletedFilesAfterStop(@NonNull @NonNull Collection<String> deletedFilesAfterStop)
      Sets the files which should get deleted when stopping a service created based on the configuration. Any path in the given collection can either represent a single file or directory, but must be inside the service directory. Path traversal to leave the service directory will result in an exception.

      This method will override all previously added file deletions. The given collection will be copied into this builder, meaning that changes made to the collection after the method call will not reflect into the builder and vice-versa.

      Parameters:
      deletedFilesAfterStop - the files to delete when a service based on the configuration gets stopped.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given file name collection is null.

    • modifyDeletedFilesAfterStop

      @NonNull public @NonNull ServiceConfiguration.Builder modifyDeletedFilesAfterStop(@NonNull @NonNull Consumer<Collection<String>> modifier)
      Modifies the files which should get deleted when stopping a service created based on the configuration. Any path in the given collection can either represent a single file or directory, but must be inside the service directory. Path traversal to leave the service directory will result in an exception.
      Parameters:
      modifier - the modifier to be applied to the already added files of this builder.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given file name collection is null.

    • maxHeapMemory

      @NonNull public @NonNull ServiceConfiguration.Builder maxHeapMemory(int maxHeapMemory)
      Sets the maximum heap memory (in MB) a service based on this configuration is allowed to allocate. The given heap memory size must be at least 50 MB (less heap memory makes no sense when running a service).
      Parameters:
      maxHeapMemory - the maximum heap memory a service is allowed to use.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      IllegalArgumentException - if the given memory size is less than 50 mb.

    • jvmOptions

      @NonNull public @NonNull ServiceConfiguration.Builder jvmOptions(@NonNull @NonNull Collection<String> jvmOptions)
      Sets 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.

      The XmX and XmS options will always get appended based on the configured maximum heap memory size.

      This method will override all previously added jvm options. Furthermore, the given collection will be copied into this builder, meaning that changes to it will not reflect into the builder after the method call.

      Overrides:
      jvmOptions in class ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
      Parameters:
      jvmOptions - the jvm options of the configuration.
      Returns:
      the same instance as used to call the method, for chaining.

    • modifyJvmOptions

      @NonNull public @NonNull ServiceConfiguration.Builder modifyJvmOptions(@NonNull @NonNull Consumer<Collection<String>> jvmOptions)
      Modifies the jvm options of this builder. JVM options are there to configure the behaviour of the jvm, for example the garbage collector.

      The XmX and XmS options will always get appended based on the configured maximum heap memory size.

      Duplicate options will be omitted by this method directly. HOWEVER, adding the same option twice with a changed value to it will most likely result in the jvm to crash, beware!

      Overrides:
      modifyJvmOptions in class ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
      Parameters:
      jvmOptions - the modifier to be applied to the already added jvm options of this builder.
      Returns:
      the same instance as used to call the method, for chaining.

    • processParameters

      @NonNull public @NonNull ServiceConfiguration.Builder processParameters(@NonNull @NonNull Collection<String> processParameters)
      Sets 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.

      This method will override all previously added process parameters options. Furthermore, the given collection will be copied into this builder, meaning that changes to it will not reflect into the builder after the method call.

      Overrides:
      processParameters in class ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
      Parameters:
      processParameters - the process parameters of the configuration.
      Returns:
      the same instance as used to call the method, for chaining.

    • modifyProcessParameters

      @NonNull public @NonNull ServiceConfiguration.Builder modifyProcessParameters(@NonNull @NonNull Consumer<Collection<String>> modifier)
      Modifies 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.

      Duplicate parameters will get omitted by this method directly.

      Overrides:
      modifyProcessParameters in class ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
      Parameters:
      modifier - the modifier to be applied to the already added process parameters of this builder.
      Returns:
      the same instance as used to call the method, for chaining.

    • environmentVariables

      @NonNull public @NonNull ServiceConfiguration.Builder environmentVariables(@NonNull @NonNull Map<String,String> environmentVariables)
      Sets the environment variables which should set in the environment the process runs in.

      This method will override all previously added environment variables options. Furthermore, the given map will be copied into this builder, meaning that changes to it will not reflect into the builder after the method call.

      Overrides:
      environmentVariables in class ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
      Parameters:
      environmentVariables - the environment variables to apply to processes created based on this configuration.
      Returns:
      the same instance as used to call the method, for chaining.

    • modifyEnvironmentVariables

      @NonNull public @NonNull ServiceConfiguration.Builder modifyEnvironmentVariables(@NonNull @NonNull Consumer<Map<String,String>> modifier)
      Modifies the environment variables which should get appended to the environment of the process.
      Overrides:
      modifyEnvironmentVariables in class ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
      Parameters:
      modifier - the modifier to be applied to the already added environment variables of this builder.
      Returns:
      the same instance as used to call the method, for chaining.

    • startPort

      @NonNull public @NonNull ServiceConfiguration.Builder startPort(@Range(from=0L,to=65535L) int startPort)
      Sets the start port for services created based on the configuration. If the given port is already taken by any other process it gets counted up until it either reaches the port limit (65535) or finds a free port to start the service on. If no free port was found an exception is thrown and the service will not start.
      Parameters:
      startPort - the port to start services upwards from.
      Returns:
      the same instance as used to call the method, for chaining.

    • self

      @NonNull protected @NonNull ServiceConfiguration.Builder self()
      Get the current instance of the builder, this removes the need for unchecked generics which are annoying.
      Specified by:
      self in class ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
      Returns:
      the current instance of this builder.

    • build

      @NonNull public @NonNull ServiceConfiguration build()
      Builds a service configuration based on all previously supplied properties. NOTE: further changes to this builder might reflect into the service configuration build from it. Do not re-use a builder, always use a new one.
      Specified by:
      build in class ServiceConfigurationBase.Builder<ServiceConfiguration, ServiceConfiguration.Builder>
      Returns:
      a new service configuration based on this builder.
      Throws:
      NullPointerException - if one of the required properties is either not set or invalid.
      IllegalArgumentException - if the given port is out of range.