Configuring
Checking for Runtime Environment
During start up, the plugin will check if the WTP Runtime instance intended to work with Google App Engine exists. If not found, a new Runtime instance will be created for you, and configured to use default Java Runtime Environment and default Google App Engine SDK. If no Google App Engine SDK is found, the Runtime will be created but you will get an error message as the Runtime cannot be used without Google App Engine SDK. In this case, the next step is to install the Google App Engine SDK and then configure the WTP Runtime manually (either edit the invalid Runtime or create a new one in Eclipse Preferences).
To do this:
Open Eclipse Preferences and navigate to Server->Runtime Environments:
Press "Edit..." and select or configure the Google App Engine SDK:
Press "Finish" and then “OK”.
Creating new Server
Once you have switched to the "Java EE" Perspective you will see a Servers view. In the Servers view, select the popup menu "New->Server" (or click “new server wizard...” link):
The "New Server" Wizard will open:
Navigate to the Google category and select Google App Engine.
If you don’t have any other Runtimes defined, then Google App Engine runtime will be pre-selected. Choose Server’s name as desired and change Server runtime environment if needed.
Pressing "Next" will bring you to Server instance configuration page:
Enter/modify Server Port (a port number which Development server will listen for connections).
Since SDK 1.8.1, it’s possible to enable automatic reloading application when resources change. The Development Server scans the published project at a regular interval (every 5 seconds) and if it detects changes, it reloads the application without the need to restart. You can check the value of the scan cycle. Enter zero or negative value if you want to disable auto-reloading.
The next option allows you to configure the local datastore to simulate the consistency model of the High Replication Datastore. Setting this option value to zero will disable HRD.
Press "Finish" to create the server.
Once the Server is created, you will need to associate a module (project) before being able to start it (see Running project on the Server for more information).
If you double click on the server node in the Servers view, the server editor window will be brought up. You can fine tune some parameters like "Publishing". By default, "Publishing" is set up to "Automatic," with zero second delay interval. The plugin will perform an automatic redeployment of the Web Application project to the local Development Server as soon as you save a resource in the project. It can be a servlet change or a JSP change, or any class or web artifact in the project.
Note that if auto scan & reload application is enabled for the Development Server, the changes will be applied after publishing is done. In other words, first Eclipse detects changes in your project, builds the project and then publishes it to Development Server (assuming you have left publish settings as automatic). After that, changes will be reloaded by the Development Server at the defined scan cycle time. Default scan cycle time is 5 sec.
If you need additional VM arguments passed to server launch configuration, you can add it here. Do not edit the launch configuration directly, your input will be ignored!
Creating new project
Dynamic Web Project
Open the "New" wizard using menu or by pressing Ctrl-N (Cmd-N) and select “New Dynamic Web Project”:
If you don’t have any other runtimes, Google App Engine runtime is pre-selected. The runtime will set up the project classpath to include the required libraries of the Google App Engine SDK.
You can press "Finish" now to get the project created with default settings or use “Next” to tune additional setting for Google App Engine facet (and/or other facets).
For this example, let's omit other facets wizard pages and skip to the Google App Engine Wizard Page:
"Package" is the default package name which will be used to generate project contents. Change it to any desired name.
The deployment section allows to configure your Application ID and version to deploy to. You can omit the Application ID while you’re working with the local Development server, but you have to provide a valid Application ID before deploying to App Engine. Clicking the "My applications" and “Existing versions” link will direct you to the Google App Engine site where you can configure your applications.
The deployment options section contains options which affect the deployment procedure. Please refer to Uploading and Managing a Java App for details.
By default, sample code is generated. Uncheck this option to generate a empty project with the required project structure (including appengine-web.xml and web.xml). The generated sample is a servlet which is registered in the web.xml file.
If you want to add any Google API libraries (such as the Google Calendar API) to your new project, select the "Open Google API Import Wizard upon project creation" checkbox. You can later add Google API libraries to your project using the Google context menu.
The new project is now created and its classpath is set to develop using Google App Engine SDK. It is fully capable of incorporating any servlet or JSP, or any other class or web artifact.
Enterprise Application (EAR)
Starting from version 1.8.2, Google App Engine supports Enterprise Applications (EAR) for modules development. To create new Enterprise Application Project, open the "New" wizard using menu or by pressing Ctrl-N (Cmd-N) and select “Enterprise Application Project”.
In opened wizard select a runtime targeted to Google App Engine SDK v.1.8.2 or newer. If you select runtime for older SDK, you cannot create EAR project for Google App Engine.
The next page of the wizard allows to add modules into EAR project:
The page lists all available projects in workspace suitable to add to EAR. Since we have created Web project named "MyFirstProject" we select it to be added to EAR. If you have to create new project to be added to EAR, press “New Module...” button.
Note, Google App Engine requires "application.xml" deployment descriptor and it will be created in any case ignoring the option “Generate application.xml deployment descriptor”. Also, not the App Engine does not support EJB Module projects...
The next wizard page is the Google App Engine page:
Notice that EAR project has Application ID and deployment options as same as in Web project. During deployment, Application ID and deployment options previously set in child Web project are ignored and only settings in EAR project will be used.
Press "Finish" and you now have your new Enterprise Application project for Google App Engine.
You can add as many Dynamic Web projects as needed into your EAR project. To distinguish different Web modules in the same EAR project a new "module" deployment descriptor tag has been introduced. Open project properties for “MyFirstProject” Web project and select the Google App Engine->Deployment property page.
If you have only one Web module in your EAR application, then you don’t need to provide module ID, value of "default" will be used.
Running project on the Server
To run the project using local Google App Engine Development Server select the "Run As" menu and then the “Run on Server” menu item. If you select Web project which is child project of EAR project, then parent EAR project will be selected to run on Server.
You will be prompted for a server to run this project:
Select Google App Engine server which was created earlier. If you skipped the server creation earlier, you will be able to create the server at this time by selecting "Manually define a new server" radio button.
By pressing the "Finish" button your project will be published to the local Google App Engine Development Server. The server will be started and internal browser will be opened and pointed to local Development Server.
Note that at this moment the server is started and synchronized. Applying changes to resources in project will cause the project to be re-published and picked up by the Development Server without restarting.
Clicking on the "MyFirstProject" link in the browser will call the MyFirstProjectServlet on the Development Server, which outputs “Hello, World”.
If you have created a server before, you're also able to start the server using the toolbar in the Servers View. The "Run on Server" and Servers View icons both create a launch configurations, so both methods of launching are equivalent. Note that the launch configuration is auto-generated and not intended to be edited by the user. If you need additional VM arguments to pass to Development Server, use the Server Editor (double-click on your server in the Servers View).
Debugging
You are able to install breakpoints on any Java class (including servlets, JPA, Web Services, etc) of a Web Application, or on JSP pages which have Java code fragments.
To debug your application, restart the server in debug mode by pressing "Restart the server in debug mode" tool button in Servers view (or select “Debug As” and “Debug on Server” menu items, if you've never run the server before).
Once you get the server running in debug mode, connect your browser (either internal or external) to Google App Engine Development Server and invoke the code being debugged (for example, click "MyFirstProject" link using sample code).
Your breakpoint will be hit, and you will be able to take advantage of all the features of the Eclipse Java debugger.
Monitoring Web Application network data
To enable monitoring, run the server (in debug or run mode), right-click on the server in Servers view and select "Monitoring->Properties":
The Monitoring properties dialog will appear:
There, click the "Add" button and add the Development Server port to do monitoring:
Note that the actual port to be monitored is not equal to the port on which the Development Server is running. By default, it’s the server port +1.
After the port is added, press "Start" to start monitoring the port:
The status will change to "Started," and this means that now it’s possible to see the data between Development Server and your browser. Open the TCP/IP Monitor view by selecting the “Window->Show View” menu item, and then choose “TCP/IP Monitor”.
Access your application by browser using the port you specified when adding the monitor (not the actual Development Server port). You will then be able to see the data in TCP/IP Monitor view.
Deploying a project to Google App Engine
After the project is associated with the server, you can deploy it to Google App Engine. Select the desired server in Servers View and press the "Google App Engine" tool button (alternatively, it’s possible to select it using the context menu) and select the “Deploy to Remote Server” menu item:
You will be prompted to log in to your Google account and, if you didn’t do it before, enter the Application ID in the project properties:
Once you’ve entered a valid Application ID, by pressing "OK" button your project will be deployed to Google App Engine and will be available at
Using JPA facet
Either during project creation or by changing project facets in project properties, it’s possible to activate JPA functionality for your project.
Click the "Further configuration available..." link to bring up JPA facet configuration page:
Select "Google App Engine (Datanucleus)" as the platform and “Google App Engine SDK” as the JPA implementation. This will set up a classpath container in your project with libs needed for using JPA. Additionally, select connection from combobox in Connection section (or click the “Add connection” link to create new connection profile).
Press "OK" to add the JPA facet to the project, add classpath container, and enable the class enhancer for classes in the project:
After the JPA facet is installed, you are able to configure classes which require enhancing in project properties. The "Google App Engine ORM" property page will appear under JPA category after you’ve installed the JPA facet:
Working with Cloud Endpoints
Cloud Endpoints work with WTP-based projects. They work similarly to how they're described in the Google Plugin for Eclipse Endpoints pages, except that you need to activate the J2EE perspective to see the Cloud Endpoints options for WTP-based projects. Take a look at the Eclipse documentation if you need more information on switching perspectives.
Once you've activated the J2EE perspective, you'll be able to see the Google App Engine WTP context menu:
From here, you'll be able to run Cloud Endpoint-related operations to generate an endpoint class, and generate client libraries for your endpoints (navigate to the GPE documentation for more information on endpoints).
If you'd like to generate a WTP-based App Engine backend for an existing Android Application, be sure to select Generate App Engine Backend from the Google App Engine WTP context menu, as opposed to the Google context menu. You'll then be taken to the Generate Backend Wizard, customized for WTP:
