COMP 405 Spring 2015	GAE Java Project Structure

Reference:  GAE Project Structure

A GAE Java project is slightly different than a regular Java project because it contains extra information that enables the application to be bundled up and deployed to the Google cloud.   The following discussion is a greatly condensed description.   Please see the reference materials for more complete documentation.

src folder

As normal, the Java source code is located in this folder.   Do not put Java source code, except that contained in a JavaServer Page (JSP) file, in the WAR folder.    JSP files are placed in the WAR folder (see below).   

test folder

JUnit test code goes in this folder.

Web ARchive ("WAR") file/folder  

This is a special kind of JAR file is that contains the code deployed to GAE.   The WAR file contains all the compiled Java classes, plus any scripts, JavaServerPages and configuration files that are needed to run the application.  In Eclipse, the WAR file appears as a folder in the project -- all references here are to equivalently to the WAR folder in Eclipse and the auto-generated and deployed WAR file. 

HTML, CSS, JavaScript and JavaServer Pages (JSP) all, by default, consider the root of the WAR file to be their "root" directory.   It is HIGHLY recommended that unless a file absolutely needs to be in the root directory, that it be placed in an appropriately named sub-directory.     The app.yaml file can be used to reconfigure what the system considers to be the root web page directory.    Support files, such as CSS, JavaScript, image and other files should be placed in dedicated folders so as not to clutter up the root directory of the WAR file.

WEB-INF folder:

This is a special folder inside the WAR file that hold configuration and other system information for the application, such as:

• app.yaml  -- The main configuration file for the application in a more "user friendly" format.    The GAE development system will use this file to automatically generate the actual configuration files, web.xml (URL routing, servlet definitions, default page, etc.)  and appengine-web.xml (multi-tasking, static files, logging, sessions, etc.).   Unfortunately, the Google Plugin for Eclipse does not automatically generate the app.yaml file, so it must be generated by hand (see below).
  • Note that JSP pages do not need to be configured in the app.yaml file.   The system will automatically create a URL route to the JSP page based on its filename and folder location relative to the root of the WAR file.   It is common however, to add customized URL routing in the app.yaml file for a JSP page, e.g. to route a folder name without a specified filename to a specific JSP page (this can be done as well for regular web pages and servlets as well.)
• logging.properties -- configuration for the logging system.
• lib folder -- Holds JAR files to be uploaded that add Java library support for the application.   If you have third-party libraries to add, e.g. the Apache Commons forms processing libraries, the JAR files for those libraries should be placed in the WEB-INF/lib folder.   Those JAR files must also be added to the Eclipse project's Java Build Path!

Manually generating the app.yaml file from the web.xml and appengine-web.xml files

This process should be done right after you have verified that Eclipse has created an operational, deployable GAE project (with sample code).    Subsequent configuration changes can then all be done in the app.yaml file.

Backup your web.xml and appengine-web.xml files, e.g. commit your code to SVN, before you create the app.yaml file as Eclipse will automatically overwrite these files without prompting!

To manually create the app.yaml file, you must express all the information in the web.xml and appengine-web.xml files in the YAML syntax.  Luckily, for the most part, each element in the XML files corresponds to a reasonably obviously named and formatted entry in the YAML file, though the URL route handlers are combined from two separate entries in XML into a single entry in YAML. 

For reference, see the following pages for information on the syntax of the various elements in each file:

• app.yaml - application and deployment configuration  (specifically, see YAML App Config)
• appengine-web.xml - "Application Configuration"
• web.xml - "Deployment Descriptors"

You can check the YAML syntax using an on-line YAML and JSON syntax verifier but these will NOT check if the entry values are valid.

The following example listing is approximately how your app.yaml file should look.   The example also shows the user sessions capability turned on, which is off by default, some added welcome files (default page names to look for if not specified by the browser) and an example of redirecting a request for a directory to a specific JSP page (could have been any kind of page).

application: my-application-id     # Put Application ID here
version: 1    # Should change this on major revisions
runtime: java   # use Java
threadsafe: true   # process requests in parallel
sessions_enabled: true   # false by default

welcome_files:    # applies to all folders
  - Codeskulptor_serv.html    # for the sample code
  - index.jsp     # allows using a JSP as a home page
  - index.html    # standard home page
  

static_files:
 
  - include: /**   # all files are treated as static/resources, which is the default

  # The following 3 entries configure serving/caching of GWT files
  
  # The following line requires App Engine 1.3.2 SDK
  - include: /**.nocache.*
    expiration: 0s

  - include: /**.cache.*
    expiration: 365d
    
  - exclude: /**.gwt.rpc

system_properties:   # tells system where to find the logging configuration file
  java.util.logging.config.file: WEB-INF/logging.properties


# URL routing handlers
handlers:

  - url: /_ah/spi/*     # used by Google Cloud Endpoints
    servlet: com.google.api.server.spi.SystemServiceServlet
    init_params: 
      service: 
    name: SystemServiceServlet

  - url: /codeskulptor_serv/greet    # used by the sample code
    servlet: edu.rice.codeskulptor.server.GreetingServiceImpl 
    name: greetServlet
    
  - url: /save/*   # redirect request for the bare directory to the upload page
    jsp: /save/upload.jsp
    

© 2015 by Stephen Wong