MyEclipse Enterprise Application Project Tutorial

Outline

1. Preface

This document was written using MyEclipse and all screenshots are based upon the default user interface 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 features, concepts, and techniques for getting started in the development of J2EE Enterprise Applications using MyEclipse Enterprise Workbench. The lessons that will be covered include: 

1. Basic concepts of Enterprise Applications and MyEclipse Projects
2. Creating a MyEclipse Enterprise Application Project
3. Add/remove EJB and Web Module Projects
4. Importing an existing Enterprise Application (TraderX)
5. Packaging, deploying, and testing an Enterprise Application Project   

Please note that this document builds upon the lessons presented by other Tutorial documents for working with Web and EJB projects, and application servers (see Resources ). 

Some of the MyEclipse tools and features that will be introduced in this document include:

• Enterprise Application Project Creation Wizard
• Add/Remove Module Project Dialog
• XML Editor for deployment descriptor customization
• Enterprise Application packaging, deployment, and debugging services

Figure 1 depicts an example project structure of the Trader Enterprise Application and its constituent TraderEJB and TraderWeb projects. Section 6 will discuss this application in more detail.

Figure 1. Example Trader Enterprise Project

3. Requirements

Below is a list of requirements needed to replicate the examples presented in this document:

• Java SDK 1.4 or greater
• Eclipse 3.1 SDK
• MyEclipse 4.1
• A MyEclipse-supported application server.  For more information view the Application Server Tutorial.

4. Enterprise Application and MyEclipse Project Overview

A MyEclipse Enterprise Application Project (EAR Project), identified by the  icon, is a specialized Eclipse project that provides a development environment and productivity tools for the creation of a J2EE Enterprise Application. Specifically, an EAR project serves as a logical container that aggregates MyEclipse Web and EJB Projects into a single server-side deployment unit known as a J2EE Enterprise Archive (EAR). The structure of an EAR Project parallels the J2EE Enterprise application structure as shown in Figure 1. The J2EE Specification defines the runtime structure of an Enterprise Application as a collection of J2EE modules and basic file resources required by the modules.

The most common types of J2EE modules are:

• Web Module - typically represented as a WEB Archive (WAR)
• EJB Module - typically represented as an EJB JAR archive

Typically a web module provides web user-interface services and user access to the business services provided by one or more EJB modules. The J2EE specification defines the EAR as "THE" standard J2EE deployment unit. Additionally the Specification allows for, but does not require, application server vendors to support other deployment forms such as standalone WAR and EJB JARs.

Figure 2.  MyEclipse Project Model Architecture

The MyEclipse project model parallels the J2EE Enterprise Application model in the following manner:

1. MyEclipse Web Module Project - Design-time equivalent of a J2EE Web Module. A Web Module Project is identical to a basic MyEclipse Web Project with the addition of internal metadata and optional project dependencies (see Section 4.2)
   
2. MyEclipse EJB Module Project -  Design-time equivalent of a J2EE EJB Module. An EJB Module Project is identical to a basic MyEclipse EJB Project with the addition of internal metadata and optional project dependencies (see Section 4.2)
   
3. MyEclipse Enterprise Project - Design-time equivalent of a J2EE Enterprise Application. Does not contain any Web or EJB project code but rather maintains associations to module projects.
   

Note: an Enterprise Project must contain at least 1 Web Project or EJB Projects.

4.1 Project Organization, Dependencies, and Class Resolution

The J2EE Specification defines a hierarchical Java class resolution strategy for Enterprise Applications. This bottom-up search strategy is depicted in Figure 2. When any module references a Java class, its local classloader first searches that module's codebase for the class. If the class is not found local to the module, then the module makes a search request to the classloader at the next level above it. This process continues until either the class is found or the top-level Java boot classloader is reached (not shown in Figure 2).

There are 2 primary reasons why you should understand the J2EE Enterprise Application classloader strategy:

1. The classloading strategy affects how you choose to distribute classes between web and EJB modules projects. For example, if you have one or more business data objects that are passed between the user-interface elements of a web module and the services of an EJB module, by locating the data objects in the EJB module, they will be visible to both the web module and the EJB module.
   
   Two common project organization mistakes that cause classloading problems are:
   

   1. Placing data object classes either in the web module which results in runtime ClassNotFoundExceptions
   2. Copying shared classes to both web and EJB module projects. The approach typically results in hard to diagnose serialization and class incompatibility related errors, which makes the practice even worse than item 1.

2. MyEclipse J2EE projects emulate this hierarchical classloader strategy to provide you accurate build-time insight into the classloader visibility of your MyEclipse Enterprise Project and its constituent Web and EJB module projects. This is accomplished using Eclipse project dependencies as shown in Figure 3.  When a web or EJB project is added to MyEclipse EAR Project, the project dependencies are set accordingly. Do not manually modify these project dependencies. Doing so will likely introduce unnecessary compilation problems. 

Note: The MyEclipse development team felt it was a paramount requirement that the classloader emulation be supported to help developers identify hard to resolve runtime errors caused by classloader visibility problems. This is one of the reasons why MyEclipse does not support physical embedding of module code within an EAR project. Instead, an EAR project maintains associations to individual web and EJB projects as modules.

Figure 3. Project dependencies to emulate J2EE EAR classloader behaviors

5. Creating an Enterprise Application Project

This section demonstrates the process for creating an EAR Project named Test1 that will be composed of new web project and EJB project using the MyEclipse New Enterprise Application Project wizard. The web and EJB projects will be named Test1Web and Test1EJB respectively. Please recall from  Section 4  that an EAR Project must have at least 1 web project or 1 EJB project associated with it.

1. From the MyEclipse menubar select File > New > Project
2. Expand J2EE folder and select Enterprise Application Project (see Figure 4)
3. Select Next
   
   
   Figure 4. Launching the New Enterprise Application Project Wizard
   

4. Enter Test1into the Project Name field.
5. Select J2EE 1.3 option for J2EE Specification level, for maximum server portability.
6. Select Next

Table-1 below describes each of the fields for the New J2EE EAR Project wizard page shown in Figure 5.

Figure 5.  New Enterprise Project Creation Details

Table 1.  New EAR Project wizard field definitions

Field	Description
Project name	The project's name. Must be a valid Eclipse project name.
Location	Enable checkbox to specify a custom file-system location for the new project and its resources.
Directory	The default file-system location for the project is under the workspace directory for which MyEclipse was started. You may choose an alternative file location outside of the workspace directory.  Note: You may not choose an alternate directory under the workspace directory as this is not allowed by Eclipse.
J2EE specification level	Specifies the J2EE specification compliance level. Please ensure that you select the proper specification level for the J2EE features your application requires and that your target deployment application server(s) support this specification level.For example, if you are working with Tomcat 5.x or JBoss 4.x, choose J2EE 1.4 specification for the latest J2EE capabilities. Check with your application server vendor for information regarding J2EE specification level compliance. For XDoclet support to generate the supplemental EJB files, select the J2EE 1.3 specification level.  The current release of XDoclet doesn't fully support version J2EE 1.4.  Using J2EE 1.4 specification may lead to unreliable XDoclet results.
Creation Tasks	To create Web or EJB module associations for this EAR project, you must define those modules using the corresponding Define... tasks. At least 1 Define ... task must be selected.

7. Select the Create Web Module Project checkbox to create a new Web Project that will serve as a module of the new Test1 EAR project.
8. Enter a  Project name if different than default value, e.g., Test1Web .
   
   The remaining fields are prepopulated from the MyEclipse Web Project Template. This template is defined by the MyEclipse J2EE Project preferences and is described in more detail in Working with Web Projects Tutorial (Section 9).  Table-2 describes each of the fields for the Define Web Project Modules wizard page shown in Figure 6.
   
   
9. Select Next
   
   
   Figure 6. New Test1Web Project details
   
   Table 2.  New Web Project Modules  page field definitions

Field	Description
Project name	The project's name. Must be a valid Eclipse Java project name.
Location	Enable checkbox to specify a custom file-system location for the new project and its resources.
Directory	The default file-system location for the project is under the workspace directory for which MyEclipse was started. You may choose an alternative file location outside of the workspace directory.  Note: You may not choose an alternate directory under the workspace directory as this is not allowed by Eclipse.
Source folder	The Java source folder - will contain Java packages and *.java files. The contents of this folder are added to the project's Java build path.
Web root folder	The folder that will contain the web content, WEB-INF and its required subfolders. If this field is empty or "/" then the project folder will serve as the web-root folder.
Context root URL	This is the context under which the MyEclipse Deployment Service will use when deploying the new Web Project. The default value of the context-root field is the name of the project. If you are unfamiliar with the purpose of the context-root, it is the root portion of a URL that is used to access this application when deployed, e.g., http://localhost:8080/TraderWeb. You may change the context-root field to any alpha-numeric value that you prefer.
Web Project Modules	In addition to creating a new Web Project you may select 1 or more existing Web projects from the  Web Project Modules list that you would like to be part of this new EAR project.

10. Select the Create EJB Module Project checkbox 
11. Enter a  Project name if different than default value, e.g., Test1EJB. 
12. Table-3 describes each of the fields for the Define EJB Project Modules page shown in Figure 7.
    
    
    Figure 7. New Test1EJB Project details
    
    Table 3. Define EJB Project Module field definitions.

Field	Description
Project name	The project's name. Must be a valid Eclipse Java project name.
Location	Enable checkbox to specify a custom file-system location for the new project and its resources.
Directory	The default file-system location for the project is under the workspace directory for which MyEclipse was started. You may choose an alternative file location outside of the workspace directory.  Note: You may not choose an alternate directory under the workspace directory as this is not allowed by Eclipse.
Source folder	The Java source folder - will contain Java packages and *.java files. The contents of this folder are added to the project's Java build path.
EJB Project Modules	If there is already an existing EJB project in your workspace that you would like to include in this EAR, you must first uncheck the "Create EJB Project Module" option.  Then, in the EJB Project Modules list, you should see the available EJB Projects.  Check which modules you want to be included in the EAR.

13. Select Finish to complete the wizard and initiate the project creation process.

Completing the wizard creates and configures three MyEclipse projects, the  Test1EAR Project, the Test1Web project, and the Test1EJB project. Figure 9 depicts the structure of the new projects. Figure 10 shows the contents of the configured application.xml EAR deployment descriptor file using the MyEclipse XML editor. 

Figure 9.  Test1 EAR, Web, and EJB Projects 

Figure 10. Configured EAR deployment descriptor

top

6.  Adding and Removing Modules

MyEclipse Web or EJB projects may be added to or removed from an EAR project at any time as long as the EAR Project maintains at least 1 web or EJB module project association.  This section demonstrates the removal and then readdition of the Test1Web module project to the Test1 EAR Project.

Note: The process of adding or removing a module project changes the physical shape of the deployed form of an EAR project. Therefore if your EAR project is deployed, you should always undeploy it before adding or removing a module project. Use the  toolbar icon or the context-menu (right-click) and select MyEclipse > Add and Remove Project Deployments.

6.1 Removing a Module Project

This section demonstrates the process for removing the Test1Web project module association from Test1. Please note that this same process is used for removing an EJB module project association from an EAR project.

1. In the  Package Explorer view, right-click on the Test1 project. From the context-menu select MyEclipse > Add and Remove Modules to open the Test1 Module Projects dialog (see Figure 11).
2. Select the Test1Web module project followed by Remove .

The removal process performs the following actions:

1. The web module definition for Test1Web is removed from Test1's application.xml deployment descriptor
2. The  Test1Web module association with the Test1 project is removed.
3. Test1Web project dependencies on the Test1EJB  module project is removed.

Note: The codebase of Test1Web project is not altered in any other way.

Figure 11. Test1 module projects 

3. Select OK to close the Enterprise Application Modules dialog

Figure 12. Test1 project after removal of Test1Web

6.2 Adding a Module Project

This section demonstrates the process for adding a Test1Web  module project association to the Test1 EAR project. Please note that this same process is used for adding an EJB module project to an EAR project.

1. In the  Package Explorer view, right-click on the Test1 project. From the context-menu select MyEclipse > Add and Remove Modules to open the Test1 Module Projects dialog (see Figure 13).
2. Select Add to open the New Application Module Wizard .  
   
   
   Figure 13. Viewing Test1 module projects
   

3. In the New Application Module wizard select the Test1Web project. If the list is empty then there are no pre-existing web or EJB projects that are associated with this EAR project.
4. Optional:  Revise the  Context-root URI field value to a URI that you will use to access the web application's resources once deployed. This field is required.
5. Select Finish

Figure 14. Adding a Web or EJB project

The completion process performs the following actions:

1. Update the Test1 project's META-INF/application.xml with the new module definition
2. Update the Test1 project's metadata, .mymetadata file 
3. Create a project dependency from Test1 to T est1Web (see Section 4.1 for more info)
4. Create a Java project dependencies from Test1Web to Test1EJB  

Figure 15. Test1 module projects following addition of Test1Web

6. Select OK to close the Enterprise Application Modules dialog

At this point you can safely deploy or redeploy your EAR project. See Section 8 for an example of an enterprise application project deployment.

7. Installing Example TraderX Enterprise Application

When creating an EAR project, a majority of the effort is concentrated toward developing the application logic of its web and EJB module projects. Rather than repeat the lengthy information that is presented in other MyEclipse web and EJB development Tutorials we refer you to the Resources Section for their access.

In this section we will introduce you to an example EAR project known as TraderX that you may download and experiment with. The TraderX application is a simple stock trading simulation consisting of a Web Project, named TraderXWeb, an EJB Project named TraderXEJB, and an Enterprise Project named TraderX. TraderXWeb consists of JSPs through which the user enters buying and selling details for a stock symbol. When the order is executed the current JSP posts the buy/sell order to a TraderX servlet that interacts with a stateless session EJB to complete the transaction.

Task-1: Download and unzip the TraderX archive

1. Select the following link traderx_src.zip and download the ZIP file to your local machine.
2. Unzip the 3 projects into an Eclipse workspace folder that you will use with MyEclipse Enterprise Workbench

For example, your default Eclipse workspace is located at the relative location <eclipse install folder>/eclipse/workspace under your eclipse installation folder.

Figure 16. File-system view of Eclipse workspace with unzipped TraderX archive

Task-2: Import TraderX, TraderXWeb, and TraderXEJB projects into MyEclipse

1. From the MyEclipse menubar select File > Import > Existing Project into workspace to open the Import Wizard.
2. Select Browse to view the workspace contents. You may need to expand the directory tree of the workspace to view its contents.
3. Select the TraderXEJB folder followed by OK to close the Folder Browser.

Figure 17. Importing TraderXEJB from workspace

4. Select OK to close the Import Wizard and create the TraderXEJB project.
5. Repeat the import process for the TraderXWeb project followed by the TraderX project.

Figure 18 depicts the 3 projects after their successful import.

Figure 18. Imported TraderX projects

Task-3: Build the TraderX projects

1. Select all 3 TraderX projects
2. From the menubar select the Project > Clean action (see Figure 19)
3. From the Clean dialog select Clean selected projects followed by OK

Completing the dialog causes the 3 projects to be rebuilt. The rebuild process involves compilation of all Java files and validation of XML and JSP files.

Figure 19. Rebuilding TraderX projects

Task-4: Regenerate xdoclet-build.xml file for TraderXEJB project

1. Select the TraderXEJB project
2. Right-click and select Properties
3. Select MyEclipse-XDoclet page and click OK
   
   The xdoclet-build.xml contains environment specific filepaths, so it must be regenerated when shared between workspaces.  When you select OK on the MyEclipse-XDoclet property page, the xdoclet-build.xml is regenerated from your XDoclet configuration settings.  Upon completion, a new xdoclet-build.xml file will have been generated to correctly operate within your development environment.
   
   
   Figure 20. Regenerate xdoclet-build.xml file.

8. Deploying and Testing the TraderX Project

MyEclipse is able to perform application-server deployment of enterprise projects through any of the MyEclipse application-server connectors that supports EAR archives (see Resources for more information about application-server connectors). MyEclipse deployment services supports 2 deployment modes: packaged archive mode and exploded archive mode. Packaged archive mode is the standard J2EE mode and involves creating a specialized JAR archive known as EAR that is copied to the application-server's automatic deployment location. Exploded mode deployment by-passes the archive creation step; instead the file/directory structure of the archive is copied to the application-server's automatic deployment location. The benefit of the exploded mode deployment over packaged mode deployment is that the exploded mode enables MyEclipse to perform incremental file synchronization in real-time (Sync-on-Demand) with the application-server as EAR project and module project resources are modified.  Sync-on-Demand allows you to deploy your project to any number of servers and be assured that they are updated with each change to your source projects in the workspace.

In this section we deploy the TraderX project to a JBoss 4 server in exploded mode and test its services.

8.1 TraderX Project Deployment

In this section we will deploy the TraderX project and its module projects to a JBoss 4 application-server instance. Please view the Application Server Tutorial for a thorough introduction to application-server configuration and deployment. 

1. From the toolbar select the MyEclipse Deployment icon  or right-click the TraderX project and select MyEclipse > Add and Remove Project Deployments.... This opens the New Deployment Dialog.
2. In the  Project field select TraderX from the drop-down menu. Select the  Add button and select the configured JBoss 4 server.
3. You can may either Packaged Archive or Exploded Archive deployment, but exploded is recommended for the most efficient development process.
   
4. Select Finish to close the New Deployment Wizard and return to the Project Deployment Dialog.
5. Select OK to close the Project Deployment Dialog.

Figure 21. Deployment wizard

4. From the toolbar, select the application server icon,  followed by the  JBoss4 > Start action .
5. As JBoss is launched you should see its stdout/stderr messages streamed to the Eclipse Console.  Watch for a message stating that TraderX was successfully deployed. 

Figure 22. JBoss output messages during startup

8.2  Testing the TraderX Project

We will test the TraderX application using the MyEclipse integrated Web Browser to access its web pages.

1. From the MyEclipse toolbar open the Web Browser View. From the menubar select  Window > Show View > Other > MyEclipse Enterprise Workbench > Web Browser.
2. Enter the URL: http://localhost:8080/TraderWeb/html/welcome.html
3. Select Enter to view the stock trading form (see Figure 23)
   

Figure 23. TraderX Welcome page

4. In the Stock Trading web form, enter values for the Stock Symbol and Quantity fields.
5. Select Submit

Figure 24. TraderX stock trading form

When the stock trading form is submitted the transaction.jsp interacts with servlet that initiates the transaction with a stateless session EJB named Trader. The Trader EJB is only for demonstration purposes and does not interact with real trading services. Figure 25 shows Trader's stdout messages printed to the Console.

Figure 25. TraderX trade confirmation

top

9. Advanced Features

9.1 Optional Package Support Using Dependent Java Projects and Deployment Policies

MyEclipse enterprise project packaging and deployment services provide partial support for optional packages as specified by the J2EE specification.

An optional package is 1 or more standalone Jar files that a J2EE module requires for its operation. 

So in many ways the term "optional package" is a misnomer as a dependent J2EE module will not function correctly outside of the presense of such Jars. A more appropriate name for such Jars is "required packages". The J2EE specification allows optional package Jar archives to be included within an EAR archive and referenced through a Class-Path entry in the MANIFEST.MF file of any module that requires the services provided by the Jars.

Optional package deployment is more commonly needed for EJB modules that use other Jar packaged services. Unlike the WAR archive that can accomodate packaged libraries, an EJB Jar has no such provision. For example, if an EJB module uses Log4J for its logging service then the Log4J Jar libraries must be included in the EAR and referenced in the EJB module's manifest file. For a complete description and background information on optional package deployment please consult Section 8.2 of the J2EE 1.4 specification. Sections 9.1.1 and 9.1.2 define how to configure an enterprise project to support optional packages during deployment.

Optional packages are supported by MyEclipse using project dependencies, their exported Jars and user libraries, and deployment policies . 

Following is the Enterprise Project deployment process:

1. The deployment policies of each Web and EJB module project are applied to each project and their respective dependent projects and libraries. The resulting output culminates into the creation of a basic EAR archive (packaged or exploded).
2. Optional packages of an Enterprise Project implemented as standard Java projects to which the Enterprise Project maintains a project reference are archived and added into the EAR archive
3. The exported Jars and user libraries of the Enterprise Project's module projects and dependent Java projects are archived and merged into the EAR archive. This policy only applies if enterprise project has a reference to the module projects.
   

9.1.1 Configuring Dependent Java Projects To Serve As Optional Packages

To configure a Java project to serve as an optional package it must be made a dependent of an enterprise project. In an example scenario, a Test1EJB project requires logging services that are defined by a Logging Java project. Because of the limited J2EE deployment form for EJB projects use an enterprise project that includes the Test1EJB project as a module and that has a project reference to the Logging Java project.  In the example depicted in Figure 26, the Logging project is configured as a dependent project of the Test1 enterprise project. In addition Jars and user libraries that the Logging project requires should be exported on the Logging project's build-path properties. In addition to the Logging project compiled source, exporting the Logging project's Jars and user libraries will make them visible to the EAR project deployer.

Note: the exported Jar and user libraries of an enterprise project's module projects are made visible to the EAR project deployer.

Figure 26. Dependent projects of the Test1 Enterprise Project

Test1EJB project requires the services provided the Logging project therefore it must reference it as dependent project as show in Figure 27 to avoid compilation problems.

1. View the Test1EJB project references by selecting Test1EJB. From the context-menu (right-click menu) select the Properties action followed by the Project References node.
2. Select the Logging project as shown in Figure 27
3. Select OK to complete the process

Figure 27. Test1EJB project references

Now set the Enterprise Project default deployment preferences or project-specific properties to deploy dependent Java projects. Figure 29 shows the Enterprise Project deployment policy for dependent projects. Deployment preferences can be defined for each project from the project properties (see Figure 30).

Figure 29. Enterprise Project deployment preferences

Table 3. Dependent Java Project Deployment Policy descriptions

Figure 30. Test1 enterprise project deployment preferences

Lastly, use the "Create Manifest" action to create a new MANIFEST.MF file for each of the module projects of an enterprise project. 

1. Select the Test1 enterprise project
2. From the context-menu (right click) select MyEclipse > Generate Module Manifests

This action will create new MANIFEST.MF files for the Test1Web and Test1EJB projects. The Test1EJB project MANIFEST.MF shown in Figure 31 indicates that that its deployed form requires the logging.jar file for its proper execution, see Class-Path segment.

Figure 31. Test1EJB MANIFEST.MF

9.2 Library Deployment Policy Configuration

In addition to deployment of dependent Java projects, an enterprise project can be configured such that the exported Jars and user libraries of its dependent projects can be deployed.  Figure 32 and Table 4 define the enterprise project library deployment policies.

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. Enterprise project default library deployment preferences

Individual enterprise projects may override the system default behavior from the MyEclipse-EAR project properties dialog (see Figure 34). 

Figure 34. Enterprise project library deployment properties

10. Summary

This concludes your introduction to Enterprise Application Projects with MyEclipse.  Additional Tutorial documents are available that introduce working with Web Projects, editing, application server configuration, enterprise application projects and database development. For more information visit the Resources section below.

11. User Feedback

We welcome all constructive feedback. If you have comments or ideas for how to improve this document please go to the Documentation Forum on our Support Site.  MyEclipse Documentation Forum

12. Resources

• Download  MyEclipse .
  
• Visit the MyEclipse Tutorial Library for more MyEclipse tutorials. 
  
• We recommend that you complete the following prerequisite Tutorial documents before starting this Tutorial:
  • Working With Web Projects
  • EJB Development Tutorial
  • Application Deployment and Server Management
    
• To download the TraderX projects and source code select the following link: traderx_src.zip