Interface CloudServiceProvider

public interface CloudServiceProvider
The main api point for accessing and managing services running in the cluster. This provider contains some common methods which are widely used by developers which are working with CloudNet. Some methods are still required to be implemented by you, because they are exceeding the normal range of methods.

There are two main ways to access a service running in the cluster. You can either get a snapshot of them, which represents the state of the service at a given time, or a provider which then allows you to execute further actions which will directly impact the service. No methods in here are available to create services, for this purpose use CloudServiceFactory instead.

Since:
4.0

  • Method Details

    • serviceProvider

      @NonNull @RPCChained @NonNull SpecificCloudServiceProvider serviceProvider(@NonNull @NonNull UUID serviceUniqueId)
      Gets a provider for the specific service with the given unique id. No check is made if the service this provider was created for actually exists. If a provider gets created for a not-existing service, then calling any method will result in a dummy return value and will execute no action on any service.

      Note: creating a provider with a unique id of a service which will be created in the future might work but is not required to work. Getting a clean instance after knowing that the service actually exists is recommended over pre-getting a provider.

      There is no need to update a provider when obtained once. An update of the provider should be done however, if a new service with the same unique id was created (after the current target stopped) as that will most likely not change the target of the provider to the new service and tries to execute requested actions on the old, unregistered service.

      Parameters:
      serviceUniqueId - the unique id of the service to get the provider for.
      Returns:
      an operational or no-op provider for a service, depending on whether the requested service exists.
      Throws:
      NullPointerException - if the given service unique id is null.

    • serviceProviderByName

      @NonNull @RPCChained @NonNull SpecificCloudServiceProvider serviceProviderByName(@NonNull @NonNull String serviceName)
      Gets a provider for the specific service with the given name. No check is made if the service this provider was created for actually exists. If a provider gets created for a not-existing service, then calling any method will result in a dummy return value and will execute no action on any service.

      Note: creating a provider with a name of a service which will be created in the future might work but is not required to work. Getting a clean instance after knowing that the service actually exists is recommended over pre-getting a provider.

      There is no need to update a provider when obtained once. An update of the provider should be done however, if a new service with the same name was created (after the current target stopped) as that will most likely not change the target of the provider to the new service and tries to execute requested actions on the old, unregistered service.

      Parameters:
      serviceName - the name of the service to get the provider for.
      Returns:
      an operational or no-op provider for a service, depending on whether the requested service exists.
      Throws:
      NullPointerException - if the service name is null.

    • services

      @NonNull @UnmodifiableView @NonNull Collection<ServiceInfoSnapshot> services()
      Gets all services which are currently registered in the cluster. Modifications to the returned collections are not possible nor will they have any effect.
      Returns:
      all services which are registered in the cluster.

    • runningServices

      @NonNull @UnmodifiableView @NonNull Collection<ServiceInfoSnapshot> runningServices()
      Gets all services which are currently registered and running in the cluster. Modifications to the returned collections are not possible nor will they have any effect.
      Returns:
      all services which are registered and running in the cluster.

    • servicesByTask

      @NonNull @UnmodifiableView @NonNull Collection<ServiceInfoSnapshot> servicesByTask(@NonNull @NonNull String taskName)
      Gets all services which are currently registered in the cluster and belong to the given task. Modifications to the returned collections are not possible nor will they have any effect.
      Parameters:
      taskName - the case-sensitive name of the task to get the services of.
      Returns:
      all services which are currently registered in the cluster and belong to the given task.
      Throws:
      NullPointerException - if the given task name is null.

    • servicesByEnvironment

      @NonNull @UnmodifiableView @NonNull Collection<ServiceInfoSnapshot> servicesByEnvironment(@NonNull @NonNull String environment)
      Gets all services which are currently registered in the cluster and belong to the given environment. Modifications to the returned collections are not possible nor will they have any effect.
      Parameters:
      environment - the case-sensitive name of the environment to get the services of.
      Returns:
      all services which are currently registered in the cluster and belong to the given environment.
      Throws:
      NullPointerException - if the given environment is null.

    • servicesByGroup

      @NonNull @UnmodifiableView @NonNull Collection<ServiceInfoSnapshot> servicesByGroup(@NonNull @NonNull String group)
      Gets all services which are currently registered in the cluster and belong to the given group. Modifications to the returned collections are not possible nor will they have any effect.
      Parameters:
      group - the case-sensitive name of the group to get the services of.
      Returns:
      all services which are currently registered in the cluster and belong to the given group.
      Throws:
      NullPointerException - if the given group name is null.

    • serviceCount

      int serviceCount()
      Gets the amount of services which are currently registered within the cluster.
      Returns:
      the amount of services which are currently registered within the cluster.

    • serviceCountByGroup

      int serviceCountByGroup(@NonNull @NonNull String group)
      Get the amount of services which are currently registered within the cluster and belong to the given group.
      Parameters:
      group - the name of the group the services to count must be in.
      Returns:
      the amount of services which are currently registered within the cluster and in the given group.
      Throws:
      NullPointerException - if the given group name is null.

    • serviceCountByTask

      int serviceCountByTask(@NonNull @NonNull String taskName)
      Get the amount of services which are currently registered within the cluster and belong to the given task.
      Parameters:
      taskName - the name of the task the services to count must belong.
      Returns:
      the amount of services which are currently registered within the cluster and belong to the given task.
      Throws:
      NullPointerException - if the given task name is null.

    • serviceByName

      @Nullable @Nullable ServiceInfoSnapshot serviceByName(@NonNull @NonNull String name)
      Gets the current snapshot of the service with the given name. This method returns null if no service with the given name is currently registered within the cluster.

      This method does not update the service info before returning it, use the force update methods from the specific service provider if you need an up-to-date version of a service snapshot.

      Parameters:
      name - the name of the service to get the snapshot of.
      Returns:
      the current snapshot of the service with the given name or null if the service is not registered.
      Throws:
      NullPointerException - if the given service name is null.

    • service

      @Nullable @Nullable ServiceInfoSnapshot service(@NonNull @NonNull UUID uniqueId)
      Gets the current snapshot of the service with the given unique id. This method returns null if no service with the given unique id is currently registered within the cluster.

      This method does not update the service info before returning it, use the force update methods from the specific service provider if you need an up-to-date version of a service snapshot.

      Parameters:
      uniqueId - the unique id of the service to get the snapshot of.
      Returns:
      the current snapshot of the service with the given unique id or null if the service is not registered.
      Throws:
      NullPointerException - if the given service unique id is null.

    • servicesAsync

      @NonNull @NonNull CompletableFuture<Collection<ServiceInfoSnapshot>> servicesAsync()
      Gets all services which are currently registered in the cluster. Modifications to the returned collections are not possible nor will they have any effect.
      Returns:
      a task completed with all services which are registered in the cluster.

    • runningServicesAsync

      @NonNull @NonNull CompletableFuture<Collection<ServiceInfoSnapshot>> runningServicesAsync()
      Gets all services which are currently registered and running in the cluster. Modifications to the returned collections are not possible nor will they have any effect.
      Returns:
      a task completed with all services which are registered and running in the cluster.

    • servicesByTaskAsync

      @NonNull @NonNull CompletableFuture<Collection<ServiceInfoSnapshot>> servicesByTaskAsync(@NonNull @NonNull String taskName)
      Gets all services which are currently registered in the cluster and belong to the given task. Modifications to the returned collections are not possible nor will they have any effect.
      Parameters:
      taskName - the case-sensitive name of the task to get the services of.
      Returns:
      a task completed with all services currently registered in the cluster and belonging to the given task.
      Throws:
      NullPointerException - if the given task name is null.

    • servicesByEnvironmentAsync

      @NonNull @NonNull CompletableFuture<Collection<ServiceInfoSnapshot>> servicesByEnvironmentAsync(@NonNull @NonNull String environment)
      Gets all services which are currently registered in the cluster and belong to the given environment. Modifications to the returned collections are not possible nor will they have any effect.
      Parameters:
      environment - the case-sensitive name of the environment to get the services of.
      Returns:
      a task completed with all services currently registered in the cluster, belonging to the given environment.
      Throws:
      NullPointerException - if the given environment is null.

    • servicesByGroupAsync

      @NonNull @NonNull CompletableFuture<Collection<ServiceInfoSnapshot>> servicesByGroupAsync(@NonNull @NonNull String group)
      Gets all services which are currently registered in the cluster and belong to the given group. Modifications to the returned collections are not possible nor will they have any effect.
      Parameters:
      group - the case-sensitive name of the group to get the services of.
      Returns:
      a task completed with all services currently registered in the cluster and belonging to the given group.
      Throws:
      NullPointerException - if the given group name is null.

    • serviceCountAsync

      @NonNull @NonNull CompletableFuture<Integer> serviceCountAsync()
      Gets the amount of services which are currently registered within the cluster.
      Returns:
      a task completed with the amount of services which are currently registered within the cluster.

    • serviceCountByGroupAsync

      @NonNull @NonNull CompletableFuture<Integer> serviceCountByGroupAsync(@NonNull @NonNull String group)
      Get the amount of services which are currently registered within the cluster and belong to the given group.
      Parameters:
      group - the name of the group the services to count must be in.
      Returns:
      a task completed with the amount of services currently registered, belonging the given group.
      Throws:
      NullPointerException - if the given group name is null.

    • serviceCountByTaskAsync

      @NonNull @NonNull CompletableFuture<Integer> serviceCountByTaskAsync(@NonNull @NonNull String taskName)
      Get the amount of services which are currently registered within the cluster and belong to the given task.
      Parameters:
      taskName - the name of the task the services to count must belong.
      Returns:
      a task completed with the amount of services currently registered, belonging the given task.
      Throws:
      NullPointerException - if the given task name is null.

    • serviceByNameAsync

      @NonNull @NonNull CompletableFuture<ServiceInfoSnapshot> serviceByNameAsync(@NonNull @NonNull String name)
      Gets the current snapshot of the service with the given name. This method returns null if no service with the given name is currently registered within the cluster.

      This method does not update the service info before returning it, use the force update methods from the specific service provider if you need an up-to-date version of a service snapshot.

      Parameters:
      name - the name of the service to get the snapshot of.
      Returns:
      a task completed with the current snapshot of the service or null if the service is not registered.
      Throws:
      NullPointerException - if the given service name is null.

    • serviceAsync

      @NonNull @NonNull CompletableFuture<ServiceInfoSnapshot> serviceAsync(@NonNull @NonNull UUID uniqueId)
      Gets the current snapshot of the service with the given unique id. This method returns null if no service with the given unique id is currently registered within the cluster.

      This method does not update the service info before returning it, use the force update methods from the specific service provider if you need an up-to-date version of a service snapshot.

      Parameters:
      uniqueId - the unique id of the service to get the snapshot of.
      Returns:
      a task completed with the current snapshot of the service or null if the service is not registered.
      Throws:
      NullPointerException - if the given service unique id is null.