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