java/src/main/com/google/apphosting/api/ApiStats.java

   1 // Copyright 2009 Google Inc. All Rights Reserved.
   2
   3 package com.google.apphosting.api;
   4
   5 /**
   6  * Represents automatic statistics collected by the ApiProxy. If present, this
   7  * object will be stored under the KEY-variable in an Environment's property.
   8  * This object is basically a pojo, a simple container for collected values.
   9  *
  10  */
  11 public abstract class ApiStats {
  12
  13   /**
  14    * The name that this object is stored in.
  15    */
  16   private static final String KEY = ApiStats.class.getName();
  17
  18   /**
  19    * For a given environment, return the corresponding ApiStats object. If the
  20    * environment does not have an ApiStats object, null will be returned.
  21    */
  22   public static ApiStats get(ApiProxy.Environment env) {
  23     return (ApiStats) env.getAttributes().get(KEY);
  24   }
  25
  26   /**
  27    * @return the overall time spent in API cycles, as returned by the system.
  28    *     Unit is megacycles.
  29    */
  30   public abstract long getApiTimeInMegaCycles();
  31
  32   /**
  33    * @return the overall time spent in CPU processing. Unit is megacycles.
  34    */
  35   public abstract long getCpuTimeInMegaCycles();
  36
  37   /**
  38    * Creates a new ApiStats object and binds it to a given Environment.
  39    * @param env the Environment object to bind this object to.
  40    * @exception IllegalStateException if an object is already bound
  41    */
  42   protected ApiStats(ApiProxy.Environment env){
  43     bind(env);
  44   }
  45
  46   /**
  47    * Binds this object to a particular environment. This step enables the
  48    * stats object to access and make available request-specific statistics that
  49    * would usually not be accessible.
  50    * @param env the Environment object to bind this object to.
  51    * @exception IllegalStateException if an object is already bound
  52    */
  53   private void bind(ApiProxy.Environment env) {
  54     ApiStats original = get(env);
  55     if (original != null) {
  56
  57       if (original != this) {
  58         throw new IllegalStateException(
  59             "Cannot replace existing ApiStats object");
  60       } else {
  61
  62       }
  63     } else {
  64       env.getAttributes().put(KEY, this);
  65     }
  66   }
  67
  68 }