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 V126.96.36.199.
Before you continue: This article was written for WebSphere Application Server Community Edition V188.8.131.52, 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
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:
- Prerequisities for the WTP Project V1.0.1 SDK:
- WTP v1.0.1 SDK
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
Follow these administrative steps to begin using the Eclipse plug-in:
To launch Eclipse the first time after you install the plug-in tool, open a command prompt and navigate to the
eclipse_homeis your Eclipse installation directory.
eclipse -cleanat the command prompt to launch Eclipse. The
-cleanoption will ensure that the new plug-in tool is recognized. You do not need to use this option for subsequent startups of Eclipse.
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.
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:
On the Eclipse menu bar, select File => New => Other, then click Next.
On the Select a wizard panel, select Server => Server, and then Next.
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.
On the New Apache Geronimo v1.0 Server Runtime panel, specify the JRE and Community Edition server installation directory, then click Next.
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
Start and stop the server:
To start the server using the Eclipse framework:
- In the J2EE perspective, open the Servers view.
- On the Servers panel, right click on the server to be started.
- Click Start on the resulting context menu.
To stop the server using the Eclipse framework:
- In the J2EE perspective, open the Servers view.
- On the Servers panel, right click on the server to be stopped.
- 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.
Download the wasce_samples zip file from the product download page and unzip it to a known location.
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.
Start the server
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.
Import the Hello application into Eclipse IDE:
- On the Eclipse menu bar, click on File and select Import....
- On the Import panel, select WAR file and then Next.
- On the War Import panel, navigate to the
samples_install\samples\wasce\hello\target\hello-1.0.waras 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
Alternatively, you can create a new Hello project instead:
- On the Eclipse menu bar, select File => New => Project....
- On the New Project panel, expand Web and select Dynamic Web Project. Click Next.
- 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.
- On the Select project facets panel, uncheck Geronimo Deployment Plans, since we will use the plan from the Hello sample application. Click Finish.
- 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.
- Also, copy the samples_install\samples\wasce\hello\src\webapp\WEB-INF\geronimo-web.xml file to the workspace\hello\WebContent\WEB-INF directory.
- 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.
To deploy the Hello project to the server:
- On the Project Explorer view, right-click on the Hello project and select Run As => Run on Server.
- 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).
- 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
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.
Update the hello.jsp by adding a new String called
Add a breakpoint at Line 6 and save the change.
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.
Wait for the server status to change to Debugging.
Figure 4. Updated Hello application
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
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.
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.
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.
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!
- IBM WebSphere Application Server Community Edition product documentation
- IBM WebSphere Application Server Community Edition resources
- Apache Geronimo project resources
- IBM WebSphere Application Server Community Edition and Apache Geronimo forums at developerWorks
Get products and technologies
- Download the latest version of IBM WebSphere Application Server Community Edition
- Download an earlier version of IBM WebSphere Application Server Community Edition
- IBM WebSphere Application Server Community Edition technical support offerings
- Kick-start your Java apps: Download free software for rapid results