1. byrongibson
  2. lift-gae-eclipse

Overview

HTTPS SSH

lift-gae-eclipse

An example Eclipse project that makes it possible to use Lift on Google App Engine.

In spite of Google's recent decision to change its billing for App Engine, significantly reducing free app quotas in the process, I created this project a while ago in hopes of having an easy-to-use template project that made it possible to use Lift on Google App Engine. Some of this work is likely transferrable to a more conventional web-app Eclipse project as well, however.

A whole lot of this example project is not yet documented, but I hope to improve that soon. Feel free to fork and add to this project, but make sure to read "License" at the end of this README.

Prerequisites

To use this example project, you need the following installed:

  • Eclipse (Indigo/3.7 or later, recommended "for Java Developers" or "Classic" distribution)

  • Google Plugin for Eclipse

  • Scala IDE (2.0.0-beta or later with Scala 2.9.x)

  • Apache IvyDE (used to resolve library dependencies dynamically)

  • version control software (optional: you may use Eclipse's EGit to pull this repository, if desired)

After importing the project into Eclipse, right-click the project and choose Export..., then export an Ant Buildfile into the project. This will pull in build-appengine.xml, which contains the Ivy bits necessary to auto-copy the dependency jars into war/WEB-INF/lib.

About the Configuration

To make this work required creation of some files and special configuration of the project within Eclipse. I have been adding comments throughout code and config files to explain the important parts of this configuration. In particular:

  • The Scala library is not included in the Eclipse build path. This is because it is in ivy.xml, indirectly via Lift, in order to ensure that the library is included in the webapp itself. Note: If you update the Scala IDE plugin, you may have to update ivy.xml to get appropriately newer runtime libraries for Scala and Lift, then Clean the project to trigger a rebuild.

  • Maven is a piece of crap. I tried, over many hours, to make this project work with Maven, until I realized that -- as a webapp -- there's absolutely no need to publish a POM for this project. Enter Ivy, a much leaner dependency management system that makes use of the Maven artifacts and public repositories. With Ivy and Ant, I'm trivially able to get all the dependencies and copy them into the output directory in less than 10% of Maven's configuration data.

  • There is an Eclipse external builder, here called warlib. This was added in the project Properties -> Builders, adding a new Ant Builder, setting its buildfile to the project's build.xml (the one exported by Eclipse above), and its working directory to the project. The targets for "After a Clean" and "Manual Build" should be set to the Ant task in build-appengine.xml (also named warlib). It's OK to set this for auto-build as well, ensuring that everything is always up to date, but it can be slow and disk-churning.

  • build-appengine.xml has special exclude directives to prevent removal of the App Engine SDK jar files upon rebuild (during Ivy dependency resolution).

  • ivy.xml has several special exclusions, as well as a special setup for slf4j, which are documented in XML comments there.

  • The GAE datastore is configured for use with JPA only, since that is the only compatible database integration layer provided by Lift.

  • It is necessary to have a configuration file (even though effectively empty here, since this example uses the slf4j-jdk14 backend) for Lift's logging support. Here it is located at src/main/resources/GAE.props, which will be found automatically by Lift.

  • Lift uses a special system property to activate particular behaviors for GAE, in.gae.j, which is set to true in war/WEB-INF/appengine-web.xml.

  • Special directives must be added to the bootstrap class (see src/main/scala/bootstrap/liftweb/Boot.scala). The parts which make Lift (and other parts of Scala, such as Reactors) work on GAE are in an if block using the same in.gae.j system property noted above.

  • (more stuff to be added here)

Other Notes

  • Don't pull in lift-mapper. GAE has a special datastore that is not based on SQL/JDBC.

Known Issues

  • The example ivy.xml has a special exclusion on the scala-compiler jar file. This is due to the fact that it exceeds 10MiB, which is normally too large for GAE, and is not currently auto-splittable under Eclipse (see Google Plugin issue 2552). This is currently pulled in via scalap from lift-json, meaning that this exclusion will likely break some Lift AJAX code. I hope to find a workaround for this soon.

  • As of this writing, scalajpa has not been built for Scala 2.9.1, so it is specially excluded from ivy.xml and there are no JPA code examples here.

  • The only code in this project is absurdly trivial. To be fixed with beefier code examples.

License

This repository, and everything underneath it, is hereby released into the public domain effective October 5, 2011.

This declaration applies worldwide, except where "public domain" is not a recognized copyright status. In such jurisdictions where "public domain" is not recognized, all copyrights normally applicable to this repository are hereby expressly waived in perpetuity.

BY SUBMITTING CHANGES INTENDED FOR INCLUSION IN THIS REPOSITORY, YOU ACKNOWLEDGE THAT YOUR CONTRIBUTED WORK(S) IS/ARE ALSO HEREBY RELEASED INTO THE PUBLIC DOMAIN, AND NO COPYRIGHT IS THEREFORE RESERVED ON YOUR BEHALF, OR ON BEHALF OF ANY OTHER PERSON.