io.smallrye.stork.api.LoadBalancer Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of stork-api Show documentation

Main Stork API classes. You are likely to need `smallrye-stork-core` and not this module.

The newest version!

package io.smallrye.stork.api;

import java.util.Collection;

/**
 * Works with a single service name.
 * Provides a single service instance.
 * 

 * Must be non-blocking
 */
public interface LoadBalancer {

    /**
     * Select a single {@link ServiceInstance} from the given list.
     *
     * @param serviceInstances instances to choose from
     *
     * @return a ServiceInstance
     *
     * @throws NoServiceInstanceFoundException if the incoming collection is empty or all the service instances in the
     *         collection
     *         are deemed invalid for some reason
     */
    ServiceInstance selectServiceInstance(Collection serviceInstances);

    /**
     * LoadBalancers often record information of the calls being made with instances they return, be it inflight requests,
     * response time, etc.
     * 

     * These calculations often assume that an operation using a previously selected service instance is marked
     * as started before the next instance selection. This prevents a situation in which multiple parallel invocations
     * of the LoadBalancer return the same service instance (because they have the same input for selection).
     * 

     * If the load balancer is insusceptible of this problem, this method should return false.
     *
     * @return true if the selecting service instance should be called atomically with marking the operation as started
     *
     * @see Service#selectInstanceAndRecordStart(boolean)
     * @see Service#selectInstanceAndRecordStart(Collection, boolean)
     */
    default boolean requiresStrictRecording() {
        return true;
    }
}