Preloader image
Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Using TomEE in Eclipse is pretty simple since it uses the existing Tomcat 7 server adaptor that comes with Eclipse.

Quick Start

An excellent instructional video with step-by-step instructions on how to install Eclipse, TomEE and create/deploy your first project is available on YouTube here: Getting Started with Apache TomEE (Remember to select the 'Generate web.xml descriptor' checkbox during project setup. Otherwise the ejb does not get injected and you will get an error.).

  1. Download and install both Apache TomEE and Eclipse.

  2. Start Eclipse and from the main menu go to File - New - Dynamic Web Project

  3. Enter a new project name

  4. In the Target Runtime section click on the New Runtime button.

  5. Pick Apache Tomcat v7.0 and click Next

  6. Change the Name field to TomEE to indicate that this is a TomEE server rather than a Tomcat server.

  7. Set the Tomcat installation directory by clicking the Browse button and selecting the folder where you extracted TomEE

  8. Click Finish to return to the New Project dialog

  9. Click Finish to complete creating your new Project

  10. When you’re ready to deploy your project, right-click your project and select Run As - Run On Server

  11. Make sure that the TomEE environment is selected in the Server runtime environment

  12. On the Run on Server dialog, click the Always use this server when running this project checkbox

  13. Click Finish - Eclipse will start TomEE and deploy your project

Advanced installation

  1. In Eclipse, click on the Servers tab, right click and select New - Server.

  2. Select Apache - Tomcat v7.0 Server and click Next

  3. Set the Tomcat installation directory by clicking the Browse button and selecting the folder where you extracted TomEE

  4. Add your webapp to the server. Click Finish.

  5. In the Servers tab, double click on your server to open up the Overview page. Click on the Modules tab

  6. Click Add External Web Module. In the Add Web Module dialog, for document base, browse to <TomEE>/webapps/tomee. Set Path: to /tomee. Uncheck Auto reloading enabled. Click OK.

  7. Return to the Overview tab for the server.

  8. Deselect the Modules auto reload by default checkbox.

  9. If you do not want Eclipse to take control of your TomEE installation, select Use Workspace Metadata under Server Locations. Please review the Workspace Metadata Installation section below for additional steps in this scenario. Otherwise, select Use Tomcat Installation

  10. Click the Save button in Eclipse so the server configuration gets saved.

  11. Click on your webapp project, then select Project - clean. Hit OK. This will cause Eclipse to clean and rebuild

  12. In the Servers tab, right click on the server and select Publish.

  13. Start the server.

Workspace Metadata Installation

If you used Use Workspace Metadata in the Server Locations definition of the TomEE server, you will have to add TomEE specific configuration files to your Servers project in your workspace in case you need to change system properties or add containers / resources and have those reflected in the server running under Eclipse.

  1. Locate your TomEE server configuration in Workspace / Servers

  2. Right-click the server project and select Import

  3. Select General - File System and click Next

  4. Browse to your <TomEE>/conf folder

  5. Select the following files for import: logging.properties, system.properties and tomee.xml

  6. Click Finish to import the files.

  7. In the Servers tab, right-click the TomEE server and select Publish to publish the files to the Eclipse metadata folder

If you need to modify system properties or change your TomEE resources, containers, etc., you now need to make those changes in the Workspace / Servers / <`Your Server>` location and publish them to the server for the changes to take effect.

JSP Hot Deployment

If jsp changes are not being hot deployed then this is because the jsp servlet is set to development=false in the web.xml file. To allow jsp hot deployment alter this value to true and restart Tomee.

This is the relevant snippet of the web.xml file.

<servlet>
    <servlet-name>jsp</servlet-name>
    <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
    ....
    <init-param>
        <param-name>development</param-name>
        <param-value>true</param-value>
    </init-param>
    ....
</servlet>

How to use JULI for TomEE in WTP?

It seems that WTP doesn’t manage correctly Tomcat logging configuration (which needs to be done through system properties). A quick workaround is to add these properties manually:

-Djava.util.logging.config.file="<tomee>/conf/logging.properties"
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager