I started by creating a tiny GAE/J application consisting only of one JSP file. In addition to the JSP file the GAE/J environment requires two additional files: the standard Java deployment descriptor web.xml and the GAE/J specific appengine-web.xml. The files required for our application are hence: index.jsp, WEB-INF/appengine-web.xml and WEB-INF/web.xml.
The smallest possible valid appengine-web.xml contains only the required elements appengine-web-app/application and appengine-web-app/version. If you want to use HTTP-sessions you're required to add an element appengine-web-app/sessions-enabled set to true. The appconfig-web.xml is documented here.
This is the smallest possible valid appengine-web.xml:
<appengine-web-app>
<application>your-app-id</application>
<version>1</version>
</appengine-web-app>
The smallest possible valid web.xml file that is accepted by GAE/J contains only the root node web-app. For some reason <web-app /> is not accepted whereas the equivalent <web-app></web-app> is. The GAE/J documentation covering web.xml is found here.
The smallest possible web.xml that is accepted by GAE/J is:
<web-app></web-app>
Now that we have the JSP-file and our minimal web.xml and appengine-web.xml we're ready to deploy.
To make the working of the deployment process as clear as possible I choose to deploy by issuing the deploy command directly rather than relying on the Ant scripts provided by the GAE/J SDK. In order to deploy we issue the command:
java -cp /some/path/to/appengine-java-sdk-1.2.0/lib/appengine-tools-api.jar com.google.appengine.tools.admin.AppCfg update .The application should now be deployed.
If we examine our GAE/J "home dir" (see this previous post about "GAE/J home dirs") after deployment we'll find the following files:
- /base/data/home/apps/[app-id]/[version-id]/index.jsp
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/classes/org/apache/jsp/index_jsp.java
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/classes/org/apache/jsp/index_jsp.class
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/web.xml
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/appengine-web.xml
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/lib/jasper-compiler-5.0.28.jar
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/lib/jakarta-jstl-1.1.2.jar
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/lib/commons-el-1.0.jar
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/lib/jakarta-standard-1.1.2.jar
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/lib/jasper-runtime-5.0.28.jar
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/lib/ant-launcher-1.6.5.jar
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/lib/commons-logging-1.1.1.jar
- /base/data/home/apps/[app-id]/[version-id]/WEB-INF/lib/ant-1.6.5.jar
Note that a couple of JAR:s have been to our application. Apache Jasper runtime (+ dependencies) is used by the servlet (org.apache.jsp.index_jsp) that is generated from our JSP-file (index.jsp). But what about the other JAR:s (say ant, ant-launcher and jasper-compiler) - should those really be required in the live environment? Is the uploading of those files a bug?
The web.xml that is uploaded to the live environment is altered during the deployment process. Servlet-mappings are added to the original web.xml to match JSP filenames against the servlets that are generated from said JSP files -- in this case the URL-pattern /index.jsp is mapped to the servlet org.apache.jsp.index_jsp.
Note also that both the original JSP file (index.jsp) and the corresponding generated servlet Java file (index_jsp.java) are uploaded although those files should not be needed in the live environment. This can be seen either as a feature (in the sense you have a backup of your source code in the live environment) or as a bug (in the sense that only what's required in the live environment should be in the live environment).
This concludes the exploration of the GAE/J deployment process this time.
I'd like to hear from you what you think about the three (very minor) issues discussed -- <web-app /> not accepted as a valid web.xml + JSP:s and Java-files uploaded to live environment + additional JAR:s uploaded of which some redundant (?). Are any of these bugs that should be reported? What do you think? Please leave a comment.
I should probably add that I'm very impressed with how smooth the deployment process is handled when using GAE/J. In particular I have not yet seen a case where deploying a new version means downtime visible for the end-user. That's very nice!
2 comments: