001/* 002 * Copyright 2009-2014 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2009-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 */ 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.ldap.sdk.LDAPMessages.*; 030import static com.unboundid.util.StaticUtils.*; 031 032 033 034/** 035 * This class provides an API that may be used to determine whether connections 036 * associated with a connection pool are valid and suitable for use. It 037 * provides the ability to check the validity of a connection at the following 038 * times: 039 * <UL> 040 * <LI>Whenever a new connection is created for use in the pool, the 041 * {@link #ensureNewConnectionValid(LDAPConnection)} method will be called 042 * before making that connection available. The default implementation 043 * provided in this class does not perform any kind of processing, but 044 * subclasses may override this behavior if desired.</LI> 045 * <LI>Whenever a connection is checked out from the pool (including 046 * connections checked out internally for operations performed in the 047 * pool), the {@link #ensureConnectionValidForCheckout(LDAPConnection)} 048 * method will be called. The default implementation provided in this 049 * class does not perform any kind of processing, but subclasses may 050 * override this behavior if desired.</LI> 051 * <LI>Whenever a connection is released back to the pool (including 052 * connections checked out internally for operations performed in the 053 * pool), the {@link #ensureConnectionValidForRelease(LDAPConnection)} 054 * method will be called. The default implementation provided in this 055 * class does not perform any kind of processing, but subclasses may 056 * override this behavior if desired.</LI> 057 * <LI>The {@link #ensureConnectionValidForContinuedUse(LDAPConnection)} 058 * method will be invoked periodically by a background thread created by 059 * the connection pool to determine whether available connections within 060 * the pool are still valid. The default implementation provided in this 061 * class does not perform any kind of processing, but subclasses may 062 * override this behavior if desired.</LI> 063 * <LI>The {@link #ensureConnectionValidAfterException} method may be invoked 064 * if an exception is caught while processing an operation with a 065 * connection which is part of a connection pool. The default 066 * implementation provided in this class only examines the result code of 067 * the provided exception and uses the 068 * {@link ResultCode#isConnectionUsable(ResultCode)} method to make the 069 * determination, but subclasses may override this behavior if 070 * desired.</LI> 071 * </UL> 072 * Note that health check implementations should be designed so that they are 073 * suitable for use with connections having any authentication state. The 074 * {@link #ensureNewConnectionValid(LDAPConnection)} method will be invoked on 075 * unauthenticated connections, and the remaining health check methods will be 076 * invoked using whatever credentials are assigned to connections in the 077 * associated connection pool. 078 */ 079@Extensible() 080@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 081public class LDAPConnectionPoolHealthCheck 082{ 083 /** 084 * Creates a new instance of this LDAP connection pool health check. 085 */ 086 public LDAPConnectionPoolHealthCheck() 087 { 088 // No implementation is required. 089 } 090 091 092 093 /** 094 * Performs any desired processing to determine whether the provided new 095 * connection is available to be checked out and used for processing 096 * operations. This method will be invoked by either {@link ServerSet} used 097 * by the connection pool (if it supports enhanced health checking) or by the 098 * connection pool itself at the time that a new connection is created. 099 * 100 * @param connection The connection to be examined. 101 * 102 * @throws LDAPException If a problem is detected which suggests that the 103 * provided connection is not suitable for use. 104 */ 105 public void ensureNewConnectionValid(final LDAPConnection connection) 106 throws LDAPException 107 { 108 // No processing is performed in this default implementation. 109 } 110 111 112 113 /** 114 * Performs any desired processing to determine whether the provided 115 * connection is available to be checked out and used for processing 116 * operations. This method will be invoked by the 117 * {@link LDAPConnectionPool#getConnection()} method before handing out a 118 * connection. This method should return normally if the connection is 119 * believed to be valid, or should throw an {@code LDAPException} if a problem 120 * is detected. 121 * 122 * @param connection The connection to be examined. 123 * 124 * @throws LDAPException If a problem is detected which suggests that the 125 * provided connection is not suitable for use. 126 */ 127 public void ensureConnectionValidForCheckout(final LDAPConnection connection) 128 throws LDAPException 129 { 130 // No processing is performed in this default implementation. 131 } 132 133 134 135 /** 136 * Performs any desired processing to determine whether the provided 137 * connection is valid and should be released back to the pool to be used for 138 * processing other operations. This method will be invoked by the 139 * {@link LDAPConnectionPool#releaseConnection(LDAPConnection)} method before 140 * making the connection available for use in processing other operations. 141 * This method should return normally if the connection is believed to be 142 * valid, or should throw an {@code LDAPException} if a problem is detected. 143 * 144 * @param connection The connection to be examined. 145 * 146 * @throws LDAPException If a problem is detected which suggests that the 147 * provided connection is not suitable for use. 148 */ 149 public void ensureConnectionValidForRelease(final LDAPConnection connection) 150 throws LDAPException 151 { 152 // No processing is performed in this default implementation. 153 } 154 155 156 157 /** 158 * Performs any desired processing to determine whether the provided 159 * connection is valid and should continue to be made available for 160 * processing operations. This method will be periodically invoked by a 161 * background thread used to test availability of connections within the pool. 162 * This method should return normally if the connection is believed to be 163 * valid, or should throw an {@code LDAPException} if a problem is detected. 164 * 165 * @param connection The connection to be examined. 166 * 167 * @throws LDAPException If a problem is detected which suggests that the 168 * provided connection is not suitable for use. 169 */ 170 public void ensureConnectionValidForContinuedUse( 171 final LDAPConnection connection) 172 throws LDAPException 173 { 174 // No processing is performed in this default implementation. 175 } 176 177 178 179 /** 180 * Indicates whether the provided connection may still be considered valid 181 * after an attempt to process an operation yielded the given exception. This 182 * method will be invoked by the 183 * {@link LDAPConnectionPool#releaseConnectionAfterException} method, and it 184 * may also be manually invoked by external callers if an exception is 185 * encountered while processing an operation on a connection checked out from 186 * the pool. It may make a determination based solely on the provided 187 * exception, or it may also attempt to use the provided connection to further 188 * test its validity. This method should return normally if the connection is 189 * believed to be valid, or should throw an {@code LDAPException} if a problem 190 * is detected. 191 * 192 * @param connection The connection to be examined. 193 * @param exception The exception that was caught while processing an 194 * operation on the connection. 195 * 196 * @throws LDAPException If a problem is detected which suggests that the 197 * provided connection is not suitable for use. 198 */ 199 public void ensureConnectionValidAfterException( 200 final LDAPConnection connection, 201 final LDAPException exception) 202 throws LDAPException 203 { 204 if (! ResultCode.isConnectionUsable(exception.getResultCode())) 205 { 206 throw new LDAPException(ResultCode.SERVER_DOWN, 207 ERR_POOL_HEALTH_CHECK_CONN_INVALID_AFTER_EXCEPTION.get( 208 getExceptionMessage(exception)), 209 exception); 210 } 211 } 212 213 214 215 /** 216 * Retrieves a string representation of this LDAP connection pool health 217 * check. 218 * 219 * @return A string representation of this LDAP connection pool health check. 220 */ 221 @Override() 222 public final String toString() 223 { 224 final StringBuilder buffer = new StringBuilder(); 225 toString(buffer); 226 return buffer.toString(); 227 } 228 229 230 231 /** 232 * Appends a string representation of this LDAP connection pool health check 233 * to the provided buffer. 234 * 235 * @param buffer The buffer to which the information should be appended. 236 */ 237 public void toString(final StringBuilder buffer) 238 { 239 buffer.append("LDAPConnectionPoolHealthCheck()"); 240 } 241}