Class ServiceTask.Builder

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

  • Field Details

    • name

      private String name

    • hostAddress

      private String hostAddress

    • javaCommand

      private String javaCommand

    • runtime

      private String runtime

    • nameSplitter

      private String nameSplitter

    • maintenance

      private boolean maintenance

    • staticServices

      private boolean staticServices

    • disableIpRewrite

      private boolean disableIpRewrite

    • autoDeleteOnStop

      private boolean autoDeleteOnStop

    • groups

      private Set<String> groups

    • associatedNodes

      private Set<String> associatedNodes

    • deletedFilesAfterStop

      private Set<String> deletedFilesAfterStop

    • processConfiguration

      private ProcessConfiguration.Builder processConfiguration

    • startPort

      private int startPort

    • minServiceCount

      private int minServiceCount

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • name

      @NonNull public @NonNull ServiceTask.Builder name(@NonNull @NonNull String name)
      Sets the name of the service task to use. This name must conform the naming pattern defined in the service task class.
      Parameters:
      name - the name of the service task to use.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given name is null.

    • runtime

      @NonNull public @NonNull ServiceTask.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 ServiceTask.Builder hostAddress(@Nullable @Nullable String hostAddress)
      Sets the host address which all services of this task 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 to bind services of this task to.
      Returns:
      the same instance as used to call the method, for chaining.

    • javaCommand

      @NonNull public @NonNull ServiceTask.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 ServiceTask.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.

    • disableIpRewrite

      @NonNull public @NonNull ServiceTask.Builder disableIpRewrite(boolean disableIpRewrite)
      Sets if rewriting the ip set in the service configuration file (for example the server.properties file) should be disabled and the set ip should be used. Note that if disabled the node starting the service will not read the ip from the configuration, therefore the configured ip of the node is still used as the service address.
      Parameters:
      disableIpRewrite - if ip rewriting should be disabled.
      Returns:
      the same instance as used to call the method, for chaining.

    • maintenance

      @NonNull public @NonNull ServiceTask.Builder maintenance(boolean maintenance)
      Sets if this service task is in maintenance. This option is used to restrict for example who is able to join on a service. On the other hand, CloudNet will not try to start any service of tasks which are in maintenance even if the configured minimum service count is more than 0.
      Parameters:
      maintenance - if the task should be in maintenance.
      Returns:
      the same instance as used to call the method, for chaining.

    • autoDeleteOnStop

      @NonNull public @NonNull ServiceTask.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.

    • staticServices

      @NonNull public @NonNull ServiceTask.Builder staticServices(boolean staticServices)
      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:
      staticServices - if services created based on the configuration should be static or dynamic.
      Returns:
      the same instance as used to call the method, for chaining.

    • associatedNodes

      @NonNull public @NonNull ServiceTask.Builder associatedNodes(@NonNull @NonNull Collection<String> associatedNodes)
      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:
      associatedNodes - 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.

    • modifyAssociatedNodes

      @NonNull public @NonNull ServiceTask.Builder modifyAssociatedNodes(@NonNull @NonNull Consumer<Collection<String>> modifier)
      Modifies nodes which are allowed to pick up services created based on the service configuration. 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:
      modifier - the modifier to be applied to the already added allowed nodes of this builder.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given node name is null.

    • groups

      @NonNull public @NonNull ServiceTask.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 ServiceTask.Builder modifyGroups(@NonNull @NonNull Consumer<Collection<String>> modifier)
      Modifies 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 is null.

    • deletedFilesAfterStop

      @NonNull public @NonNull ServiceTask.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.

    • modifyDeletedFileAfterStop

      @NonNull public @NonNull ServiceTask.Builder modifyDeletedFileAfterStop(@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.

    • processConfiguration

      @NonNull public @NonNull ServiceTask.Builder processConfiguration(@NonNull ProcessConfiguration.Builder processConfiguration)
      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:
      processConfiguration - 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.

    • startPort

      @NonNull public @NonNull ServiceTask.Builder startPort(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.

    • minServiceCount

      @NonNull public @NonNull ServiceTask.Builder minServiceCount(int minServiceCount)
      Sets the amount of services which should be always online if this task is not in maintenance. CloudNet tries to start services until the minimum amount of them is online if possible, if for example no nodes are online which are able to pick up the service, the minimum service count might not get reached.
      Parameters:
      minServiceCount - the minimum amount of services CloudNet should try to keep online.
      Returns:
      the same instance as used to call the method, for chaining.

    • maxHeapMemory

      @NonNull public @NonNull ServiceTask.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.

    • serviceEnvironmentType

      @NonNull public @NonNull ServiceTask.Builder serviceEnvironmentType(@NonNull @NonNull ServiceEnvironmentType serviceEnvironmentType)
      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. If no default start port is yet set the default port of the service environment will be used.
      Parameters:
      serviceEnvironmentType - 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.

    • jvmOptions

      @NonNull public @NonNull ServiceTask.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<ServiceTask, ServiceTask.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 ServiceTask.Builder modifyJvmOptions(@NonNull @NonNull Consumer<Collection<String>> modifier)
      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<ServiceTask, ServiceTask.Builder>
      Parameters:
      modifier - 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 ServiceTask.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<ServiceTask, ServiceTask.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 ServiceTask.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<ServiceTask, ServiceTask.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 ServiceTask.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<ServiceTask, ServiceTask.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 ServiceTask.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<ServiceTask, ServiceTask.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.

    • self

      @NonNull protected @NonNull ServiceTask.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<ServiceTask, ServiceTask.Builder>
      Returns:
      the current instance of this builder.

    • build

      @NonNull public @NonNull ServiceTask build()
      Builds an instance of the service configuration type this builder is targeting.
      Specified by:
      build in class ServiceConfigurationBase.Builder<ServiceTask, ServiceTask.Builder>
      Returns:
      the build service configuration.
      Throws:
      NullPointerException - if no task name is given.
      IllegalArgumentException - if the start port is invalid.