001    /*
002     * Copyright 2008-2014 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2014 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.ldap.sdk;
022    
023    
024    
025    
026    import static com.unboundid.util.Debug.*;
027    
028    
029    
030    /**
031     * This class defines an API that can be used to select between multiple
032     * directory servers when establishing a connection.  Implementations are free
033     * to use any kind of logic that they desire when selecting the server to which
034     * the connection is to be established.  They may also support the use of
035     * health checks to determine whether the created connections are suitable for
036     * use.
037     * <BR><BR>
038     * Implementations MUST be threadsafe to allow for multiple concurrent attempts
039     * to establish new connections.
040     */
041    public abstract class ServerSet
042    {
043      /**
044       * Creates a new instance of this server set.
045       */
046      protected ServerSet()
047      {
048        // No implementation is required.
049      }
050    
051    
052    
053      /**
054       * Attempts to establish a connection to one of the directory servers in this
055       * server set.  The connection should be established but unauthenticated.  The
056       * caller may determine the server to which the connection is established
057       * using the {@code LDAPConnection#getConnectedAddress} and
058       * {@code LDAPConnection#getConnectedPort} methods.
059       *
060       * @return  An {@code LDAPConnection} object that is established to one of the
061       *          servers in this server set.
062       *
063       * @throws  LDAPException  If it is not possible to establish a connection to
064       *                         any of the servers in this server set.
065       */
066      public abstract LDAPConnection getConnection()
067             throws LDAPException;
068    
069    
070    
071      /**
072       * Attempts to establish a connection to one of the directory servers in this
073       * server set, using the provided health check to further validate the
074       * connection.  The connection should be established but unauthenticated.
075       * The caller may determine the server to which the connection is established
076       * using the {@code LDAPConnection#getConnectedAddress} and
077       * {@code LDAPConnection#getConnectedPort} methods.
078       *
079       * @param  healthCheck  The health check to use to make the determination, or
080       *                      {@code null} if no additional health check should be
081       *                      performed.
082       *
083       * @return  An {@code LDAPConnection} object that is established to one of the
084       *          servers in this server set.
085       *
086       * @throws  LDAPException  If it is not possible to establish a connection to
087       *                         any of the servers in this server set.
088       */
089      public LDAPConnection getConnection(
090                                 final LDAPConnectionPoolHealthCheck healthCheck)
091             throws LDAPException
092      {
093        final LDAPConnection c = getConnection();
094    
095        if (healthCheck != null)
096        {
097          try
098          {
099            healthCheck.ensureNewConnectionValid(c);
100          }
101          catch (LDAPException le)
102          {
103            debugException(le);
104            c.close();
105            throw le;
106          }
107        }
108    
109        return c;
110      }
111    
112    
113    
114      /**
115       * Retrieves a string representation of this server set.
116       *
117       * @return  A string representation of this server set.
118       */
119      @Override()
120      public String toString()
121      {
122        final StringBuilder buffer = new StringBuilder();
123        toString(buffer);
124        return buffer.toString();
125      }
126    
127    
128    
129      /**
130       * Appends a string representation of this server set to the provided buffer.
131       *
132       * @param  buffer  The buffer to which the string representation should be
133       *                 appended.
134       */
135      public void toString(final StringBuilder buffer)
136      {
137        buffer.append("ServerSet(className=");
138        buffer.append(getClass().getName());
139        buffer.append(')');
140      }
141    }