WebObjects 5.2

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:

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

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.