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-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.common.scripting; 028 029 030 031 import java.util.List; 032 033 import com.unboundid.directory.sdk.broker.internal.IdentityBrokerExtension; 034 import com.unboundid.directory.sdk.common.config.ErrorLoggerConfig; 035 import com.unboundid.directory.sdk.common.internal.Reconfigurable; 036 import com.unboundid.directory.sdk.common.types.LogCategory; 037 import com.unboundid.directory.sdk.common.types.LogSeverity; 038 import com.unboundid.directory.sdk.common.types.ServerContext; 039 import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension; 040 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension; 041 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension; 042 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension; 043 import com.unboundid.ldap.sdk.LDAPException; 044 import com.unboundid.ldap.sdk.ResultCode; 045 import com.unboundid.util.Extensible; 046 import com.unboundid.util.ThreadSafety; 047 import com.unboundid.util.ThreadSafetyLevel; 048 import com.unboundid.util.args.ArgumentException; 049 import com.unboundid.util.args.ArgumentParser; 050 051 052 053 /** 054 * This class defines an API that must be implemented by scripted extensions 055 * which record information about warnings, errors, and events which occur in 056 * the server. 057 * <BR><BR> 058 * Each error logger may configured to indicate whether whether to include or 059 * exclude log messages based on their category and/or severity. This is 060 * handled automatically by the server, so individual error logger 061 * implementations no not need to attempt to perform that filtering on their 062 * own. However, they may perform additional processing if desired to further 063 * narrow the set of messages that should be logged. 064 * <BR> 065 * <H2>Configuring Groovy-Scripted Error Loggers</H2> 066 * In order to configure a scripted error logger based on this API and written 067 * in the Groovy scripting language, use a command 068 * like: 069 * <PRE> 070 * dsconfig create-log-publisher \ 071 * --publisher-name "<I>{logger-name}</I>" \ 072 * --type groovy-scripted-error \ 073 * --set enabled:true \ 074 * --set "script-class:<I>{class-name}</I>" \ 075 * --set "script-argument:<I>{name=value}</I>" 076 * </PRE> 077 * where "<I>{logger-name}</I>" is the name to use for the error logger 078 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Groovy 079 * class written using this API, and "<I>{name=value}</I>" represents name-value 080 * pairs for any arguments to provide to the logger. If multiple arguments 081 * should be provided to the logger, then the 082 * "<CODE>--set script-argument:<I>{name=value}</I></CODE>" option should be 083 * provided multiple times. 084 * 085 * @see com.unboundid.directory.sdk.common.api.ErrorLogger 086 * @see com.unboundid.directory.sdk.common.api.FileBasedErrorLogger 087 * @see ScriptedFileBasedErrorLogger 088 */ 089 @Extensible() 090 @DirectoryServerExtension() 091 @DirectoryProxyServerExtension(appliesToLocalContent=true, 092 appliesToRemoteContent=false) 093 @SynchronizationServerExtension(appliesToLocalContent=true, 094 appliesToSynchronizedContent=false) 095 @MetricsEngineExtension() 096 @IdentityBrokerExtension() 097 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 098 public abstract class ScriptedErrorLogger 099 implements Reconfigurable<ErrorLoggerConfig> 100 { 101 /** 102 * Creates a new instance of this error logger. All error logger 103 * implementations must include a default constructor, but any initialization 104 * should generally be done in the {@code initializeErrorLogger} method. 105 */ 106 public ScriptedErrorLogger() 107 { 108 // No implementation is required. 109 } 110 111 112 113 /** 114 * {@inheritDoc} 115 */ 116 public void defineConfigArguments(final ArgumentParser parser) 117 throws ArgumentException 118 { 119 // No arguments will be allowed by default. 120 } 121 122 123 124 /** 125 * Initializes this error logger. 126 * 127 * @param serverContext A handle to the server context for the server in 128 * which this extension is running. 129 * @param config The general configuration for this error logger. 130 * @param parser The argument parser which has been initialized from 131 * the configuration for this error logger. 132 * 133 * @throws LDAPException If a problem occurs while initializing this 134 * error logger. 135 */ 136 public void initializeErrorLogger(final ServerContext serverContext, 137 final ErrorLoggerConfig config, 138 final ArgumentParser parser) 139 throws LDAPException 140 { 141 // No initialization will be performed by default. 142 } 143 144 145 146 /** 147 * Performs any cleanup which may be necessary when this error logger is to be 148 * taken out of service. 149 */ 150 public void finalizeErrorLogger() 151 { 152 // No implementation is required. 153 } 154 155 156 157 /** 158 * {@inheritDoc} 159 */ 160 public boolean isConfigurationAcceptable(final ErrorLoggerConfig config, 161 final ArgumentParser parser, 162 final List<String> unacceptableReasons) 163 { 164 // No extended validation will be performed. 165 return true; 166 } 167 168 169 170 /** 171 * {@inheritDoc} 172 */ 173 public ResultCode applyConfiguration(final ErrorLoggerConfig config, 174 final ArgumentParser parser, 175 final List<String> adminActionsRequired, 176 final List<String> messages) 177 { 178 // By default, no configuration changes will be applied. If there are any 179 // arguments, then add an admin action message indicating that the extension 180 // needs to be restarted for any changes to take effect. 181 if (! parser.getNamedArguments().isEmpty()) 182 { 183 adminActionsRequired.add( 184 "No configuration change has actually been applied. The new " + 185 "configuration will not take effect until this error logger " + 186 "is disabled and re-enabled or until the server is restarted."); 187 } 188 189 return ResultCode.SUCCESS; 190 } 191 192 193 194 /** 195 * Records information about the provided message, if appropriate. 196 * 197 * @param category The category for the message to be logged. 198 * @param severity The severity for the message to be logged. 199 * @param messageID The unique identifier with which the message text is 200 * associated. 201 * @param message The message to be logged. 202 */ 203 public abstract void logError(final LogCategory category, 204 final LogSeverity severity, 205 final long messageID, final String message); 206 }