001    package org.hackystat.telemetry.analyzer.reducer;
002    
003    import org.hackystat.telemetry.analyzer.model.TelemetryStreamCollection;
004    import org.hackystat.dailyprojectdata.client.DailyProjectDataClient;
005    import org.hackystat.sensorbase.resource.projects.jaxb.Project;
006    import org.hackystat.utilities.time.interval.Interval;
007    
008    /**
009     * Provides the Telemetry reducer interface. A reducer is responsible for processing raw software
010     * metrics to generate an instance of <code>TelemetryStreamCollection</code>. 
011     * <p>
012     * Note to reducer implementers: 
013     * <ul>
014     *   <li> The "time periods" for the data points in the generated telemetry stream(s) 
015     *        must be derived from the 'interval' parameter.  
016     *   <li> Reducer implementation class must have a public constructor which takes no parameters.
017     *   <li> Reducer implementation must be thread-safe.
018     * </ul>
019     * 
020     * @author Qin ZHANG
021     */
022    public interface TelemetryReducer {
023    
024      /**
025       * Computes telemetry streams. Note that if there is no data for any particular time period, 
026       * null should be used as the value for that time period.
027       * 
028       * @param project The project which defines the scope of metrics to be used in the computation.
029       * @param dpdClient The DPD Client.
030       * @param interval The time interval.
031       * @param parameters Parameters passed to reducer implementation. In case a reducer does not
032       *        need any parameters, either null or an empty array may be passed.
033       * @throws TelemetryReducerException If there is any error during metrics computation.
034       * @return The resulting telemetry stream collection.
035       */
036      TelemetryStreamCollection compute(Project project, DailyProjectDataClient dpdClient, 
037          Interval interval, String[] parameters) throws TelemetryReducerException;
038    }