java/src/main/com/google/appengine/api/quota/QuotaService.java

   1 // Copyright 2009 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.quota;
   4
   5 /**
   6  * The {@code QuotaService} provides measurement of API and CPU usage
   7  * during requests.
   8  *
   9  */
  10 public interface QuotaService {
  11
  12   /**
  13    * Represents all types of data that a QuotaService might be able to provide.
  14    */
  15   enum DataType {
  16     API_TIME_IN_MEGACYCLES,
  17     CPU_TIME_IN_MEGACYCLES;
  18   }
  19
  20   /**
  21    * Tests if the QuotaService can provide a certain kind of data at this
  22    * point in time. Depending on the underlying app server implementation and
  23    * what state it is in, a QuotaService might not always have access to all
  24    * categories of data. For example, the dev-appserver might not be able to
  25    * measure the megacycles of api calls. Trying to access that data would lead
  26    * to an IllegalStateException, which would then need to be handled. To make
  27    * it easier to prevent this, it is possible to ask the service if a
  28    * particular kind of data is supported.
  29    *
  30    * @param type the type of data in question.
  31    * @return true if the QuotaService can provide such data at this time.
  32    * @exception NullPointerException if a null argument is passed into
  33    *   the method.
  34    */
  35   boolean supports(DataType type);
  36
  37   /**
  38    * @deprecated This value is no longer meaningful.
  39    * @return the overall amount spent in API cycles, as returned by the system.
  40    *   Returns 0 if the feature is not supported.
  41    */
  42   @Deprecated
  43   long getApiTimeInMegaCycles();
  44
  45   /**
  46    * Measures the duration that the current request has spent so far processing
  47    * the request within the App Engine sandbox. Note that time spent in API
  48    * calls will not be added to this value.
  49    * <p>
  50    * The unit the duration is measured is Megacycles. If all instructions
  51    * were to be executed sequentially on a standard 1.2 GHz 64-bit x86 CPU,
  52    * 1200 megacycles would equate to one second physical time elapsed.
  53    *
  54    * @return the overall amount spent in CPU cycles, as returned by the system.
  55    *   Returns 0 if the feature is not supported.
  56    */
  57   long getCpuTimeInMegaCycles();
  58
  59   /**
  60    * Expresses a value in megaCycles as its approximate equivalent of CPU
  61    * seconds on a theoretical 1.2 GHz CPU.
  62    *
  63    * @param megaCycles the value, in megacycles, to convert.
  64    * @return a double representing the CPU-seconds the input megacycle value
  65    *    converts to.
  66    */
  67   double convertMegacyclesToCpuSeconds(long megaCycles);
  68
  69   /**
  70    * Expresses a value in megaCycles as its approximate equivalent of CPU
  71    * seconds on a theoretical 1.2 GHz CPU.
  72    *
  73    * @param cpuSeconds the value, in cpu seconds, to convert.
  74    * @return a long representing the megacycles the input CPU-seconds value
  75    *    converts to.
  76    */
  77   long convertCpuSecondsToMegacycles(double cpuSeconds);
  78
  79 }