001    /*
002     * Copyright 2008-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2016 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    import com.unboundid.util.Extensible;
026    import com.unboundid.util.ThreadSafety;
027    import com.unboundid.util.ThreadSafetyLevel;
028    
029    import static com.unboundid.util.Debug.*;
030    
031    
032    
033    /**
034     * This class defines an API that can be used to select between multiple
035     * directory servers when establishing a connection.  Implementations are free
036     * to use any kind of logic that they desire when selecting the server to which
037     * the connection is to be established.  They may also support the use of
038     * health checks to determine whether the created connections are suitable for
039     * use.
040     * <BR><BR>
041     * Implementations MUST be threadsafe to allow for multiple concurrent attempts
042     * to establish new connections.
043     */
044    @Extensible()
045    @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
046    public abstract class ServerSet
047    {
048      /**
049       * Creates a new instance of this server set.
050       */
051      protected ServerSet()
052      {
053        // No implementation is required.
054      }
055    
056    
057    
058      /**
059       * Attempts to establish a connection to one of the directory servers in this
060       * server set.  The connection should be established but unauthenticated.  The
061       * caller may determine the server to which the connection is established
062       * using the {@link LDAPConnection#getConnectedAddress} and
063       * {@link LDAPConnection#getConnectedPort} methods.
064       *
065       * @return  An {@code LDAPConnection} object that is established to one of the
066       *          servers in this server set.
067       *
068       * @throws  LDAPException  If it is not possible to establish a connection to
069       *                         any of the servers in this server set.
070       */
071      public abstract LDAPConnection getConnection()
072             throws LDAPException;
073    
074    
075    
076      /**
077       * Attempts to establish a connection to one of the directory servers in this
078       * server set, using the provided health check to further validate the
079       * connection.  The connection should be established but unauthenticated.
080       * The caller may determine the server to which the connection is established
081       * using the {@link LDAPConnection#getConnectedAddress} and
082       * {@link LDAPConnection#getConnectedPort} methods.
083       *
084       * @param  healthCheck  The health check to use to make the determination, or
085       *                      {@code null} if no additional health check should be
086       *                      performed.
087       *
088       * @return  An {@code LDAPConnection} object that is established to one of the
089       *          servers in this server set.
090       *
091       * @throws  LDAPException  If it is not possible to establish a connection to
092       *                         any of the servers in this server set.
093       */
094      public LDAPConnection getConnection(
095                                 final LDAPConnectionPoolHealthCheck healthCheck)
096             throws LDAPException
097      {
098        final LDAPConnection c = getConnection();
099    
100        if (healthCheck != null)
101        {
102          try
103          {
104            healthCheck.ensureNewConnectionValid(c);
105          }
106          catch (LDAPException le)
107          {
108            debugException(le);
109            c.close();
110            throw le;
111          }
112        }
113    
114        return c;
115      }
116    
117    
118    
119      /**
120       * Retrieves a string representation of this server set.
121       *
122       * @return  A string representation of this server set.
123       */
124      @Override()
125      public String toString()
126      {
127        final StringBuilder buffer = new StringBuilder();
128        toString(buffer);
129        return buffer.toString();
130      }
131    
132    
133    
134      /**
135       * Appends a string representation of this server set to the provided buffer.
136       *
137       * @param  buffer  The buffer to which the string representation should be
138       *                 appended.
139       */
140      public void toString(final StringBuilder buffer)
141      {
142        buffer.append("ServerSet(className=");
143        buffer.append(getClass().getName());
144        buffer.append(')');
145      }
146    }