org.springframework.aop.interceptor

Class CustomizableTraceInterceptor

java.lang.Object

org.springframework.aop.interceptor.AbstractTraceInterceptor

org.springframework.aop.interceptor.CustomizableTraceInterceptor

All Implemented Interfaces:

java.io.Serializable

public class CustomizableTraceInterceptor
extends AbstractTraceInterceptor

MethodInterceptor implementation that allows for highly customizable method-level tracing, using placeholders.

Trace messages are written on method entry, and if the method invocation succeeds on method exit. If an invocation results in an exception, then an exception message is written. The contents of these trace messages is fully customizable and special placeholders are available to allow you to include runtime information in your log messages. The placeholders available are:

• $[methodName] - replaced with the name of the method being invoked
• $[targetClassName] - replaced with the name of the class that is the target of the invocation
• $[targetClassShortName] - replaced with the short name of the class that is the target of the invocation
• $[returnValue] - replaced with the value returned by the invocation
• $[argumentTypes] - replaced with a comma-separated list of the short class names of the method arguments
• $[arguments] - replaced with a comma-separated list of the String representation of the method arguments
• $[exception] - replaced with the String representation of any Throwable raised during the invocation
• $[invocationTime] - replaced with the time, in milliseconds, taken by the method invocation

There are restrictions on which placeholders can be used in which messages: see the individual message properties for details on the valid placeholders.

Since:

1.2

Author:

Rob Harrop, Juergen Hoeller

See Also:

setEnterMessage(java.lang.String), setExitMessage(java.lang.String), setExceptionMessage(java.lang.String), SimpleTraceInterceptor, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
private static java.util.Set<java.lang.Object>	ALLOWED_PLACEHOLDERS The Set of allowed placeholders.
private static java.lang.String	DEFAULT_ENTER_MESSAGE The default message used for writing method entry messages.
private static java.lang.String	DEFAULT_EXCEPTION_MESSAGE The default message used for writing exception messages.
private static java.lang.String	DEFAULT_EXIT_MESSAGE The default message used for writing method exit messages.
private java.lang.String	enterMessage The message for method entry.
private java.lang.String	exceptionMessage The message for exceptions during method execution.
private java.lang.String	exitMessage The message for method exit.
private static java.util.regex.Pattern	PATTERN The Pattern used to match placeholders.
static java.lang.String	PLACEHOLDER_ARGUMENT_TYPES The $[argumentTypes] placeholder.
static java.lang.String	PLACEHOLDER_ARGUMENTS The $[arguments] placeholder.
static java.lang.String	PLACEHOLDER_EXCEPTION The $[exception] placeholder.
static java.lang.String	PLACEHOLDER_INVOCATION_TIME The $[invocationTime] placeholder.
static java.lang.String	PLACEHOLDER_METHOD_NAME The $[methodName] placeholder.
static java.lang.String	PLACEHOLDER_RETURN_VALUE The $[returnValue] placeholder.
static java.lang.String	PLACEHOLDER_TARGET_CLASS_NAME The $[targetClassName] placeholder.
static java.lang.String	PLACEHOLDER_TARGET_CLASS_SHORT_NAME The $[targetClassShortName] placeholder.

Fields inherited from class org.springframework.aop.interceptor.AbstractTraceInterceptor

defaultLogger

Constructor Summary

Constructors

Constructor and Description
CustomizableTraceInterceptor()

Method Summary

Modifier and Type	Method and Description
private void	appendArgumentTypes(MethodInvocation methodInvocation, java.util.regex.Matcher matcher, java.lang.StringBuffer output) Adds a comma-separated list of the short Class names of the method argument types to the output.
private void	appendReturnValue(MethodInvocation methodInvocation, java.util.regex.Matcher matcher, java.lang.StringBuffer output, java.lang.Object returnValue) Adds the String representation of the method return value to the supplied StringBuffer.
private void	checkForInvalidPlaceholders(java.lang.String message) Checks to see if the supplied String has any placeholders that are not specified as constants on this class and throws an IllegalArgumentException if so.
protected java.lang.Object	invokeUnderTrace(MethodInvocation invocation, Log logger) Writes a log message before the invocation based on the value of enterMessage.
protected java.lang.String	replacePlaceholders(java.lang.String message, MethodInvocation methodInvocation, java.lang.Object returnValue, java.lang.Throwable throwable, long invocationTime) Replace the placeholders in the given message with the supplied values, or values derived from those supplied.
void	setEnterMessage(java.lang.String enterMessage) Set the template used for method entry log messages.
void	setExceptionMessage(java.lang.String exceptionMessage) Set the template used for method exception log messages.
void	setExitMessage(java.lang.String exitMessage) Set the template used for method exit log messages.
protected void	writeToLog(Log logger, java.lang.String message) Writes the supplied message to the supplied Log instance.
protected void	writeToLog(Log logger, java.lang.String message, java.lang.Throwable ex) Writes the supplied message and Throwable to the supplied Log instance.

Methods inherited from class org.springframework.aop.interceptor.AbstractTraceInterceptor

getClassForLogging, getLoggerForInvocation, invoke, isInterceptorEnabled, isLogEnabled, setHideProxyClassNames, setLoggerName, setUseDynamicLogger

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PLACEHOLDER_METHOD_NAME

public static final java.lang.String PLACEHOLDER_METHOD_NAME

The $[methodName] placeholder. Replaced with the name of the method being invoked.

See Also:

Constant Field Values

PLACEHOLDER_TARGET_CLASS_NAME

public static final java.lang.String PLACEHOLDER_TARGET_CLASS_NAME

The $[targetClassName] placeholder. Replaced with the fully-qualifed name of the Class of the method invocation target.

See Also:

Constant Field Values

PLACEHOLDER_TARGET_CLASS_SHORT_NAME

public static final java.lang.String PLACEHOLDER_TARGET_CLASS_SHORT_NAME

The $[targetClassShortName] placeholder. Replaced with the short name of the Class of the method invocation target.

See Also:

Constant Field Values

PLACEHOLDER_RETURN_VALUE

public static final java.lang.String PLACEHOLDER_RETURN_VALUE

The $[returnValue] placeholder. Replaced with the String representation of the value returned by the method invocation.

See Also:

Constant Field Values

PLACEHOLDER_ARGUMENT_TYPES

public static final java.lang.String PLACEHOLDER_ARGUMENT_TYPES

The $[argumentTypes] placeholder. Replaced with a comma-separated list of the argument types for the method invocation. Argument types are written as short class names.

See Also:

Constant Field Values

PLACEHOLDER_ARGUMENTS

public static final java.lang.String PLACEHOLDER_ARGUMENTS

The $[arguments] placeholder. Replaced with a comma separated list of the argument values for the method invocation. Relies on the toString() method of each argument type.

See Also:

Constant Field Values

PLACEHOLDER_EXCEPTION

public static final java.lang.String PLACEHOLDER_EXCEPTION

The $[exception] placeholder. Replaced with the String representation of any Throwable raised during method invocation.

See Also:

Constant Field Values

PLACEHOLDER_INVOCATION_TIME

public static final java.lang.String PLACEHOLDER_INVOCATION_TIME

The $[invocationTime] placeholder. Replaced with the time taken by the invocation (in milliseconds).

See Also:

Constant Field Values

DEFAULT_ENTER_MESSAGE

private static final java.lang.String DEFAULT_ENTER_MESSAGE

The default message used for writing method entry messages.

See Also:

Constant Field Values

DEFAULT_EXIT_MESSAGE

private static final java.lang.String DEFAULT_EXIT_MESSAGE

The default message used for writing method exit messages.

See Also:

Constant Field Values

DEFAULT_EXCEPTION_MESSAGE

private static final java.lang.String DEFAULT_EXCEPTION_MESSAGE

The default message used for writing exception messages.

See Also:

Constant Field Values

PATTERN

private static final java.util.regex.Pattern PATTERN

The Pattern used to match placeholders.

ALLOWED_PLACEHOLDERS

private static final java.util.Set<java.lang.Object> ALLOWED_PLACEHOLDERS

The Set of allowed placeholders.

enterMessage

private java.lang.String enterMessage

The message for method entry.

exitMessage

private java.lang.String exitMessage

The message for method exit.

exceptionMessage

private java.lang.String exceptionMessage

The message for exceptions during method execution.

Constructor Detail

CustomizableTraceInterceptor

public CustomizableTraceInterceptor()

Method Detail

setEnterMessage

public void setEnterMessage(java.lang.String enterMessage)
                     throws java.lang.IllegalArgumentException

Set the template used for method entry log messages. This template can contain any of the following placeholders:

• $[targetClassName]
• $[targetClassShortName]
• $[argumentTypes]
• $[arguments]

Throws:

java.lang.IllegalArgumentException

setExitMessage

public void setExitMessage(java.lang.String exitMessage)

Set the template used for method exit log messages. This template can contain any of the following placeholders:

• $[targetClassName]
• $[targetClassShortName]
• $[argumentTypes]
• $[arguments]
• $[returnValue]
• $[invocationTime]

setExceptionMessage

public void setExceptionMessage(java.lang.String exceptionMessage)

Set the template used for method exception log messages. This template can contain any of the following placeholders:

• $[targetClassName]
• $[targetClassShortName]
• $[argumentTypes]
• $[arguments]
• $[exception]

invokeUnderTrace

protected java.lang.Object invokeUnderTrace(MethodInvocation invocation,
                                            Log logger)
                                     throws java.lang.Throwable

Writes a log message before the invocation based on the value of enterMessage. If the invocation succeeds, then a log message is written on exit based on the value exitMessage. If an exception occurs during invocation, then a message is written based on the value of exceptionMessage.

Specified by:

invokeUnderTrace in class AbstractTraceInterceptor

logger - the Log to write trace messages to

Returns:

the result of the call to MethodInvocation.proceed()

Throws:

java.lang.Throwable - if the call to MethodInvocation.proceed() encountered any errors

See Also:

setEnterMessage(java.lang.String), setExitMessage(java.lang.String), setExceptionMessage(java.lang.String)

writeToLog

protected void writeToLog(Log logger,
                          java.lang.String message)

Writes the supplied message to the supplied Log instance.

See Also:

#writeToLog(org.apache.commons.logging.Log, String, Throwable)

writeToLog

protected void writeToLog(Log logger,
                          java.lang.String message,
                          java.lang.Throwable ex)

Writes the supplied message and Throwable to the supplied Log instance. By default messages are written at TRACE level. Sub-classes can override this method to control which level the message is written at.

replacePlaceholders

protected java.lang.String replacePlaceholders(java.lang.String message,
                                               MethodInvocation methodInvocation,
                                               java.lang.Object returnValue,
                                               java.lang.Throwable throwable,
                                               long invocationTime)

Replace the placeholders in the given message with the supplied values, or values derived from those supplied.

Parameters:

message - the message template containing the placeholders to be replaced

methodInvocation - the MethodInvocation being logged. Used to derive values for all placeholders except $[exception] and $[returnValue].

returnValue - any value returned by the invocation. Used to replace the $[returnValue] placeholder. May be null.

throwable - any Throwable raised during the invocation. The value of Throwable.toString() is replaced for the $[exception] placeholder. May be null.

invocationTime - the value to write in place of the $[invocationTime] placeholder

Returns:

the formatted output to write to the log

appendReturnValue

private void appendReturnValue(MethodInvocation methodInvocation,
                               java.util.regex.Matcher matcher,
                               java.lang.StringBuffer output,
                               java.lang.Object returnValue)

Adds the String representation of the method return value to the supplied StringBuffer. Correctly handles null and void results.

Parameters:

methodInvocation - the MethodInvocation that returned the value

matcher - the Matcher containing the matched placeholder

output - the StringBuffer to write output to

returnValue - the value returned by the method invocation.

appendArgumentTypes

private void appendArgumentTypes(MethodInvocation methodInvocation,
                                 java.util.regex.Matcher matcher,
                                 java.lang.StringBuffer output)

Adds a comma-separated list of the short Class names of the method argument types to the output. For example, if a method has signature put(java.lang.String, java.lang.Object) then the value returned will be String, Object.

Parameters:

methodInvocation - the MethodInvocation being logged. Arguments will be retrieved from the corresponding Method.

matcher - the Matcher containing the state of the output

output - the StringBuffer containing the output

checkForInvalidPlaceholders

private void checkForInvalidPlaceholders(java.lang.String message)
                                  throws java.lang.IllegalArgumentException

Checks to see if the supplied String has any placeholders that are not specified as constants on this class and throws an IllegalArgumentException if so.

Throws:

java.lang.IllegalArgumentException