1 // Copyright 2008 Google Inc. All Rights Reserved.
3 package com
.google
.appengine
.tools
.admin
;
5 import com
.google
.appengine
.tools
.info
.SdkInfo
;
6 import com
.google
.appengine
.tools
.util
.ClientCookieManager
;
9 import java
.io
.PrintWriter
;
10 import java
.nio
.charset
.Charset
;
11 import java
.util
.Collections
;
15 * Creates a new {@link AppAdmin} for a designated App Engine application.
18 public class AppAdminFactory
{
20 private static final String JAVA_CMD_PROP
= "appengine.java";
21 private static final String JAVAC_CMD_PROP
= "appengine.javac";
23 private ApplicationProcessingOptions appOptions
= new ApplicationProcessingOptions();
25 private Class
<?
extends AppVersionUpload
> appVersionUploadClass
= AppVersionUpload
.class;
28 * Creates a new {@link AppAdmin} that can be used to administer the
29 * designated App Engine application.
31 * @param options The options used to connect to the remote server. Must not
33 * @param app The application to be administered. May be {@code null}.
34 * @param errorWriter A writer to which error logs can be written. The logs
35 * can be used for diagnosis if a failure occurs during operation. May
37 * @return a not {@code null} AppAdmin
39 public AppAdmin
createAppAdmin(ConnectOptions options
, Application app
, PrintWriter errorWriter
) {
40 return new AppAdminImpl(options
, app
, errorWriter
, appOptions
, appVersionUploadClass
);
44 * Creates a new {@link AppAdmin} that can be used to administer the
45 * designated App Engine application.
47 * @param options The options used to connect to the remote server. Must not
49 * @param app The application to be administered. May be {@code null}.
50 * @param errorWriter A writer to which error logs can be written. The logs
51 * can be used for diagnosis if a failure occurs during operation. May
53 * @return a not {@code null} AppAdmin
55 public AppAdmin
createAppAdmin(ConnectOptions options
, GenericApplication app
,
56 PrintWriter errorWriter
) {
57 return new AppAdminImpl(options
, app
, errorWriter
, appOptions
, appVersionUploadClass
);
60 public ApplicationProcessingOptions
getAppOptions() {
64 public Class
<?
extends AppVersionUpload
> getAppVersionUploadClass() {
65 return appVersionUploadClass
;
69 * Sets the class used for uploading the application to the server. Should
70 * only be used for advanced customization of the upload process.
72 public void setAppVersionUploadClass(Class
<?
extends AppVersionUpload
> klass
) {
73 appVersionUploadClass
= klass
;
77 * Callback that is invoked to prompt the user to enter a password.
79 public interface PasswordPrompt
{
84 * The options used to connect to the remote App Engine administration server.
87 public static class ConnectOptions
{
90 * Retrieves the user's email address used to authenticate to the server.
92 * @return user identity
94 public String
getUserId() {
99 * The user id for the App Engine account. This should be the same e-mail
100 * address used to register the account owning the App Engine application.
102 * @param userId the not {@code null} e-mail address
104 public void setUserId(String userId
) {
105 this.userId
= userId
;
109 * Retrieves the prompter used to get the user's password.
111 * @return the {@link PasswordPrompt} to be used
113 public PasswordPrompt
getPasswordPrompt() {
114 return passwordPrompt
;
118 * The password prompt to get the user's password.
120 * @param prompt the {@link PasswordPrompt} that's being used
122 public void setPasswordPrompt(PasswordPrompt prompt
) {
123 this.passwordPrompt
= prompt
;
126 /** Returns the server address to connect to. */
127 public String
getServer() {
132 * The remote administration server to connect to. This is an advanced
133 * option that should rarely be set by users.
135 * @param server May be set to {@code null} to use the default server.
137 public void setServer(String server
) {
138 this.server
= server
;
142 * Returns the value used for the Host header sent to the server with RPCs.
144 * @return hostname to insert into request headers
146 public String
getHost() {
151 * The host name to supply to the remote server. This is an advanced option
152 * that should rarely be set by users.
154 * @param host May be set to {@code null} to use the default host name.
156 public void setHost(String host
) {
161 * Controls whether we clean up our temporary files, or leave it for
164 public void setRetainUploadDir(boolean flag
) {
165 this.keepUpload
= flag
;
168 /** Returns {@code true} if the upload directory should not be deleted. */
169 public boolean getRetainUploadDir() {
173 /** Returns the location of the AppEngine SDK directory. */
174 public String
getSdkRoot() {
179 * A file path to the top directory of the Google App Engine SDK.
181 * @param sdkRoot the not {@code null} path to the SDK
183 public void setSdkRoot(String sdkRoot
) {
184 this.sdkRoot
= sdkRoot
;
188 * Retrieves the current cookie manager.
190 * @return the cookie manager set with
191 * {@link #setCookies(ClientCookieManager)}.
193 public ClientCookieManager
getCookies() {
198 * Associates a {@link ClientCookieManager} to store cookies received from
199 * the server, for later reuse in other requests.
201 * @param cookies the cookie manager to use
203 public void setCookies(ClientCookieManager cookies
) {
204 this.cookies
= cookies
;
208 * Returns whether to use HTTPS for communicating with the Admin Console. By
209 * default, this returns true.
211 public boolean getSecure() {
216 * Sets whether to use HTTPS for communicating with the Admin Console.
218 * @param secure true for HTTPS, false for HTTP
220 public void setSecure(boolean secure
) {
221 this.secure
= secure
;
225 * Sets the OAuth 2.0 token to use for authentication (instead of requiring
226 * a username and password).
228 public void setOauthToken(String oauthToken
) {
229 this.oauthToken
= oauthToken
;
233 * Returns the OAuth 2.0 token being used for authentication, or {@code
236 public String
getOauthToken() {
241 * Sets whether to use persisted credentials (load/save to/from disk).
243 public void setUsePersistedCredentials(boolean usePersistedCredentials
) {
244 this.usePersistedCredentials
= usePersistedCredentials
;
248 * Returns whether to use persisted credentials (load/save to/from disk).
250 public boolean getUsePersistedCredentials() {
251 return usePersistedCredentials
;
254 private String userId
;
255 private String server
= SdkInfo
.getDefaultServer();
257 private String sdkRoot
;
259 private ClientCookieManager cookies
;
260 private PasswordPrompt passwordPrompt
;
261 private boolean secure
= true;
262 private String oauthToken
;
263 private boolean usePersistedCredentials
= true;
266 public boolean equals(Object o
) {
270 if (o
== null || getClass() != o
.getClass()) {
273 ConnectOptions that
= (ConnectOptions
) o
;
275 if (host
!= null ?
!host
.equals(that
.host
) : that
.host
!= null) {
278 if (server
!= null ?
!server
.equals(that
.server
) : that
.server
!= null) {
281 if (userId
!= null ?
!userId
.equals(that
.userId
) : that
.userId
!= null) {
284 if (sdkRoot
!= null ?
!sdkRoot
.equals(that
.sdkRoot
) : that
.sdkRoot
!= null) {
292 public int hashCode() {
294 result
= (userId
!= null ? userId
.hashCode() : 0);
295 result
= 31 * result
+ (server
!= null ? server
.hashCode() : 0);
296 result
= 31 * result
+ (host
!= null ? host
.hashCode() : 0);
297 result
= 31 * result
+ (sdkRoot
!= null ? sdkRoot
.hashCode() : 0);
303 * Options used in preparing an application directory for upload.
305 public static class ApplicationProcessingOptions
{
308 private boolean compileJsps
= true;
309 private boolean doBatch
= true;
310 private String compileEncoding
= "UTF-8";
311 private boolean splitJars
= false;
312 private boolean jarJSPs
= true;
313 private boolean jarClasses
= false;
314 private boolean deleteJSPs
= false;
315 private Set
<String
> splitExcludes
= Collections
.emptySet();
318 * Returns an appropriate "java" executable. If a prior call to
319 * {@link #setJavaExecutable(File)} was made, that value is returned (on
320 * windows, the algorithm is forgiving if ".exe" was omitted, and will add
321 * it). If not, the system property {@code java.home} is used to identify
322 * the currently-running JVM, and if that directory contains a file named
323 * {@code bin/java} (Unix) or {@code bin\\java.exe} (Windows), that is
326 * @return the Java executable, as a {@link File}.
327 * @throws IllegalStateException if the java cannot be found by the
328 * heuristic above, but {@link #setJavaExecutable(File)} has not
329 * been called, or if it has been called, but the specified file
332 public File
getJavaExecutable() {
337 String javaProp
= System
.getProperty(JAVA_CMD_PROP
);
338 if (javaProp
!= null) {
339 java
= new File(javaProp
);
340 if (!java
.exists()) {
341 if (Utility
.isOsWindows() && !javaProp
.endsWith(".exe")
342 && (new File(javaProp
+ ".exe")).exists()) {
343 java
= new File(javaProp
+ ".exe");
345 throw new IllegalStateException("cannot find java executable \"" + javaProp
+ "\"");
349 String javaHome
= System
.getProperty("java.home");
351 javaHome
+ File
.separator
+ "bin" + File
.separator
+ "java"
352 + (Utility
.isOsWindows() ?
".exe" : "");
353 java
= new File(javaCmd
);
354 if (!java
.exists()) {
356 throw new IllegalStateException("cannot find java executable "
357 + "based on java.home, tried \"" + javaCmd
+ "\"");
364 * Explicitly requests a specific {@code java} program be used for launched
365 * tasks, such as compiling JSP files.
367 * @param java the executable file to run.
369 void setJavaExecutable(File java
) {
374 * Returns an appropriate "javac" executable. If a prior call to
375 * {@link #setJavaCompiler(File)} was made, that value is returned (on
376 * windows, the algorithm is forgiving if ".exe" was omitted, and will add
377 * it). If not, the system property {@code java.home} is used to identify
378 * the currently-running JVM. If that pathname ends with "jre", then its
379 * parent is used instead as a hoped-for JDK root. If that directory
380 * contains a file named {@code bin/javac} (Unix) or {@code bin\\javac.exe}
381 * (Windows), that is returned.
383 * @return the Java compiler, as a {@link File}.
384 * @throws IllegalStateException if the javac cannot be found by the
385 * heuristic above, but {@link #setJavaCompiler(File)} has not be
386 * called, or if it has been called but the file does not exist.
388 public File
getJavaCompiler() {
393 String javacProp
= System
.getProperty(JAVAC_CMD_PROP
);
394 if (javacProp
!= null) {
395 javac
= new File(javacProp
);
396 if (!javac
.exists()) {
397 if (Utility
.isOsWindows() && !javacProp
.endsWith(".exe")
398 && (new File(javacProp
+ ".exe")).exists()) {
399 javac
= new File(javacProp
+ ".exe");
401 throw new IllegalStateException("cannot find javac executable \"" + javacProp
+ "\"");
405 String javaHome
= System
.getProperty("java.home");
406 String javacDir
= javaHome
;
408 javacDir
+ File
.separator
+ "bin" + File
.separator
+ "javac"
409 + (Utility
.isOsWindows() ?
".exe" : "");
410 javac
= new File(javacCmd
);
411 if (!javac
.exists()) {
413 javacDir
= (new File(javaHome
)).getParentFile().getPath();
415 javacDir
+ File
.separator
+ "bin" + File
.separator
+ "javac"
416 + (Utility
.isOsWindows() ?
".exe" : "");
417 javac
= new File(javacCmd2
);
418 if (!javac
.exists()) {
420 throw new IllegalStateException("cannot find javac executable "
421 + "based on java.home, tried \"" + javacCmd
+ "\" and \"" + javacCmd2
+ "\"");
429 * Explicitly requests a specific {@code javac} program be used for launched
430 * Java compilations, such as compiling JSP files into classes.
432 * @param javac the executable file to run.
434 void setJavaCompiler(File javac
) {
438 /** Returns whether we should attempt to compile JSPs */
439 public boolean isCompileJspsSet() {
444 * Requests that *.jsp files should be compiled into Java byte code, or if
445 * false should be left untouched.
447 * @param doJsps {@code true} to compile .jsp files
449 void setCompileJsps(boolean doJsps
) {
450 this.compileJsps
= doJsps
;
454 * Returns whether we should use batch upload
456 public boolean isBatchModeSet() {
461 * Requests we use the upload batch mode
463 * @param doBatch {@code true} to use batch mode
465 void setBatchMode(boolean doBatch
) {
466 this.doBatch
= doBatch
;
469 public String
getCompileEncoding() {
470 return compileEncoding
;
473 public void setCompileEncoding(String compileEncoding
) {
474 this.compileEncoding
= compileEncoding
;
477 /** Returns whether we should split large jar files. */
478 public boolean isSplitJarsSet() {
482 /** Sets whether we should split large jar files. */
483 public void splitJars(boolean b
) {
487 /** Sets whether we should jar the classes generated from JSPs. */
488 public void setJarJSPs(boolean b
) {
492 /** Returns whether we should jar the classes generated from JSPs. */
493 public boolean isJarJSPsSet() {
497 /** Sets whether we should jar the WEB-INF/classes content. */
498 public void setJarClasses(boolean b
) {
502 /** Returns whether we should jar the WEB-INF/classes content. */
503 public boolean isJarClassesSet() {
507 /** Sets whether we should delete the JSP source files. */
508 public void setDeleteJSPs(boolean b
) {
512 /** Returns whether we should delete the JSP source files. */
513 public boolean isDeleteJSPs() {
518 * Sets suffixes of filenames to exclude when splitting jars.
520 * @param jarSplittingExcludeSuffixes suffixes of filenames to exclude when
523 void setJarSplittingExcludes(Set
<String
> jarSplittingExcludeSuffixes
) {
524 splitExcludes
= jarSplittingExcludeSuffixes
;
528 * Returns the set of suffixes of filenames that should be excluded when
531 * @return a set of suffixes of filenames to exclude.
533 public Set
<String
> getJarSplittingExcludes() {
534 return splitExcludes
;
539 * Specifies the location of a java executable, used when compiling JSPs. By
540 * default, the system property {@code java.home} is used to identify the
541 * currently-running JVM, and if that directory contains a file named {@code
542 * bin/java} (Unix) or {@code bin\\java.exe} (Windows), that is returned.
544 * @param java the Java executable to be used.
546 public void setJavaExecutable(File java
) {
547 appOptions
.setJavaExecutable(java
);
551 * Specifies the location of a javac executable, used when compiling JSPs. By
552 * default, the system property {@code java.home} is used to identify the
553 * currently-running JVM. If that pathname ends with "jre", then its parent is
554 * used instead as a hoped-for JDK root. If that directory contains a file
555 * named {@code bin/javac} (Unix) or {@code bin\\javac.exe} (Windows), that is
558 * @param javac the Java compiler executable to be used.
560 public void setJavaCompiler(File javac
) {
561 appOptions
.setJavaCompiler(javac
);
565 * Requests that *.jsp files should be compiled into Java byte code, or if
566 * false should be left untouched.
568 * @param flag {@code true} to compile .jsp files
570 public void setCompileJsps(boolean flag
) {
571 appOptions
.setCompileJsps(flag
);
575 * Requests we do upload using batch
577 * @param flag {@code true} to use batch mode for upload
579 public void setBatchMode(boolean flag
) {
580 appOptions
.setBatchMode(flag
);
584 * Enables or disables jar splitting.
586 * @param doSplit {@code false} to leave jars unsplit, and perhaps fail to
587 * upload due to large files, {@code true} to split into chunks of some
590 public void setJarSplittingEnabled(boolean doSplit
) {
591 appOptions
.splitJars(doSplit
);
595 * Enables or disables jarring classes generated from JSPs.
597 * @param doJarJSPs {@code true} to jar the generated classes from JSPs.
599 public void setJarJSPsEnabled(boolean doJarJSPs
) {
600 appOptions
.setJarJSPs(doJarJSPs
);
604 * Enables or disables jarring WEB-INF/classes content.
606 * @param doJarClasses {@code true} to jar the WEB-INF/classes content.
608 public void setJarClassessEnabled(boolean doJarClasses
) {
609 appOptions
.setJarClasses(doJarClasses
);
613 * Deletes or not the JSPs source files.
615 * @param deleteJSPs {@code true} remove all JSPs source (not needed after compilation).
617 public void setDeleteJSPs(boolean deleteJSPs
) {
618 appOptions
.setDeleteJSPs(deleteJSPs
);
621 * Sets suffixes for files to exclude when performing jar splitting.
623 * @param jarSplittingExcludeSuffixes a set of filename suffixes to exclude
624 * when performing jar splitting.
626 public void setJarSplittingExcludes(Set
<String
> jarSplittingExcludeSuffixes
) {
627 appOptions
.setJarSplittingExcludes(jarSplittingExcludeSuffixes
);
631 * Sets the character encoding to use when compiling JSP files.
633 * @throws IllegalArgumentException If the specified encoding is illegal or
636 public void setCompileEncoding(String compileEncoding
) {
637 Charset
.forName(compileEncoding
);
638 appOptions
.setCompileEncoding(compileEncoding
);