Author: bleny Date: 2011-12-12 17:48:26 +0100 (Mon, 12 Dec 2011) New Revision: 159 Url: http://nuiton.org/repositories/revision/nuiton-web/159 Log: some more javadoc around JMX and MonitoringFilter Modified: trunk/nuiton-web/src/main/java/org/nuiton/web/filter/MonitoringFilter.java trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/RequestStatistics.java trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/ServletStatisticsService.java trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/ServletStatisticsServiceMBean.java Modified: trunk/nuiton-web/src/main/java/org/nuiton/web/filter/MonitoringFilter.java =================================================================== --- trunk/nuiton-web/src/main/java/org/nuiton/web/filter/MonitoringFilter.java 2011-12-12 15:27:31 UTC (rev 158) +++ trunk/nuiton-web/src/main/java/org/nuiton/web/filter/MonitoringFilter.java 2011-12-12 16:48:26 UTC (rev 159) @@ -58,10 +58,15 @@ /** Logger. */ private static final Log log = LogFactory.getLog(MonitoringFilter.class); + /** The objectName where the MBean will be registered. */ protected ObjectName servletStatisticsMBeanName; + /** The service used to record statistics before and after filter is called. */ protected ServletStatisticsService servletStatisticsService; + /** + * Attach the MBean. + */ @Override public void init(FilterConfig filterConfig) throws ServletException { try { @@ -72,7 +77,10 @@ // Register the Mbean on the server servletStatisticsMBeanName = new ObjectName("Servlet:application=Statistics"); server.registerMBean(servletStatisticsService, servletStatisticsMBeanName); - log.info("mbean " + servletStatisticsService + " attached as " + servletStatisticsMBeanName); + if (log.isInfoEnabled()) { + log.info("mbean " + servletStatisticsService + " attached as " + + servletStatisticsMBeanName); + } } catch (MalformedObjectNameException e) { log.error("unable to register mbean", e); } catch (InstanceAlreadyExistsException e) { @@ -95,10 +103,15 @@ } + /** + * Detach the MBean, print statistics. + */ @Override public void destroy() { - log.info("statistics:\n" + servletStatisticsService.toCsv()); + if (log.isInfoEnabled()) { + log.info("statistics:\n" + servletStatisticsService.toCsv()); + } try { MBeanServer server = ManagementFactory.getPlatformMBeanServer(); Modified: trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/RequestStatistics.java =================================================================== --- trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/RequestStatistics.java 2011-12-12 15:27:31 UTC (rev 158) +++ trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/RequestStatistics.java 2011-12-12 16:48:26 UTC (rev 159) @@ -26,6 +26,10 @@ import java.io.Serializable; +/** + * This pojo gather statistics for a given (not stored) request. + * + */ public class RequestStatistics implements Serializable { protected int count; @@ -36,29 +40,53 @@ protected long highestElapsed; + /** The number of time this Url was killed. + * @return the total number of times this url was called + */ public int getCount() { return count; } + /** The total time passed to process all the request. + * @return a duration in milli-seconds. + */ public long getElapsedSum() { return elapsedSum; } + /** The shortest time observed (duration of the fastest request) + * @return a duration in milli-seconds. + */ public long getLowestElapsed() { return lowestElapsed; } + /** The longest time observed (duration of the lowest request) + * @return a duration in milli-seconds. + */ public long getHighestElapsed() { return highestElapsed; } + /** The average time observed + * @return a duration in milli-seconds. + */ public long getAverageElapsed() { - return elapsedSum / count; + return getElapsedSum() / getCount(); } + /** Each time a request is processed, this method should be called. It will + * record the statistics for this request. + * + * @param start the time (in ms), when the request was queried by the user + * @param stop the time (in ms), the request processing ended + */ public void count(long start, long stop) { + long elapsed = stop - start; + if (elapsed < 0) { + throw new IllegalStateException("a request can't be processed in less than 0 ms"); + } count += 1; - long elapsed = stop - start; elapsedSum += elapsed; if (elapsed < lowestElapsed) { lowestElapsed = elapsed; Modified: trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/ServletStatisticsService.java =================================================================== --- trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/ServletStatisticsService.java 2011-12-12 15:27:31 UTC (rev 158) +++ trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/ServletStatisticsService.java 2011-12-12 16:48:26 UTC (rev 159) @@ -32,8 +32,10 @@ import java.util.Map; /** Implementation of {@link ServletStatisticsServiceMBean}. - * - * + * + * For each request, it has a {@link RequestStatistics} instance and provide + * an pre-filter and post-filter facade suitable for use in + * {@link org.nuiton.web.filter.MonitoringFilter}. */ public class ServletStatisticsService implements ServletStatisticsServiceMBean { @@ -76,10 +78,19 @@ requestStartTime.remove(servletRequest); } + /** Implementation of the MBean contract. + * + * @see ServletStatisticsServiceMBean#getPerRequestStatistics() + */ + @Override public Map<String, RequestStatistics> getPerRequestStatistics() { return perRequestStatistics; } + /** Implementation of the MBean contract. + * + * @see ServletStatisticsServiceMBean#toCsv() + */ @Override public String toCsv() { StringBuilder csv = new StringBuilder(); @@ -97,6 +108,10 @@ return csv.toString(); } + /** Implementation of the MBean contract. + * + * @see ServletStatisticsServiceMBean#reset() + */ @Override public void reset() { perRequestStatistics.clear(); Modified: trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/ServletStatisticsServiceMBean.java =================================================================== --- trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/ServletStatisticsServiceMBean.java 2011-12-12 15:27:31 UTC (rev 158) +++ trunk/nuiton-web/src/main/java/org/nuiton/web/jmx/ServletStatisticsServiceMBean.java 2011-12-12 16:48:26 UTC (rev 159) @@ -26,11 +26,33 @@ import java.util.Map; +/** Contract exposed to JMX exposing statistics gathered while the application + * was used. + * + * It follows the convention imposed by JMX spec, objects used as parameters + * or returned as value are {@link java.io.Serializable}. Contract name ends + * with "MBean" while implementation not. + */ public interface ServletStatisticsServiceMBean { + /** The statistics gathered while the application was in use. + * + * @return a map with as key, the request Url, as value the statistics + * gathered for this Url. + */ Map<String, RequestStatistics> getPerRequestStatistics(); + /** Reset statistics for all request. Statistics will acts like if the + * monitored application was never used (0 request processed). + */ void reset(); + /** Get the statistics under the form of a CSV file suitable for + * post-processing and use in a spreadsheet. + * + * @return the csv content. Seperator is ','. One line per entries returned + * by {@link #getPerRequestStatistics()}. One column per attribute of + * {@link RequestStatistics}. + */ String toCsv(); }