MyEclipse Application Server Tutorial

Outline

1. Preface

All screenshots are based upon the default user interface settings for Eclipse, MyEclipse, and Windows XP. If you experience difficulty with the instruction of this document, please see the User Feedback section for how to provide feedback to the MyEclipse documentation team.

2. Introduction

MyEclipse Enterprise Workbench provides developers the ability to seamlessly deploy, execute, and test their MyEclipse J2EE applications to any of over 20 different application servers including:

MyEclipse interacts with a local application server instance through an application server connector. Each connector is configured through the MyEclipse preferences. MyEclipse provides a Server Manager (see Figure 1) for central server operation and integrated controls on the MyEclipse workbench toolbar and context-menus that allow you to:

• Start an application server in Run or Debug mode
• Monitor application server operation via stdout log messages which is redirected to the MyEclipse console
• Test deployed applications through your custom test client or web browser
• Perform hot-swap Java debugging of deployed application code
• Perform JSP source-level debugging on JSR-045 compliant application servers such as Tomcat 5.x
• Stop the application server

3. Requirements

The requirements for MyEclipse application server support are: 

1. MyEclipse application server connectors require direct access to application server installation. Therefore the application server must be installed on the file system of the machine that MyEclipse will operate. Note: MyEclipse Blue Edition does support application deployment to remote WebSphere application servers.

2. To support JSP source level debugging, your application server must support JSR-045 specification for debugging of non-Java source code.
   

3. Hot-swap debugging requires that your application server be launched with a JDK 1.4.x or later virtual machine. If you are working with an older application server that requires JDK 1.3 debugger, breakpoints will be honored but hot-swapping of modified code in your MyEclipse workbench will not be possible since 1.3 JVM's do not support the JPDA specification.

4. Application server connectors should be configured to launch their respective application server with a full JDK (javac included) environment. Do not use a JRE.   The full JDK is required because it provides a Java compiler that is required by all application servers to compile JSP pages or dynamically process and deploy EJBs.  A full JDK for your platform can be downloaded from Sun Microsystems at http://java.sun.com/j2se/downloads/index.html

4. Server Manager Overview

Opening the Server Manager view:

	Launch the selected application server in Run Mode
	Launch the selected application server in Debug Mode - supports hot-swap debugging
	Restart the selected application server in its current launch mode
	Stop the selected application server
	Configure the selected application server connector
	Open the Deployment Manager
	Undeploy the selected deployed J2EE project
	Redeploy the selected deployed J2EE project
	Browse the auto-deployment area of the application server and view the deployed projects

5. Browsing Application Server Connectors

To configure a connector for you favorite application server, open the Application Server Connector preferences dialog using the button on the Server Manager toolbar or from the main Eclipse menubar by choosing Window > Preferences > MyEclipse.

When the preferences dialog appears you may need to expand the left panel topics to view the Application Servers node to view the list of connectors available.  Click on the server connector you wish configure. 

Figure 3. MyEclipse application server connector preference pages

Below is an example of the main configuration page for JBoss. In addition to this page there are three additional configuration pages for specifying the JDK and launch mode to use when starting the application server and setting the classpath and DLL load paths. 

Figure 4. Example JBoss connector configuration page

6.  Connector Configuration

Configuring an application server connector is a 3-step process. It involves:

Note that some connectors may require additional configuration. Consult your specific application vendor for additional requirements.

Step-1: Specify application server installation details

Browse to and select the root directory of your application server installation (see Figure 5). MyEclipse will attempt to prepopulate the remaining connector fields with common default values used by your application server. Figure 6 depicts the default settings for the Tomcat 5 installation at the d:\dev\appservers\Tomcat 5 path.

Figure 5.  Initial Tomcat 5 server location details

Figure 6. Default Tomcat 5 server location details

Step-2:  Enabling the connector

Selecting the Enable button enables the connector to be used by MyEclipse J2EE project deployment and debugging services.

Figure 7. Tomcat 5 connector enabled

 

Step-3: Specify the JDK environment to be used for launching the application server

The final configuration step is to specify the JDK installation that the connector will use to launch the application server instance. See requirement #4 for background details for this task. The JDK information is specified on the connector's JDK preference page. Figure 8 illustrates the Tomcat 5 JDK preference page and the JDK selection list highlighted in red. If you have previously configured a JDK installation then select it now from the JDK drop-down list (see Figure 10); otherwise perform Step-3a to configure a JDK installation. The JDK list shown in Figure 8 only lists the default JRE that is used to launch MyEclipse, which is insufficient for supporting the requirements of most application servers. Therefore for the sake of this example we must perform Step-3a to complete this connector's configuration.

Figure 8.  Tomcat 5 JDK preference page 

Step-3a: Defining a new JDK installation for Eclipse

From the connector's JDK preference page select " Add".  This will open the Eclipse Add JVM dialog (see Figure 9). Note that while the fields of this dialog refer to the a JRE environment, our objective is to specify the location of a full JDK as the runtime environment, not the default JRE provided by Sun Microsystems. Do the following:

1. Enter the JRE name
2. For the "JRE home directory" field select Browse... to open a File Browser dialog (not shown)
3. 1. In the File Browser dialog navigate to the root directory of your JDK installation directory, not the JRE directory it contains. Select this directory in the File Browser and enter OK to return to the Add JVM dialog
4. The Add JVM dialog's remaining fields should be prepopulated with default values derived from the value of the "JRE home directory" field
5. Select OK to close the Add JVM dialog and return to the Tomcat 5 JDK preference page
   

Figure 9.  Add JVM dialog

Now select the newly configured JDK from the JDK drop-down list.  Figure 10 illustrates selecting the newly defined JDK from Step-3a.

Figure 10. Tomcat 5 JDK preference page with valid JDK selection 

Step-4: Accept changes

Lastly, select OK to accept the changes and complete the configuration.

Note: Your application server may require additional configuration steps.  Use the additional settings pages and paths to customize the connector's launch configuration as needed. Please review all settings, as they will affect the proper launch and operation of your application server.

top

7. J2EE Project Deployment

7.1 J2EE Project Deployment Modes

MyEclipse can deploy Web, EJB, and Enterprise Application projects to any MyEclipse enabled application server. Two deployment packaging modes are supported by MyEclipse: exploded archive deployment and packaged archive deployment.

• Exploded Archive Deployment - This is a development-centric but non-standard J2EE application packaging and deployment model. Similar to packaged deployment, an application's deployable resources are organized to conform to a J2EE standard directory/file structure. But, rather than create and deploy a single archived file, the entire application resource structure - directories and files - is copied by the application server connector to the server's special deployment location for exploded archives. The MyEclipse Deployment Service, using "Sync-on-Demand" technology, will keep all MyEclipse project deployments synchronized with all source changes in their corresponding MyEclipse project.  Note: exploded deployment is not supported by the J2EE standard and is not supported by all application servers.

• Packaged Archive Deployment - This is the production-centric J2EE standard application packaging model for deployment. It consists of packaging an application's resource into a single ZIP archive file with an internal J2EE standard file structure. The resulting single archive file is then deployed to a target application server by application server's connector. Packaged archive deployment does not support incremental or automatic archive update. Thus a package deployment will become out of sync with its source project as edits are made to the project's resources. Periodic redeployment is required to resynchronize a deployed application's state with the latest version of its MyEclipse project source.
  

7.2 Deploying a J2EE Project to an Application Server

Step-1: Open Deployment dialog

To deploy a J2EE project select the button found on the toolbar of the Server Manager or the MyEclipse perspective workbench. This will launch the Project Deployments dialog, shown in Figure 11.

Step-2: Select J2EE project to deploy

Select the J2EE project you wish to deploy from the "Project" field drop-down list.

Figure 11. Deployer dialog

Next select the Add... button to open the New Deployment Wizard (see Figure 12).

Figure 12.  New Deployment dialog

Step-3:  Specify new deployment details

1. Select the desired Deployment Type, Exploded Archive or Packaged Archive.
2. In the Server drop-down list, select the target deployment server. Note that only servers that support the desired deployment type and project type will be presented as valid choices.
3. If the deployment type is Exploded Archive then the Exploded location field will be automatically filled with the appropriate deployment path, based on the type of server that is selected.
4. Select Finish to initiate the deployment.
5. The New Deployment Wizard will display a progress monitor that describes deployment progress.
6. Upon completion of the deployment the New Deployment Wizard will close and control is returned to the Project Deployments dialog.
   

Figure 13.  New HelloWorld deployment

top

8. Application Server Operation and Debugging

8.1 Launching an Application Server

To launch an application server do the following:

Step-1: Initiate application server start-up

From the Server Manager select the to launch the server in the RUN mode or the to launch the server in DEBUG mode. Alternatively from the MyEclipse toolbar select the application server management menu. Next expand the menu to the Start action of your target server and select it as shown in Figure 14.

The later launch method will launch the application server in the default mode set in the application server's connector preferences. 

Figure 14. Starting Tomcat 5 from Application Server Management toolbar

Step-2: Monitor application server start up for problems

The application server connector redirects the application server's stdout and stderr streams to the MyEclipse console. Monitor the console for server start-up problems. Figure 15 illustrates a successful startup of Tomcat 5.

Figure 15.  Successful Tomcat 5 startup process

8.2  Debugging A Deployed Application

MyEclipse extends the Eclipse debugger platform to support JSP breakpoints and debug actions. Debugging a deployed J2EE application is similar to debugging a standard Java application. From either the Java or JSP source editor you enter breakpoints in the left margin. During application server execution when execution control encounters a breakpoint the Eclipse Debug Perspective is invoked and debug information displayed.

The application server must be launched in DEBUG mode in order for breakpoints to be enabled and execution to halt in a breakpoint context. See the connector's preferences to configure the connector's default launch mode.  The default launch mode is referenced when starting an application server using the MyEclipse server management toolbar actions.

Figure 16.  JSP debugging session

8.3 Stopping an Application Server

To shutdown an application server do the following:

Step-1: Stopping an application server

From the Server Manager select the to terminate the server's execution. Alternatively from the MyEclipse toolbar select the application server management menu. Next expand the menu and select the Stop action of your target server as shown in Figure 17.

The application server connector will begin the shutdown process for the application server instance.

Figure 17.  Initiating Tomcat 5 shutdown

Step-2: Monitor application server shutdown for completion

As the application server terminates you should observe thread termination of the application server's process. In many cases shutdown progress messages from the application server will be output to the MyEclipse console. Figure 18 depicts a successful Tomcat 5 server shutdown. Notice that Tomcat process threads have been terminated and a shutdown message appears in the console.

Figure 18.  Tomcat 5 shutdown completion

top

9. Advanced: Working with Multiple Server Connector Configurations

Occasionally you may have a need to launch an application server with an alternative configuration. In such cases it is possible to create a custom launch configuration for the particular server. In this section you will learn how to create a MyEclipse Server launch configuration and how to launch a server with an alternative launch configuration.

9.1 Creating a Custom Application Server Connector Launch Configuration

1. From the Server Manager, select the configure button. This will open the server connector preferences as shown in Figure 19.
2. In the left pane, navigate to your server and open the Launch preference page.

3. Select the Create Launch Configuration button. (See Figure 20)
4. A custom launch configuration based on the server connectors default configuration details is created and opened in a custom launch configuration editor dialog. Provide a unique name for the launch configuration and customize the various launch details as needed.
   
• Select Apply to save the new MyEclipse server launch configuration and continue editing
  
• Select Debug to save the new MyEclipse server launch configuration and launch the server with the configuration's details
• Select Close to close the launch configuration window
  

9.2 Launching a Custom Application Server Connector Launch Configuration

To launch a custom MyEclipse application server connector launch configuration do the following:

1. From the menubar or toolbar select the Run>Run... or Run>Debug... action. This will open the Eclipse Launch Configuration Manager (See Figure 21)

2. In the left panel expand the MyEclipse Server node to view the custom server launch configurations.
3. Select the launch configuration you would like to execute.
4. Depending up on the mode you selected in step-1 select either the Run or Debug button. This will launch an instance of the application server with the configuration specified by the selected launch configuration.
   

Figure 22. Activating Tomcat-Custom launch configuration

The Server Manager will display the run/stop status of this new custom server launch configuration.

Figure 23. Server Manager view with custom Tomcat launch configuration

top

10. User Feedback