001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2010 Sun Microsystems, Inc.
025 *      Portions Copyright 2013-2015 ForgeRock AS.
026 */
027
028package org.forgerock.opendj.ldap;
029
030import static org.forgerock.util.time.Duration.duration;
031
032import java.io.Closeable;
033import java.util.concurrent.ScheduledExecutorService;
034
035import org.forgerock.util.Option;
036import org.forgerock.util.time.Duration;
037
038/**
039 * A load balancing algorithm distributes connection requests across one or more underlying connection factories in an
040 * implementation defined manner.
041 *
042 * @see Connections#newLoadBalancer(LoadBalancingAlgorithm)
043 */
044public interface LoadBalancingAlgorithm extends Closeable {
045    /**
046     * Specifies the interval between successive attempts to reconnect to offline load-balanced connection factories.
047     * The default configuration is to attempt to reconnect every second.
048     */
049    Option<Duration> LOAD_BALANCER_MONITORING_INTERVAL = Option.withDefault(duration("1 seconds"));
050
051    /**
052     * Specifies the event listener which should be notified whenever a load-balanced connection factory changes state
053     * from online to offline or vice-versa. By default events will be logged to the {@code LoadBalancingAlgorithm}
054     * logger using the {@link LoadBalancerEventListener#LOG_EVENTS} listener.
055     */
056    Option<LoadBalancerEventListener> LOAD_BALANCER_EVENT_LISTENER =
057            Option.of(LoadBalancerEventListener.class, LoadBalancerEventListener.LOG_EVENTS);
058
059    /**
060     * Specifies the scheduler which will be used for periodically reconnecting to offline connection factories. A
061     * system-wide scheduler will be used by default.
062     */
063    Option<ScheduledExecutorService> LOAD_BALANCER_SCHEDULER = Option.of(ScheduledExecutorService.class, null);
064
065    /**
066     * Releases any resources associated with this algorithm, including any associated connection factories.
067     */
068    @Override
069    void close();
070
071    /**
072     * Returns a connection factory which should be used in order to satisfy the next connection request.
073     *
074     * @return The connection factory.
075     * @throws LdapException
076     *         If no connection factories are available for use.
077     */
078    ConnectionFactory getConnectionFactory() throws LdapException;
079}