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