Using the Eclipse Plug-in for WebSphere Application Server Community Edition

Develop, deploy, and test applications on Community Edition using the Eclipse framework

With the Eclipse plug-in for IBM® WebSphere® Application Server Community Edition V1.0.1.1, developers can develop, deploy, and debug their J2EE™ applications to a Community Edition server. This article steps you through everything you need to deploy and test your J2EE applications quickly to Community Edition using the Eclipse framework, from setting up your environment to deploying and debugging your applications.

Lin Sun (linsun@us.ibm.com), Staff Software Engineer, IBM 

Lin SunLin Sun is an advisory software engineer for IBM in Research Triangle Park, North Carolina, in the Software Group WebSphere Application Server Community Edition Development Team. She received a master's degree in information science from the University of North Carolina at Chapel Hill.



November 2007 (First published 26 April 2006)

Also available in Chinese Russian

Introduction

IBM WebSphere Application Server Community Edition (hereafter referred to as Community Edition) is a Java™ 2 Platform, Enterprise Edition (J2EE) application server built on top of Apache Geronimo, an open-source application server created by the Apache Software Foundation. Eclipse is an integrated development environment (IDE), developed by an open source community for easy and cost-effective software development and deployment. The Eclipse plug-in tool provides intergration between Apache Geronimo and the Web Tools Platform (WTP) Project. The tool is built on top of the Apache Geronimo devtools subproject.

With the Eclipse Plug-in, you can perform basic administration of the server, plus you can also develop, deploy, and debug your J2EE applications to a Community Edition server. Additionally, if you want to develop portable J2EE applications that can be easily deployed to any other application server, you can use the J2EE Profiling feature included in the plug-in. Combined with Tim Francis's article, Create, deploy, and debug Apache Geronimo applications, this article provides the most recent and specific information as it applied to WebSphere Application Server Community Edition V1.0.1.1.

Before you continue: This article was written for WebSphere Application Server Community Edition V1.0.1.1, which was the current version at the time the article was published. Some of the information in this article may not be applicable to later versions. To follow along with this article, be sure to use the product version on which this article is based. If you wish, you can download the current version of WebSphere Application Server Community Edition, or you can download an earlier version by visiting the product archive page.


Download and install

Prerequisites

Since the Eclipse plug-in tool depends on Eclipse and Web Tools Platform (WTP), you will need to install the following prerequisite software before you install the plug-in tool:

If you don't have any of the above components already installed, a convenient alternative is to download the WTP all-in-one bundle, which contains all the above prerequisite components.

The plug-in tool also requires a Community Edition server on a recommended platform with a recommended 32-bit Java 2 Standard Edition (J2SE) SDK; having only a J2SE Java Runtime Environment (JRE) is not sufficient. Please refer to the product documentation (see Resources) for recommended platforms and Java environments for Community Edition and the plug-in tool.

Download and install

The Eclipse plug-in tool can be downloaded for free from the product web site. The file to download is the wasce_eclipse_plugin zip file.

Install all of the above prerequisites, before attempting to install the plug-in tool. Installation of the plug-in tool is relatively simple: just unzip the contents of the wasce_eclipse_plugin zip file to your Eclipse home directory.


Basic server administration

A note about versions
The information in this article refers to WebSphere Application Server Community Edition V1.0.1.1. Beginning with V1.0.1.2, when defining a new server, you will notice that Geronimo under vendor Apache has been replaced with WebSphere Application Server Community Edition under vendor IBM. Similarly, "Community Edition" will appear in many places where "Geronimo" is specified in this article.

Follow these administrative steps to begin using the Eclipse plug-in:

  1. Launch Eclipse:

    1. To launch Eclipse the first time after you install the plug-in tool, open a command prompt and navigate to the eclipse_home directory where eclipse_home is your Eclipse installation directory.

    2. Type eclipse -clean at the command prompt to launch Eclipse. The -clean option will ensure that the new plug-in tool is recognized. You do not need to use this option for subsequent startups of Eclipse.

  2. Switch to the J2EE persepective, which is the preferred perspective for J2EE application development using the Eclipse framework. If you are not already in the J2EE perspective, select Windows => Open Perspective => Other..., then J2EE and OK on the Select Perspective panel.

  3. Before you perform any deployment or testing activities with the server, you must define a new server and server runtime, which are two WTP concepts:

    • Server is the target server to which the J2EE application can be deployed. It contains server information such as hostname, port numbers, administrator username, password, and server type.

    • Server runtime is made up of the class libraries and their access rules for a specific type and version of server.

    To define a new Community Edition server and server runtime:

    1. On the Eclipse menu bar, select File => New => Other, then click Next.

    2. On the Select a wizard panel, select Server => Server, and then Next.

    3. On the New Server panel, make sure the Server host name is set to localhost. For Server type, select Apache, Apache Geronimo v1.0 Server. Click Next.

    4. On the New Apache Geronimo v1.0 Server Runtime panel, specify the JRE and Community Edition server installation directory, then click Next.

    5. Change the values of administrator name, password, and ports as appropriate, then click Finish.

    Figure 1 shows the newly defined server in the J2EE persepective.

    Figure 1. The newly defined server
    Figure 1. The newly defined server
  4. Start and stop the server:

    To start the server using the Eclipse framework:

    1. In the J2EE perspective, open the Servers view.
    2. On the Servers panel, right click on the server to be started.
    3. Click Start on the resulting context menu.

    To stop the server using the Eclipse framework:

    1. In the J2EE perspective, open the Servers view.
    2. On the Servers panel, right click on the server to be stopped.
    3. On the resulting context menu, click Stop.

    In addition to starting and stopping, you can also right click the server and select other actions, such as Delete, Restart, Debug, Publish, Add and Remove Projects, or Launch Geronimo Console. The Eclipse plug-in monitors the server's status and sets the stopped, starting, and started indicators as appropriate. This information is accurate even if you do not start or stop the server using Eclipse, or if your server is a remote server.


Create and Deploy your first program

One of the downloads available from the product web site is a ZIP file containing sample applications. These samples are a great way to get started using Community Edition. By deploying the simplest of these applications, the Hello sample, you can learn the basics of what you need to know to create and deploy your own applications in the Eclipse IDE.

  1. Download the wasce_samples zip file from the product download page and unzip it to a known location.

  2. Within the samples\wasce directory, the hello directory contains both the source and binary forms of the application. If you navigate into src\webapp, you will see that this is a very simple Web application.

  3. Launch Eclipse, switch to the J2EE persepective and define a new server and server runtime.

  4. Start the server

  5. When you import or create a new J2EE project, make sure your machine has Internet access. You may be asked to accept the Sun Microsystems™ license so that Eclipse can cache document type definitions (DTDs) and XML schema definitions (XSDs) for deployment descriptors and other XML documents associated with the project. If there is no Internet access, the process may appear to be hung or very slow.

  6. Import the Hello application into Eclipse IDE:

    1. On the Eclipse menu bar, click on File and select Import....
    2. On the Import panel, select WAR file and then Next.
    3. On the War Import panel, navigate to the samples_install\samples\wasce\hello\target\hello-1.0.war as the value of the WAR file, where samples_install is the samples installation directory. Set the server runtime you defined previously as the target runtime. Uncheck add module to an EAR application and click Finish.

    Figure 2 shows the imported Hello application in Eclipse. The G icon next to the Geronimo Web deployment plan (geronimo-web.xml) indicates the plan can be recognized and viewed by the Geronimo Web deployment plan editor; otherwise, without this indicator, the plan will be viewed by the plain text editor. When you develop your J2EE applications, make sure your Geronimo deployment plans can be recognized and viewed by the Geronimo Web deployment plan editor so that your applications can be deployed to the Community Edition server.

    Figure 2. Imported Hello application in Eclipse
    Figure 2. Imported Hello application in Eclipse

    Alternatively, you can create a new Hello project instead:

    1. On the Eclipse menu bar, select File => New => Project....
    2. On the New Project panel, expand Web and select Dynamic Web Project. Click Next.
    3. On the Dynamic Web Project panel, specify a project name such as Hello. Make sure the server runtime you defined previously is value of the target runtime, and make sure Add module to an EAR application is unchecked. Click Next.
    4. On the Select project facets panel, uncheck Geronimo Deployment Plans, since we will use the plan from the Hello sample application. Click Finish.
    5. Copy the samples_install\samples\wasce\hello\src\webapp\index.jsp to the workspace\hello\WebContent directory, where samples_install is the samples installation directory, and workspace is the current workspace of your Eclipse IDE.
    6. Also, copy the samples_install\samples\wasce\hello\src\webapp\WEB-INF\geronimo-web.xml file to the workspace\hello\WebContent\WEB-INF directory.
    7. On the Project Explorer view, navigate to the Hello project, right-click, and select Refresh to refresh the project. You should see the geronimo-web.xml and index.jsp files.
  7. To deploy the Hello project to the server:

    1. On the Project Explorer view, right-click on the Hello project and select Run As => Run on Server.
    2. On the Run on server panel, keep the Choose an existing server option and select the server you defined previously. If you don't want to be asked again for the server you want to use, check Set server as project default (do not ask again).
    3. Click Next to see a list of available projects in your workspace and a list of projects that have been deployed to the server. Click Finish.

    You should see that http://localhost:8080/hello is opened in the newly launched internal Web browser included in Eclipse IDE.

    Figure 3. The Hello application in Eclipse
    Figure 3. The Hello application in Eclipse

You have successfully deployed and run the Hello application. It doesn't get much easier than that. If you deploy an application that is more complex (for instance, one that has dependencies on external libraries, or one that needs to map any resource references to actual resources), you can use the Geronimo deployment plan editor to build your plans. The deployment plan editor is minimal. In certain cases you will need to use the Source view to specify additional configuration and deployment elements in the deployment plan.


Debug your first application

You can start the server in debugging status and add breakpoints to debug your applications. Let's use the Hello application again as an example for debugging your first application using Eclipse.

  1. Update the hello.jsp by adding a new String called hello (Figure 4).

  2. Add a breakpoint at Line 6 and save the change.

  3. Start the server in debugging status. If your server is already running, right click on the server in the Servers view and select Restart => Debug. If your server is stopped, right click on the server in the Servers view and select Debug.

  4. Wait for the server status to change to Debugging.

    Figure 4. Updated Hello application
    Figure 4. Updated Hello application
  5. In the Project Explorer view, right click the Hello project and select Debug as => Debug on Server. Change to the Debug Perspective if it is not changed automatically for you. Your newly created JSP is compiled, the application is redeployed to the server, and the debugger stops at the line at which you put the breakpoint. You can now step through your JSP, viewing and changing variable values as you go. When you continue execution (using the green arrow), the JSP is served into the Web browser.

    Figure 5. Debug the Hello application
    Figure 5. Debug the Hello application

Use the J2EE profiling feature

The Geronimo server runtime includes classes that are unique to that server. If you use any of these unique classes in your J2EE assets, you will be unable to deploy those assets to any other application server. In other words, your J2EE applications will not be portable. If you want to develop portable J2EE applications, use the J2EE profiling feature included in the Eclipse plug-in.

No special steps are required to install the J2EE profiling feature. As long as the Geronimo server you defined is the target runtime of your project, this feature is included and available for your project. If you project uses non-J2EE APIs, discouraged access wanings will appear in the Problems view when the project is saved. Refer to the product documentation (see Resources) on how to turn on and turn off the discouraged access warnings.


Troubleshooting

Logging

The first place to look when you encounter a problem is in the logs:

  • View server console output on the Console view in Eclipse IDE. The default server console output level is INFO. To enable the server console output level to debug, double click the server in the Servers view. On the Server Overview panel, set the console output level to DEBUG, then save the change.
  • Check the workspace\.metadata\.log file, where workspace is the current workspace of your Eclipse IDE.
  • Community Edition server logs can be found at installDir/var/log directory where installDir is the server's installation directory. The server.log file contains server startup, deployment, confirguration, application running, and server shutdown data.

Purchase support

Although WebSphere Application Server Community Edition is free, you can purchase support as an annual subscription. For more information, see Technical Support Offerings for WebSphere Application Server Community Edition.


Conclusion

The information provided in this article will help you install and begin using the Eclipse plug-in for WebSphere Application Server Community Edition. Download the Eclipse plug-in today, explore, and have fun!

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Open source
ArticleID=109309
ArticleTitle=Using the Eclipse Plug-in for WebSphere Application Server Community Edition
publish-date=11262007