001/* 002 * Copyright 2008-2017 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2008-2017 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 */ 021package com.unboundid.ldap.sdk; 022 023 024 025import com.unboundid.util.Extensible; 026import com.unboundid.util.ThreadSafety; 027import com.unboundid.util.ThreadSafetyLevel; 028 029import 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) 046public 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}