Server targeting explained in WebSphere Studio V5.1.1

Document options Document options requiring JavaScript are not displayed My developerWorks needs you! Connect to your technical community Rate this page Help us improve this content

Level: Intermediate

Daniel Berg (danberg@us.ibm.com), Senior Software Engineer, J2EE Tools Team Lead, IBM Research Triangle Park Lab, North Carolina, IBM
Vijay Bhadriraju (vbhadrir@us.ibm.com), Advisory Software Engineer, J2EE Tools, IBM Research Triangle Park Lab, North Carolina, IBM

01 Feb 2004

Server targeting takes the guesswork out of figuring out which JDK is supported by the server on which you intend to install your application, and which JAR files should be added to the build path for a given server. This article explains the details of server targeting.

Introduction

In order for a J2EE Enterprise Application to be used, it must first be installed on an application server using an Enterprise Archive (EAR) file. An EAR file is a self-contained archive consisting of module archives (such as EJB and Web) and utility archives (such as simple JAR files). Applications are not required to package a version of the Java™ run time, because it is made available by the application server, which also makes available a number of other JAR files such as j2ee.jar and xerces.jar, so that each application is not required to package its own version of this code.

In IBM ® WebSphere® Studio, J2EE enterprise applications and J2EE modules (including EJB, Web, Connector, and Application Client) are defined as individual projects. All of these projects, except for Enterprise Application, are also Java projects, which means that you can develop and compile Java files in these projects. The JAR files available at compilation time are defined in the Java build path of these Java projects.

When developing Java application code, you would like to compile your code against the public JAR files for that application server on which you plan to install and run your application. Versions of WebSphere Studio prior to V5.1.1 did this by creating a Java classpath variable to a WebSphere run time shipped with the product, and a classpath variable to the Java run time JAR file for the same WebSphere run time. Then, each J2EE module project would get rt.ja (the Java run-time code) as well as a handful of known server JAR files added to its Java build path when the project was created, using these two classpath variables. The figure below shows the Java build path for a new EJB 1.1 project:

Notice the two classpath variables SERVERJDK_PLUGINDIR and WAS_PLUGINDIR. The first resolves to the WebSphere Application Server V4 run-time installation's java directory (D:\eclipse\targets\v511\1013\runtimes\aes_v4\java). The second resolves to the WebSphere Application Server V4 run-time directory (D:\eclipse\targets\v511\1013\runtimes\aes_v4) that is shipped with WebSphere Studio. The classpath variables SERVERJDK_V5_PLUGINDIR and WAS_V5_PLUGINDIR resolve to similar locations, except for WebSphere Application Server V5. The variable used, as well as the set of JAR files added, are determined by the J2EE version of the module project. For example, J2EE 1.2 project versions use the WebSphere Application Server V4 variables, and J2EE 1.3 versions use the WebSphere Application Server V5 variables. Therefore, the server JAR files against which you compile your J2EE module projects are determined by the J2EE version, regardless of which server you actually plan to install against.

Back to top

Problems solved by server targeting

Now that you've had a brief description of how public server JAR files are added to a J2EE module's Java build path, it's time to introduce you to a new feature in WebSphere Studio V5.1.1 called server targeting. Server targeting helps address the following issues with WebSphere Studio V5.1 and earlier versions:

• Server JAR files based on J2EE version -- As described above in the Introduction, the subset of JAR files are added to the J2EE module project Java build path at creation time, and this set of JAR files is based on the project's J2EE version and not on the server that you plan to target. Therefore, you are coding against files that may or may not be present when the application is run on the server.
• Targeting WebSphere Application Server Express or Enterprise Edition (EE) -- WebSphere Application Server Express does not support EJB and Connector modules. Therefore, the Express server has a smaller number of public JAR files available. However, when coding an application, the J2EE module projects will always have either the WebSphere Application Server V4 or V5 public JAR files. Therefore, some JAR files on the Java build path will not be available at run time on a WebSphere Application Server Express application server. A similar problem exists for WebSphere Application Server EE, except that it requires more JAR files on the Java build path than are available in other WebSphere Application Server versions.
• JDK 1.4.1 Support -- The previous discussion pointed out that the server JAR files on a J2EE module project's Java build path will have the rt.jar file from either V4 or V5 of WebSphere Application Server. WebSphere Studio V5.1.1 now ships WebSphere Application Server V5.1, which is based on JDK 1.4.1, not on JDK 1.3 as V4 and V5 are. The current implementation for adding server JAR files to the Java build path will only add a JDK 1.3 run-time JAR file to the path. There is therefore no way to target the JRE for WebSphere Application Server V5.1. You might think that you could just change the SERVERJDK_PLUGINDIR classpath variable to point to the WebSphere Application Server V5.1 java directory. The problem with this approach is that JDK 1.4.1 no longer has a rt.jar file -- it now has multiple JAR files that need to be on the Java build path.

Back to top

What is server targeting?

New in WebSphere Studio V5.1.1, server targeting is a mechanism that lets you specify the server on which your Enterprise Application will be developed. Each module and utility JAR file in the application will default to the same server target as the application itself. This server target serves two purposes:

• It sets the Java build path to have only those JAR files that are actually available on the target server.
• It provides information to the other components in WebSphere Studio about the server on which you plan to install the application. For example, when testing the application, the test server automatically selected to be created is the same as the target server.

When you select a particular server to target, all of the WebSphere-specific JAR files that use the WebSphere classpath variables described in the Introduction will be removed from the Java build path. Then two classpath containers will be added to the project's Java build path. A classpath container in Eclipse is a single classpath entry for a Java project that resolves to one or more libraries (JAR files). The first classpath container is an installed JRE container for the target server, which means that you will develop using the exact same JDK version as the server on which you intend to install the application. The second classpath container resolves to the list of public JAR files for the target server. Therefore the JAR files available to all applications within the server will be on the project's Java build path. So you can be assured that the classes you use from this container or the JRE container will be available at run time. This feature prevents the frustrating problem of developing enterprise code, and then realizing during testing that it will not run on the server because some classes are missing.

When you first use WebSphere Studio V5.1.1, you will not see the new server targeting feature. By default, it is turned off because using server targeting breaks compatibility with earlier versions of WebSphere Studio. Remember that two classpath containers will be added to your Java build path, and these containers must resolve to a set of JAR files. In earlier versions of WebSphere Studio, these classpath containers do not exist, and therefore the JAR files cannot be resolved. So take care when using this new feature, and make sure that all developers on the team use WebSphere Studio V5.1.1 for the projects that have a target server.

Important: J2EE projects that use the server targeting feature in WebSphere Studio V5.1.1 cannot be shared with earlier versions of WebSphere Studio.

Enabling the Server Targeting Preference

To activate server targeting, select Windows => Preferences and then select J2EE:

If you select Enable server targeting support, the window for specifying a server target will open. Even when server targeting is enabled, you can still create a J2EE module project that can be used with earlier versions of WebSphere Studio by selecting No target server specified.

The "No target server specified" option

When selecting an available server target for a given J2EE project, the No target server specified option is always available. This option provides backward compatibility with earlier versions of WebSphere Studio, and is used to revert the Java build path on the project to what it was in versions of WebSphere Studio prior to V5.1.1, as described above in the Introduction. This option removes the two classpath containers and uses the WebSphere classpath variables to add a set number of public JAR files to the build path. This option was introduced to let you use server targeting and still be able to define some J2EE projects without a target server in the same workspace. This is necessary if you are working with a group that has been only partially migrated to WebSphere Studio V5.1.1. The projects with No target server specified can be shared with prior versions of WebSphere Studio. This option is not intended to let you switch back and forth between having a target server and not having one. Although this will work, some JAR files may not be replaced on the build path when you remove the target server (such as JAR files that were added manually after the project was created).

The examples below should help you understand how to target a server within an Enterprise Application and how to deal with issues that can arise when doing so.

Back to top

Server targeting examples

J2EE projects

In WebSphere Studio, you can set a target server on a J2EE project at the time of project creation or during the import of a J2EE archive into a new J2EE project. You can set a target server on an existing J2EE project using the Target Server => Modify pop-up menu option available in the J2EE Hierarchy view or the Navigator view or the J2EE properties page of a J2EE project. (For details, see the Modify Target Server section below.) The different ways of setting a target server mentioned here are applicable for all J2EE project types: Enterprise Application, Application Client, Web, EJB, and Connector.

Module projects

This example will go through all functions available on an EJB project for setting a new target server and modifying an existing one. All other module projects (Application Client, Web, and Connector) follow the same approach as the EJB project described here. WebSphere Application Server V5.1 is the target server in this example.

When you select the No target server specifiedoption on the target server drop-down list, no target server is set on the EJB project or the new EAR project. If you select an existing EAR project with a target server, then the target server on the EAR project remains unchanged. For details, see the section The "No target server specified" option above.

After it is created, the TestEJB project has the following changes:

1. The classpath file in the project is updated with two new containers, as shown below. The first container points to the JAR files of the JDK associated with the target server, and the second container points to the server JAR files of WebSphere Application Server V5.1:

   <?xml version="1.0" encoding="UTF-8"?> <classpath> <classpathentry kind="src" path="ejbModule"/> <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/ org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/WebSpherev5.1 JRE"/> <classpathentry kind="con" path="com.ibm.etools.server.target.container/ com.ibm.etools.websphere.serverTarget.base.v51/j2ee.ejb/1"/> <classpathentry kind="output" path="ejbModule"/> </classpath>

   
   
   
   
2. A new .server file is generated in the root folder of the EJB project that indicates the target server set on the project as shown below:

   <?xml version="1.0" encoding="UTF-8"?> <server-target target-id="com.ibm.etools.websphere.serverTarget.base.v51" type-id="j2ee.ejb"/>

   
   

The figures below show the build path of the project when viewed from the Properties => Java Build Path => libraries page. The first figure shows the target server's JRE container expanded to show all resolved libraries.
The second figure shows the target server classpath container expanded to show all of its resolved libraries which are the public JAR files for the target server.

The EJB Import wizard has a new Target Server drop down similar to the EJB project creation wizard as shown in the figure below. The drop down lists all the available target servers for a new EJB project based on the J2EE specification level of the selected EJB JAR. The target servers in the drop down are calculated based on the J2EE specification level of the selected EJB JAR. For details on how the target server is set on the new EJB project created during import refer to the Project Creation section. If the JAR is imported into an existing EJB project, the Java build path or the target server of the project, if one exists, remains unchanged.

1. Modify Target Server Pop-up Menu Option -- There is a pop-up menu available in the the J2EE Hierarchy view and the Navigator view by selecting the Target Server => Modify context menu option for the J2EE project. The Modify action launches the Modify Target Server dialog shown in the figure below for an existing EJB project . When opened the dialog shows the current target server set on the J2EE project. If no target server is set on the J2EE project then the "No target server specified" option is selected. The target server drop down always shows the valid target servers for the J2EE project type and the J2EE specification level of the selected J2EE project.

   

2. J2EE Properties -- The target server can also be modified from the J2EE properties page which is found by selecting the Properties context menu and then selecting the J2EE category of all J2EE projects except for a Web project. For Web projects, the target server property is shown in the Web category of the properties page. The figure below shows the properties page for an EJB project. The target server modify function in the J2EE properties page works similar to the Modify Target Server dialog. You can select the target server of choice and click OK or Apply to set the selected target server.

   

Enterprise application project

In this example we will go through all of the functions available on an Enterprise Application project for setting a new target server and modifying an existing target server. We will be using WebSphere Application Server V5.1 as the target server in this example.

In the Enterprise Application project creation wizard there is a new Target Server drop down that lists all the available target servers based on the J2EE specification level selected for the new Enterprise Application project as shown in the figure below. The default target server that is preselected in the wizard is WebSphere Application Server V5.1. Any target server of choice can be selected from the drop down. After clicking Finish, the selected target is set on the " TestEAR" project and any default or custom module projects created in the New Module Project wizard of the Enterprise Application project wizard to be added to TestEAR will have the same target server set on them. The target server of each module project within an Enterprise Application needs to be compatible with the target server of the Enterprise Application. Refer to the Compatibility Sample section for more details about compatible target servers.

There is a "No target server specified" option in the target server drop down. When this option is selected there is no target server set on the Enterprise Application project and any default or custom modules created from this wizard. Refer to the What is "No target server specified?" section for more details about this option.

Enterprise Applications are deployed and packaged into Enterprise Archive (EAR) files. This is essentially an archive file containing all of the module archive files plus any additional utility archive files (JARs). WebSphere Studio has an import wizard that allows you to import EAR file into an Enterprise Application project and all module archives will be imported into J2EE module projects.
The Enterprise Application Import wizard has a new Target Server drop down similar to the Enterprise Application project creation wizard as shown in the figure below. The drop down lists all the available target servers for a new Enterprise Application project based on the J2EE specification level of the selected ear file for import. The target servers in the drop down are calculated based on the J2EE specification level of the selected ear file. For details on how the target server is set on the new Enterprise Application project created during import refer to the Enterprise Application Project creation section.

1. Modify Target Server Pop-up Menu Option -- The Modify Target Server pop up menu for an Enterprise Application is virtually the same as that of a J2EE module project as described in the Modify Target Server section. However for Enterprise Application projects there is an additional Update EAR modules and utility projects to the selected target server check box. This option, when selected, ensures that all module, utility and web library projects (associated with Web projects in the Enterprise Application project) get the same target server as that of the Enterprise Application project during the target server modify operation. If this option is not selected, the target server of all module, utility and web library projects in the Enterprise Application can become out-of-synch with the Enterprise Application project. Refer to the Synchronize Target Server section about the warnings that are put out when target servers of module projects are out-of-synch with that of the Enterprise Application project.

   

2. J2EE Properties -- Again, this property is virtually the same as that of a J2EE module project as described in the Modify Target Server section. The only difference between the property page for a J2EE module project and an Enterprise Application project is the Update EAR modules and utility projects to the selected target server check box as shown in the figure below. The function of this property page is the same as the Modify Target Server option described above.

   

Enterprise application editor

Server target migration

The J2EE migration wizard in WebSphere Studio when migrating a J2EE 1.2 specification project to a J2EE 1.3 specification project, migrates a WebSphere Application Server V4.0 target server to WebSphere Application Server V5.0 target server if a WebSphere Application Server V4.0 target server is set on the J2EE 1.2 specification project. There is no user action required in the J2EE Migration Wizard for the target server migration. It automatically migrates the target server along with the J2EE Specification level migration. When migration is performed at a EAR project level then the target server of the EAR project and any module projects being migrated are migrated to WebSphere Application Server V5.0. When migration is performed at a Module project level then the WebSphere Application Server V4.0 target server only of the module project is migrated to WebSphere Application Server V5.0.

Back to top

Compatible server targets

The table below shows the list of valid target servers supported in WebSphere Studio V5.1.1 for J2EE and Java projects. Depending on which WebSphere Studio product that you are using you may see all of these server targets or just a subset of this table. This table is useful because it indicates the J2EE specification versions that are supported by each target as well as the supported J2EE module types and the highest JDK version supported by the server. You should use this table as a guideline for other servers which you would like to target that are not supported by WebSphere Studio. If you have a need to target a server that is not listed here, you should select one of the supported servers that has the same level of support as the server you which to target. You may need to refer to your server documentation for details.

WebSphere Studio target server support details table

* WAS stands for WebSphere Application Server

Compatibility within an application

An Enterprise Application with a target server can include module projects with a target server that do not match but are compatible with the target server of the Enterprise Application. When an automatic or manual validation is run on an Enterprise Application project, it validates all modules and utility projects in the Enterprise Application project. There are specific validations for inconsistent target servers. The validation routines raise warnings in the task list for the following situations listed below.

• If a valid target server does not exist on each of the module and utility projects in the ear with a target server set.
• If the target server of each module and utility project does not match with that of the EAR target server.
• If a module project with a valid target server belongs to an EAR with no target server set.

The warning can be ignored if the module project's target server is compatible with that of the application's project. The table lists the Application project server target in the first column and across the top are all available module server targets. An "X" indicates that a module or utility project's server target is compatible with the corresponding application project server target on that row.

Target server compatibility table

* WAS stands for WebSphere Application Server

Let's take a look at two simple scenarios. These scenarios will show two common ways to have inconsistencies with target servers and what is required to correct the problem.

Scenario A

TestTomcatEAR
    Server = Tomcat 4.1
    TestTomcatWeb
        Server = Tomcat 4.1

TestWASEAR
    Server = WebSphere Application Server 5.1
    TestTomcatWeb
        Server = Tomcat 4.1

In this scenario we have an Enterprise Application project named TestTomcatEAR which has a target server of Tomcat 4.1. This application contains one Web module which is in the TestTomcatWeb project and it's target server is Tomcat 4.1. So far there is not a problem because the target servers are the same. Now we create a second application project named TestWASEAR which has a target server of WebSphere Application Server 5.1. WebSphere Studio packages modules in projects peer to the application project so that the module projects can be shared among applications and not packaged twice. So, in this scenario, we add the TestTomcatWeb from the first application to the TestWASEAR application without changing the target server because then we would cause an inconsistency with the TestTomcatEAR application. When validation is run, a warning is added to the Tasks list because the TestTomcatWeb server does not match with the TestWASEAR server. If we look at the compatibility table for the WAS 5.1 application server, we will see that the Tomcat 4.1 is a compatible target server. Therefore, we can ignore this warning message.

If we had changed the target server of the TestTomcatWeb module project when it was added to the TestWASEAR application project, we would have had an incompatible server situation with the TestTomcatEAR application because the WebSphere Application Server 5.1 module server is not compatible with a Tomcat 4.1 application server.

Scenario B

TestWASEAR
    Server = WebSphere Application Server 5.1
    TestWASWeb
        Server = WebSphere Application Server 5.1

TestWASExpEAR
    Server = WebSphere Application Server Express 5.0
    TestWASWeb
        Server = WebSphere Application Server 5.1

In this scenario we have an Enterprise Application project named TestWASEAR which has a target server of WebSphere Application Server 5.1. This application contains one Web module which is in the TestWASWeb project and it's target server is WebSphere Application Server 5.1. So far there is not a problem because the target servers are the same. Now we create a second application project named TestWASExpEAR which has a target server of WebSphere Application Server Express 5.0. We now add the TestWASWeb from the first application to the TestWASEAR application without changing the target server. Looking at the compatibility table, we realize that we have an incompatible server situation in the TestWASExpEAR application project. There are two ways that this scenario can be corrected.

1. Update the target server of TestWASWeb when it is added to TestWASExpEAR (see the Add Module/Utility Java Project section for details). This will change the TestWASWeb server target to WebSphere Application Server Express 5.0 when it is added to the application. This will work since the express server is compatible with the WebSphere Application Server as shown in the compatibility table.
2. If you had already added the TestWASWeb project and you were unsure about changing the server (as is the case in this scenario), you could modify the server target of the TestWASWeb project to WebSphere Application Server Express 5.0 following the steps from the Modify Target Server section. Another option to change the target server would be to synchronize the module project's target servers with that of the TestWASExpEAR application (see the Synchronize Target Server section for more details).

Synchronize target server

As the scenarios above have indicated, there may be times that you will need to update all target servers of module, utility, and web library projects within the application to match that of the application. For an Enterprise Application project, WebSphere Studio has a mechanism to do just this without having to worry about which server to choose and without having to update each target server at a time. Here's how it works.

1. Select the Enterprise Application project that you whish to have servers synchronized.
2. Select the Target Server => Synchronize context menu action to launch the Synchronize Target Server dialog as shown in the figure below.
3. The target server drop down in this dialog is always disabled and the target server that is currently set on selected application project is displayed in the drop down. The Update EAR modules and utility projects to the selected target server option is selected by default and should be left selected to synchronize the target servers of module, utility, and web library projects in the selected application to the target server displayed in the dialog.
4. Click OK.

Server target stubs

In WebSphere Studio V5.1.1 the installation of all WebSphere test application servers is optional. You have the option to not have any test servers installed. For test servers that are not installed during WebSphere Studio installation, target server stubs are created in the runtimes folder of the WebSphere Studio install directory. An example of WebSphere Application Server Express V5.0 stub folder looks like "C:\Program Files\IBM\WebSphere Studio\Application Developer\v5.1.1\runtimes\express_v5_stub". The stub folder contains the minimum set of JAR files needed to compile against that target server. Thus, you will still see the target server available in the drop down list in the UI even though it is not installed.

Standard VM's

When WebSphere Studio V5.1.1 is installed, a Standard VM that points to the JDK associated with the workbench is added to the list of installed JRE's as shown in the figure below. This is similar in behavior to earlier versions of WSAD.

With server targeting disabled or enabled if any WebSphere Unit Test tooling is accessed three standard VM's for the WebSphere Application Server V5.1 are added to the list of Standard VM's as shown in the figure below. These VM's are added so the user can take advantage of JDK 1.4 support in WebSphere Application Server V5.1 for Java applications which do not have any J2EE artifacts.

When Server Targeting feature is enabled and any J2EE project is created targeting a WebSphere Application Server that is not installed, then Standard VM's for that server are added to the list of Installed Java Runtime Environments as shown in the figure below. The figure below depicts the Standard VM's added for WebSphere Application Server V5.0 that was not installed when installing WebSphere Studio V5.1.1. The location of the Standard VM's for WebSphere Application Server V5.0 points to the JDK associated with the workbench as that is the default JRE for WebSphere Application Server V5.0 and V4.0.

Back to top

Conclusion

Server targeting takes the guesswork out of figuring out which JDK is supported by the server on which you intend to install your application, and which JAR files should be added to the build path for a given server. Server targeting ensures that the set of server JAR files that your projects compile against will be the same set that the application will run against.

About the authors

		Daniel Berg is a software engineer at IBM Research Triangle Park Lab in Durham, North Carolina. He is the lead architect for the J2EE tooling component in WebSphere Studio Application Developer.

		Vijay Bhadriraju is a software engineer at IBM Research Triangle Park Lab in Durham, North Carolina. He is a developer of the J2EE tooling component for WebSphere Studio Application Developer

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Back to top