java/src/main/com/google/appengine/tools/admin/AppAdmin.java

   1 // Copyright 2008 Google Inc. All rights reserved.
   2
   3 package com.google.appengine.tools.admin;
   4
   5 import com.google.apphosting.utils.config.BackendsXml;
   6 import com.google.common.base.Preconditions;
   7
   8 import java.io.Reader;
   9 import java.util.List;
  10
  11 /**
  12  * The application administration interface to App Engine. Use this
  13  * API to update, configure, and otherwise manage an App Engine
  14  * application. Use {@link AppAdminFactory} to retrieve an {@code AppAdmin}
  15  * instance configured for a specific application.
  16  * <p>
  17  * <b>Synchronous versus Asynchronous requests:</b>
  18  * Some requests, such as {@link #update}, occur asynchronously
  19  * and must be monitored with a {@code listener}. Other requests, such as
  20  * {@link #updateIndexes}, are made synchronously. In either case,
  21  * work often continues to occur asynchronously on the remote server after the
  22  * request has been completed.
  23  * <p>
  24  * <b>Error handling:</b> Most configuration operations require communicating
  25  * to App Engine's remote administration server occur over a
  26  * network connection. In cases where unrecoverable failures occur (such as a
  27  * network failure), this API throws an
  28  * {@link com.google.appengine.tools.admin.AdminException}.
  29  * <p>
  30  * Application updates occur transactionally. If a failure occurs during
  31  * update, you must {@link #rollback} the incomplete transaction before
  32  * beginning another.
  33  *
  34  */
  35 public interface AppAdmin {
  36
  37   /**
  38    * Uploads a new version of the application and updates its indexes.
  39    * The update may occur asynchronously, so an {@link UpdateListener}
  40    * must be installed to track progress.
  41    *
  42    * @param listener The listener to be notified of updates. Must not be
  43    * {@code null}.
  44    *
  45    * @throws AdminException if an error occurs.
  46    */
  47   void update(UpdateListener listener);
  48
  49   /**
  50    * Rolls back an "in-progress" transaction. This operation occurs
  51    * synchronously.
  52    *
  53    * @throws AdminException if an error occurs.
  54    */
  55   void rollback();
  56
  57   /**
  58    * Rolls back an "in-progress" transaction on a backend. This operation occurs
  59    * synchronously.
  60    *
  61    * @param backend to rollback, or null for default app
  62    *
  63    * @throws AdminException if an error occurs.
  64    */
  65   void rollbackBackend(String backend);
  66
  67   /**
  68    * Rolls back an "in-progress" transaction on all backends. This operation occurs
  69    * synchronously.
  70    *
  71    * @throws AdminException if an error occurs.
  72    */
  73   void rollbackAllBackends();
  74
  75   /**
  76    * Sends a synchronous request to update the application's indexes. This work
  77    * completes asynchronously on the server.
  78    *
  79    * @throws AdminException if an error occurs.
  80    */
  81   void updateIndexes();
  82
  83   /**
  84    * Sends a synchronous request to update the application's cron jobs. This
  85    * work completes synchronously on the server.
  86    *
  87    * @throws AdminException if an error occurs.
  88    */
  89   void updateCron();
  90
  91   /**
  92    * Sends a synchronous request to update the application's task queue
  93    * definitions. This work completes synchronously on the server.
  94    *
  95    * @throws AdminException if an error occurs.
  96    */
  97   void updateQueues();
  98
  99   /**
 100    * Sends a synchronous request to update the application's Dispatch configuration.
 101    *
 102    * @throws AdminException if an error occurs.
 103    */
 104   void updateDispatch();
 105
 106   /**
 107    * Sends a synchronous request to update the application's DoS configuration.
 108    * This work completes synchronously on the server.
 109    *
 110    * @throws AdminException if an error occurs.
 111    */
 112   void updateDos();
 113
 114   /**
 115    * Locally parses an application's configured cron entries and reports the
 116    * upcoming several execution times.
 117    *
 118    * @throws AdminException if an error occurs.
 119    */
 120   List<CronEntry> cronInfo();
 121
 122   /**
 123    * Gets the resource limits. The values returned are a combination of
 124    * values reported by the adminconsole/appserver plus locally defined
 125    * defaults for any missing values.
 126    *
 127    * @return The ResourceLimits object.
 128    *
 129    * @throws AdminException if an error occurs.
 130    */
 131   ResourceLimits getResourceLimits();
 132
 133   /**
 134    * Performs the following three steps:
 135    * <ol>
 136    * <li>Queries the remote administration server for existing indexes
 137    * that are not included in the local index configuration file. We will
 138    * refer to these as <b>orphaned</b> indexes.
 139    * <li>If {@code callback} is not null, then the {@link
 140    * ConfirmationCallback#confirmAction(ConfirmationCallback.Action)
 141    * confirmAction} method will be called once for each of the orphaned indexes
 142    * to confirm that it really should be deleted.
 143    * <li>A request will be sent to the server to delete each of the confirmed
 144    * indexes. This work completes asynchronously on the server.
 145    *</ol>
 146    *
 147    * @param callback Used to confirm deletions. May be {@code null} in which case no
 148    * confirmation will be done.
 149    *
 150    * @param listener The listener to be notified of updates. Must not be
 151    * {@code null}.
 152    *
 153    * @throws AdminException if an error occurs.
 154    */
 155   void vacuumIndexes(
 156       ConfirmationCallback<IndexDeleter.DeleteIndexAction> callback, UpdateListener listener);
 157
 158   /**
 159    * Retrieves application logs from the remote administration server.
 160    *
 161    * @param numDays The number of days to retrieve logs for. The cut-off
 162    * point is midnight UTC. Use 0 to get all available logs.
 163    *
 164    * @param severity The severity of app-level log messages to get. If null,
 165    * only request logs are returned.
 166    *
 167    * @param includeAll Include everything we know about a request, including
 168    * ms, cpu_ms and so on.
 169    *
 170    * @return a non-null {@code Reader} which can be used to stream the logs
 171    * from the remote administration server. You should
 172    * {@link Reader#close close} the {@code Reader} when you're finished reading
 173    * logs. It is ok to {@code close} the {@code Reader} before all logs have
 174    * been read (streaming from the server is cancelled).
 175    *
 176    * @throws AdminException if an error occurs.
 177    */
 178   Reader requestLogs(int numDays, LogSeverity severity, boolean includeAll);
 179
 180   /**
 181    * Redeploy the backend with the specified name.
 182    */
 183   void updateBackend(String backendName, UpdateListener listener);
 184
 185   /**
 186    * Redeploy the backends with the specified names.
 187    */
 188   void updateBackends(List<String> backendNames, UpdateListener listener);
 189
 190   /**
 191    * Redeploy all backends.
 192    */
 193   void updateAllBackends(UpdateListener listener);
 194
 195   /**
 196    * Retrieve a list of registered backends with their associated state.
 197    */
 198   List<BackendsXml.Entry> listBackends();
 199
 200   /**
 201    * Update the state of the backend with the specified name to {@code newState}.
 202    */
 203   void setBackendState(String backendName, BackendsXml.State newState);
 204
 205   /**
 206    * Delete the backend with the specified name.
 207    */
 208   void deleteBackend(String backendName);
 209
 210   /**
 211    * Reconfigure the backend with the specified name.
 212    */
 213   void configureBackend(String backendName);
 214
 215   /**
 216    * Start the specified module version.
 217    */
 218   void startModuleVersion();
 219
 220   /**
 221    * Stop the specified module version.
 222    */
 223   void stopModuleVersion();
 224
 225   /**
 226    * The severity levels for App Engine application logging.
 227    */
 228   enum LogSeverity {
 229     DEBUG,
 230     INFO,
 231     WARN,
 232     ERROR,
 233     CRITICAL,
 234   }
 235
 236   /**
 237    * Sends a synchronous request to update the application's default version.
 238    * This work completes synchronously on the server.
 239    *
 240    * @throws AdminException if an error occurs.
 241    */
 242   void setDefaultVersion();
 243
 244   /**
 245    * Sends a synchronous request to retrieve the list of versions for each module.
 246    *
 247    * @return Returns the YAML server response as a String.
 248    *
 249    * @throws AdminException if an error occurs.
 250    */
 251   String listVersions();
 252
 253   /**
 254    * Sends a synchronous request to delete the specified version
 255    *
 256    * @param appId The application to delete the version from.
 257    *
 258    * @param moduleId The module to delete the version from.
 259    *
 260    * @param versionId The version to delete.
 261    *
 262    * @return Returns the YAML server response as a String
 263    *
 264    * @throws AdminException if an error occurs.
 265    */
 266   String deleteVersion(String appId, String moduleId, String versionId);
 267
 268   /**
 269    * Sends a synchronous request to turn on debugging for the specified vm version.
 270    *
 271    * @return Returns the YAML server response as a String
 272    *
 273    * @throws AdminException if an error occurs.
 274    */
 275   String debugVersion();
 276
 277   /**
 278    * Sends a synchronous request to get the status of a debug request for the specified version.
 279    *
 280    * @return Returns the YAML server response as a String
 281    *
 282    * @throws AdminException if an error occurs.
 283    */
 284   String debugVersionState();
 285
 286   /**
 287    * Sends a synchronous request to start a traffic migration. This work continues asynchronously on
 288    * the server.
 289    *
 290    * @throws AdminException if an error occurs.
 291    */
 292   void migrateTraffic();
 293
 294   /**
 295    * Returns the {@link UpdateOptions} for this {@link AppAdmin}.
 296    */
 297   UpdateOptions getUpdateOptions();
 298
 299   /**
 300    * Settable options for configuring the behavior of update operations.
 301    */
 302   public static class UpdateOptions {
 303     /**
 304      * SDK version for logging in cases the SDK version is unavailable.
 305      */
 306     static final String UNKNOWN_SDK_VERSION = "Java/unknown";
 307
 308     private boolean updateGlobalConfigurations = true;
 309     private String sdkVersion = UNKNOWN_SDK_VERSION;
 310     private boolean updateUsageReporting = true;
 311
 312     /**
 313      * When set to true {@link AppAdmin#update}, {@link AppAdmin#updateBackend}
 314      * and {@link AppAdmin#updateAllBackends} automatically include
 315      * updates to global application settings. This is the default behavior and
 316      * preserves compatibility for these operations.
 317      * <p>
 318      * The updated settings include indexes, cron, queues, dos and pagespeed.
 319      * <p>
 320      * When called with false these these global application settings
 321      * are not updated. The false setting is appropriate when uploading
 322      * all but the first WAR in an EAR.
 323      */
 324     void setUpdateGlobalConfigurations(boolean updateGlobalConfigurations) {
 325       this.updateGlobalConfigurations = updateGlobalConfigurations;
 326     }
 327
 328     /**
 329      * Returns true if global application configuration values that have
 330      * historically been automatically updated should be updated by
 331      * version updates.
 332      * <p>
 333      * For details see {@link #setUpdateGlobalConfigurations(boolean)}.
 334      */
 335     boolean getUpdateGlobalConfigurations() {
 336       return updateGlobalConfigurations;
 337     }
 338
 339     /**
 340      * Set the SDK version.
 341      * <p>
 342      * This is currently used for logging purposes.
 343      *
 344      * @param sdkVersion
 345      */
 346     void setSdkVersion(String sdkVersion) {
 347       this.sdkVersion = Preconditions.checkNotNull(sdkVersion);
 348     }
 349
 350     /**
 351      * Returns the SDK version if it has been set and a string
 352      * indicating an unknown version if it has not been set.
 353      */
 354     String getSdkVersion() {
 355       return sdkVersion;
 356     }
 357
 358     /**
 359      * Enables or disables usage reporting (aka client deploy logging).
 360      */
 361     void setUpdateUsageReporting(boolean updateUsageReporting) {
 362       this.updateUsageReporting = updateUsageReporting;
 363     }
 364
 365     /**
 366      * Returns true iff usage reporting (aka client deploy logging) is enabled.
 367      */
 368     boolean getUpdateUsageReporting() {
 369       return updateUsageReporting;
 370     }
 371   }
 372 }