001    package org.hackystat.telemetry.analyzer.function;
002    
003    /**
004     * Provides an abstract base class for telemetry functions. 
005     * A telemetry function operates on an array of
006     * <code>Number</code> and/or <code>TelemetryStreamCollection</code> objects, and 
007     * returns either a <code>Number</code> or a <code>TelemetryStreamCollection</code> object.
008     * <p/>
009     * There will be exactly one instance of each implementation. Therefore, all implementation
010     * should be thread-safe.
011     * 
012     * @author (Cedric) Qin ZHANG
013     */
014    public abstract class TelemetryFunction {
015    
016      /** The name of this function. */
017      private String name;
018      
019      /**
020       * Constructs this instance.
021       * 
022       * @param name The assigned name of this function.
023       */
024      protected TelemetryFunction(String name) {
025        this.name = name;    
026      }
027      
028      /**
029       * The name of this function.
030       * 
031       * @return The name.
032       */
033      public String getName() {
034        return this.name;
035      }
036      
037      /**
038       * Invokes the function. Note that multiple thread might call this method at the same time.
039       * The implementation must be thread-safe.
040       * 
041       * @param parameters An array of objects of type either <code>String</code>,
042       *        <code>Number</code>, and/or <code>TelemetryStreamCollection</code>. 
043       *        <b>Note: Since telemetry chart analyses might pass in parameter values as Strings,
044       *        the implementation should be prepared to handle Strings even if it is expecting
045       *        a number instance.</b>
046       * 
047       * @return Either an instance of <code>Number</code> or <code>TelemetryStreamCollection</code>.
048       *          
049       * @throws TelemetryFunctionException If anything is wrong.
050       */
051      public abstract Object compute(Object[] parameters) throws TelemetryFunctionException;
052    }