com.google.appengine.tools.admin

## Interface AppAdmin

-     public interface AppAdmin

  The application administration interface to App Engine. Use this API to update, configure, and otherwise manage an App Engine application. Use `AppAdminFactory` to retrieve an `AppAdmin` instance configured for a specific application.

  Synchronous versus Asynchronous requests: Some requests, such as `update(com.google.appengine.tools.admin.UpdateListener)`, occur asynchronously and must be monitored with a `listener`. Other requests, such as `updateIndexes()`, are made synchronously. In either case, work often continues to occur asynchronously on the remote server after the request has been completed.

  Error handling: Most configuration operations that communicate with App Engine's remote administration server use a network connection. In cases where unrecoverable failures occur (such as a network failure), this API throws an `AdminException`.

  Application updates occur transactionally. If a failure occurs during update, you must `rollback()` the incomplete transaction before beginning another.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `AppAdmin.LogSeverity` The severity levels for App Engine application logging.
    `static class` | `AppAdmin.UpdateOptions` Settable options for configuring the behavior of update operations.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `configureBackend(java.lang.String backendName)` Reconfigure the backend with the specified name.
    `java.util.List<CronEntry>` | `cronInfo()` Locally parses an application's configured cron entries and reports the upcoming several execution times.
    `java.lang.String` | `debugVersion()` Sends a synchronous request to turn on debugging for the specified vm version.
    `java.lang.String` | `debugVersionState()` Sends a synchronous request to get the status of a debug request for the specified version.
    `void` | `deleteBackend(java.lang.String backendName)` Delete the backend with the specified name.
    `java.lang.String` | `deleteVersion(java.lang.String appId, java.lang.String moduleId, java.lang.String versionId)` Sends a synchronous request to delete the specified version
    `com.google.appengine.tools.admin.ResourceLimits` | `getResourceLimits()` Gets the resource limits.
    `AppAdmin.UpdateOptions` | `getUpdateOptions()` Returns the `AppAdmin.UpdateOptions` for this `AppAdmin`.
    `java.util.List<BackendsXml.Entry>` | `listBackends()` Retrieve a list of registered backends with their associated state.
    `java.lang.String` | `listVersions()` Sends a synchronous request to retrieve the list of versions for each module.
    `void` | `migrateTraffic()` Sends a synchronous request to start a traffic migration.
    `java.io.Reader` | `requestLogs(int numDays, AppAdmin.LogSeverity severity, boolean includeAll)` Retrieves application logs from the remote administration server.
    `void` | `rollback()` Rolls back an "in-progress" transaction.
    `void` | `rollbackAllBackends()` Rolls back an "in-progress" transaction on all backends.
    `void` | `rollbackBackend(java.lang.String backend)` Rolls back an "in-progress" transaction on a backend.
    `void` | `setBackendState(java.lang.String backendName, BackendsXml.State newState)` Update the state of the backend with the specified name to `newState`.
    `void` | `setDefaultVersion()` Sends a synchronous request to update the application's default version.
    `void` | `stageApplicationWithDefaultResourceLimits(java.io.File stagingDir)` Stage an application directory with default resource limits
    `void` | `stageApplicationWithRemoteResourceLimits(java.io.File stagingDir)` Stage an application directory with remote resource limits
    `void` | `startModuleVersion()` Start the specified module version.
    `void` | `stopModuleVersion()` Stop the specified module version.
    `void` | `update(UpdateListener listener)` Uploads a new version of the application and updates its indexes.
    `void` | `updateAllBackends(UpdateListener listener)` Redeploy all backends.
    `void` | `updateBackend(java.lang.String backendName, UpdateListener listener)` Redeploy the backend with the specified name.
    `void` | `updateBackends(java.util.List<java.lang.String> backendNames, UpdateListener listener)` Redeploy the backends with the specified names.
    `void` | `updateCron()` Sends a synchronous request to update the application's cron jobs.
    `void` | `updateDispatch()` Sends a synchronous request to update the application's Dispatch configuration.
    `void` | `updateDos()` Sends a synchronous request to update the application's DoS configuration.
    `void` | `updateIndexes()` Sends a synchronous request to update the application's indexes.
    `void` | `updateQueues()` Sends a synchronous request to update the application's task queue definitions.
    `void` | `vacuumIndexes(com.google.appengine.tools.admin.ConfirmationCallback<com.google.appengine.tools.admin.IndexDeleter.DeleteIndexAction> callback, UpdateListener listener)` Performs the following three steps: Queries the remote administration server for existing indexes that are not included in the local index configuration file.

- - ### Method Detail

    - #### update

          void update(UpdateListener listener)

      Uploads a new version of the application and updates its indexes. The update may occur asynchronously, so an `UpdateListener` must be installed to track progress.
      Parameters:
        `listener` - The listener to be notified of updates. Must not be `null`.
      Throws:
        `AdminException` - if an error occurs.

    - #### rollback

          void rollback()

      Rolls back an "in-progress" transaction. This operation occurs synchronously.
      Throws:
        `AdminException` - if an error occurs.

    - #### rollbackBackend

          void rollbackBackend(java.lang.String backend)

      Rolls back an "in-progress" transaction on a backend. This operation occurs synchronously.
      Parameters:
        `backend` - to rollback, or null for default app
      Throws:
        `AdminException` - if an error occurs.

    - #### rollbackAllBackends

          void rollbackAllBackends()

      Rolls back an "in-progress" transaction on all backends. This operation occurs synchronously.
      Throws:
        `AdminException` - if an error occurs.

    - #### updateIndexes

          void updateIndexes()

      Sends a synchronous request to update the application's indexes. This work completes asynchronously on the server.
      Throws:
        `AdminException` - if an error occurs.

    - #### updateCron

          void updateCron()

      Sends a synchronous request to update the application's cron jobs. This work completes synchronously on the server.
      Throws:
        `AdminException` - if an error occurs.

    - #### updateQueues

          void updateQueues()

      Sends a synchronous request to update the application's task queue definitions. This work completes synchronously on the server.
      Throws:
        `AdminException` - if an error occurs.

    - #### updateDispatch

          void updateDispatch()

      Sends a synchronous request to update the application's Dispatch configuration.
      Throws:
        `AdminException` - if an error occurs.

    - #### updateDos

          void updateDos()

      Sends a synchronous request to update the application's DoS configuration. This work completes synchronously on the server.
      Throws:
        `AdminException` - if an error occurs.

    - #### cronInfo

          java.util.List<CronEntry> cronInfo()

      Locally parses an application's configured cron entries and reports the upcoming several execution times.
      Throws:
        `AdminException` - if an error occurs.

    - #### getResourceLimits

          com.google.appengine.tools.admin.ResourceLimits getResourceLimits()

      Gets the resource limits. The values returned are a combination of values reported by the adminconsole/appserver plus locally defined defaults for any missing values.
      Returns:
        The ResourceLimits object.
      Throws:
        `AdminException` - if an error occurs.

    - #### vacuumIndexes

          void vacuumIndexes(com.google.appengine.tools.admin.ConfirmationCallback<com.google.appengine.tools.admin.IndexDeleter.DeleteIndexAction> callback,
                             UpdateListener listener)

      Performs the following three steps:
      1. Queries the remote administration server for existing indexes that are not included in the local index configuration file. We will refer to these as orphaned indexes.
      2. If `callback` is not null, then the `confirmAction` method will be called once for each of the orphaned indexes to confirm that it really should be deleted.
      3. A request will be sent to the server to delete each of the confirmed indexes. This work completes asynchronously on the server.
      Parameters:
        `callback` - Used to confirm deletions. May be `null` in which case no confirmation will be done.
        `listener` - The listener to be notified of updates. Must not be `null`.
      Throws:
        `AdminException` - if an error occurs.

    - #### requestLogs

          java.io.Reader requestLogs(int numDays,
                                     AppAdmin.LogSeverity severity,
                                     boolean includeAll)

      Retrieves application logs from the remote administration server.
      Parameters:
        `numDays` - The number of days to retrieve logs for. The cut-off point is midnight UTC. Use 0 to get all available logs.
        `severity` - The severity of app-level log messages to get. If null, only request logs are returned.
        `includeAll` - Include everything we know about a request, including ms, cpu_ms and so on.
      Returns:
        a non-null `Reader` which can be used to stream the logs from the remote administration server. You should `close` the `Reader` when you're finished reading logs. It is ok to `close` the `Reader` before all logs have been read (streaming from the server is cancelled).
      Throws:
        `AdminException` - if an error occurs.

    - #### updateBackend

          void updateBackend(java.lang.String backendName,
                             UpdateListener listener)

      Redeploy the backend with the specified name.

    - #### updateBackends

          void updateBackends(java.util.List<java.lang.String> backendNames,
                              UpdateListener listener)

      Redeploy the backends with the specified names.

    - #### updateAllBackends

          void updateAllBackends(UpdateListener listener)

      Redeploy all backends.

    - #### listBackends

          java.util.List<BackendsXml.Entry> listBackends()

      Retrieve a list of registered backends with their associated state.

    - #### setBackendState

          void setBackendState(java.lang.String backendName,
                               BackendsXml.State newState)

      Update the state of the backend with the specified name to `newState`.

    - #### deleteBackend

          void deleteBackend(java.lang.String backendName)

      Delete the backend with the specified name.

    - #### configureBackend

          void configureBackend(java.lang.String backendName)

      Reconfigure the backend with the specified name.

    - #### startModuleVersion

          void startModuleVersion()

      Start the specified module version.

    - #### stopModuleVersion

          void stopModuleVersion()

      Stop the specified module version.

    - #### setDefaultVersion

          void setDefaultVersion()

      Sends a synchronous request to update the application's default version. This work completes synchronously on the server.
      Throws:
        `AdminException` - if an error occurs.

    - #### listVersions

          java.lang.String listVersions()

      Sends a synchronous request to retrieve the list of versions for each module.
      Returns:
        Returns the YAML server response as a String.
      Throws:
        `AdminException` - if an error occurs.

    - #### deleteVersion

          java.lang.String deleteVersion(java.lang.String appId,
                                         java.lang.String moduleId,
                                         java.lang.String versionId)

      Sends a synchronous request to delete the specified version
      Parameters:
        `appId` - The application to delete the version from.
        `moduleId` - The module to delete the version from.
        `versionId` - The version to delete.
      Returns:
        Returns the YAML server response as a String
      Throws:
        `AdminException` - if an error occurs.

    - #### debugVersion

          java.lang.String debugVersion()

      Sends a synchronous request to turn on debugging for the specified vm version.
      Returns:
        Returns the YAML server response as a String
      Throws:
        `AdminException` - if an error occurs.

    - #### debugVersionState

          java.lang.String debugVersionState()

      Sends a synchronous request to get the status of a debug request for the specified version.
      Returns:
        Returns the YAML server response as a String
      Throws:
        `AdminException` - if an error occurs.

    - #### migrateTraffic

          void migrateTraffic()

      Sends a synchronous request to start a traffic migration. This work continues asynchronously on the server.
      Throws:
        `AdminException` - if an error occurs.

    - #### stageApplicationWithDefaultResourceLimits

          void stageApplicationWithDefaultResourceLimits(java.io.File stagingDir)

      Stage an application directory with default resource limits

    - #### stageApplicationWithRemoteResourceLimits

          void stageApplicationWithRemoteResourceLimits(java.io.File stagingDir)

      Stage an application directory with remote resource limits

    - #### getUpdateOptions

          AppAdmin.UpdateOptions getUpdateOptions()

      Returns the `AppAdmin.UpdateOptions` for this `AppAdmin`.