001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2013-2016 ForgeRock AS.
015 */
016
017package org.forgerock.opendj.ldap;
018
019import static com.forgerock.opendj.ldap.CoreMessages.LOAD_BALANCER_EVENT_LISTENER_LOG_OFFLINE;
020import static com.forgerock.opendj.ldap.CoreMessages.LOAD_BALANCER_EVENT_LISTENER_LOG_ONLINE;
021
022import java.util.EventListener;
023
024import org.forgerock.i18n.slf4j.LocalizedLogger;
025
026/**
027 * An object that registers to be notified when a connection factory associated
028 * with a load-balancer changes state from offline to online or vice-versa.
029 * <p>
030 * <b>NOTE:</b> load-balancer implementations must ensure that only one event is
031 * sent at a time. Event listener implementations should not need to be thread
032 * safe.
033 *
034 * @see Connections#LOAD_BALANCER_EVENT_LISTENER
035 */
036public interface LoadBalancerEventListener extends EventListener {
037    /**
038     * An event listener implementation which logs events to the LoadBalancingAlgorithm logger. This event listener is
039     * the default implementation configured using the {@link Connections#LOAD_BALANCER_EVENT_LISTENER}
040     * option.
041     */
042    LoadBalancerEventListener LOG_EVENTS = new LoadBalancerEventListener() {
043        private final LocalizedLogger logger = LocalizedLogger.getLocalizedLogger(LoadBalancer.class);
044
045        @Override
046        public void handleConnectionFactoryOnline(final ConnectionFactory factory) {
047            logger.info(LOAD_BALANCER_EVENT_LISTENER_LOG_ONLINE.get(factory));
048        }
049
050        @Override
051        public void handleConnectionFactoryOffline(final ConnectionFactory factory, final LdapException error) {
052            logger.warn(LOAD_BALANCER_EVENT_LISTENER_LOG_OFFLINE.get(factory, error.getMessage()));
053        }
054    };
055
056    /** An event listener implementation which ignores all events. */
057    LoadBalancerEventListener NO_OP = new LoadBalancerEventListener() {
058        @Override
059        public void handleConnectionFactoryOnline(final ConnectionFactory factory) {
060            // Do nothing.
061        }
062
063        @Override
064        public void handleConnectionFactoryOffline(final ConnectionFactory factory, final LdapException error) {
065            // Do nothing.
066        }
067    };
068
069    /**
070     * Invoked when the load-balancer is unable to obtain a connection from the
071     * specified connection factory. The connection factory will be removed from
072     * the load-balancer and monitored periodically in order to determine when
073     * it is available again, at which point an online notification event will
074     * occur.
075     *
076     * @param factory
077     *            The connection factory which has failed.
078     * @param error
079     *            The last error that occurred.
080     */
081    void handleConnectionFactoryOffline(ConnectionFactory factory, LdapException error);
082
083    /**
084     * Invoked when the load-balancer detects that a previously offline
085     * connection factory is available for use again.
086     *
087     * @param factory
088     *            The connection factory which is now available for use.
089     */
090    void handleConnectionFactoryOnline(ConnectionFactory factory);
091}