Google App Engine (GAE) allows you to deploy web applications without incurring the costs of infrastructure stand-up and maintenance. Here at Windward, we have worked to provide a Java library that is custom built to support GAE. GAE only allows pure Java, and as a result, a few standard Java packages are not supported, such as java.awt and javax.imagio. Furthermore, GAE does not allow system calls, and does not have a standard file system, which means that handling files does not work the same.
To solve some of the problems mentioned above, we take interest in a couple of open-source Apache-licensed projects. The first is appengine-awt which replaces the java.awt and javax.imageio packages. The second is GaeVFS or Google App Engine Virtual File System which extends the Apache Commons VFS library to include support for GAE datastore. All of the jar files required to run the Windward Engine on Google App Engine are located in the “appengine” directory at the top-level of your Java Engine installation directory.
1.0.1-WINDWARD (Windward custom version)
appengine-awt replaces the java.awt and javax.imageio packages with the equivalents from the Apache Harmony and Apache Commons Imaging projects respectively. Any application you deploy to GAE will need to use this package or something similar. The packages provided by this library (com.google.code.appengine.awt and com.google.code.appengine.imagio) mirror the API of java.awt and javax.imageio fairly closely which makes conversion easy.
One issue we have found with this library is that it does not account for the fact that GAE does not support the standard file system API; however, file system usages in the java.awt and javax.imageio packages is very limited. We have made a few of our own minor modifications to this library including switching file system usages to use gaevfs instead in order to make it work with the Windward engine. Soon, we will open-source these modifications and post them online.
gaevfs provides a standard API for performing file operations on GAE by extending Apache Commons VFS. While it does not mirror the java.io package similar to how appengine-awt mirrors its respective packages, the functionality provided is still phenomenal, especially for cross-platform development. We recommend using gaevfs with our engine. In our modified version of appengine-awt, we have altered a couple of occurences of File I/O code to use GaeVFS, and this code, if hit, may throw an error if GaeVFS is not properly initialized. Therefore, instructions on initializing GaeVFS are in the Initialization section.
- commons-vfs 2.0 (must use modified version provided by GaeVFS) (commons-vfs-2.0-SNAPSHOT.jar)
- commons-logging 1.1 (commons-logging-api-1.1.jar)
- commons-collections 3.2.1 (commons-collections-3.2.1.jar)
The standard Windward engine for Java does not run on Google App Engine without some modifications. After modifying our engine to work with GAE, we had to remove some features due to the incompatibility of some of the third-party libraries we use. Below is a list of some of the things that work and do not work.
All of the input formats supported by Windward are supported in our engine when running on Google App Engine.
Almost all of the output formats supported by Windward are also supported when running on Google App Engine. However, we do not currently support printer outputdirectly. If you need this functionality, you could look into Google Cloud Print, although we do not offer technical support for this technology.
Unfortunately, due to Google App Engine restrictions, we are not able to support all of the standard datasources we normally support. Generally, most file-based and stream-based datasources are supported. The following datasources are known to work well:
- MySQL -- you must use Google's SQL connector for this -- details found here: https://cloud.google.com/appengine/d...le_connector_j -- it still works with external servers and the "com.mysql.jdbc.Driver" class
The following datasource drivers, however, will not work at all:
- IBM DB2– the driver’s “Automatic Client Reroute” (ACR) feature utilizes the Java Naming and Directory Interface (JNDI) API which is not allowed by Google App Engine.
- Microsoft SQL Server
- ODBC – The JDBC-ODBC bridge will be deprecated in Java 8. Furthermore, the JDBC-ODBC bridge connector utilizes native code through Java Native Interface which is explicitly not allowed by Google App Engine.
Most of our latest formatting features work, except for charting. The charting package that we use is incompatible with Google App Engine.
Servlet Initialization and Cleanup
In order to successfully use the Windward Engine on Google App Engine, you need to initialize a couple of things first, and perform some cleanup when you are done. This and a few clean-up procedures are documented in the GaeVFS documentation. First, you will need to set GaeVFS’ root path to your webapp’s real path. This can be done with the following line (ideally placed in your servlet’s init() method):
GaeVFS.setRootPath( getServletContext().getRealPath( "/" ) );
GaeVFS should also be safely closed, ideally in your servlet’s destroy() method:
And finally, at the end of each request, the file cache should be cleared. This step is quite important. The best place to add this clause is in a finally block following code which uses GaeVFS. We recommend surrounding your report.processComplete() call at least):
Using the Engine
In general, using the Windward engine on Google App Engine is similar to how you would normally use the engine. You can find more detailed instructions on our wiki in the Java Engine section. The only thing that is different when programming for Google App Engine is that everything runs in a servlet. More information on programming for a servlet can be found on many places on the internet. We have also provided a sample for you which can be found in the Java/Specialized section of our Catapult sample browser which comes with the Java Engine. It can also be found in your Java Engine installation directory under demo/Samples/Java/Specialized/GAEServlet.
- Google App Engine SDK:
- You can download the Google App Engine Java SDK Here: https://cloud.google.com/appengine/downloads#Google_App_Engine_SDK_for_Java
- Additionally, we recommend setting the following environment variable to denote the location of your GAE Java SDK. This environment variable is used by the Apache Ant buidl file.
- Variable name: APPENGINE_HOME
- Variable value: C:\appengine-java-sdk (or wherever you have extracted the App Engine SDK to)
- Apache Ant:
- We recommend using Apache Ant to simplify the process of building your application and uploading it to Google App Engine.
- Download location: http://ant.apache.org/bindownload.cgi
Using Apache Ant
In order to run the sample, you will want to take advantage of the Ant build file, build.xml which we have provided. This file provides targets for running the development server and uploading your app.
In a command prompt shell, navigate to the top level directory of the GAE servlet sample (e.g. Java/Specialized/GAEServlet/) and use the following command to see a list of possible targets:
Assuming you have set the APPENGINE_HOME environment variable, the runserver target will copy the required jars from the App Engine SDK, compile your source code and start up the local development server on port 8080. The dev server port can be configured in build.xml by editing the “gaeservlet.port” property. From the GAEServlet directory, run the runserver target by issuing the following command:
If you have logging set to INFO, you will see the following message when the dev server is ready:
INFO: Dev App Server is now running
You will now be able to access the dev server at http://localhost:8080
Feel free to browse the code. Most of the classes are simply helper classes. The two that do most of the grunt work (and are worth checking out) are GenerateReport.java and RunAllTemplates.java.
You can access a few different applications by going to the following dev server URLs:
Run All Templates
This sample runs through several sample templates to demonstrate the capabilities of Windward on Google App Engine. The first URL will run every template and may take some time to complete. The second URL allows you to pick a specific template to run. Some of the templates in this application may require data drivers that you do not have installed. In order to use those data drivers, you should copy the respective jar to war/WEB-INF/lib and restart the server to reset the classpath. More information on data drivers can be found on our Wiki: Types of Datasources