Before you start
About this series
Rational Application Developer for WebSphere Software is the IBM Software Development Platform that allows you to quickly design, develop, analyze, test, profile and deploy Web, Web services, Java™, J2EE, and portal applications. This series of seven tutorials helps you prepare to take the IBM certification Test 255, Developing with IBM Rational Application Developer for WebSphere Software V6 to become an IBM Certified Associate Developer. This certification targets entry level developers and is intended for new adopters of IBM Rational Web Developer or IBM Rational Application Developer for WebSphere Software V6.0, specifically professionals and students entering into Web development using IBM products.
About this tutorial
This tutorial has you create a J2EE project and import its components into Rational Application Developer. While you will be working with a fairly simple J2EE application, you are not required to write the code for it. The primary focus of this tutorial is to make sure you know how to package J2EE applications and how they are organized within the development environment. While it is not necessary to run the application to meet the objectives of the tutorial, you can do so at any time with the test environment of Application Developer. To run the application, download the sample code for the tutorial and perform the setup requirements, including building a Cloudscape database. Use the database script and instructions provided in the zip file to complete this process.
By the end of this tutorial you should have a good understanding of how to:
- Create J2EE projects
- Import and export J2EE modules
- Create and locate resources in the appropriate location of the project hierarchy
- Work with Web and Application Deployment Descriptor Editors
The tutorial assumes that you have followed the Rational Application Developer certification series tutorial track and are already somewhat familiar with the development environment. If you are unfamiliar with the environment, or J2EE applications, review all the preceding tutorials before attempting this tutorial.
To run the examples in this tutorial, install Rational Application Developer for WebSphere Software or Rational Web Developer for WebSphere Software. You can download a free trial version of Rational Application Developer for WebSphere Software if you don't already have a copy of it.
The hardware and software requirements for this software can be located at IBM Rational Application Developer System Requirements.
This tutorial teaches how J2EE projects are created and organized within Rational Application Developer, hereafter Application Developer. To get the most benefit out of it, you should already understand the fundamentals of the J2EE architecture, such as the structure of applications and how they are packaged. If you are not familiar with J2EE fundamentals, the Resources section of this tutorial has a pointer to the J2EE specification where you can learn more about the general structure of J2EE applications.
You should complete this section to run the sample application that is packaged with the tutorial. You can complete the tutorial and meet its objectives without running the application.
- Create the sample database to run the application that is provided with this tutorial. When you install Application Developer a version of the Cloudscape relational database engine is installed with it. Cloudscape can be used to host the AddressBook database. To create the database, open Cloudview. If you installed Application Developer in the default location, follow the path C:\Program Files\IBM\Rational\SDP\6.0\runtimes\base_v6\cloudscape\bin\embedded\cview.bat. If you installed Application Developer in another location, adjust the path accordingly.
- Double-click cview.bat to run the file.
- When Cloudview opens, select File > New > Database.
Figure 1. Cloudview
C:\tutorial\database\AddressBookDBas the name for the database (you can put it in a different location, but remember where you placed it because you will need this information when you later create the data source).
- Click OK.
Figure 2. New database
You have just created the database. Use Application Developer to populate it and create the tables.
- Start Application Developer to workspace
- Switch to the Data perspective.
- The following script has been provided to assist you in creating the initial database. Code this script and run it against Cloudscape, or you can follow the instructions below and import the script into Application Developer to create the database.
Listing 1. AddressBook DDL
ALTER TABLE ADDRESSBOOK.PERSON DROP CONSTRAINT FK_PERSON; DROP TABLE ADDRESSBOOK.ADDRESS CASCADE; DROP TABLE ADDRESSBOOK.PERSON CASCADE; DROP SCHEMA ADDRESSBOOK; CREATE SCHEMA ADDRESSBOOK; CREATE TABLE ADDRESSBOOK.PERSON (PERSONID INTEGER NOT NULL, FNAME VARCHAR(250) NOT NULL, MNAME VARCHAR(250) NULL, LNAME VARCHAR(250) NOT NULL, TITLE VARCHAR(250) NULL, SUFFIX1 VARCHAR(250) NULL, EMAIL VARCHAR(250) NOT NULL, ADDRESS_ADDRESSID INTEGER NOT NULL); CREATE TABLE ADDRESSBOOK.ADDRESS (ADDRESSID INTEGER NOT NULL, STREET VARCHAR(250) NOT NULL, CITY VARCHAR(250) NOT NULL, POSTAL VARCHAR(250) NOT NULL, STATE1 VARCHAR(250) NOT NULL, COUNTRY VARCHAR(250) NOT NULL, PHONE VARCHAR(250) NULL); ALTER TABLE ADDRESSBOOK.ADDRESS ADD CONSTRAINT PK_ADDRESS PRIMARY KEY (ADDRESSID); ALTER TABLE ADDRESSBOOK.PERSON ADD CONSTRAINT PK_PERSON PRIMARY KEY (PERSONID); ALTER TABLE ADDRESSBOOK.PERSON ADD CONSTRAINT FK_PERSON FOREIGN KEY (ADDRESS_ADDRESSID) REFERENCES ADDRESSBOOK.ADDRESS (ADDRESSID) ON DELETE CASCADE ON UPDATE NO ACTION; ALTER TABLE ADDRESSBOOK.PERSON ADD CONSTRAINT UK_PERSON UNIQUE (EMAIL); INSERT INTO ADDRESSBOOK.ADDRESS (ADDRESSID, STREET, CITY, POSTAL, STATE1, COUNTRY, PHONE) VALUES (1, '50 Slater Street', 'Ottawa', 'K2G OG6', 'ON', 'CN', '555-555-5555'); INSERT INTO ADDRESSBOOK.ADDRESS (ADDRESSID, STREET, CITY, POSTAL, STATE1, COUNTRY, PHONE) VALUES (2, '44 Terry Fox Dr.', 'Kanata', 'K2M 4B6', 'ON', 'CN', '555-545-5855'); INSERT INTO ADDRESSBOOK.ADDRESS (ADDRESSID, STREET, CITY, POSTAL, STATE1, COUNTRY, PHONE) VALUES (3, '123 ABC Ave.','Alphabet Town', '90210','CA', 'US', '555-555-5454'); INSERT INTO ADDRESSBOOK.PERSON (PERSONID, FNAME, MNAME, LNAME, TITLE, SUFFIX1, EMAIL, ADDRESS_ADDRESSID) VALUES (1, 'Isaac', 'William', 'Stobo', 'Master', 'Jr', 'firstname.lastname@example.org', 1); INSERT INTO ADDRESSBOOK.PERSON (PERSONID, FNAME, MNAME, LNAME, TITLE, SUFFIX1, EMAIL, ADDRESS_ADDRESSID) VALUES (2, 'Claire', 'Anne', 'Stobo', 'Miss', NULL, 'email@example.com', 2); INSERT INTO ADDRESSBOOK.PERSON (PERSONID, FNAME, MNAME, LNAME, TITLE, SUFFIX1, EMAIL, ADDRESS_ADDRESSID) VALUES (3, 'Tina', 'Marie', 'Walsh', 'Ms', NULL, 'firstname.lastname@example.org', 3);
Creating the database using Application Developer
To create the database using Application Developer:
- Create a new Java project and call it AddressBookSetup:
- Click File > New > Project > Java > Java Project.
AddressBookSetupas the Project Name.
Figure 3. New Java project
- Click Finish.
- From the menus choose File > import > Zip file.
- Browse to the directory where you extracted the downloaded source code and import AddressBookSetup.jar. Be sure to import the source code into your new Java Project. It contains only one file: Table.ddl. This script is used to create the database. The path to the zip file varies depending on where you placed it.
Your screen should look like this:
Figure 4. Import window
- Open a context menu on Table.ddl and choose Deploy... from the list of items.
Figure 5. Data definition view
- The Run Script window opens showing the various commands in the script. Accept the defaults on this screen.
- Click Next.
Figure 6. Run script window
- Choose the option Commit changes only upon success in the next window.
- Click Next again.
- Use the following image to enter the fields in the Database Connection screen:
Figure 7. Database connection screen
- Click Finish.
That's it. You have created the database. Take a second to verify the contents of the database. Verify the contents of the database within the Data perspective by using the Database Explorer view to look at the Sample Contents of each of the tables. If you are unfamiliar with the Data perspective of Application Developer, be sure to check out Part 4: Working with databases of this series.
You are now ready to create a JDBC provider and datasource in order to connect the application to the database.
Running the application (optional)
Now you need to set up a Cloudscape JDBC provider and datasource that uses the Cloudscape JDBC driver and points at the AddressBook database. To create the datasource:
- Import the solution for the AddressBook Enterprise application.
- Open the deployment descriptor for the Enterprise Application and navigate to the deployment tab, also known as the Enhanced EAR editor. On this editor, click Add beside the JDBC provider list table.
- In the next window, choose Cloudscape as the Database type and Cloudscape JDBC Provider as the JDBC provider type.
Figure 8. Create a JDBC provider
- Click Next.
AddressBookProvideras the name for the JDBC provider.
Figure 9. JDBC provider type
- Click Finish.
- Select AddressBookProvider provider and click Add next to the "Data source defined in the JDBC provider selected above" section.
Figure 10. Deployment tab
- Select Cloudscape JDBC Provider and Version 5.0 data source in the Create a Data Source window.
Figure 11. Create a data source window
- Click Next.
AddressBookDatasourcein the Name field and
jdbc/AddressBookDBin the JNDI name field as shown in the following screen and leave the default values for the rest of the entries:
Figure 12. Modify Data Source window
- Click Next.
C:\tutorial\database\AddressBookDBin the Value field for the database name.
Figure 13. Create resource properties
- Click Finish.
You are now ready to test the application.
The Web application is a very simple application designed for educational purposes and not meant for an enterprise solution. It has only enough functionality implemented to make it work. Feel free to explore the code and change it.
- To start the application, right-click on the Index.jsp file in the /jsp directory located under AddressBookWeb and run it on the server. Once your server starts up and the browser opens, the application should look as pictured below:
Figure 14. Little black book
Insert and update functionality have not been implemented, so you can only read from the database. Feel free to play with the application as much as possible to implement any other functionality.
- Click Browse the address book. The names in the database are listed:
Figure 15. Contents page
There are only three entries in the database. To add more entries, edit the DDL you used to create the database and rerun it.
- Click on any of the names to see a details page for that person. Click Isaac William Stobo to see the following page:
Figure 16. Search results page
- From Index.jsp, or Little Black Book welcome screen, click Search for person to open the Search page.
Figure 17. Search page
- You can search by either id or last name. Remember there is only limited information in the database based on the DDL scripts that you ran. The ids are 1, 2, and 3. The last names are Stobo and Walsh.
Searching on id 2 returns the following screen:
Figure 18. Search results page
- You can also search on last name. Try searching on Stobo:
Figure 19. Search page
It should return the following:
Figure 20. Results
Have fun with the application!
Creating J2EE projects
If not already open, create a new workspace in the following location: C:\devworks\tutorials\Packaging&Deployment
Figure 21. Workspace launcher
Once the workspace is open, switch to the J2EE perspective. The J2EE perspective is the ideal place to browse an Enterprise Application project hierarchy or, for our purposes, the perfect place to create an Enterprise Application. Let's do so now!
- Choose File > Enterprise Application Project from the menu.
The New Enterprise Application Project window opens and displays basic entry fields, such as the name of the project. To see advanced features of the project, click Show Advanced. Choose the appropriate J2EE version for your application and the version of target server where you want to deploy your code. Remember that Application Developer supports J2EE 1.2, 1.3, and 1.4, as well as the target servers of WebSphere Application Server 5.0.2, 5.1, and 6.0 and the Express versions of these products.
- Take a moment to explore the advanced features.
Feel free to experiment with the drop-down lists. Notice that a larger list of possible target servers appears if you change to an earlier J2EE version.
Before continuing, enter the following data in the specified fields:
- J2EE version:
- Target Server:
WebSphere Application Server v6.0
Figure 22. New Enterprise Application Project
- Click Next.
- On the screen that follows, you can choose to select existing modules or you can efficiently create new ones on the fly right here. Let's choose the latter option.
- Click New Module... The New Module Project window displays.
- Use the options shown in Figure 23 by entering the following names for your projects:
- Application Client project:
- EJB project:
- Web project:
- Connector project:
Figure 23. New module project window
- Click Finish.
- The projects should now appear in the New Enterprise Application Project window (not shown here). Click Finish again.
You have just created an Enterprise Application and four J2EE modules.
This tutorial does not cover working with Application Clients, EJBs, and JCA Connectors. It led you through the creation all four module types so you can understand how an enterprise project is organized within Application Developer's J2EE perspective.
Let's review a little background on J2EE applications. Remember that in J2EE, enterprise applications are based on a component architecture. The top level components are referred to as modules. An enterprise application can contain one of more of these modules. The enterprise application is packaged in a compressed file known as an EAR file, which is a version of a Java archive file, or JAR, used specifically for J2EE. In addition to the modules, an EAR file contains a deployment descriptor that is used to describe its contents, and to provide the runtime with instructions on how to manage the enterprise application. Each module contained in the EAR is also packaged in a compressed format. Web Modules are packaged in WAR files, EJB and Application Client modules in JAR files, and Resource Adapters in RAR files. Similar to the EAR file, each of these compressed file types also contains components and a deployment descriptor. These components, such as Servlets and JSPs, are the ones that actually run on the server. Like the one for the EAR file, the deployment descriptor for a module is used to describe its contents and to provide instructions to the Application Server on how to manage the components inside. Later on you can look at the relevant deployment descriptors in more detail.
That is how an enterprise application is organized in general. Now let's look at how an enterprise application is organized within Application Developer!
The image below shows the structure of your enterprise application AddressBookEnterprise. Be sure to explore the enterprise application within your copy of Application Developer.
Figure 24. EAR in Project Explorer view
Expand the Enterprise Applications folder in the Project Explorer view to find the enterprise application that you just created: AddressBookEnterprise. Expand the AddressBookEnterprise application to expose its structure. The application contains a visual representation of the Deployment Descriptor and the actual named file for the deployment descriptor: application.xml. These two icons represent one and the same thing. They provide a shortcut to open the editor for the EAR's deployment descriptor. You can also see the modules contained within this enterprise application using this view.
Notice two other directories contained within your enterprise application: Project Utility JARs and Utility JARs. These two projects are used to hold any "helper" jar files, or resources, that you want deployed with the application. Again, these two directories are just visual representations in the tool and do not exist in your project on the file system. Project Utility JARs contains any Java projects in the workspace that you make part of the enterprise application. Utility JARs contains any non-expanded JAR files that you want packaged in your enterprise application.
Double-click either the Deployment Descriptor icon, or the application.xml icon to open the deployment descriptor editor for the EAR. Look at the source code for the deployment descriptor. Later in the tutorial, there are more details about using this editor.
Click the Source tab of the Application Deployment Descriptor editor.
Figure 25. Application Deployment Descriptor
As mentioned before, this file provides information the application server uses to manage our J2EE application at runtime. Notice the four modules you created. Another key piece of information residing here is the context root for the Web application. The context root makes up part of our Web application's URI. The URI is structured as follows:
If you wanted to change the context root, this is one of two places where that is possible. The other is through the properties of the Web project itself.
You have just looked at the xml view of the project, which is what the application server is actually concerned with. As you have seen, Application Developer makes it a little easier for you by giving you a visual representation of this information within the Project Explorer View. The modules listed in the xml are graphically represented as shown below:
Figure 26. J2EE Modules as projects in Project Explorer view
Notice that each of the different types of Projects provides access to its deployment descriptor through an icon. For this tutorial you are only concerned with the deployment descriptors for the Enterprise Application (EAR) and the Web module (WAR). It is not required that you understand the other types of deployment descriptors for this certification.
Remove the projects you will not be using from your workspace. Remember, when you created the Enterprise Application, you also created a connector project and an application client project. As they go beyond the scope of this tutorial, select and delete the AddressBookConnector and AddressBookClient projects. The Delete Module Options window opens. Select Also delete references to selected project(s) to remove the modules from the application.xml file, as well.
Figure 27. Delete Modules Option window
When the confirmation window appears select Also delete contents in the file system. This option cleans up the files from the workspace directories on the file system.
Figure 28. Confirm delete window
After you have successfully deleted the projects, be sure to go back and look at the deployment descriptor for the EAR and verify that these two modules were removed. It should now only contain the entries for the Web module and the EJB module. You could have deleted the EJB module as well at this point, but it takes care of itself later on.
While creating the J2EE modules at the same time as the Enterprise Application is very efficient, there are many different ways to do it. You are not limited to defining all the parts of your application at creation time. You can always add a new module to an existing EAR later on. Let's do so now!
- Select File > new > Dynamic Web Project from the toolbar menu.
Choose this option when creating projects that will contain dynamically generated content like servlets and JSPs. If you are creating a Web project that only contains static documents like HTML and XML, choose the Static Web Project option instead.
- When the New Dynamic Web Project window opens, enter
BlackBookAdminas the name for the project and select Show Advanced. The advanced section is where you select the EAR project to which you want to add your module. Use the EAR Project drop-down list to select AddressBookEnterprise. Notice the New button beside the drop down. If you want, you can also add your module to a brand new enterprise application. For instance, if you didn't already have an EAR, this is a very efficient way to create one. Try it yourself... select New to see what the windows look like. Just be sure to hit the cancel button to return to this window before proceeding. Your screen should look like the following image when you are finished. You have entered all the information that you need for now.
Figure 29. New Dynamic Web project window
- Click Finish.
- If you are prompted to switch to the Web perspective, choose No.
You might normally select Yes to this window when designing Web Components such as servlets, and JSPs. In this tutorial, however, you are concerned with the structure of the projects and not the creation of the components. If you need more information about creating Web components, see Part 3: Web development in this series.
- Re-examine the deployment descriptor for your EAR. You should now see two Web modules in it. Besides finding the modules listed in the EAR DD, you will also see two separate Web projects under Dynamic Web Projects in the Project Explorer view:
Figure 30. Dynamic web projects in Project Explorer
- Application Developer organizes projects this way because you might want to reuse one of the modules in another enterprise application. By having enterprise applications share projects, you only have to load them in once and maintain the code in one place. Try this! Create a new enterprise application named
- Select File > New > Enterprise Application Project.
- Other than the name, accept the defaults on the first screen and click Next.
- Notice that the existing modules now appear as choices you can add to a new project. Select BlackBookAdmin and click Finish.
Figure 31. New EAR
- Look at how the projects are structured within the Project Explorer.
Figure 32. Shared Web module in Project Explorer
- Notice that the BlackBookAdmin.war file appears in two separate projects, while the module shows up only once under Dynamic Web Projects. This structure lets you update code in one place, the BlackBookAdmin project, and have it automatically updated in two separate projects. Delete the enterprise project named ToBeDeleted because you are not going to use it.
- When the deletion options window comes up, select Delete selected Enterprise Application project(s) only. If you choose the other option, the BlackBookAdmin module is deleted from both EARS and the workspace. On the confirmation window, select the option to delete the files from the workspace, as well.
Figure 33. Delete EAR options window
You have now seen how to create J2EE projects and modules; however, you might face the situation where you have to export your code to share with other developers or import some code that another programmer or team developed. Let's explore how to do this.
Importing and exporting J2EE modules
Although you are not developing code in this tutorial, you still need some code to work with. This is a very "real-world" situation, as a packager or deployer you are often not the developer of the whole application, nor any part of it. The J2EE specification refers to this construct, through its description of J2EE roles. Importing code provides a perfect opportunity to play the J2EE role of the Application Assembler and for you to understand how to import code into the workspace.
There is a completed version of the application available for you to download and import into the workspace. But first, delete the application that you have built so far because it uses the same project names as the completed application.
- In the Project Explorer, select and right-click AddressBookEnterprise.
- Select Delete or select the delete key on your keyboard.
- In the Delete Enterprise Application Options window, select the second option to Also delete module and utility Java projects.
- Take any other defaults at this time.
- Click Details to view the modules that you are about to delete.
- Once you have finished exploring the details, click OK.
Figure 34. Details view
- In the resulting confirmation window, choose select Also delete contents in the file system. This option removes source code from the workspace on the file system. If you don't remove it from the file system, later decide if you want to overwrite it.
Figure 35. Confirm delete
- Expand the headings for the individual modules to verify that there are no projects left in the workspace. They should all be empty. If they are not, individually delete the projects.
- As the following instructions describe, download the source files from the server, if you haven't yet done so, and import a completed J2EE project.
- Select File > Import... trom the menu.
- Browse the options that are on the Select screen of the Import window to understand the various choices that are available to you. Choose to import an enterprise application by highlighting the EAR file option and clicking Next.
- Browse to <source_code_root>\devworks\tutorials\AddressBook.ear.
- Enter the name
AddressBookEnterprisefor the EAR project name, accept all other defaults, and click Next.
Figure 36. Import window
- On the following screen, select the utility JARs for your project. A utility JAR is a resource that can be shared by all of the modules contained in the project. You have two choices at this time: Import the JAR as a JAR, or import the JAR as a project. If you want to continue parallel development on the resource, import it as a project; otherwise, import it as a JAR. Try both ways so you can see the difference. First, import it in as a JAR. To do this, do not select the check box beside AddressBookModel.jar and click Next.
Figure 37. Enterprise application import
- On the screen that follows, take the default names for the Web modules. Notice here that there is no EJB module in this version of the application. Any database access that the application does is through JDBC. The JDBC code is in the AddressBookModel.jar that you imported on the previous screen.
Figure 38. EAR Module and Utility JAR projects
- Click Finish to import the application.
- If you get a prompt to switch to the J2EE perspective, click Yes.
- Expand the various modules to see what was created when you imported the ear file.
- Your Project Explorer view should look similar to the following:
Figure 39. Utility JAR in Project Explorer
Notice that you have an enterprise application, two Web modules, and a Utility JAR. When you import code as a Utility JAR, only the binary code is imported into the workspace. If you don't have access to the source code, or do not want to do parallel development on shared resources, importing a Utility JAR gives your application compile time and runtime access to the code. This choice is fine if you are not in control of the source code for the Utility JAR or, more particularly, if it is a shared resource and you don't want to make changes to it because it would affect other projects.
- Open up the deployment descriptor for the EAR file and look at it.
Figure 40. Module tab
On the module tab there are two Web applications: AddressBookWeb.war and BlackBookAdmin.war. The Project Utility JAR's window is empty. If you had imported the Utility JAR as a project, it would display here. You imported it as a Utility JAR instead, so it shows up as a JAR file in the classpath of the Web module instead.
- Close the deployment descriptor editor and right-click on the AddressBookWeb module to open its properties.
- When the context menu opens, choose Properties.
- In the Properties window, select Java Build Path from the left side, as shown in Figure 41. With the Libraries tab selected, you should see the AddressBookModel.jar in the list of entries. This means that the classes found in AddressBookModel.jar are in the class path and available to the Web project.
Figure 41. Web project properties
- If you would like to try running the application, review the "Setup" and "Running the application" sections in this tutorial for the details on how to do that.
- What would have happened if you had alternatively imported the module as a utility project? Delete the Enterprise project as you did before. If you can't remember how, go back and review the information in the previous steps.
- After the deletion is complete, verify that the workspace is empty.
- Import the application again. Right-click the Enterprise Applications folder and choose Import... > EAR file from the menu options.
- Browse to <source_code_root>\devworks\tutorials\AddressBook.ear.
AddressBookEnterprisefor the name and click Next.
- This time select the check box to import the jar as a utility project:
Figure 42. EAR import
- Click Next and notice that the utility jar file now shows up as a contained project. You can change the name of any of the projects on this screen. You might do this if one of the projects was already in the workspace and you were loading an older version for comparison's sake.
Figure 43. EAR Module and Utility JAR Modules
- Click Finish.
- Examine the structure of your project once again.
Figure 44. Project Utility JARS in Project Explorer
There is nothing under the Utility JARs folder here, as there was in the previous section. Now the utility project is placed in the Project Utility JARs folder.
Another difference is that you now have a Java project created under the Other Projects directory. Use this approach to update utility code in parallel to a Web project. If you make any source code changes to the AddressBookModel project, the J2EE application within the development environment picks them up.
Take a moment to understand how the new project is placed in the deployment descriptor. If you open up the application deployment descriptor (application.xml) and select the Modules tab, you should see that the AddressBookModel.jar file was added to the deployment descriptor editor under Project Utility JARs.
Figure 45. Module tab
Because the Utility JAR appears here, it must appear in the source code of application.xml, right? If you look at the Source tab, however, you notice that it does not appear anywhere in the source code. How then is this information used?
The main place to access this information is through the Project Explorer view
- Navigate to the AddressBookWeb project contained under Dynamic Web Projects. Once you have found it, open the context menu and select Properties.
When the Properties window for the project opens, locate the Java JAR Dependencies option:
Figure 46. Web project properties window
With Java JAR Dependencies selected, you should notice that the AddressBookModel.jar appears in the list of Available dependent JARs. If you check the check box next to AddressBookModel.jar, an entry is added to the manifest file of your Web project.
- Let's look at the manifest file now! The manifest file is located in the Web project in the following location: AddressBookWeb > WebContent > META-INF > MANIFEST.MF
- Open this file to see its contents. You can see that it contains minimal, but critical, information for our project. In this instance it only contains Class-Path information. Setting up the JAR dependency makes the classes in AddressBookModel.jar available to your Web module. You can alternatively open the MANIFEST.MF file by using a context menu and opening it with the JAR Dependency Editor.
Figure 47. Manifest file
You have now seen how to import applications into Application Developer. You can also import modules into an existing project. To try this:
- Open the context menu on the Web module AddressBookWeb and export it as a WAR file.
- Export your Web module and then import it again as a separate module.
Figure 48. Export select window
- Make sure that AddressBookWeb is displayed as the Web project. If it's not, click Browse to locate and select it.
- Enter a destination for your WAR file, such as
C:\exportdemo\AddressBookWeb.war. If the directory does not exist, the tool creates it for you. Make sure the destination ends with .war or you get an error.
- Check Export source files because you want to be able to import them back into the tool later.
Figure 49. Exporting AddressBookWeb.war
- Click Finish.
- Import them back into the project: Choose File > import > WAR file.
- Use the Browse button to navigate to the WAR file you just exported (C:\exportdemo\AddressBookWeb.war).
Application Developer is intelligent enough to realize that you already have a Web Project named AddressBookWeb inside the workspace, so it suggests an alternative of AddressBookWeb1. You can import the project under different names, in case you want multiple versions of it in the workspace at the same time.
- Change the name to
- Select Add module to an EAR project.
- Select AddressBook as the EAR project.
Figure 50. Importing AddressBookWebv2
- Click Finish.
- If you are prompted to switch to the Web perspective choose No.
- Take a look at the Project Explorer, to see how your Enterprise Application is now organized. Notice that there is an error (red X) beside AddressBookWebv2. What do you think is causing this error? Look in the Problems view and see if you get any information that helps you there.
Figure 51. Viewing errors in Project Explorer
If you think that the problems are related to class-path issues you are correct. Fixing these errors is a perfect opportunity to examine how resources are organized in Application Developer. You will fix these errors in the next section of the tutorial.
Creating and locating resources in the appropriate location of the project hierarchy
In the previous section you imported a new Web module into your enterprise application. Upon importing it, you should have noticed several errors as shown in the following Problems view:
Figure 52. Problems window
Error descriptions in a particular class stating cannot be resolved or is not a type, mean there is a class-path problem or the class does not exist. These errors occur here because AddressBookWebv2 is trying to use classes that are located in the AddressBookModel project. Recall that you imported that project as a Utility JAR in the last section. As a quick review, open the Deployment Descriptor on the Enterprise Application.
The Module tab lists both AddressBookWebv2.war and AddressBookModel.jar. Having them both listed here means only that the Enterprise Application knows about both of them; they do not necessarily know about each other.
Figure 53. Viewing details in Module tab
The key information necessary to let one module know about the existence of another module is in the projects manifest file. Open the manifest file of AddressBookWebv2. The Class-Path information for AddressBookModel.jar should already be there since this is a complete copy of your other project. Remember that class-path information helps the compiler and runtime find the required classes.
Figure 54. Manifest file
Review where you originally set this information.
- Right-click AddressBookWebv2 and select ...Properties.
- Locate and select Java JAR Dependencies from the left side of the window. You should see AddressBookModel.jar presented in the list of Available dependent JARs. Any utility projects that are listed in the EAR deployment descriptor are also shown here. If your project requires access to classes that are in one of the utility JARs, check them here. The tool then creates an entry in the Web project's manifest file.
- If you are showing errors in your Problems view related to class-path issues, try the following:
- Uncheck the box next to AddressBookModel.jar.
- Click Apply.
- Click OK.
The tool rebuilds your class-path with the new information. The errors should still be there.
- Now fix the errors:
- Go back into the Properties editor as before and this time check the box next to AddressBookModel.jar.
- Click Apply.
- Click OK.
Your class-path issues should now be resolved.
Figure 55. Web project properties
So far you have only used a utility project that was created for you; you can also create one and should place it in an appropriate within your project hierarchy.
To create a resource to be used by your J2EE project, first create a Java project to contain it.
- Select File > New > Project > Java > Java Project.
- Click Next.
- Name it
Figure 56. New Java Project window
- Click Finish.
- Click No if the tool asks you to switch perspectives.
You should now have two projects -- AddressBookModel and ResourceProject -- listed under Other Projects with the Project Explorer view as pictured below:
Figure 57. Viewing a java project in Project Explorer
The code that requires access to your classes determines where to place them:
- If the classes are to be used only by a single Web project, they belong in the Web project, itself.
- If the classes can be used by many different modules, place them in the EAR file, as you had done earlier, and set up a dependency.
- If the classes can be used by many different Enterprise Applications, bundle the resource up with each EAR, or consider creating a shared library for the applications on the Application Server. There are trade-offs to both approaches; the Resources section contains a link to an interesting article on packaging and deployment that provides information about both approaches.
The second item in the preceding list is most relevant to this discussion. To package ResourceProject as part of the J2EE application:
- Open the Deployment Descriptor on the EAR file...application.xml.
- Go to the Module tab and click Add under Project Utility JARs.
Figure 58. Adding a resource to application.xml
- Select ResourceProject and save your changes.
The utility project is now packaged up with your Enterprise Application when you export it. To make the project available to the other modules, use the Property editor to make Java JAR Dependencies as before.
So far, you have done a lot of work with the Deployment Descriptors; The next section provides the opportunity to explore them in more detail. You don't need ResourceProject or AddressBookWebv2 anymore, so feel free to delete them.
Working with Web and application deployment descriptor editors
Take another look at the deployment descriptor editors to make sure you are familiar with them. The application deployment descriptor editor has five tabs. The output from this editor goes to three different xml files: application.xml, ibm-application-bnd.xmi, and ibm-application-ext.xmi. The first file, application.xml, is the standard deployment descriptor for the Enterprise Application Archive or EAR file. It is defined in the J2EE standard and is portable across all J2EE 1.4 compliant servers. This tutorial does not include details about every attribute of the deployment descriptor, but knowing the attributes is necessary if you want to do serious J2EE development. The Resources section contains a link to the J2EE specification, which explains all of the attributes of this file in detail, including the application.xml's DTD.
The purpose of this deployment descriptor editor is to make XML editing more intuitive. When using this editor, you don't have to know every detail of the application deployment descriptor's DTD. Take some time to explore the file.
First look at the Overview tab. It contains information such as the Display name of the project. The display name is the name that visual tools, such as Application Developer, use to display the project internally. Most other items are self-explanatory, as you have worked with them in previous parts of this tutorial. One piece you haven't looked at is the WebSphere Extensions section. You won't use the information here, but feel free to update the deployment descriptor in any way you choose. If you still want to run the application, be sure not to save it when you close the file.
Let's play a little. Enter
60 seconds for the Reload interval and check the box next to Shared session context. These are both IBM extensions to the J2EE. The first option, Reload interval, specifies a time in seconds for scanning the J2EE application's file system for any changes. The default is 0. The other option lets you share your Http Session context between Web applications in the same EAR project. In the case of your project, checking this off would allow servlets in AddressBookWeb and BlackBookAdmin to share session information. Both of these items go beyond the scope of the J2EE, so IBM chose to keep that information in a separate file named ibm-application-ext.xmi. This file is not visible in your workspace unless you have made the changes noted above and saved the information.
Figure 59. Overview tab
Once you have saved the deployment descriptor, double-click on the ibm-application-ext.xmi file, under META-INF, to look at its contents. Yours may not look exactly like the following screen-shot because it has been reformatted for demonstration purposes. Notice the two items appearing in this file. When you deploy the project to the server, this file is deployed with it so the server has this information. If you put it there only for testing purposes, set it back to its defaults or your application may not behave as expected on the server.
Figure 60. IBM extensions xmi
The second tab is the Module tab. You do not use it again here, so if you need more information on it, review the previous sections of this tutorial.
Figure 61. Review of Module tab
Another tab of interest is the Security tab. J2EE security is beyond the scope of this tutorial, but this is where you create J2EE security roles and map them to resources in either an LDAP server or your local operating system's security. The following screen shot shows a J2EE role name, Manager, mapped to a local OS security called, Admins. This information is kept in two different places; the role is kept in application.xml and the linkage, or binding, between the security role and the actual security resource is kept in ibm-application-bnd.xmi. Again ibm-application-bnd.xmi is not visible unless you make the changes mentioned and save the file. Feel free to try it because it won't affect anything unless J2EE security is enabled.
Figure 62. Security tab
Notice the Role name in the picture below. It is part of the J2EE, so it is kept in this file.
Figure 63. Source tab
The binding between the role and the physical resource is implementation-specific. The following approach shows how IBM does this with an xmi file that lets you export this configuration with your application. The other option is for the deployer to map these at deployment time.
Figure 64. IBM bindings xmi
The last of the screens covered in this deployment descriptor is the deployment tab, also known as the Enhanced EAR tab. This is where you configure your test environment, as you may have done earlier if you chose to test the application on the server. If you need detailed instructions to do this, see the Running the Application section of this tutorial.
The deployment tab is new in Application Developer Version 6. It serves two purposes within Application Developer. First, it is where you configure the resources, such as data sources, substitution variables, or shared libraries for your test server. Second, it lets you create enhanced EARs that let you export your configuration with your application. The reason to export the configuration with an application is to guarantee that the application behaves the same way on all servers. Be aware, however, that you are overriding configuration that the administrator has placed on the server instance. It is usually best to remove this configuration before you export your application for deployment, or have the administrator disable this function on the application server upon installing the EAR file on the production machine.
Once you have edited this tab, the tool creates a directory under the Enterprise Application's META-INF directory named ibmconfig. The easiest way to remove your test configuration is to delete this directory before you export your application.
Figure 65. Deployment tab
The Source tab contains the source code for any standard application elements that you have changed on the previous tabs. Notice that it lists the modules that make up your Enterprise Application, the servlet-context roots for the Web modules, and any security roles.
Figure 66. Source tab
The next file of interest is the Web deployment descriptor: web.xml. To know all of the tags and attributes of the Web Deployment Descriptor is complicated and that is why there are certifications dealing specifically with this task. This tutorial focuses on gaining a familiarity with the Web Deployment Descriptor editor and how to use it, like learning some of the fundamental tabs and the information that is contained within them.
If you want detailed information on all of the tags and attributes of Web.xml, the Resources section contains a link to the Servlet specification.
Like the Application Deployment Descriptor, the Web Deployment Descriptor has an editor designed to make entering information into web.xml more intuitive and less error prone. The Web Deployment Descriptor editor, like the Application Deployment Descriptor editor, is responsible for maintaining three files: web.xml, ibm-web-ext.xmi, and ibm-web-bnd.xmi. All three are packaged with an application when you deploy it into WebSphere Application Server. The first file, web.xml, is the deployment descriptor for the Web application. The Web container of the application server uses the information in this file to manage the runtime environment for servlets and JSPs. The structure and grammar of this file is mandated by the J2EE. Let's look at some of these features first.
Figure 67. Web.xml in Project Explorer
The Overview page of the editor provides an overview of all the features and attributes of Web.xml all in one place. Clicking on the details button beside any of the items takes you to the appropriate page within the Deployment Descriptor editor to edit them. Try it! Click Details beside AddressBookServlet in the Servlets and JSPs section of the page. What happened? You are now on the Servlets page of the editor.
Figure 68. Overview tab of web.xml
The Servlets page of the editor is used for entering information that a Servlet might need at runtime. Select AddressBookServlet in the list on the left hand side. Notice that some of the other fields in this page of the editor are now populated with information specific to this servlet, including its display name and class name. There is also a section to edit URL mappings to the Servlet. Remember that URL mappings make up part of the URI of a Servlet, where the structure of a URI is http://<host:port>/<servlet-context>/<URL_mapping>. This editor provides a convenient place to change a particular mapping to a servlet. Under the initialization section you can enter initialization parameters that the ServletConfig object passes into the Servlet. Adding functionality is not implemented in our application, so remove the attribute from the initialization parameters.
Select Param: Add in the list. Once it is highlighted, the Remove button becomes enabled.
Click Remove and save the Deployment Descriptor.
Figure 69. Servlets tab
Look at the Source page and notice the init-param and servlet-mapping elements.
Figure 70. Source tab of web.xml
Another important page is the References page. It is on this page that a local reference to the datasource was created and you can make local JNDI references that map to actual distributed objects. Try it so you can understand the process of what has been done.
First select the ResourceRef jdbc/AddressBookDB in the list. Click Remove.
Figure 71. References tab
Click the Add... button below the References section of the page to display the Add Reference window:
Figure 72. Add Reference
You can create local references pointing to many different types of distributed resources. It is considered a best practice to map local names in the Environmental Naming Context to actual JNDI names. Try that now.
Select Resource reference and click Next.
Complete the fields as shown in the following image:
Figure 73. Add Resource Reference
You have just created a resource reference that your developers can use in code. Now bind it to an actual JNDI resource.
jdbc/AddressBookDB as the JNDI name for the resource. This is the name of the datasource that you created on the Deployment page of the Application Deployment Descriptor. The binding information of the logical name to the physical name is kept in ibm-web-bnd.xmi. It just so happens that in this case they are the same. They did not have to be, however.
Figure 74. References
In certain areas, however, WebSphere extends the capabilities of the J2EE. The data used for management of any IBM J2EE extensions is kept in ibm-web-ext.xmi. These features are edited on the extensions page within the Web Deployment Descriptor editor . You can extend the capabilities of a regular J2EE application with features such as dynamic reloading of Web applications, and pre-compiling JSPs. This lets you specify deployment information and ensure your application behaves the same way on any WebSphere instance to which you deploy.
Figure 75. Extensions
This concludes the tutorial. I hope it helped clear up a few features of Rational Application Developer and how it structures and packages J2EE applications.
This was the final tutorial in the series for Exam #255. Congratulations on completing them all! Good luck on the exam!
|Source code for the tutorial||tut7_solution.zip||63KB|
- To learn about packaging and deployment, read the article "J2EE Packaging and Common Code," by Keys Botzum (developerWorks, January 2002).
- Read the J2EE Specification to understand how J2EE applications are organized.
- Find detailed information about all of the tags and attributes of Web.xml in the Servlet specification.
- Get certified as an IBM Certified Associate Developer. Check out the objectives, sample assessment tests, and training resources for test 255, "Developing with IBM Rational Application Developer for WebSphere Software V6".
- Stay current with developerWorks technical events and webcasts.
Get products and technologies
- Download a free trial version of IBM Rational Application Developer.
- Build your next development project with IBM trial software, available for download directly from developerWorks.
- Participate in the discussion forum.
- Participate in developerWorks blogs and get involved in the developerWorks community.