Using Fiz with Google AppEngine

Owned by Former user (Deleted)
Last updated: Dec 05, 2009Version comment
3 min read

NOTE: At present, support is not yet present in the Fiz distributions.  This note will be removed once Fiz has been updated.

Uploading a Fiz application to Google AppEngine

Fiz applications can be uploaded and run on Google's AppEngine framework.  To begin, first download the AppEngine SDK and read the instructions on the AppEngine website for registering and uploading a Java application.  Note that Fiz has provided a correctly-located instance of appengine-web.xml at FIZ-APP/web/WEB-INF/appengine-web.xml - before building and uploading your application, you should configure appengine-web.xml with the name of your application.  As with Tomcat, the specific directory you will need to upload is the one generated by a call to ant build: for instance, if the name of your application was myApp, the following command would upload your application:

APPENGINE-SDK/bin/appcfg.sh update FIZ-APP/out/myApp

where APPENGINE-SDK is the location of your AppEngine SDK, and FIZ-APP is the top-level directory of your application.  Note that if you are performing this command from Windows, you will have to use appcfg.cmd instead of appcfg.sh.  The AppEngine SDK also provides a local AppEngine simulation environment for you to test your applications - this can be run with a call to APPENGINE-SDK/bin/dev_appserver.sh, or APPENGINE-SDK/bin/dev_appserver.cmd.

While AppEngine will let you upload your Fiz application as-is, you will encounter numerous problems if you do not take the following actions:

  • In FIZ-APP/web/WEB-INF/fiz/config/main.yaml, the property googleAppEngine must be set as 1.
  • In FIZ-APP/src/log4j.properties the root logger must be set as either STD or NIL - DRFA cannot be used, as AppEngine prohibits filesystem access on their servers.  If using STD, the logs for an application can be downloaded from or viewed on the AppEngine website.

Writing a Fiz application using the AppEngine Datastore

Google AppEngine provides a non-traditional data storage mechanism called Datastore, which is similar to Google's BigTable.  Unlike traditional relational database schemas, the Datastore uses a single large table with varying row types.  Each row, an Entity, can have varying "columns" (referred to as "properties") with varying values - although rows have types (kinds), that typing does not place any restriction on what properties or values an Entity can or cannot have.  Fiz provides a back-end DataManager to support interactions with Datastore, called GaeDataManager.  In GaeDataManager, Entities are presented to the developer as Datasets - an Entity property-value pair is encapsulated as a Dataset key-value pair.  Although there are no separate tables in Datastore, Entities are grouped both by their kind and by their ancestry.  Every Entity has a pointer to an optional parent Entity, creating a tree-like organization of Entities.  Entities with the same root (a parent-less ancestor) are all stored near each other within the Datastore, which makes queries by common ancestor very efficient.

Each Entity in the Datastore has an associated Key.  Keys uniquely identify Entities, and encapsulate the Entity's kind, a unique ID, and an optional pointer to a parent Key.  In GaeDataManager, Keys are often returned to the developer and are expected as arguments to many functions. 

While Datasets support values of arbitrary types, the Datastore is more restrictive: only supported Java Objects can be stored.  Datastore also supports collections of these Objects - as in Datasets, Entities support the notion of multiple values associated with a key or property.

GaeDataManager provides the application developer with a number of ways to store and access information in the Datastore, including custom queries on Entity type, ancestry, and property value.  Many queries that your application may perform will require that you specify an associated query index.  Query indexes must be specified in a file titled datastore-indexes.xml, in FIZ-APP/web/WEB-INF/.  See the AppEngine documentation on query indexes for details on how to specify an index.

Developing Fiz with Google AppEngine

There are a few important things to keep in mind when developing Fiz in order to maintain compatability with Google AppEngine:

  • All objects written to the HttpSession must be Serializable.  This means that the object itself must implement the Serializable interface, and any instance variables contained within that object must also be Serializable.  Tomcat does not have this restriction, nor does the API enforce it.
  • All Java standard library classes used by your application must be on the JRE class white list.

Maintaining Fiz with Google AppEngine

Fiz contains three AppEngine libraries, which are needed both for GaeDataManager and its unit tests.  As such, these libraries must be kept up-to-date.  As of this writing (December 2009), Fiz contains libraries from AppEngine SDK version 1.2.8.