MyEclipse Web Project Tutorial

Outline

1. Preface

This document was written MyEclipse and all screenshots were taken using the default settings for 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

This tutorial presents the basic and advanced features, concepts, and techniques for rapidly getting started in the development of J2EE web applications using MyEclipse Web Tools. Specifically, this document presents how to:

• Create a MyEclipse Web Project
• Create a JSP using the JSP Wizard
• Editing a JSP using the JSP Editor
  
• Deploy, test and debug a Web Project as a web application
• Add web project capabilities to an existing Java project
• Create dependent Java projects and configure their deployment policy
• Add an external library to a Web Project and configure its deployment policy
• Customize Web Project preferences

3.  Web Project Concepts and Terminology

This section introduces the key Web Project concepts and terminology used throughout the MyEclipse product. Having a basic understanding of these concepts will enable you to work with MyEclipse Web Projects and productivity tools proficiently and intuitively.

In simplest terms:

A MyEclipse Web Project is an Eclipse Java Project that includes metadata that defines the project's web nature and a directory structure patterned after the J2EE web archive (WAR) structure .

Figure 1 presents an annotated view of the structure of an example HelloWorld web project. Note that MyEclipse web projects are decorated with a small globe icon in the top-right corner of a project folder,  .  Within this example project,  two special subfolders are shown: " src" and " WebRoot" The " src " folder contains Java source code such as Java packages and their classes and interfaces. The "WebRoot" folder is the root or base folder of a directory structure patterned after the J2EE web archive (WAR) structure . The root directory is formally known as the web-root and it contains 3 subdirectories. Web content and resources such as JSP and HTML files, tag libraries, and JAR files are located under the web-root directory and its subdirectories. Table-1 defines the role of the web-root subdirectories and resources.

Figure 1. Example Web Project file structure

Note: While the actual name of the web-root directory and its location within the project are user definable, its subdirectory structure must include the layout shown in Table 1.

Table 1. Web-root Description

Additionally, MyEclipse includes two special project members, the .mymetadata file and the optional .myeclipse folder. The .mymetadata file is an XML formatted file that defines MyEclipse-specific information such as the location of the web-root folder and other important details required by MyEclipse web tools for their proper operation. This file should be treated with equal importance as the project's corresponding Eclipse . project and .classpath files.  If you are maintaining your project within a source management system, e.g., CVS,  include the .mymetadata file under version control.

The optional .myeclipse folder is MyEclipse's transient work area for storing temporary data such as compiled JSPs. Since it is a temporary work area it may be created and deleted dynamcially by MyEclipse Web Tools. You do not need to maintain this folder under your source code control system. For example, if you are maintaining your project under CVS we recommend adding .myeclipse it the project's.cvsignore file. 

The default names for the Java source and web-root folders are defined by the Web Project template. See  Section 9  to learn more about customizing Web Project preferences. Figure 2, illustrates a Web Project for which the project folder serves as the web-root folder.

Figure 2.  Web Project serves as web-root folder

4. Creating a Web Project

This section introduces the steps for creating an example Web Project named "HelloWorld".

Step-1: Open the new Web Project Wizard by selecting File > New > Project > MyEclipse > J2EE Projects > Web Project as shown in Figure 3.

Figure 3. Opening web project wizard

Select Next >

Step-2: Enter HelloWorld into the Project Name field.

The remaining fields are prepopulated from the MyEclipse Web Project Template. This template is defined under the MyEclipse J2EE Project preferences and is described in more detail in  Section 9 .  Table-2 describes each of the fields for the New J2EE Web Project wizard shown in Figure 4.

Figure 4. Web Project creation details
 

Table 2.  New Web Project wizard field definitions

Step 3: Select Finish

Completing the wizard creates and configures the HelloWorld Web Project. Figure 5 depicts the structure of the new project from the MyEclipse perspective. To open the MyEclipse perspective select from the MyEclipse menubar Window > Open Perspective > Other and select . The Java Package Explorer is opened by selecting Window > Show View > Java > Package Explorer.

In Figure 4, note the J2EE 1.4 Library Container . This is a library of J2EE API Jars provided by MyEclipse to your project for compilation and code completion support. These API JAR files are placed only on the project's build path. Note: No J2EE JAR files or other resources are physically copied into your project.

Figure 5. Newly created HelloWorld web project

Congratulations on the creation of a MyEclipse Web Project!!! The next step is to create the project's web content and functionality. Section 5 provides a brief overview of the tools you will want to be familiar with as you develop your web application. Go to  Section 6   to begin creating web content.

5. Web Development Productivity Tools - Overview

MyEclipse provides a number of productivity tools for the development of web applications. This section outlines the key tools and their use.

• Editors
• • HTML Designer (source, WYSIWYG, preview modes)
  • JSP (source, preview modes)
  • XML, XSL (source, graphical modes)
  • DTD/XSD
  • Javascript
  • CSS
  • Text

All editors support user customizable syntax color highlighting, font, layout and formatting. The HTML, JSP, and XML editors provide real-time validation and error marking similar to the Eclipse Java editor.

• Wizards
• • Web Project creation
  • HTML creation
  • JSP creation includes Struts
  • web.xml document creation and maintenance
  • XML creation

• Validation
• • JSP including custom tags, and Java scriptlets
  • HTML
  • CSS
  • XML/XSL
  • Deployment descriptors

• Deploy, Test, and Debug
• • Deploy directly from MyEclipse to test application server environment
  • Support for over 20 different application servers
  • Launch and control an application server
    
  • Hot-swap/update debugging of JSP and Java code

• Advanced Capabilities
• • Struts Designer and Wizards
  • XDoclet support
  • Java Server Faces support
  • Hibernate support

6. Developing JSP Resources

This section introduces the process for creating a simple helloworld.jsp JSP file using the MyEclipse wizards and JSP Editor. We will continue working with the HelloWorld Web Project created in Section 4 .

6.1 Creating a helloworld.jsp

Begin by creating a JSP named helloworld.jsp using the MyEclipse JSP wizard. Access this wizard as follows:

• Select the " WebRoot " folder.
• From the context-menu (e.g., right-click menu) select New > Other > MyEclipse > Web > JSP

Alternatively you may select New > JSP from the tools as shown in Figure 6b or from menubar File > New action.

Figure 6a.  Opening JSP creation wizard from context-menu action

Figure 6b.  Opening JSP creation wizard from toolbar

The JSP wizard is a single page form that defines the JSP's location and name within the project. Please enter the following helloWorld JSP details:

Location: /HelloWorld/WebRoot Filename: helloWorld.jsp Template: Default JSP template
Figure 7.  JSP wizard, page 1

Select Finish to generate the helloWorld.jsp. From the Java package perspective verify that the file is located in the Web Root folder.

Note that the specified JSP location was under the WebRoot folder of the project. A location under the web-root folder is required to enable the JSP Editor to fully provide code completion and validation features and for the MyEclipse Deployment Service to deploy the JSP.

6.2 Editing helloWorld.jsp

Open helloWorld.jsp in the MyEclipse JSP editor by double-clicking the file or from the "Open with..." context-menu action if you have a customized JSP editor associated for .jsp extension files. Scroll to line 27 and enter the text, <% out . Followed by the ctrl->space key sequence to invoke MyEclipse code completion suggestions. Figure 8 illustrates an example JSP code completion for Java scriptlets.

Figure 8. Invoking JSP code completion

6.3  JSP and HTML Tag Completion

In the previous step you learned how to invoke the java scriplet code completion feature. In addition to scriplet completion, MyEclipse JSP editor provides code completion for JSP directives, e.g., <%@ %>, custom JSP tags, e.g., <x:if>, and HTML tags. The ctl+space sequence is used to invoke all relevant forms of code completion. Figures 9 and 10 illustrate JSP directive completion and HTML tag completion examples respectively.

Figure 9.  JSP tag completion example

Figure 10.  HTML tag completion example

6.4 Validating JSPs - Automatic & Manual Methods

MyEclipse JSP validation capabilities can help identify JSP coding errors early in the development cycle at their precise point of occurance. This section introduces the two levels of JSP validation and how problems are identified in the JSP Editor and elsewhere in the workbench. The first level, or type, of JSP validation applies to the JSP editor. This editor is patterned after the Java editor and provides real-time type-in validation on the editor's contents. The second level of validation is a build-time action that is performed automatically on JSP files whenever they are modified and saved, or when a workspace "Clean" operation is performed on the project.  Lastly, manual JSP validation may be activated from the context-menu on a single JSP file or recursively starting at a project or subfolder level.

6.4.1 JSP Editor Real-time Type-in Problem Detection

The JSP editor can detect a wide range of syntax and potential compilation problems as you enter source text. Warnings and errors that are detected in this manner are displayed in the JSP editor's overview column (right-hand side annotation column). You may enable/disable this behavior as well as modify the annotation colors from the Workbench>Editor>Annotations preference page.

Note: Real-time type-in problems will not appear in the Problems View.  

 
Figure 11.  JSP Editor real-time syntax checking error indicators

6.4.2 JSP Compilation Errors - Automatic Validation

To enable automatic JSP validation when saving the contents of a JSP Editor or performing a "Project clean..." operation ensure that the following settings are defined accordingly:

1. Launch MyEclipse with a full JDK JVM in order for the the JSP validator to have access to the Java compiler. A traditional JRE JVM does not include a Java compiler and is thus insufficient to properly validate JSP files. Note that future versions of MyEclipse will relax this requirement and provide additional preferences to improve the configurability of this behavior.

2. Enable the Build Automatically setting found under the Project menubar. See Figure 12 for the location of this setting.

Figure 12.  Workbench automatic build settings

3. Enable the project-specific validation from the project properties dialog. To access this dialog select the HelloWorld project in the Package Explorer view. Then from the context menu (right-click menu) select Properties>MyEclipse-Validation and check the JSP Validation checkbox . See Figure 13 for an example.

 
Figure 13. Web Project validation properties

Let's begin by introducing a simple syntax error in our helloworld.jsp to see how automatic validation works. On line 29 insert the following text:

<% out.println("Hello World") %>   

Note, the ';' to terminate the statement is intentional omitted to illustrate error detection and marking.

Next save the file using Ctl-S or the system menu, File->Save . During the save operation the internal MyEclipse JSP compiler analyzes the JSP file for syntax and Java type correctness by compiling the JSP. Detected errors and warning are presented in a manner similar to that of the Java editor. Figure 14 illustrates the various error/warning identifiers.

Figure 14.  JSP validation and error marking

Now add the ';' to the end of println statement and save the helloWorld.jsp file. The error should be resolved and all error related markers eliminated.

6.4.3 Manual Validation

At anytime you may manually invoke the JSP validation. Select any file or directory in the Package Explorer view of your Web Project and then from the context-menu select MyEclipse > Run Validation. This will cause JSP validation to be performed on the target resource(s). In the case of a selected directory or project, validation will be performed recursively on all of its files and subdirectories.

Figure 15. Invoking JSP validation from context-menu action

6.4.4 Configuring MyEclipse Validation Preferences

You may enable/disable MyEclipse automatic JSP validation at either a system-wide level by modifying the MyEclipse validation preferences or at the individual project level using the Web Project's MyEclipse-Validation properties. Figure 10 depicts the MyEclipse default validation preferences. To access these preferences using the menubar path, Window > Preferences > MyEclipse > Validation .

Figure 16.  MyEclipse validation preferences

MyEclipse validation preferences can be overridden at the project level by modifying the validation properties of each Web Project. To access these properties select the Web Project. Then from the context-menu (right-click menu) select Properties > MyEclipse-Validation . The project validation settings will take precedent over the MyEclipse system-wide validation preferences.

Figure 17.  MyEclipse Web Project validation properties

7. Deploying, Testing, and Debugging a Web Application

7.1 Deploy Web Project

In this step we will deploy the HelloWorld Web Project to a Tomcat 5 server. For application server configuration details please review the Application Servers Tutorial document. From the Java Package Explorer view, select the HelloWorld project. Then use either the MyEclipse deploy icon on the toolbar (Figure 18) or the Web Project context-menu (Figure 19) to launch the Deploymentment Management Dialog.

Figure 18.  Accessing the Deployment Management Dialog from the MyEclipse toolbar

Figure 19.  Accessing the Deployment Management Dialog from a context menu

From the Deployment Wizard shown in Figure 20a & 20b, select Add followed by Tomcat 5 as the target server followed by Finish . This will deploy the Hello World project under the Tomcat-5 work area in exploded WAR format.  The context-root under which the project is deployed is "/HelloWorld" and is accessible at http://localhost:8080/HelloWorld . Recall that the context-root is a user-defined Web Project property, see MyEclipse-Web properties available from the Web Project context-menu>Properties>MyEclipse-Web.

Figure 20a. Deploying to the Tomcat Server - Selecting the Project

Figure 20b. Deploying to the Tomcat Server - Selecting the Server

The Exploded Archive deployment mode utilizes the MyEclipse "Sync-on-Demand" technology to continuously synchronize projects with their respective deployments.  Thus when you add, modify, or remove files in your project the deployed instance(s) will be automatically synchronized at the time of the change. Therefore you do not need to worry about inconsistent state between your project and the application servers to which an application is deployed.  At any time that you wish to discontinue "Sync-on-Demand" deployment for a project, simply undeploy the project using the Deployment Wizard again.

To undeploy the HelloWorld web application, access the Manage Deployments dialog from the toolbar. Select the project and server you wish to undeploy. Complete the undeployment operation by selecting the Remove button.

Figure 21. Undeploying HelloWorld from the Tomcat Server

7.2 Testing a Deployed Web Project

We need to launch Tomcat in order to test the HelloWorld application.  A properly configured the Tomcat 5 Application Server Connector is a prerequisite for completion of this section.  Please see the Application Server Tutorial for details on how to configure the connector properly.  Once the server is configured, from the MyEclipse Server toolbar select Tomcat > Start (see Figure 22).  Monitor Tomcat's startup progress in the console.

Figure 22.  Starting Tomcat

Verify that the output includes a message similar to the following:

 INFO: Installing web application at context path /HelloWorld from URL file:C:\dev\webservers\Tomcat5.0\webapps\HelloWorld
					

Open a web-browser to the URL location: http://localhost:8080/HelloWorld/helloworld.jsp. It will take several seconds to open this page as Tomcat must first compile the helloWorld.jsp page before it can be presented. Your output should be similar to that of Figure 23.

7.3 JSP Debugging

Open the JSP editor on the helloWorld.jsp file created earlier. If you corrected the errors we intentionally introduced in Section 6.4.2 there should be no error markers on any line of this file. Now, inside the scriplet code starting on line 29 add a breakpoint by double-clicking in the left margin of the editor on the scriplet line (See Figure 24).

Figure 24. Setting JSP breakpoint

Next, from your web-browser refresh or revisit the http://localhost:8080/HelloWorld/helloworld.jsp page. This time you should observe the Eclipse workbench activate the Debug perspective and the execution suspended at the helloWorld.jsp breakpoint (see Figure 25). The suspended line is marked with inverted color background and foreground colors. All Java variables and constructs are visible and available for modification in the Variables View.  Additionally you can select a parent stack-frame in the stack view and invoke "Drop to frame" to rollback the stack and reenter the JSP.  Doing so will allow you to step through execution of the JSP line by line.

Note: if execution continues past the breakpoint without suspending, check the breakpoint marker. If it does not include a checkmark then it has not been registered and activated with the Tomcat JVM.  This typically occurs when your server does not support the JSR045 specification to enable native JSP debugging or your project. In such cases review the server provider's release notes, e.g., Tomcat 4.X does not support JSP debugging natively.

Figure 25.  JSP breakpoint activation

8.  Working with an Existing Web Project

If you have an existing Eclipse Java project you may enable it for use with MyEclipse Web Tools by adding MyEclipse Web Capabilities to the project. The central requirement of the "Add Web Capabilities..." action is that the resulting Web Project must include a web-root folder who's contents are patterned after the "web archive" subdirectory structure described in Section 2 . If the Java project does not originally support this web-root directory structure the Web Capabilities wizard will create it as part of its actions.

Note that while most of the MyEclipse Web Tool editors will operate with limited functionality on Eclipse web resources that are not part of a MyEclipse Web Project you are encouraged to upgrade your Java projects to MyEclipse Web Projects for maximum convenience and support.

Following is the upgrade process for adding MyEclipse Web capabilities to a Java project:

Step 1:  Select the Java project followed by MyEclipse > Add Web Capabilities... from the context-menu or the MyEclipse menubar entry. This will open the "Add Web Capabilities" wizard. See Figures 26 and 27.

Figure 26. Invoking the Web Capabilities Wizard

Figure 27.  The Web Capabilities Wizard

Step 2: Enter the folder that will serve as the web-root. Use the Advanced button to create a new folder if needed.

Step 3: Select Finish to update the project. The key changes you will notice to the Java project in the upgrade is the output location of the project's Java Builder Properties is set to <web-root location>/WEB-INF/classes. Also, all <web-root location>/WEB-INF/lib JAR files are added to the project's Java build path.

Step 4: Lastly relocate all project resources that are not already under the designated web-root folder to their respective web-root subdirectory location.

Figure 28. Upgraded Java project with Web capabilities

9. Customizing Web Project Preferences

MyEclipse provides a number of customizable preferences. You are encouraged to familiarize yourself with each of these. We have already seen several Web Project wizards and dialogs with prepopulated fields. The value of many prepopulated dialog fields is frequently derived from the MyEclipse system preferences. Two MyEclipse preferences that you should be aware of are the Web Project folder template and deployment policies.  See the Advanced Features section for a description of the later preferences.

To access the MyEclipse preferences do the following:

From the menubar select Window > Preferences > MyEclipse > J2EE Project > Web Project (See Figure 29).

Figure 29. MyEclipse Web Project Template preferences

Set the "Web root folder name" to "/" if you don't want an explicit web root folder.

Note: changing the Web Project template will only affect new projects, not exising projects.

10. Advanced Features

10.1 Dependent Java Project Setup and Deployment Policy Configuration

Frequently the codebase of a web application may be partitioned between a primary MyEclipse Web Project and 1 or more Java projects upon which the web project depends. Typically the role of these dependent Java projects is to localize common or shared code that has other uses beyond that of the web project. MyEclipse can be configured to package and weave dependent Java projects into the deployment of a Web Project. In this section we introduce the procedure for establishing a project dependency and configuring Web Project deployment policies for dependent projects.

10.1.1 Establishing a Java Project dependency

A dependent Java project is defined through the Web Project's Build Path properties . To access the Build Path properties dialog from the target Web Project's context-menu select Properties > Java Build Path > Projects. See Figure 30 for an example of establishing the example Logging Java project as a dependent project of the HelloWorld Web Project. Doing this enables HelloWorld to have access to the services defined by an example Logging Java project. Code completion, validation, and other tools are able to reference Logging project resources.

Figure 30. Making the Logging Java project a dependent of the HelloWorld Web Project

10.1.2 Configuring the Deployment Policy of Dependent Java Projects

The MyEclipse Web Project Deployment Service provides 3 policies that define how dependent Java projects are processed during Web Project deployment. Table 3 describes each of these policies.

Table 3. Dependent Java Project Deployment Policy descriptions

Figure 31. MyEclipse default dependent Java project deployment preferences

Individual Web Projects may override the system default behavior from the MyEclipse-Web project properties dialog (see Figure 32). 

Figure 32. MyEclipse Web Project deployment properties.

10.2 Library Deployment Policy Configuration

All Eclipse Java projects including MyEclipse Web Projects maintain a build-path that consists of a collection of Java resources similar to the Java classpath. During the build process the Eclipse compiler searches the project's build-path seeking Java classes referenced by the project's source files. A Web Project's build-path typically includes all Jar libraries contained in the project's WEB-INF/lib folder. Additionally, a Web Project's build-path may be configured to include:

1. Jar files that reside in a different location within the project
2. External Jar files that reside outside the Eclipse workspace
3. User libraries assigned to the
4. Jars exported by dependent Java projects
5. User libraries exported by dependent Java projects

To learn more about the managing Jar libraries within Eclipse see the following Eclipse help topic:  Java Development User Guide>Tasks>Building>Working With Build-Paths>Adding a JAR file to the build path .

When a Web Project is deployed it typically requires non-system resources such as the Jar libraries defined on the project build-path to be included as part of the deployment. The Deployer employs 4 library deployment policies that enable it identify the relevant build-path Jar files to be copied into the WEB-INF/lib folder of the deployment. Table 4 describes each of these library deployment policies. If the Web Project's deployment mode is "packaged" then the relevant Jar libraries are included in the resulting WAR file that is copied to the target application server's automatic deployment area. If the Web Project's deployment mode is "exploded" then the relevant Jar libraries are copied into the expanded WAR file structure in the target application server's automatic deployment area.

Table 4. Library Deployment Policy descriptions

The default deployment behavior for all external libraries is defined by the MyEclipse system preferences (see Figure 33). 

Figure 33. MyEclipse default external library deployment preferences

Individual Web Projects may override the system default behavior from the MyEclipse-Web project properties dialog (see Figure 34). 

Figure 34. MyEclipse Web Project external library deployment properties

10.3  Adding Advanced Capabilities ...

MyEclipse provides optional support for the following web-related technologies that you may wish to employ in your web project:

To add support for one of these technologies to your web project use its corresponding "Add Capabilities" wizard. Each technology addition wizard is accessible by selecting the target Web Project and then invoking the wizard from either the MyEclipse context-menu (i.e., right-click menu) or the MyEclipse menubar entry.

Figure 35. Add Capabilites actions

The use for each of these technologies and their associate MyEclipse prod__%%__uctivity tools is beyond the scope of this document. For more information visit the MyEclipse Tutorial library.

11. Summary

This concludes the introduction to working with MyEclipse Web Projects. Additional Tutorial documents are available that into editing, application server configuration, enterprise application and EJB project development, and database development. For more information visit the MyEclipse Tutorial library.