All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.datastax.driver.core.policies.LoadBalancingPolicy Maven / Gradle / Ivy

/*
 * Copyright DataStax, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.datastax.driver.core.policies;

import com.datastax.driver.core.Cluster;
import com.datastax.driver.core.Host;
import com.datastax.driver.core.HostDistance;
import com.datastax.driver.core.Statement;
import java.util.Collection;
import java.util.Iterator;

/**
 * The policy that decides which Cassandra hosts to contact for each new query.
 *
 * 

Two methods need to be implemented: * *

    *
  • {@link LoadBalancingPolicy#distance}: returns the "distance" of an host for that balancing * policy. *
  • {@link LoadBalancingPolicy#newQueryPlan}: it is used for each query to find which host to * query first, and which hosts to use as failover. *
* *

The {@code LoadBalancingPolicy} is informed of hosts up/down events. For efficiency purposes, * the policy is expected to exclude down hosts from query plans. */ public interface LoadBalancingPolicy { /** * Initialize this load balancing policy. * *

Note that the driver guarantees that it will call this method exactly once per policy object * and will do so before any call to another of the methods of the policy. * * @param cluster the {@code Cluster} instance for which the policy is created. * @param hosts the initial hosts to use. */ public void init(Cluster cluster, Collection hosts); /** * Returns the distance assigned by this policy to the provided host. * *

The distance of an host influence how much connections are kept to the node (see {@link * HostDistance}). A policy should assign a {@code LOCAL} distance to nodes that are susceptible * to be returned first by {@code newQueryPlan} and it is useless for {@code newQueryPlan} to * return hosts to which it assigns an {@code IGNORED} distance. * *

The host distance is primarily used to prevent keeping too many connections to host in * remote datacenters when the policy itself always picks host in the local datacenter first. * * @param host the host of which to return the distance of. * @return the HostDistance to {@code host}. */ public HostDistance distance(Host host); /** * Returns the hosts to use for a new query. * *

Each new query will call this method. The first host in the result will then be used to * perform the query. In the event of a connection problem (the queried host is down or appear to * be so), the next host will be used. If all hosts of the returned {@code Iterator} are down, the * query will fail. * * @param loggedKeyspace the currently logged keyspace (the one set through either {@link * Cluster#connect(String)} or by manually doing a {@code USE} query) for the session on which * this plan need to be built. This can be {@code null} if the corresponding session has no * keyspace logged in. * @param statement the query for which to build a plan. * @return an iterator of Host. The query is tried against the hosts returned by this iterator in * order, until the query has been sent successfully to one of the host. */ public Iterator newQueryPlan(String loggedKeyspace, Statement statement); /** * Called when a new node is added to the cluster. * *

The newly added node should be considered up. * * @param host the host that has been newly added. */ void onAdd(Host host); /** * Called when a node is determined to be up. * * @param host the host that has been detected up. */ void onUp(Host host); /** * Called when a node is determined to be down. * * @param host the host that has been detected down. */ void onDown(Host host); /** * Called when a node is removed from the cluster. * * @param host the removed host. */ void onRemove(Host host); /** * Gets invoked at cluster shutdown. * *

This gives the policy the opportunity to perform some cleanup, for instance stop threads * that it might have started. */ void close(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy