001 /* 002 * Copyright 2008-2009 the original author or authors. 003 * The contents of this file are subject to the Mozilla Public License 004 * Version 1.1 (the "License"); you may not use this file except in 005 * compliance with the License. You may obtain a copy of the License at 006 * http://www.mozilla.org/MPL/ 007 * 008 * Software distributed under the License is distributed on an "AS IS" 009 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the 010 * License for the specific language governing rights and limitations 011 * under the License. 012 */ 013 014 package com.mtgi.analytics; 015 016 /** 017 * Top-level application interface for logging behavior tracking 018 * events to the BehaviorTracking database. 019 * 020 * Most applications should <i>never</i> have to call a method on this 021 * interface or {@link BehaviorEvent} directly. Rather, behavior tracking 022 * should be managed automatically as an Aspect or using a servlet filter. 023 * 024 * The lifecyle of a behavior tracking event has four steps: 025 * <ol> 026 * <li>An event is created using {@link #createEvent(String, String)}</li> 027 * <li>The event is populated with event metadata, like parameter values, using the {@link BehaviorEvent} API methods</li> 028 * <li>The event begins measuring execution time with a call to {@link #start(BehaviorEvent)}</li> 029 * <li>The execution time measurement is stopped with a call to {@link #stop(BehaviorEvent)}, and the finished event is written to the behavior tracking database.</li> 030 * </ol>. 031 * 032 * @see SessionContext 033 */ 034 public interface BehaviorTrackingManager { 035 036 /** 037 * Create a new event of the given type and name. If another event 038 * is still pending on the current thread, the pending event 039 * will become the {@link BehaviorEvent#getParent() parent} of the newly created event. 040 * The returned event will also reflect the user Id and session Id associated 041 * with the current thread, if any. 042 * 043 * The returned event does <i>not</i> 044 * become active until {@link #start(BehaviorEvent)} is called, which 045 * should be done after all event metadata has been gathered. 046 * 047 * @see SessionContext 048 * @see #start(BehaviorEvent) 049 */ 050 public BehaviorEvent createEvent(String type, String name); 051 052 /** 053 * Set the given event as the currently executing event for this thread, 054 * and start measuring event time. 055 * @throws IllegalStateException if this event has already been started or stopped. 056 */ 057 public void start(BehaviorEvent event); 058 059 /** 060 * Stop measuring execution time for the given event, and set the current 061 * event for this thread to be the parent of the given event, if any. 062 * The event data will subsequently be logged to the behavior tracking database. 063 * @throws IllegalStateException if this event has not been started, has already been stopped, or is not the currently executing event on the calling thread. 064 */ 065 public void stop(BehaviorEvent event); 066 067 }