001 /*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License"). You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt. If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 * Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 * Copyright 2010-2012 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.proxy.api;
028
029
030
031 import java.util.Collections;
032 import java.util.List;
033 import java.util.Map;
034
035 import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
036 import com.unboundid.directory.sdk.common.internal.Reconfigurable;
037 import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
038 import com.unboundid.directory.sdk.proxy.config.LDAPHealthCheckConfig;
039 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
040 import com.unboundid.directory.sdk.proxy.types.BackendServer;
041 import com.unboundid.directory.sdk.proxy.types.CompletedProxyOperationContext;
042 import com.unboundid.directory.sdk.proxy.types.HealthCheckResult;
043 import com.unboundid.directory.sdk.proxy.types.ProxyServerContext;
044 import com.unboundid.ldap.sdk.LDAPConnection;
045 import com.unboundid.ldap.sdk.LDAPException;
046 import com.unboundid.ldap.sdk.ResultCode;
047 import com.unboundid.util.Extensible;
048 import com.unboundid.util.ThreadSafety;
049 import com.unboundid.util.ThreadSafetyLevel;
050 import com.unboundid.util.args.ArgumentException;
051 import com.unboundid.util.args.ArgumentParser;
052
053
054
055 /**
056 * This class defines an API that must be implemented by extensions which are
057 * used to assess the health of backend servers accessed through the Directory
058 * Proxy Server. Each health check invocation generates a health check result,
059 * which contains the following elements:
060 * <UL>
061 * <LI>Health Check State -- This indicates the general health state for the
062 * backend server. The state may be AVAILABLE (the server is completely
063 * suitable for use), DEGRADED (the server should be avoided if there are
064 * better servers but may be used if necessary), or UNAVAILABLE (the
065 * server not not be used at all).</LI>
066 * <LI>Health Check Score -- This provides an integer value between 10 (the
067 * best score) and 1 (the worst score) that may help rank servers with the
068 * same state. Some load-balancing algorithms (e.g., the health-weighted
069 * algorithm) may use this to prefer servers with a higher score over
070 * those with a lower score. Servers with a state of UNAVAILABLE will
071 * always have a score of zero.</LI>
072 * <LI>Messages -- This may optionally provide information about the reason
073 * for the state and/or score. This is primarily useful for results
074 * indicating that the server is DEGRADED or UNAVAILABLE to provide
075 * information about the problem(s) preventing it from being considered
076 * AVAILABLE.</LI>
077 * </UL>
078 * <BR><BR>
079 * LDAP health checks may be invoked in two ways. They will be invoked on a
080 * regular basis to periodically re-assess the health of each backend server,
081 * but they may also be invoked after a failed operation in order to more
082 * quickly detect a problem that should cause the server to be transitioned to a
083 * less-available state. The server will ensure that no more than one health
084 * check is in progress at a time for a given server in order to avoid
085 * overwhelming it with health checking, but it is still recommended that
086 * health checks triggered as a result of a failed operation attempt to use the
087 * operation result code to decide whether it may be necessary to actually
088 * attempt to communicate with the server.
089 * <BR><BR>
090 * Further, it may also be useful to have more stringent criteria for promoting
091 * the health of a server than for demoting it in order to avoid a ping-pong
092 * effect that may occur if a server is hovering near the border between
093 * AVAILABLE and DEGRADED or between DEGRADED and UNAVAILABLE. For example, if
094 * a health check attempts to perform an operation in the backend server and the
095 * response time for that operation is taken into account when determining the
096 * server health, it might be better to require a lower response time in order
097 * to transition from DEGRADED to AVAILABLE than was originally required to
098 * transition from AVAILABLE to DEGRADED.
099 * <BR>
100 * <H2>Configuring LDAP Health Checks</H2>
101 * In order to configure an LDAP health check created using this API, use a
102 * command like:
103 * <PRE>
104 * dsconfig create-ldap-health-check \
105 * --check-name "<I>{check-name}</I>" \
106 * --type third-party \
107 * --set enabled:true \
108 * --set "extension-class:<I>{class-name}</I>" \
109 * --set "extension-argument:<I>{name=value}</I>"
110 * </PRE>
111 * where "<I>{check-name}</I>" is the name to use for the LDAP health check
112 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Java class
113 * that extends {@code com.unboundid.directory.sdk.proxy.api.LDAPHealthCheck},
114 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to
115 * provide to the LDAP health check. If multiple arguments should be provided
116 * to the LDAP health check, then the
117 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
118 * provided multiple times.
119 *
120 * @see com.unboundid.directory.sdk.proxy.scripting.ScriptedLDAPHealthCheck
121 */
122 @Extensible()
123 @DirectoryProxyServerExtension(appliesToLocalContent=false,
124 appliesToRemoteContent=true)
125 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
126 public abstract class LDAPHealthCheck
127 implements UnboundIDExtension, Reconfigurable<LDAPHealthCheckConfig>,
128 ExampleUsageProvider
129 {
130 /**
131 * Creates a new instance of this LDAP health check. All LDAP health check
132 * implementations must include a default constructor, but any initialization
133 * should generally be done in the {@code initializeLDAPHealthCheck} method.
134 */
135 public LDAPHealthCheck()
136 {
137 // No implementation is required.
138 }
139
140
141
142 /**
143 * {@inheritDoc}
144 */
145 public abstract String getExtensionName();
146
147
148
149 /**
150 * {@inheritDoc}
151 */
152 public abstract String[] getExtensionDescription();
153
154
155
156 /**
157 * {@inheritDoc}
158 */
159 public void defineConfigArguments(final ArgumentParser parser)
160 throws ArgumentException
161 {
162 // No arguments will be allowed by default.
163 }
164
165
166
167 /**
168 * Initializes this LDAP health check.
169 *
170 * @param serverContext A handle to the server context for the Directory
171 * Proxy server in which this extension is running.
172 * @param config The general configuration for this LDAP health
173 * check.
174 * @param parser The argument parser which has been initialized from
175 * the configuration for this LDAP health check.
176 *
177 * @throws LDAPException If a problem occurs while initializing this LDAP
178 * health check.
179 */
180 public void initializeLDAPHealthCheck(final ProxyServerContext serverContext,
181 final LDAPHealthCheckConfig config,
182 final ArgumentParser parser)
183 throws LDAPException
184 {
185 // No initialization will be performed by default.
186 }
187
188
189
190 /**
191 * {@inheritDoc}
192 */
193 public boolean isConfigurationAcceptable(final LDAPHealthCheckConfig config,
194 final ArgumentParser parser,
195 final List<String> unacceptableReasons)
196 {
197 // No extended validation will be performed by default.
198 return true;
199 }
200
201
202
203 /**
204 * {@inheritDoc}
205 */
206 public ResultCode applyConfiguration(final LDAPHealthCheckConfig config,
207 final ArgumentParser parser,
208 final List<String> adminActionsRequired,
209 final List<String> messages)
210 {
211 // By default, no configuration changes will be applied. If there are any
212 // arguments, then add an admin action message indicating that the extension
213 // needs to be restarted for any changes to take effect.
214 if (! parser.getNamedArguments().isEmpty())
215 {
216 adminActionsRequired.add(
217 "No configuration change has actually been applied. The new " +
218 "configuration will not take effect until this LDAP health " +
219 "check is disabled and re-enabled or until the server is " +
220 "restarted.");
221 }
222
223 return ResultCode.SUCCESS;
224 }
225
226
227
228 /**
229 * Performs any cleanup which may be necessary when this LDAP health check is
230 * to be taken out of service.
231 */
232 public void finalizeLDAPHealthCheck()
233 {
234 // No implementation is required.
235 }
236
237
238
239 /**
240 * Attempts to determine the health of the provided LDAP external server whose
241 * last health check result indicated that the server had a state of
242 * AVAILABLE. This method may be periodically invoked for AVAILABLE servers
243 * to determine whether their state has changed.
244 *
245 * @param backendServer A handle to the LDAP external server whose health is
246 * to be assessed.
247 * @param connection A connection that may be used to communicate with
248 * the server in the course of performing the
249 * evaluation. The health check should not do anything
250 * which may alter the state of this connection.
251 *
252 * @return Information about the result of the health check.
253 */
254 public abstract HealthCheckResult checkAvailableServer(
255 final BackendServer backendServer,
256 final LDAPConnection connection);
257
258
259
260 /**
261 * Attempts to determine the health of the provided LDAP external server whose
262 * last health check result indicated that the server had a state of DEGRADED.
263 * This method may be periodically invoked for DEGRADED servers to determine
264 * whether their state has changed.
265 *
266 * @param backendServer A handle to the LDAP external server whose health is
267 * to be assessed.
268 * @param connection A connection that may be used to communicate with
269 * the server in the course of performing the
270 * evaluation. The health check should not do anything
271 * which may alter the state of this connection.
272 *
273 * @return Information about the result of the health check.
274 */
275 public abstract HealthCheckResult checkDegradedServer(
276 final BackendServer backendServer,
277 final LDAPConnection connection);
278
279
280
281 /**
282 * Attempts to determine the health of the provided LDAP external server whose
283 * last health check result indicated that the server had a state of
284 * UNAVAILABLE. This method may be periodically invoked for UNAVAILABLE
285 * servers to determine whether their state has changed.
286 *
287 * @param backendServer A handle to the LDAP external server whose health is
288 * to be assessed.
289 * @param connection A connection that may be used to communicate with
290 * the server in the course of performing the
291 * evaluation. The health check should not do anything
292 * which may alter the state of this connection.
293 *
294 * @return Information about the result of the health check.
295 */
296 public abstract HealthCheckResult checkUnavailableServer(
297 final BackendServer backendServer,
298 final LDAPConnection connection);
299
300
301
302 /**
303 * Attempts to determine the health of the provided LDAP external server in
304 * which an attempted operation did not complete successfully.
305 *
306 * @param operationContext A handle to the operation context for the
307 * operation that failed.
308 * @param exception The exception caught when attempting to process
309 * the associated operation in the backend server.
310 * @param backendServer A handle to the backend server in which the
311 * operation was processed.
312 *
313 * @return Information about the result of the health check.
314 */
315 public abstract HealthCheckResult checkFailedOperation(
316 final CompletedProxyOperationContext operationContext,
317 final LDAPException exception,
318 final BackendServer backendServer);
319
320
321
322 /**
323 * Retrieves a string representation of this LDAP health check.
324 *
325 * @return A string representation of this LDAP health check.
326 */
327 @Override()
328 public final String toString()
329 {
330 final StringBuilder buffer = new StringBuilder();
331 toString(buffer);
332 return buffer.toString();
333 }
334
335
336
337 /**
338 * Appends a string representation of this LDAP health check to the provided
339 * buffer.
340 *
341 * @param buffer The buffer to which the string representation should be
342 * appended.
343 */
344 public abstract void toString(final StringBuilder buffer);
345
346
347
348 /**
349 * {@inheritDoc}
350 */
351 public Map<List<String>,String> getExamplesArgumentSets()
352 {
353 return Collections.emptyMap();
354 }
355 }