Using Apache Maven and the App Engine Plugin (App Engine SDK-based)

Warning: The information below specifies using the toolset that was delivered with the standalone App Engine SDK. This SDK and its tools such as AppCfg are now deprecated and you should use the Cloud SDK tooling such as the gcloud command line, or the Cloud SDK-based Maven, Gradle, Eclipse, or IntelliJ plugins.

This page explains how to manage an App Engine project using Apache Maven, a software project management and comprehension tool. It is capable of building WAR files for deployment into App Engine. Google provides a plugin and Maven Archetypes which are included with Maven 3.5.

When you use Maven, you don't need to manually download the Java libraries from the App Engine SDK. Maven automatically downloads the appropriate libraries when necessary. You can also use Maven to test your app locally and deploy it to production App Engine.

Setting up Maven

Configuring Java

1. If you don't have Java, download, install and configure it.
2. Set the compiler flags in the pom.xml to specify Java 8 bytecode.
   appengine-standard-java8/helloworld-gae-javasdk-tools/pom.xml

   View on GitHub

   <properties>
     <maven.compiler.source>1.8</maven.compiler.source>
     <maven.compiler.target>1.8</maven.compiler.target>
   </properties>

Installing Maven 3.5

To determine whether Maven is installed and which version you have, invoke the following command:

 mvn -v

If you don't have the proper version of Maven installed:

1. Download Maven 3.5 from the Maven website.
2. Install Maven 3.5 on your local machine.

Note: Linux users may need to download Maven instead of using apt-get install to install Maven 3.5.

Setting up and validating your Cloud project

You need to set up your Cloud project and install the App Engine SDK:

1. Use the Google Cloud Console to create and set up your Cloud project:

   Go to App Engine

   1. Select or create a new Cloud project.
   2. If you need to create an App Engine application for your project, you are prompted to select the region where you want your App Engine application located.
   3. The Dashboard opens after your App Engine application has been created in your project.

2. Install the App Engine SDK for Java and add the directory to your PATH.

   Note: Ensure that you always have the latest version of the App Engine SDK for Java. You must update the SDK periodically.

Using Maven

Adding the App Engine plugin to an existing project (optional)

To add the Google App Engine Maven plugin to an existing Maven project, add the following into the plugins section in the project pom.xml file:

<plugin>
   <groupId>com.google.appengine</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>1.9.88</version>
</plugin>

Choosing an archetype

Maven Archetypes allow users to create Maven projects using templates that cover common scenarios. App Engine takes advantage of this Maven feature to provide some useful App Engine archetypes at Maven Central. Select an App Engine archetype appropriate for your app:

Application type	Artifact	Description
App Engine app	guestbook-archetype	Generates the guestbook demo sample, complete and ready to run and test.
App Engine app	appengine-skeleton-archetype	Generates a new, empty App Engine project ready for your own classes and resources, but with required files and directories.

Creating a new project

During project creation, Maven prompts you to supply groupId, artifactId, version, and the package for the project.

Term	Meaning
groupId	A namespace within Maven to keep track of your artifacts. When people consume your project in their own Maven Project, it will serve as an attribute of the dependency they will end up specifying.
artifactId	The name of your project within Maven. It is also specified by consumers of your project when they depend on you in their own Maven projects.
version	The initial Maven version you want to have your project generated with. It's a good idea to have version suffixed by -SNAPSHOT because this will provide support in the Maven release plugin for versions that are under development. For more information, see the Maven guide to using the release plugin.
package	The Java package created during the generation.

The following procedure describes how to use App Engine Maven archetypes to create an App Engine application.

Note: Some of the following commands can take time to execute, and some can potentially download large artifacts. We recommended that you run these with a good internet connection.

To create an App Engine App:

1. Change directory to a directory where you want to build the project.

2. Invoke the following Maven command:

    mvn archetype:generate -Dappengine-version=1.9.88 -Djava8=true -DCloudSDK_Tooling=false -Dapplication-id=your-app-id -Dfilter=com.google.appengine.archetypes:
   

   Set -Dappengine-version to the most recent version of the App Engine SDK for Java, and application-id to the ID of your Cloud project.

   Set -Djava8=true to deploy the project in the Java 8 runtime.

   Set -DCloudSDK_Tooling=false to use the App Engine SDK for Java tooling.

3. When prompted to choose an archetype, choose the value 2 for the App Engine skeleton archetype. This creates an empty project that contains the required directory structure and files.

4. When prompted for version, press ENTER to select the default most recent version.

5. When prompted to Define value for property 'groupId', supply the desired namespace for your app; for example, com.mycompany.myapp.

6. When prompted to Define value for property 'artifactId', supply the project name; for example, myapp.

7. When prompted to Define value for property 'version', accept the default value.

8. When prompted to Define value for property 'package', supply your preferred package name (or accept the default). The generated Java files will have the package name you specify here.

9. When prompted to confirm your choices, accept the default value (Y).

10. Wait for the project to finish creating the necessary directories and files. Then go into new project directory, for example myapp/.

    When the project successfully finishes you will see a message similar to this one:

    [INFO] --------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] --------------------------------------------------
    [INFO] Total time: 1:16.656s
    [INFO] Finished at: 2017-06-04T16:18:24-07:00
    [INFO] Final Memory: 16M/228M
    [INFO] --------------------------------------------------
    

11. Before starting to code your own classes for the app, familiarize yourself with the basic project layout and the required project files is complete: inside the directory where you created the project, you'll have a subdirectory named myapp, which contains a pom.xml file, the src/main/java subdirectory, and the src/main/webapp/WEB-INF subdirectory:

    

    • You'll add your own application Java classes to src/main/java/...
    • You'll configure your application using the file src/main/webapp/WEB-INF/appengine-web.xml
    • You'll configure your application deployment using the file src/main/webapp/WEB-INF/web.xml

12. Create your application Java classes and add them to src/main/java/.../ For more information, see Building an App on App Engine

13. Add the UI that you want to provide to your app users. For more information, see Handling Form Data.

14. The artifact you used to create the project has done the basic src/main/webapp/WEB-INF/appengine-web.xml configuration for you. However, for more advanced configuration, you may need to edit this file. For more information, see Configuring with appengine-web.xml.

15. Edit the file src/main/webapp/WEB-INF/web.xml to map URLs to your app handlers, specify authentication, filters, and so forth. This is described in detail in The Deployment Descriptor.

Managing a Maven project

Compiling and building your project

To build an app created with the Maven App Engine archetypes:

1. Change directory to the main directory for your project, for example, guestbook/

2. Invoke Maven:

   mvn clean package
   

3. Wait for the project to build. When the project successfully finishes you will see a message similar to this one:

   BUILD SUCCESS
    Total time: 10.724s
    Finished at: Thur Jul 04 14:50:06 PST 2017
    Final Memory: 24M/213M
   

4. Optionally, test the application using the following procedure.

Testing your app with the development server

During the development phase, you can run and test your app at any time in the development server by invoking the App Engine Maven plugin. The procedure varies slightly depending on the artifact used to create the project.

To test your app:

1. If you haven't already done so, build your app (mvn clean package).

2. Change directory to the top level of your project (for example, to myapp) and invoke Maven:

   mvn appengine:devserver
   

   Wait for the server to start. When the server is completely started with your app running, you will see a message similar to this one:

   Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
   INFO: The server is running at http://localhost:8080/
   Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
   INFO: The admin console is running at http://localhost:8080/_ah/admin
   

3. Use your browser to visit http://localhost:8080/ to access your app.

4. Shut down the app and the development server by pressing Control+C in the Windows/Linux terminal window where you started it, or CMD+C on the Mac.

Specifying a port for local testing

When you run your app in the local development server, the default port is 8080. You can change this default by modifying the plugin entry for appengine-maven-plugin (or adding it if it doesn't exist). For example, we specify port and address in the following <plugin> entry within <plugins> inside the main app directory pom.xml file (myapp/pom.xml):

 <plugin>
     <groupId>com.google.appengine</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>1.9.88</version>
     <configuration>
         <enableJarClasses>false</enableJarClasses>
         <port>8181</port>
         <address>0.0.0.0</address>
     </configuration>
 </plugin>

Notice that the <port> sets the port here to 8181 as shown, and the address 0.0.0.0 is specified, which means the development server will listen to requests coming in from the local network.

Deploying your app

See the Deploying your app guide.

Reference: Available goals

Once the App Engine Maven plugin is added to the project's pom.xml file, several App Engine-specific Maven goals are available. To see all of the available goals, invoke the command:

 mvn help:describe -Dplugin=appengine

The App Engine Maven plugin goals can be categorized as devserver goals, app and project management goals, and Endpoints goals.

Development server goals

These are the development server goals:

appengine:devserver

Runs the App Engine development server. When the server is running, it continuously checks to determine whether appengine-web.xml has changed. If it has, the server does a hot reload of the application. This means that you do not need to stop and restart your application because of changes to appengine-web.xml. The following parameters are available:

• <fullScanSeconds>
• <address>
• <disableUpdateCheck>
• <jvmFlags>
• <port>
• <server>

For example, to enable running the server in debug mode on port 8000 without suspending at start time, you can use the following flags:

<jvmFlags>
  <jvmFlag>-Xdebug</jvmFlag>
  <jvmFlag>-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n</jvmFlag>
</jvmFlags>

By default, the <fullScanSeconds> flag is set to 5 seconds, which means server is checking every 5 seconds for changes in the web application files, and reloads the application automatically. This is useful with IDEs that support the compile on save feature like NetBeans. In order to use this feature, you must configure the <build> section:

<build>
   <outputDirectory>target/${project.artifactId}-${project.version}/WEB-INF/classes</outputDirectory>
   <plugins>
      ....
   </plugins>
</build>

appengine:devserver_start

Performs an asynchronous start for the devserver and then returns to the command line. When this goal runs, the behavior is the same as the devserver goal except that Maven continues processing goals and exits after the server is up and running.

appengine:devserver_stop

Stops the development server. Available only if you started the development server with appengine:devserver_start.

Application management goals

For application and project management, the goals are listed in the following table:

Goal	Description	Corresponding gcloud Command
appengine:backends_stop	This stops any running development server listening on the port as configured in your pom.xml file. This goal can be used in conjunction with the devserver_start command to do integration tests with the Maven plugin.
appengine:backends_configure	Configure the specified backend.
appengine:backends_delete	Delete the specified backend.
appengine:backends_rollback	Roll back a previously in-progress update.
appengine:backends_start	Start the specified backend.
appengine:backends_update	Update the specified backend or (if no backend is specified) all backends.
appengine:enhance	Runs the App Engine Datanucleus JDO enhancer.
appengine:rollback	Rollback an in-progress update.	gcloud app versions start, gcloud app versions stop
appengine:set_default_version	Set the default application version.	gcloud app services set-traffic
appengine:update	Create or update an app version.	gcloud app deploy
appengine:update_cron	Update application cron jobs.	gcloud app deploy
appengine:update_dispatch	Update the application dispatch configuration.	gcloud app deploy
appengine:update_dos	Update application DoS protection configuration.	gcloud app deploy
appengine:update_indexes	Update application indexes.	gcloud datastore create-indexes [INDEX_YAML]
appengine:update_queues	Update application task queue definitions.	gcloud app deploy
appengine:vacuum_indexes	Delete unused indexes from application.	gcloud datastore cleanup-indexes [INDEX_YAML]
appengine:start_module_version	Start the specified module version.	gcloud app versions start
appengine:stop_module_version	Stop the specified module version.	gcloud app versions stop

Troubleshooting upload errors

If you use the update goal, your update attempt may fail with a message similar to this one: 404 Not Found This application does not exist (app_id=u'your-app-ID'). This error will occur if you have multiple Google accounts and are using the wrong account to perform the update.

To solve this issue, change directories to ~, locate a file named .appcfg_oauth2_tokens_java, and rename it. Then try updating again.