Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
It's easy to use the Eclipse development environment to develop your Java App Engine application, just as you can to develop any other servlet-based web application. With the Google Plugin for Eclipse, it's even easier. The plugin lets you create, test and upload App Engine applications from within Eclipse.
The Google Plugin for Eclipse also makes it easy to develop applications using Google Web Toolkit (GWT), to run on App Engine or in any other environment.
This article describes how to install the Google Plugin for Eclipse, create a new App Engine project, and debug it using the development server running within Eclipse. The article also describes how to use the plugin to upload your project to App Engine.
For more information about the plugin, including how to use it for Google Web Toolkit projects, see the Google Plugin for Eclipse documentation.
The Google Plugin for Eclipse is available for Eclipse 3.3 (Europa), Eclipse 3.4 (Ganymede), Eclipse 3.5 (Galileo), Eclipse 3.6 (Helios), and Eclipse 3.7 (Indigo). The "Eclipse IDE for Java EE Developers" includes all of the components you will need for web application development.
In addition to the Google Plugin for Eclipse, we recommend the Web Tools Platform (WTP) plugins for web development. See the Web Tools Platform website. Among other things, WTP provides editing modes for JSP and HTML files.
You can install the Google Plugin for Eclipse using the Software Update feature of Eclipse.
To install the plugin, using Eclipse 3.7 (Indigo):
http://dl.google.com/eclipse/plugin/3.7Click the Add... button. In the dialog that shows, click OK (keep the name blank, it will be retrieved from the update site.)
To install the plugin, using Eclipse 3.6 (Helios):
http://dl.google.com/eclipse/plugin/3.6Click the Add... button. In the dialog that shows, click OK (keep the name blank, it will be retrieved from the update site.)
The process for installing the plugin for Eclipse 3.5 (Galileo) is almost exactly the same, with only a different install location. The location for the Google Plugin for Eclipse 3.5 is as follows:
http://dl.google.com/eclipse/plugin/3.5
To install the plugin, using Eclipse 3.4 (Ganymede):
http://dl.google.com/eclipse/plugin/3.4Click OK. The dialog closes, and the new location is added to the list of available software.
Click the triangle next to the new install location, then click the triangle next to "Google" to display installation options. Check the boxes next to "Google Plugin for Eclipse 3.4" and "Google App Engine Java SDK". You can also select the "Google Web Toolkit SDK" if you'd like to use Google Web Toolkit with your apps. Click the Install... button. Follow the prompts to accept the terms of service and install the plugin.
Note: The plugin install process may take several minutes to complete as Eclipse updates dependencies. See the FAQ for more information.
The process for installing the plugin for Eclipse 3.3 (Europa) is similar, but with different prompts and a different install location. The location for the Google Plugin for Eclipse 3.3 is as follows:
http://dl.google.com/eclipse/plugin/3.3
See the Eclipse documentation for more information about Software Update.
To create a new App Engine project:
Guestbook
for the project described in the Getting Started Guide. For "Package," enter an appropriate package name, such as guestbook
.appengine-java-sdk/
directory.The wizard creates a directory structure for the project, including a src/
directory for Java source files, and a war/
directory for compiled classes and other files for the application, libraries, configuration files, static files such as images and CSS, and other data files. The wizard also creates a servlet source file and two configuration files. The complete directory structure looks like this:
Guestbook/ src/ guestbook/ server/ GuestbookServlet.java META-INF/ jdoconfig.xml log4j.properties logging.properties war/ WEB-INF/ lib/ ...App Engine JARs... appengine-web.xml web.xml index.html
The war/
directory uses the WAR standard layout for bundling web applications. (WAR archive files are not yet supported by the SDK.) The Eclipse plugin uses this directory for running the development server, and for deploying the app to App Engine.
When Eclipse builds your project, it creates a directory named classes/
in war/WEB-INF/
, and puts compiled class files here. Eclipse also copies non-source files found in src/
to war/WEB-INF/classes/
, including META-INF/
and the log4j.properties
and logging.properties
files. The final contents of the war/
directory make up your application for testing and deployment.
For details about the new project that the plugin creates, see the Getting Started Guide.
The App Engine SDK includes a web server for testing your application in a simulated environment. The Google Plugin for Eclipse adds new items to the Run menu for starting this server.
To run your application in the web server inside the Eclipse debugger, select the Run menu, Debug As > Web Application. Eclipse builds the project, switches to the Debug perspective, and the server starts. If the server starts successfully, the server displays several messages, including a message similar to the following, in the Console:
The server is running at http://localhost:8888/
If you want to customize how the server is started, you can create a new Run/Debug configuration of the type "Web Application."
To test the new application that the plugin created, start the server as above, then visit the following URL in your browser (using a URL path appropriate to your application):
With Eclipse, you can leave the server running in the debugger while you make changes to source code, JSPs, static files and appengine-web.xml
. When you save changes to source code, Eclipse compiles the class automatically, then attempts to insert it into the running web server dynamically. In most cases, you can simply reload the page in your browser to test the new version of the code. Changes to JSPs, static files and appengine-web.xml
are recognized by the development server automatically, and also take effect without restarting the server. If you change web.xml
or other configuration files, you must stop and start the server for the changes to take effect.
To stop the server, make sure the Debug panel is selected, then click the Terminate button:
The Google Plugin for Eclipse adds several buttons to the Eclipse toolbar. The App Engine deploy button uploads your application to App Engine:
Before you upload your app for the first time, you must register an application ID with App Engine using the Admin Console. Register an application ID, then edit the appengine-web.xml
file and change the <application>...</application>
element to contain the new ID.
When you click the App Engine deploy button, Eclipse prompts you for your administrator account username (your email address) and password. Enter your account information and click the Upload button to complete the upload. Eclipse gets the application ID and version information from the appengine-web.xml
file, and uploads the contents of the war/
directory.
Test your application on App Engine by visiting its URL:
http://your_app_id.appspot.com/guestbook
Some features of the App Engine Java SDK tools are only available by running the tools directly from the command line. If you have installed the SDK using Eclipse, you can run these tools from the Eclipse plugin installation directory.
The SDK is located in your Eclipse installation directory, under plugins/com.google.appengine.eclipse.sdkbundle_VERSION/
, where VERSION
is a version identifier for the SDK. In this directory is the appengine-java-sdk/bin/
subdirectory containing the tools.
Note: If you are using Mac OS X or Linux, you must give the command files executable permission before you can run them. For example, to give appcfg.sh
executable permission, enter the following command from the appengine-java-sdk/bin/
directory: chmod u+x appcfg.sh
For more information on the features available exclusively from the command line, see Uploading and Managing.