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 2011-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.http.scripting; 028 029 030 031 import java.util.List; 032 import java.util.Map; 033 034 import javax.servlet.http.HttpServletRequest; 035 import javax.servlet.http.HttpServletResponse; 036 037 import com.unboundid.directory.sdk.broker.internal.IdentityBrokerExtension; 038 import com.unboundid.directory.sdk.common.internal.Reconfigurable; 039 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension; 040 import com.unboundid.directory.sdk.http.config.HTTPOperationLoggerConfig; 041 import com.unboundid.directory.sdk.http.types.HTTPServerContext; 042 import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension; 043 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension; 044 import com.unboundid.ldap.sdk.LDAPException; 045 import com.unboundid.ldap.sdk.ResultCode; 046 import com.unboundid.util.Extensible; 047 import com.unboundid.util.ThreadSafety; 048 import com.unboundid.util.ThreadSafetyLevel; 049 import com.unboundid.util.args.ArgumentException; 050 import com.unboundid.util.args.ArgumentParser; 051 052 053 054 /** 055 * This class defines an API that must be implemented by extensions which 056 * record information about interaction with HTTP clients. Scripted HTTP 057 * operation loggers may write information to files, but they may also write to 058 * other locations, including databases, message, queues, e-mail messages, or 059 * other targets. 060 * <BR> 061 * <H2>Configuring Scripted HTTP Operation Loggers</H2> 062 * In order to configure a scripted HTTP operation logger created using this 063 * API, use a command like: 064 * <PRE> 065 * dsconfig create-log-publisher \ 066 * --publisher-name "<I>{logger-name}</I>" \ 067 * --type groovy-scripted-http-operation \ 068 * --set enabled:true \ 069 * --set "script-class:<I>{class-name}</I>" \ 070 * --set "script-argument:<I>{name=value}</I>" 071 * </PRE> 072 * where "<I>{logger-name}</I>" is the name to use for the scripted HTTP 073 * operation logger instance, "<I>{script-class}</I>" is the fully-qualified 074 * name of the Groovy class written using this API, and "<I>{name=value}</I>" 075 * represents name-value pairs for any arguments to provide to the logger. If 076 * multiple arguments should be provided to the logger, then the 077 * "<CODE>--set script-argument:<I>{name=value}</I></CODE>" option should be 078 * provided multiple times. 079 * 080 * @see com.unboundid.directory.sdk.http.api.HTTPOperationLogger 081 */ 082 @Extensible() 083 @DirectoryServerExtension() 084 @DirectoryProxyServerExtension(appliesToLocalContent=true, 085 appliesToRemoteContent=true) 086 @MetricsEngineExtension() 087 @IdentityBrokerExtension() 088 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 089 public abstract class ScriptedHTTPOperationLogger 090 implements Reconfigurable<HTTPOperationLoggerConfig> 091 { 092 /** 093 * The key that will be used to hold the time the request was received, in 094 * milliseconds since January 1, 1960, UTC, as reported by 095 * {@code System.currentTimeMillis()}. It will always be present in the state 096 * map when the {@link #logResponse} method is invoked. The value associated 097 * with this key will be a {@code java.lang.Long} object. 098 */ 099 public static final String STATE_KEY_REQUEST_TIME_MILLIS = 100 "___request_time_millis___"; 101 102 103 104 /** 105 * The key that will be used to hold the response content length in the state 106 * map. It will always be present in the state map when the 107 * {@link #logResponse} method is invoked. The value associated with this key 108 * will be a {@code java.lang.Long} object. 109 */ 110 public static final String STATE_KEY_RESPONSE_CONTENT_LENGTH = 111 "___response_content_length___"; 112 113 114 115 /** 116 * The key that will be used to hold the operation processing time in 117 * milliseconds. It will always be present in the state map when the 118 * {@link #logResponse} method is invoked. The value associated with this key 119 * will be a {@code java.lang.Long} object. 120 */ 121 public static final String STATE_KEY_PROCESSING_TIME_MILLIS = 122 "___processing_time_millis___"; 123 124 125 126 /** 127 * The key that will be used to hold the operation processing time in 128 * nanoseconds. It will always be present in the state map when the 129 * {@link #logResponse} method is invoked. The value associated with this key 130 * will be a {@code java.lang.Long} object. 131 */ 132 public static final String STATE_KEY_PROCESSING_TIME_NANOS = 133 "___processing_time_nanos___"; 134 135 136 137 /** 138 * Creates a new instance of this scripted HTTP operation logger. All 139 * scripted HTTP operation logger implementations must include a default 140 * constructor, but any initialization should generally be done in the 141 * {@code initializeHTTPOperationLogger} method. 142 */ 143 public ScriptedHTTPOperationLogger() 144 { 145 // No implementation is required. 146 } 147 148 149 150 /** 151 * {@inheritDoc} 152 */ 153 public void defineConfigArguments(final ArgumentParser parser) 154 throws ArgumentException 155 { 156 // No arguments will be allowed by default. 157 } 158 159 160 161 /** 162 * Initializes this scripted HTTP operation logger. 163 * 164 * @param serverContext A handle to the server context for the server in 165 * which this extension is running. 166 * @param config The general configuration for this HTTP operation 167 * logger. 168 * @param parser The argument parser which has been initialized from 169 * the configuration for this HTTP operation logger. 170 * 171 * @throws LDAPException If a problem occurs while initializing this HTTP 172 * operation logger. 173 */ 174 public void initializeHTTPOperationLogger( 175 final HTTPServerContext serverContext, 176 final HTTPOperationLoggerConfig config, 177 final ArgumentParser parser) 178 throws LDAPException 179 { 180 // No initialization will be performed by default. 181 } 182 183 184 185 /** 186 * {@inheritDoc} 187 */ 188 public boolean isConfigurationAcceptable( 189 final HTTPOperationLoggerConfig config, 190 final ArgumentParser parser, 191 final List<String> unacceptableReasons) 192 { 193 // No extended validation will be performed by default. 194 return true; 195 } 196 197 198 199 /** 200 * {@inheritDoc} 201 */ 202 public ResultCode applyConfiguration(final HTTPOperationLoggerConfig config, 203 final ArgumentParser parser, 204 final List<String> adminActionsRequired, 205 final List<String> messages) 206 { 207 // By default, no configuration changes will be applied. If there are any 208 // arguments, then add an admin action message indicating that the extension 209 // needs to be restarted for any changes to take effect. 210 if (! parser.getNamedArguments().isEmpty()) 211 { 212 adminActionsRequired.add( 213 "No configuration change has actually been applied. The new " + 214 "configuration will not take effect until this scripted HTTP " + 215 "operation logger is disabled and re-enabled or until the " + 216 "server is restarted."); 217 } 218 219 return ResultCode.SUCCESS; 220 } 221 222 223 224 /** 225 * Performs any cleanup which may be necessary when this HTTP operation logger 226 * is to be taken out of service. 227 */ 228 public void finalizeHTTPOperationLogger() 229 { 230 // No implementation is required. 231 } 232 233 234 235 /** 236 * Logs information about a servlet request that has been received from the 237 * client. 238 * 239 * @param request An object with information about the request received 240 * from the client. 241 * @param stateMap An empty map which may be updated to hold state 242 * information that can be used to correlate information 243 * between the request and response. The same map instance 244 * will be passed to the {@link #logResponse} method. 245 */ 246 public void logRequest(final HttpServletRequest request, 247 final Map<String,Object> stateMap) 248 { 249 // No processing performed by default. 250 } 251 252 253 254 /** 255 * Logs information about a servlet response to be returned to the client. 256 * 257 * @param request An object with information about the request received 258 * from the client. 259 * @param response An object with information about the response to be 260 * returned to the client. 261 * @param stateMap A map containing state any information added while 262 * processing the {@link #logRequest} method. 263 */ 264 public void logResponse(final HttpServletRequest request, 265 final HttpServletResponse response, 266 final Map<String,Object> stateMap) 267 { 268 // No processing performed by default. 269 } 270 }