eu.planets_project.services.utils
Class ServicePerformanceHelper

java.lang.Object
  eu.planets_project.services.utils.ServicePerformanceHelper

public class ServicePerformanceHelper
extends Object

A standardised timing and performance data collection class, used to monitor performance consistently across services.

To use it, first instantiate this class when your preservation action method starts. The helper starts timing on construction. This is to prevent accidental re-use of each instance of the object, in order to avoid copies of the object being used in an non-thread-safe manner.

When the service has finished it's work, and before creating the final ServiceReport, call the .stop() method to halt the timer. Then use getPerformanceProperties() to get the results, which should be added to the ServiceReport (not the return object specific to that preservation action.

As well as measuring how long the process took (wall-clock time), these methods also measure how much CPU time this current thread required (e.g. half the wall-clock time if this process is only getting 50% of the CPU time). Note that this will only give meaningful results if your service runs in a single thread. Also, while the thread is running, this helper measures the peak memory usage of the JVM. While this does not explicitly identify the resource usage associated with your service, it should be indicative in the main 'interesting' cases, e.g. when your service is passed a large file. A number of standard system properties are also measured, in order to understand the context of the execution process.

Additionally, this helper provides two methods by which the caller can record when it has finished transferring the input arguments (e.g. one or more DigitalObjects) from the caller (.transferred()), and/or record when the input arguments have been loaded into memory (.loaded()), if that is relevant. Note that the .loaded() time should include the .transferred() time. If the input streams are loaded directly into memory, the calling code should only record the .loaded() time.

For examples of how these calls should be used see JavaImageIOCompare, JavaImageIOMigrate and JavaImageIOIdentify in the PA/java-se component.

Note that we use System.nanoTime() rather than System.currentTimeMills() because that call generally more accurate. In particular, on Windows, the currentTimeMillis is often rounded rather coarsely. See below for details.

Author:

Andrew.Jackson@bl.uk

See Also:

http://savvyduck.blogspot.com/2008/06/java-getting-thread-time-with.html, http://java.sun.com/javase/6/docs/api/java/lang/System.html#currentTimeMillis%28%29, http://nadeausoftware.com/articles/2008/03/java_tip_how_get_cpu_and_user_time_benchmarking, http://stackoverflow.com/questions/351565/system-currenttimemillis-vs-system-nanotime, http://blogs.sun.com/dholmes/entry/inside_the_hotspot_vm_clocks, http://stackoverflow.com/questions/47177/how-to-monitor-the-computers-cpu-memory-and-disk-usage-in-java

Constructor Summary

ServicePerformanceHelper()

Method Summary

List<Property>	getPerformanceProperties()
void	loaded() Allows developers to specify when the service has retrieved the data and loaded it into memory, ready for processing.
void	stop() Stop all timers, as all work has been done apart from returning from the service call method.
void	transferred() Allows developers to specify when the service has finished retrieving data, and is now only going to process the inputs and compose the response.

Methods inherited from class java.lang.Object

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

Constructor Detail

ServicePerformanceHelper

public ServicePerformanceHelper()

Method Detail

transferred

public void transferred()

Allows developers to specify when the service has finished retrieving data, and is now only going to process the inputs and compose the response. Should only be used when it is really clear that the load/retrieval time can be clearly distinguished from the processing time.

loaded

public void loaded()

Allows developers to specify when the service has retrieved the data and loaded it into memory, ready for processing. Should NOT be used if the data is not accessed in this manner.

stop

public void stop()

Stop all timers, as all work has been done apart from returning from the service call method.

getPerformanceProperties

public List<Property> getPerformanceProperties()