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    }