1 Introduction
2 Getting Started
2.1 Creating a Web Application Project
2.2 Importing a Web Application Project from a WAR Files
2.3 Launching a Web Application Project
2.3.1 Launching
2.3.2 Relaunching
2.4 Changing the Web Application Properties
2.5 Exporting a Web Application Project
2.6 Web Application Server Configuration
2.6.1 Web Application Preferences
2.6.2 Editing the Server Configuration Files
2.6.3 Editing the WebApp Plug-in Preferences.ini File
2.7 Starting, Restarting and Stopping a Web Application Server
2.8 Running & Debugging a Web Application
2.8.1 Run a Web Application
2.8.2 Debug a Web Application
3 Concepts
3.1 Web Application Projects
3.2 Web Application Server Adapters
The WebApp Plug-in is a tool designed to help with the development of web applications within Eclipse.
The plug-in provides the ability to:
The plug-in also provides some debug support and a framework for developing web application server adapters.
To create an empty Web Application Project right click in the Eclipse Navigator panel (or Java Package Explorer) and select New > Project... or select New > Project... from the File menu.
Then from the New Project window select WebApp Project and press the Next button.
This will display the New WebApp Project wizard.
Enter a Project name for the WebApp project and press the Next button again, to display the WebApp Project Options page.
This page allows you to enter a context name and to create a default manifest file for the WebApp project. The default context name is blank, the ‘root’ context, this can be changed but the name cannot contain a space or other special characters. Selecting create default manifest file simply generates a META-INF directory and an empty MANIFEST.MF file in the WebApp project, ready for you to populate.
Press the Finish button to create the WebApp project.
The new WebApp project contains the default directory structure for a J2EE web application, including a basic web.xml file, a default web page (index.html) and optionally a default manifest directory and file (if selected in the WebApp Project wizard).
To create a new Web Application Project from a WAR file select File menu > New > Project... and then select WebApp Project from WAR from the New Project window.
This will display the New WebApp Project wizard for creating a WebApp project from a WAR file.
Enter a Project name and select the Next button to display the WebApp Project Options page.
Enter any WebApp project options and press the Next button to display the WAR File page.
This page allows a WAR file to be selected for import. Press the Browse... button to display the Open file dialogue box.
Select the WAR (.war) file to import and press the Open button and then the Finish button to create the WebApp project from the WAR file.
Note: The WAR file must contain at least a web.xml file within a WEB-INF directory otherwise the selected file will be considered corrupted, an error message displayed and the import cancelled.
The new WebApp project contains all the files from the WAR file, including the manifest directory and file. The create default manifest file option, in the New WebApp Project wizard, will be overridden if a the WAR file contains a manifest, i.e. a default manifest file will only be created if the option is selected and no manifest is available in the WAR file, otherwise the WAR file manifest will be imported. A default web page (index.html) is not created by the New WebApp Project from WAR File wizard as it is assumed the WAR file will contain it’s own.
The Java Package Explorer demonstrates other capabilities of the WAR File wizard.
During the import:
A Web Application Project can be launched, (and relaunched) directly into a web browser. This is very useful shortcut for testing, reducing the need to remember the correct URL for the web application server, project and context. The project can also be launched into a web browser in debug mode, and using the Run and Debug menus, see Running & Debugging a Web Application later in this guide.
In the Eclipse Navigator (Java Resource Explorer) right click the project and select Launch Web Application from the context menu.
A progress bar indicates the project is launching.
During the launching a number of things are happening:
If the port that the web application server is configured to start on is already in use then the following error message is displayed.
If for any other reason the web application server does not start then the launch process should timeout after 30 seconds and an error message displayed.
Opening the Eclipse console may assist in tracking down the problem.
Once a web application project is launched, it can be relaunched by selecting Relaunch Web Application from the context menu. This may be necessary if changes to the web.xml file or the server configuration files have been made since the project was last launched. It is not normally necessary to relaunch the project if changes have been made to web pages (.html) or Java Server Pages (.jsp), simply pressing the Refresh button in the browser should show any changes.
Note: The Launch Web Application menu item is disabled once a project has launched.
The only property of a web application project that can be changed is the context name. To change the context name, select Properties from the context menu of the project.
Then select Web Application from the Properties| window to display the web application project properties. Enter the new context name for the project and press the OK button to apply the changes.
Note: The web application server configuration file is automatically updated with the context name every time a web application project is launched.
A web application project can be exported to a Web Archive (WAR) file. To create a WAR file right click the project and select Web Application > Export to WAR File from the context menu.
This will display the WAR Export wizard.
Use the Browse... button to display the Save As file dialogue and enter the required file name and destination. The WAR Export wizard options allow the Java source (.java) files to be included in the archive and the WAR file to be compressed. Pressing the Finish button creates the Web Archive file at the selected destination.
Note: An empty manifest (MANIFEST.MF) file is created in the WAR file if none exists in the web application project.
Web application servers are packaged as Eclipse Plug-ins and are referred to as web application server adapters. They are installed in the same manner as any other plug-in, search the Eclipse Help for further information on plug-in installation.
A default web application server is installed with the WebApp Plug-in (this plug-in) and based on the Tomcat Plug-in that comes with the base Eclipse install. A plug-in for Jetty 4.1.2 is also available and further server plug-ins should be available soon.
Web application servers are configured in three ways. Firstly the default web application server is configured in the Web Application Preferences page. Secondly the specific configuration files for a server can be edited in the Eclipse workbench. Finally the default port number of the server can be changed, by editing the WebApp Plug-in preferences.ini file.
Currently only one web application server, the default server, can be started at a time, even though more than one server plug-in may be available. This decision was made on the assumption that an application would be developed on one server and tested against many, furthermore the resources of the platform may not support multiple servers running on multiple ports.
To set the default web application server, select Preferences from the Window menu to display the Preferences window.
In the Preferences window select Web Application Servers to display the Web Application preferences.
Selecting a new server, from the list of installed web application server adapters, and then pressing the OK button changes the default web application. The default server will then be used when a web application project is launched or when the server is started, restarted or stopped (see Starting, Restarting and Stopping a Web Application Server).
Note: If a server is currently running and the default server is changed, then a confirmation message is displayed to stop the current server.
The WebApp Plug-in stores the configuration files (and log files) for web application servers in a special ‘.servers’ project in the Eclipse workspace. This allows the configuration files to be edited within the workbench by anyone familiar with the server configuration parameters.
Note: The Filters... option for the Navigator may need to be changed to show projects starting with a ‘.’ (period).
The web application server adapter is responsible for creating the configuration files. The files are specific to each server, however they are always located in a folder with the same name as the server adapter, e.g. Jetty 4.1.2, under the ‘.servers’ project.
When a new web application project is launched its’ context and working directory are added to the relevant server configuration file by the WebApp Plug-in, e.g. context ‘helpdesk’ is added to the web.xml file of the Tomcat server. The working directory is always that of the web application project, e.g. the Helpdesk project, for the previous example.
The web application server configuration files are updated at each launch/relaunch, this allows changed working directories and/or context names to always be up-to-date. Furthermore any deleted web application projects will automatically be removed from the relevant configurations files of the default server.
So why provide direct access to the configuration files? One example is to enable changes to be made to the web application server authentication properties, e.g. the tomcat-users.xml file or the Jetty defaultRealm.properties file. This is very useful if the project uses container authentication and various users, roles and passwords need to be tested during development.
Obviously any server configuration property known by the developer can be changed and it envisaged that a number of different configurations might be kept, for a server, and possibly version controlled along with other project resources.
Finally it is worthwhile noting that if for any reason the configuration files become corrupt, through direct editing for example, then they can be deleted (or renamed) and the WebApp Plug-in will recreate new configuration files during the next launch.
Each web application server adapter should have a preferences.ini located in the plug-in installation directory, e.g. ECLIPSE_HOME\plugins\com.blueskytime.eclipse.jetty_4.1.2\preferences.ini for the Jetty 4.1.2 server adapter. The preferences.ini file contains three optional parameters port, host and timeout. For Jetty 4.1.2 these are:
port=8889
host=localhost
timeout=30
These parameters are used to set the default port and host of the web application server, and the time (in seconds) to wait for the server to start. However if, for example, a server is already running on a particular port on the development system then the port value can be changed in the preferences.ini file.|
Note: The preferences.ini file changes may not take effect until Eclipse is restarted. If one or more of the values are not set then the values default to 8080, localhost and 30 respectively.
A web application server can be started, restarted and stopped independently of a web application project. To start the default server right click the project and select Web Application > Start Server from the context menu.
Note: A web application server can also be launched using the Run and Debug menus (see Running & Debugging a Web Application Project).
To restart or stop a running web application server, right click the project and select Web Application > Restart Server or Web Application > Stop Server from the context menu.
Note: The Start Server option is disabled if a server is running and, likewise, the Restart Server and Stop Server options are disabled for a stopped server.
A web application project and/or server can be started using the Run and Debug menus from some Eclipse perspectives. A project can also be launched into the Debug Perspective from the context menu.
Note: Only project class files can be debugged, JSP debugging is not currently supported.
In the Java, Java Browsing, Java Type Hierarchy or Debug perspectives optionally select one or more web application projects, then select Run As > Web Application from the Run menu.
Note: A web application server cannot be stopped from the Run menu. It can be stopped by selecting a web application project, and then selecting Web Application > Stop Server from the context menu, or by selecting Terminate from the Console view.
This will add any selected web application projects to the default web application server and start the default server but will not open the project in a web browser. A Launch Shortcut, for the web application server, is created in the Run menu and can be used to run or re-run a web application server.
Note: A launch shortcut is also created when a web application project is launched from the context menu (see Launching a Web Application Project).
If the default web application server is running when the launch shortcut is selected. Then a confirmation message is displayed to restart the current server.
If the selected launch shortcut is not the default web application server.
Then a confirmation message is displayed to set the default server to the server referenced by the launch shortcut.
In the Java, Java Browsing, Java Type Hierarchy or Debug perspectives optionally select one or more web application projects, then select Debug As > Web Application from the Debug menu.
or select Debug Web Application from the context menu (this will also open the project in the default web browser).
This will add the selected web application projects to the default web application server, start the default server in debug mode, and open the Debug Perspective.
A Launch Shortcut, for the web application server, is created in the Debug menu and can be used to run or re-run a web application server in debug mode.
Note: If the web application server does not support debug mode then a warning is displayed and debugging is cancelled.
The WebApp Plug-in adds two new concepts to the Eclipse workbench, Web Application Projects and Web Application Servers. The following describes these concepts in more detail and it is assumed that the user has a basic understanding of the Eclipse workbench and the JDT Plug-in.
The Web Application Project is a special case of a Java Project and therefore requires the JDT Plug-in. It has a minimum directory structure and set of files:
Apart from a Web Application Nature (see Eclipse Help on natures), to identify it as a Web Application Project, and a Context Name property, a Web Application Project is no different from a Java Project. Therefore any changes that can be made to a Java Project can also be made to a Web Application Project, e.g. adding classpath and libraries, or changing source and binary folders.
A Web Application Server runs a Web Application. They are usually Java applications that are run by a Java Virtual Machine (JVM) and can be launched in a variety of ways, e.g. as services within Windows NT, daemons within Unix or executed at a DOS or Unix prompt.
In the WebApp Plug-in, a Web Application Server is run externally to Eclipse, i.e. not embedded, and an adapter is used to start and stop the Web Application Server as well as automatically configure the server configuration files.
Adapters are implemented as Eclipse Plug-ins that can be installed into the Eclipse workbench. Currently two adapters are available, one for the Tomcat 4.0.3 and one for Jetty 4.1.2. Adapters simply package off-the-shelf Web Application Server classes, e.g. Apache Tomcat, into a plug-in and provide an adapter class to start, stop and configure the server, and a factory class to instantiate the adapter class as a singleton.
The adapter class must implement the IWebAppServer interface and implement the following methods:
public void addContext(String contextName, String docBase, String workDir);
public void debug() throws CoreException;
public String[] getContexts();
public String getHost();
public int getPort();
public int getTimeout();
public void init() throws CoreException;
public boolean isStarted();
public boolean isStopped();
public void removeContext(String contextName);
public void start() throws CoreException;
public void stop() throws CoreException;
public void supportsDebug();
public void terminate();
A full example implementation is beyond the scope of this document, however see the WebApp Plug-in Java Docs for more details.
Although it is quite possible to write an adapter class from scratch, an abstract WebAppServer class and a fully implemented JettyServerAdapter class are available as examples. A factory class must implement the IWebAppServerFactory interface which contains the following method:
public IWebAppServer createServerServer();
It is only required to instantiate and return the singleton of the associated adapter class. The following example shows the full implementation for the Jetty 4.1.2 Plug-in:
/*
* (c) Copyright BlueSkyTime. 2002.
* All Rights Reserved.
*/
package com.blueskytime.eclipse.jetty;
import com.blueskytime.eclipse.webapp.IWebAppServer;
import com.blueskytime.eclipse.webapp.IWebAppServerFactory;
public class JettyFactory implements IWebAppServerFactory {
public IWebAppServer createServer() {
return JettyServerAdapter.getInstance();
}
}
The WebApp Plug-in provides a default server adapter for the internal Tomcat classes included with Eclipse 2.0. Therefore at least one default web application server is available with this plug-in.
