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-2013 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.common.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.config.AlertHandlerConfig;
036 import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
037 import com.unboundid.directory.sdk.common.internal.Reconfigurable;
038 import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
039 import com.unboundid.directory.sdk.common.types.AlertNotification;
040 import com.unboundid.directory.sdk.common.types.ServerContext;
041 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
042 import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension;
043 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
044 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
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 will
057 * be invoked whenever an administrative alert is generated within the server.
058 * Administrative alerts may be used to notify administrators whenever a
059 * significant error, warning, or other type of event occurs within the server.
060 * Alert handlers may be used to help ensure that those notifications are made
061 * available to administrators in an appropriate manner.
062 * <BR><BR>
063 * Each alert handler may be configured so that it will only be invoked for
064 * certain types of alerts, either based on the specific alert type or based on
065 * the alert severity. This is handled automatically by the server, so
066 * individual alert handler implementations do not need to attempt to perform
067 * that filtering on their own. However, they may perform additional processing
068 * if desired to further narrow the set of alerts that should be made available
069 * to administrators.
070 * <BR>
071 * <H2>Configuring Alert Handlers</H2>
072 * In order to configure an alert handler created using this API, use a command
073 * like:
074 * <PRE>
075 * dsconfig create-alert-handler \
076 * --handler-name "<I>{handler-name}</I>" \
077 * --type third-party \
078 * --set enabled:true \
079 * --set "extension-class:<I>{class-name}</I>" \
080 * --set "extension-argument:<I>{name=value}</I>"
081 * </PRE>
082 * where "<I>{handler-name}</I>" is the name to use for the alert handler
083 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Java class
084 * that extends {@code com.unboundid.directory.sdk.common.api.AlertHandler},
085 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to
086 * provide to the alert handler. If multiple arguments should be provided to
087 * the alert handler, then the
088 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
089 * provided multiple times.
090 *
091 * @see com.unboundid.directory.sdk.common.scripting.ScriptedAlertHandler
092 */
093 @Extensible()
094 @DirectoryServerExtension()
095 @DirectoryProxyServerExtension(appliesToLocalContent=true,
096 appliesToRemoteContent=false)
097 @SynchronizationServerExtension(appliesToLocalContent=true,
098 appliesToSynchronizedContent=false)
099 @MetricsEngineExtension()
100 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
101 public abstract class AlertHandler
102 implements UnboundIDExtension, Reconfigurable<AlertHandlerConfig>,
103 ExampleUsageProvider
104 {
105 /**
106 * Creates a new instance of this alert handler. All alert handler
107 * implementations must include a default constructor, but any initialization
108 * should generally be done in the {@code initializeAlertHandler} method.
109 */
110 public AlertHandler()
111 {
112 // No implementation is required.
113 }
114
115
116
117 /**
118 * {@inheritDoc}
119 */
120 public abstract String getExtensionName();
121
122
123
124 /**
125 * {@inheritDoc}
126 */
127 public abstract String[] getExtensionDescription();
128
129
130
131 /**
132 * {@inheritDoc}
133 */
134 public void defineConfigArguments(final ArgumentParser parser)
135 throws ArgumentException
136 {
137 // No arguments will be allowed by default.
138 }
139
140
141
142 /**
143 * Initializes this alert handler.
144 *
145 * @param serverContext A handle to the server context for the server in
146 * which this extension is running.
147 * @param config The general configuration for this alert handler.
148 * @param parser The argument parser which has been initialized from
149 * the configuration for this alert handler.
150 *
151 * @throws LDAPException If a problem occurs while initializing this alert
152 * handler.
153 */
154 public void initializeAlertHandler(final ServerContext serverContext,
155 final AlertHandlerConfig config,
156 final ArgumentParser parser)
157 throws LDAPException
158 {
159 // No initialization will be performed by default.
160 }
161
162
163
164 /**
165 * {@inheritDoc}
166 */
167 public boolean isConfigurationAcceptable(final AlertHandlerConfig config,
168 final ArgumentParser parser,
169 final List<String> unacceptableReasons)
170 {
171 // No extended validation will be performed by default.
172 return true;
173 }
174
175
176
177 /**
178 * {@inheritDoc}
179 */
180 public ResultCode applyConfiguration(final AlertHandlerConfig config,
181 final ArgumentParser parser,
182 final List<String> adminActionsRequired,
183 final List<String> messages)
184 {
185 // By default, no configuration changes will be applied. If there are any
186 // arguments, then add an admin action message indicating that the extension
187 // needs to be restarted for any changes to take effect.
188 if (! parser.getNamedArguments().isEmpty())
189 {
190 adminActionsRequired.add(
191 "No configuration change has actually been applied. The new " +
192 "configuration will not take effect until this alert handler " +
193 "is disabled and re-enabled or until the server is restarted.");
194 }
195
196 return ResultCode.SUCCESS;
197 }
198
199
200
201 /**
202 * Performs any cleanup which may be necessary when this alert handler is to
203 * be taken out of service.
204 */
205 public void finalizeAlertHandler()
206 {
207 // No implementation is required.
208 }
209
210
211
212 /**
213 * Performs any processing which may be necessary to handle the provided alert
214 * notification.
215 *
216 * @param alert The alert notification generated within the server.
217 */
218 public abstract void handleAlert(final AlertNotification alert);
219
220
221
222 /**
223 * {@inheritDoc}
224 */
225 public Map<List<String>,String> getExamplesArgumentSets()
226 {
227 return Collections.emptyMap();
228 }
229 }