1 // Copyright 2008 Google Inc. All rights reserved.
3 package com
.google
.appengine
.tools
.admin
;
5 import com
.google
.apphosting
.utils
.config
.BackendsXml
;
6 import com
.google
.common
.base
.Preconditions
;
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.
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.
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}.
30 * Application updates occur transactionally. If a failure occurs during
31 * update, you must {@link #rollback} the incomplete transaction before
35 public interface AppAdmin
{
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.
42 * @param listener The listener to be notified of updates. Must not be
45 * @throws AdminException if an error occurs.
47 void update(UpdateListener listener
);
50 * Rolls back an "in-progress" transaction. This operation occurs
53 * @throws AdminException if an error occurs.
58 * Rolls back an "in-progress" transaction on a backend. This operation occurs
61 * @param backend to rollback, or null for default app
63 * @throws AdminException if an error occurs.
65 void rollbackBackend(String backend
);
68 * Rolls back an "in-progress" transaction on all backends. This operation occurs
71 * @throws AdminException if an error occurs.
73 void rollbackAllBackends();
76 * Sends a synchronous request to update the application's indexes. This work
77 * completes asynchronously on the server.
79 * @throws AdminException if an error occurs.
84 * Sends a synchronous request to update the application's cron jobs. This
85 * work completes synchronously on the server.
87 * @throws AdminException if an error occurs.
92 * Sends a synchronous request to update the application's task queue
93 * definitions. This work completes synchronously on the server.
95 * @throws AdminException if an error occurs.
100 * Sends a synchronous request to update the application's Dispatch configuration.
102 * @throws AdminException if an error occurs.
104 void updateDispatch();
107 * Sends a synchronous request to update the application's DoS configuration.
108 * This work completes synchronously on the server.
110 * @throws AdminException if an error occurs.
115 * Locally parses an application's configured cron entries and reports the
116 * upcoming several execution times.
118 * @throws AdminException if an error occurs.
120 List
<CronEntry
> cronInfo();
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.
127 * @return The ResourceLimits object.
129 * @throws AdminException if an error occurs.
131 ResourceLimits
getResourceLimits();
134 * Performs the following three steps:
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.
147 * @param callback Used to confirm deletions. May be {@code null} in which case no
148 * confirmation will be done.
150 * @param listener The listener to be notified of updates. Must not be
153 * @throws AdminException if an error occurs.
156 ConfirmationCallback
<IndexDeleter
.DeleteIndexAction
> callback
, UpdateListener listener
);
159 * Retrieves application logs from the remote administration server.
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.
164 * @param severity The severity of app-level log messages to get. If null,
165 * only request logs are returned.
167 * @param includeAll Include everything we know about a request, including
168 * ms, cpu_ms and so on.
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).
176 * @throws AdminException if an error occurs.
178 Reader
requestLogs(int numDays
, LogSeverity severity
, boolean includeAll
);
181 * Redeploy the backend with the specified name.
183 void updateBackend(String backendName
, UpdateListener listener
);
186 * Redeploy the backends with the specified names.
188 void updateBackends(List
<String
> backendNames
, UpdateListener listener
);
191 * Redeploy all backends.
193 void updateAllBackends(UpdateListener listener
);
196 * Retrieve a list of registered backends with their associated state.
198 List
<BackendsXml
.Entry
> listBackends();
201 * Update the state of the backend with the specified name to {@code newState}.
203 void setBackendState(String backendName
, BackendsXml
.State newState
);
206 * Delete the backend with the specified name.
208 void deleteBackend(String backendName
);
211 * Reconfigure the backend with the specified name.
213 void configureBackend(String backendName
);
216 * Start the specified module version.
218 void startModuleVersion();
221 * Stop the specified module version.
223 void stopModuleVersion();
226 * The severity levels for App Engine application logging.
237 * Sends a synchronous request to update the application's default version.
238 * This work completes synchronously on the server.
240 * @throws AdminException if an error occurs.
242 void setDefaultVersion();
245 * Sends a synchronous request to retrieve the list of versions for each module.
247 * @return Returns the YAML server response as a String.
249 * @throws AdminException if an error occurs.
251 String
listVersions();
254 * Sends a synchronous request to delete the specified version
256 * @param appId The application to delete the version from.
258 * @param moduleId The module to delete the version from.
260 * @param versionId The version to delete.
262 * @return Returns the YAML server response as a String
264 * @throws AdminException if an error occurs.
266 String
deleteVersion(String appId
, String moduleId
, String versionId
);
269 * Sends a synchronous request to turn on debugging for the specified vm version.
271 * @return Returns the YAML server response as a String
273 * @throws AdminException if an error occurs.
275 String
debugVersion();
278 * Sends a synchronous request to get the status of a debug request for the specified version.
280 * @return Returns the YAML server response as a String
282 * @throws AdminException if an error occurs.
284 String
debugVersionState();
287 * Sends a synchronous request to start a traffic migration. This work continues asynchronously on
290 * @throws AdminException if an error occurs.
292 void migrateTraffic();
295 * Returns the {@link UpdateOptions} for this {@link AppAdmin}.
297 UpdateOptions
getUpdateOptions();
300 * Settable options for configuring the behavior of update operations.
302 public static class UpdateOptions
{
304 * SDK version for logging in cases the SDK version is unavailable.
306 static final String UNKNOWN_SDK_VERSION
= "Java/unknown";
308 private boolean updateGlobalConfigurations
= true;
309 private String sdkVersion
= UNKNOWN_SDK_VERSION
;
310 private boolean updateUsageReporting
= true;
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.
318 * The updated settings include indexes, cron, queues, dos and pagespeed.
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.
324 void setUpdateGlobalConfigurations(boolean updateGlobalConfigurations
) {
325 this.updateGlobalConfigurations
= updateGlobalConfigurations
;
329 * Returns true if global application configuration values that have
330 * historically been automatically updated should be updated by
333 * For details see {@link #setUpdateGlobalConfigurations(boolean)}.
335 boolean getUpdateGlobalConfigurations() {
336 return updateGlobalConfigurations
;
340 * Set the SDK version.
342 * This is currently used for logging purposes.
346 void setSdkVersion(String sdkVersion
) {
347 this.sdkVersion
= Preconditions
.checkNotNull(sdkVersion
);
351 * Returns the SDK version if it has been set and a string
352 * indicating an unknown version if it has not been set.
354 String
getSdkVersion() {
359 * Enables or disables usage reporting (aka client deploy logging).
361 void setUpdateUsageReporting(boolean updateUsageReporting
) {
362 this.updateUsageReporting
= updateUsageReporting
;
366 * Returns true iff usage reporting (aka client deploy logging) is enabled.
368 boolean getUpdateUsageReporting() {
369 return updateUsageReporting
;