com.webobjects.appserver
Class WOStatisticsStore

java.lang.Object
  |
  +--com.webobjects.appserver.WOStatisticsStore

All Implemented Interfaces:

NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

public class WOStatisticsStore

extends Object

implements NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

This class holds various runtime statistics of an application.

There is only one instance of this class in an application, so access to all methods must be thread-safe. If at all possible, use "volatile" instead of synchronization to avoid scalability issues here.

Recording Information

The WOStatisticsStore object records the bulk of its statistics at the end of each cycle of the request-response loop. Specifically, at the end of WOSession's appendToResponse method, the WOSession sends the recordStatisticsForResponse message to the WOStatisticsStore. This message tells the WOStatisticsStore to begin recording statistics. Then, WOSession sends it a descriptionForResponse message. This method also sends the response component a descriptionForResponse message. The default implementation of descriptionForResponse in WOComponent returns the component's name.

You can override descriptionForResponse in each of the components if the user wants to record more information. For example, you might want to record the values of all of the component's variables or perhaps just one or two key variables.

If the user want to record extra information about the session, the user can override WOStatisticsStore's recordStatisticsForResponse method.

Maintaining a Log File

The user can maintain an application log file by sending the message setLogFile to the WOStatisticsStore object. When a log file has been specified, each session keeps information about the previous requests, and pages, it has served. When the session expires, it writes this aggregated information to the log file all at once. This is faster than recording the information on a per request basis in the log file, but it has the disadvantage that if an application crashes, all non-expired sessions' information will be lost.

The session information is saved as several lines in the Common Log File Format (CLFF), one line per request served. The log is maintained in the CLFF format so that it can be analyzed by any standard CLFF-analysis tool. (For more information about the statistics recorded in the log file, see the formatDescription method description.).

See Also:

recordStatisticsForResponse(WOResponse, WOContext), descriptionForResponse(WOResponse, WOContext), setLogFile(String, long), formatDescription(String, WOResponse, WOContext)

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

protected

WOStatisticsStore()

Method Summary

void	applicationDidHandleComponentActionRequestWithPageNamed(String pageName) A component action request handler should call this method at the appropriate time to register the fact that it just handled a component action request.
void	applicationDidHandleDirectActionRequestWithActionNamed(String anActionName) A direct action request handler should call this method at the appropriate time to register the fact that it just handled a direct action request.
void	applicationDidHandleWebServiceRequestWithActionNamed(String anActionName) A web service request handler should call this method at the appropriate time to register the fact that it just handled a web service request.
void	applicationWillHandleComponentActionRequest() A component action request handler should call this method at the appropriate time to register the fact that it is about to handle a component action request.
void	applicationWillHandleDirectActionRequest() A direct action request handler should call this method at the appropriate time to register the fact that it is about to handle a direct action request.
void	applicationWillHandleWebServiceRequest() A web service request handler should call this method at the appropriate time to register the fact that it is about to handle a web service request.
static boolean	canAccessFieldsDirectly() WOStatisticsStore's implementation of this static method returns true, indicating that key-value coding is allowed to access fields in this object if an appropriate method isn't present.
String	descriptionForResponse(WOResponse aResponse, WOContext aContext) Records information about the current response by invoking descriptionForResponse on the current response page and returning the result.
String	formatDescription(String statistics, WOResponse aResponse, WOContext aContext) If log file recording is enabled, this method formats the string statistics using the Common Log File Format (CLFF).
Object	handleQueryWithUnboundKey(String key) Conformance to NSKeyValueCoding.ErrorHandling.
void	handleTakeValueForUnboundKey(Object value, String key) Conformance to NSKeyValueCoding.ErrorHandling.
String	logFile() Gets the full path of the log file.
long	logFileRotationFrequency() The number of milliseconds a log file lasts.
double	logFileRotationFrequencyInDays() Deprecated. Use logFileRotationFrequency() instead.
void	logString(String statistics) Writes the string statistics to the log file specified by logFile.
NSMutableDictionary	memoryUsage() Gets an NSMutableDictionary that indicates the total amount of memory in the Java Virtual Machine (access this value using the dictionary key "Total Memory"), and an approximation of the amount of free memory in the system (access this value using the dictionary key "Free Memory").
void	recordStatisticsForResponse(WOResponse aResponse, WOContext aContext) Records statistics for the current cycle of the request-response loop.
int	sessionMovingAverageSampleSize() The WOStatisticsStore object uses the returned sample size to compute the response time for the last n transactions and the idle time between the last n transactions, where n is the number returned by this method.
void	setLogFile(String path, double days) Deprecated. Use setLogFile(String path, long milliseconds) instead
void	setLogFile(String path, long milliseconds) Sets the full path of the log file to which statistics will be recorded; these statistics will be in Common Log File Format (CLFF).
void	setPassword(String password) Implements security for the WOStats page by setting its password to password.
void	setSessionMovingAverageSampleSize(int aCount) Sets the moving average sample size for each session to aCount.
void	setTransactionMovingAverageSampleSize(int aCount) Sets the moving average sample size for each transaction to aCount.
NSDictionary	statistics() Gets a dictionary containing the statistics that the WOStatisticsStore records.
void	takeValueForKey(Object value, String key) Conformance to NSKeyValueCoding.
void	takeValueForKeyPath(Object value, String keyPath) Conformance to NSKeyValueCodingAdditions.
int	transactionMovingAverageSampleSize() The WOStatisticsStore object uses the returned sample size to compute the response time for the last n transactions and the idle time between the last n transactions, where n is the number returned by this method.
void	unableToSetNullForKey(String key) Conformance to NSKeyValueCoding.ErrorHandling.
boolean	validateLogin(String string, WOSession aSession) Validates if the password string is correct so as to allow viewing of the application's statistics.
Object	valueForKey(String key) Conformance to NSKeyValueCoding.
Object	valueForKeyPath(String keyPath) Conformance to NSKeyValueCodingAdditions.

Methods inherited from class java.lang.Object

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

Constructor Detail

WOStatisticsStore

protected WOStatisticsStore()

Method Detail

applicationDidHandleComponentActionRequestWithPageNamed

public void applicationDidHandleComponentActionRequestWithPageNamed(String pageName)

A component action request handler should call this method at the appropriate time to register the fact that it just handled a component action request.

Parameters:

pageName - input page name

applicationDidHandleDirectActionRequestWithActionNamed

public void applicationDidHandleDirectActionRequestWithActionNamed(String anActionName)

A direct action request handler should call this method at the appropriate time to register the fact that it just handled a direct action request.

Parameters:

anActionName - the direct action name

applicationDidHandleWebServiceRequestWithActionNamed

public void applicationDidHandleWebServiceRequestWithActionNamed(String anActionName)

A web service request handler should call this method at the appropriate time to register the fact that it just handled a web service request.

Parameters:

anActionName - the web service name

applicationWillHandleComponentActionRequest

public void applicationWillHandleComponentActionRequest()

A component action request handler should call this method at the appropriate time to register the fact that it is about to handle a component action request.

applicationWillHandleDirectActionRequest

public void applicationWillHandleDirectActionRequest()

A direct action request handler should call this method at the appropriate time to register the fact that it is about to handle a direct action request.

applicationWillHandleWebServiceRequest

public void applicationWillHandleWebServiceRequest()

A web service request handler should call this method at the appropriate time to register the fact that it is about to handle a web service request.

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

WOStatisticsStore's implementation of this static method returns true, indicating that key-value coding is allowed to access fields in this object if an appropriate method isn't present.

Returns:

descriptionForResponse

public String descriptionForResponse(WOResponse aResponse,
                                     WOContext aContext)

Records information about the current response by invoking descriptionForResponse on the current response page and returning the result. This method is invoked at the end of the request-response loop in WOSession's appendToResponse method, after the recordStatisticsForResponse method.

Parameters:

aResponse - the current WOResponse to be described

aContext - the WebObjects context in which the current response page resides

Returns:

information about the current response

See Also:

recordStatisticsForResponse(WOResponse, WOContext), WOSession.appendToResponse(WOResponse, WOContext), WOComponent.descriptionForResponse(WOResponse, WOContext)

formatDescription

public String formatDescription(String statistics,
                                WOResponse aResponse,
                                WOContext aContext)

If log file recording is enabled, this method formats the string statistics using the Common Log File Format (CLFF). The resulting string contains:

• The host from which the HTTP request was received
• The name of the user that performed the request
• The current date
• The request's HTTP method (GET or PUT)
• The WebObjects application name
• The result of the descriptionForResponse method (by default, this method returns the response component's name)
• The request's HTTP version
• The HTTP status of the response
• The size of the response

Log file recording is enabled by setting a log file using the setLogFile method.

This method is used by WOSession to record information about the current transaction when log file recording is enabled.

Parameters:

statistics - the description string to be formatted

aResponse - the current WOResponse to be described

aContext - the current WebObjects context

Returns:

the formatted description

See Also:

descriptionForResponse(WOResponse, WOContext), setLogFile(String, long)

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling.

Specified by:

handleQueryWithUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key -

Returns:

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)

Conformance to NSKeyValueCoding.ErrorHandling.

Specified by:

handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

value -

key -

logFile

public String logFile()

Gets the full path of the log file. This log file does not exist unless setLogFile has been called.

Returns:

the full path to the log file

See Also:

setLogFile(String, long)

logFileRotationFrequency

public long logFileRotationFrequency()

The number of milliseconds a log file lasts. That is, a log file's contents are flushed after a certain time interval to ensure that it does not grow too large and a new log file is started. This method returns that time interval.

Before a new log file is started, the contents of the current log file are saved to a backup file. You can then inspect this log file and/or removed when its data has grown stale.

Returns:

the number of milliseconds a log file lasts

See Also:

setLogFile(String, long)

logFileRotationFrequencyInDays

public double logFileRotationFrequencyInDays()

Deprecated. Use logFileRotationFrequency() instead.

Returns:

the number of days a log file lasts

See Also:

logFileRotationFrequency()

logString

public void logString(String statistics)

Writes the string statistics to the log file specified by logFile. The method is used to record a session's statistics when that session ends. You can also use it to record any string to the log file that you might find helpful.

Parameters:

statistics - the input string giving the details of the session

See Also:

formatDescription(String, WOResponse, WOContext), setLogFile(String, long)

memoryUsage

public NSMutableDictionary memoryUsage()

Gets an NSMutableDictionary that indicates the total amount of memory in the Java Virtual Machine (access this value using the dictionary key "Total Memory"), and an approximation of the amount of free memory in the system (access this value using the dictionary key "Free Memory"). Both values are measured in bytes. These values can be obtained directly from the java.lang.Runtime object by using the totalMemory() and freeMemory() methods, respectively.

Returns:

an NSMutableDictionary that contains memory usage information

recordStatisticsForResponse

public void recordStatisticsForResponse(WOResponse aResponse,
                                        WOContext aContext)

Records statistics for the current cycle of the request-response loop. This method is invoked at the end of WOSession's appendToResponse method, immediately before the descriptionForResponse method. By default, this method records the name of the response page for later use by descriptionForResponse. You can override it if you want to record more information about the session before the current request and response are garbage collected. You must begin your implementation by invoking the superclass method.

Parameters:

aResponse - the response to be appended

aContext - the WebObjects context in which the response will be appended

See Also:

descriptionForResponse(WOResponse, WOContext), WOSession.appendToResponse(WOResponse, WOContext)

sessionMovingAverageSampleSize

public int sessionMovingAverageSampleSize()

The WOStatisticsStore object uses the returned sample size to compute the response time for the last n transactions and the idle time between the last n transactions, where n is the number returned by this method. The default sample size is 10.

Returns:

the sample size used to compute moving average statistics for each session

See Also:

setSessionMovingAverageSampleSize(int)

setLogFile

public void setLogFile(String path,
                       long milliseconds)

Sets the full path of the log file to which statistics will be recorded; these statistics will be in Common Log File Format (CLFF). It also sets the rotation period of the log file in milliseconds. After each period the contents of the current log file are saved to a backup file and a new log file is started.

The default is not to record information to a log file.

Parameters:

path - full path of the log file

milliseconds - the log rotation period in milliseconds

See Also:

logFileRotationFrequency(), logFile()

setLogFile

public void setLogFile(String path,
                       double days)

Deprecated. Use setLogFile(String path, long milliseconds) instead

Parameters:

path - full path of the log file

days - specifies the log rotation period in days

See Also:

setLogFile(String, long)

setPassword

public void setPassword(String password)

Implements security for the WOStats page by setting its password to password. By default, there is no password, and access to the WOStats page is disabled. You can call this method to set the access password or you can set the password in the Java system properties through the property key "WOStatisticsPassword".

When you enter the WOStats URL, a login panel appears. You can leave the user name field blank; as long as you type the appropriate password in the password field, the WOStats page will appear.

Parameters:

password - password for WOStats page is set to this value

See Also:

validateLogin(String, WOSession), NSProperties

setSessionMovingAverageSampleSize

public void setSessionMovingAverageSampleSize(int aCount)

Sets the moving average sample size for each session to aCount. The WOStatisticsStore object uses this sample size to compute the response time for the last aCount transactions and the idle time between the last aCount transactions.

The default moving average session sample size is 10 transactions.

Parameters:

aCount - the moving average size per session is set to this value

See Also:

sessionMovingAverageSampleSize()

setTransactionMovingAverageSampleSize

public void setTransactionMovingAverageSampleSize(int aCount)

Sets the moving average sample size for each transaction to aCount. The WOStatisticsStore object uses this sample size to compute the response time for the last aCount transactions and the idle time between the last aCount transactions.

The default moving average transaction sample size is 100 transactions.

Parameters:

aCount - the moving average size per transaction is set to this value

See Also:

transactionMovingAverageSampleSize()

statistics

public NSDictionary statistics()

Gets a dictionary containing the statistics that the WOStatisticsStore records.

The averages that are displayed by this method are not computed until this method is invoked. Therefore, invoking this method is costly and should not be done at every request.

Returns:

a dictionary containing the recorded statistics

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Conformance to NSKeyValueCoding.

Specified by:

takeValueForKey in interface NSKeyValueCoding

Parameters:

key - identifies the property to be set

value - the value to which the property specified by key should be set

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)

Conformance to NSKeyValueCodingAdditions.

Specified by:

takeValueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - identifies a derived property of the receiver

value - value to which the derived property identified by keyPath will be set

transactionMovingAverageSampleSize

public int transactionMovingAverageSampleSize()

The WOStatisticsStore object uses the returned sample size to compute the response time for the last n transactions and the idle time between the last n transactions, where n is the number returned by this method. The default sample size is 100.

Returns:

the sample size used to compute moving average statistics for each transaction

See Also:

setTransactionMovingAverageSampleSize(int)

unableToSetNullForKey

public void unableToSetNullForKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling.

Specified by:

unableToSetNullForKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key -

validateLogin

public boolean validateLogin(String string,
                             WOSession aSession)

Validates if the password string is correct so as to allow viewing of the application's statistics.

Parameters:

string - the password to be validated

aSession - the current WOSession for viewing statistics

Returns:

true if validation is done correctly; false otherwise

See Also:

setPassword(String password)

valueForKey

public Object valueForKey(String key)

Conformance to NSKeyValueCoding.

Specified by:

valueForKey in interface NSKeyValueCoding

Parameters:

key - identifies the property of an object

Returns:

the receiver's value for the property identified by key

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Conformance to NSKeyValueCodingAdditions.

Specified by:

valueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - identifies the derived property of an object

Returns:

receiver's value for the derived property identified by keyPath