Question & Answer
Question
Why does IBM Rational Application Developer for WebSphere Software v7.0 no longer update the Java Build Path .classpath project file with projects specified for J2EE Modules Dependencies (as was the case in version 6.0) when specifying the corresponding Java Jar Dependencies?
Cause
Example Scenario:
CANCELLED APAR PK59600, requested dynamic recomputing of the Rational Application Developer v7 WTP EAR Libraries classpath container on project checkout from a Software Configuration Management tool, such as CVS, demonstrates the misunderstanding of the new Eclipse WTP 1,5+ J2EE build paradigm.
This APAR was the motivation for this technote and helps in understanding these changes.
"..Back in v6 Rational Application Developer relied on individual .classpath entries for every single project dependency to resolve the build path.
For example, if a WAR project depended on a Java Utility project in the MANIFEST.MF then there would be a .classpath entry to that Java Utility project. In v7, however, this is not the case. V7 relies on the EAR Libraries classpath container which resolves all projects by reading the MANIFEST.MF and the workspace metadata. Though v7 has moved away from modifying the .classpath directly the old .classpath entries are still supported, but they are discouraged. There is a classpath checker (under Preferences -> J2EE) which can detect when there is a .classpath entry in place where it is not needed (because it can be dynamically computed from the MANIFEST.MF) which by default adds a warning message to the Errors view...."
The EAR Libraries classpath container (when fully updated) contain every project entry in the MANIFEST.MF that is not also in the .classpath. If there is an entry in both, as occurs in adding a duplicate project to the Java Build Path of a J2EE project, a "Duplicate classpath entry" error is displayed.
Answer
About the change in Rational Application Developer v7
Restore traditional .classpath
Migration Tip
Overview of .classpath with J2EE class path containers
Error and Warning Avoidance
Conclusion
Additional Java Build Path Changes in Rational Application Developer v7.0
Background
J2EE builds were directly linked to the Java Build Path .classpath file in WebSphere Studio Application Developer v5.1.2 and Rational Application Developer v6. Any changes to the runtime Java Jar Dependencies (now J2EE Module Dependencies == MANIFEST.MF runtime classpath settings), were mapped/synchronized to .classpath automatically.
This has been changed as of Rational Application Developer v7.0. This change is associated with how builds and runtime dependencies are managed in the Eclipse Web Tools Project (WTP) v1.5+. Rational Application Developer v7.0 J2EE tools are based on WTP 1.5.
Note: This is not explicitly documented in the Rational Application Developer v7.0 Help.
Rational Application Developer v7.0 no longer updates .classpath with specific projects when J2EE Module dependencies are specified.
As of Rational Application Developer v7.0, the Eclipse WTP 1.5+ concept of EAR Libraries and Web Libraries classpath containers was introduced as part of J2EE Module Dependencies. J2EE classpath containers serve to group related classpath information under one classpath entry within the .classpath file (an example is shown later).
A visible example of this change is that an EAR project, as of Rational Application Developer v7.0, has both
- a J2EE Module Dependencies property that lists all physical java jars associated with this EAR
and - java utility projects added to the Modules tab of the EAR Deployment Descriptor editor
This the concept of an EAR Library.
In the case of a Dynamic Web Application project, the J2EE Module Dependencies (Java EE Module Dependencies in RAD 7.5 and Assembly Deployment in RAD v8+) property has an EAR Libraries tab and a Web Libraries tab, while an EJB project only has EAR Libraries listed.
The EAR Libraries or Web App Libraries containers are explicitly added to the .classpath file corresponding to any J2EE/JEE's project property Java Build Path:Libraries [Tab] , hence the projects specified in those containers are implicitly part of the build path.
The workspace Preferences for J2EE (Java EE RAD7.5+) introduced Classpath containers settings for EAR Libraries classpath containers and Web App Libraries classpath containers as of Rational Application Developer v7.0.0.1, which are checked/set by default.
Note: They were also the default as of Rational Application Developer v7.0.0.0 where they could not be changed.
If these J2EE preferences are unchecked and a new J2EE project is created, and other projects or utility jars are specified as J2EE Module Dependencies, the build path .classpath file will not be updated with these containers . In this case, the classpath validator will find these missing entries and can add them for you as a quickfix.
To have the previous Rational Application Developer v6.0 Java Build Path behavior in which the .classpath file explicitly listing all build members (such as all projects needed to build this project) so that the build could be managed manually or using Ant Task based builds, it is necessary to disable these J2EE classpath containers.
These preferences were introduced as of Rational Application Developer v7.0.0.1 to accommodate users who had Ant Build Tasks that explicitly managed/edited the .classpath file.
Having these new J2EE preferences set by default as of RAD 7.0.0.1 was causing these library containers to be added to the .classpath files of RAD v6 and earlier J2EE projects unexpectedly, when J2EE Module Dependencies are specified and causing unexpected build errors such as "Duplicate classpath entry" error. In short the .classpath file had older individual entries for items that are also specified in J2EE container libraries.
It is now possible to uncheck these preferences and remove any tampering with the .classpath file in scenarios where customers need to have control over their .classpath.
To restore the traditional Eclipse or Rational Application Developer v6.0 .classpath based build paradigm:
Many large J2EE development projects write ant task build scripts focused on the .classpath file, making any automatic or unsolicited changes this file undesirable. Hence, the changes in Rational Application Developer v7.0/WTP 1.5 for J2EE project builds may be a problem.
It was not a good design in WebSphere Studio Application Developer v5.1.2 or Rational Application Developer v6.0 in which changes in MANIFEST.MF (Java Jar Dependancies) were reflected automatically to the .classpath build file. At the same time the new J2EE classpath containers simplify builds to take advantage of specified runtime dependencies.
If a project is using ant task builds exclusively, based on the traditional Eclipse Java project .classpath paradigm, can remove the EAR Libraries and Web App Libraries classpath containers by:
- Unchecking the two J2EE Libraries classpath container preferences so that any new projects being added to the workspace will not have the containers added to the Java Build Path (.classpath file)
and
- In existing J2EE project they can be removed from the Java Build Path property under Libraries or
deleting the corresponding classpathentry elements/lines in the project .classpath file.:
<classpathentry kind="con"
path="org.eclipse.jst.j2ee.internal.{module|web}.container"/>
Migration Tip (if Build Errors):
Its possible to have an EAR and all its modules in Rational Application Developer v6.0 or WebSphere Studio Application Developer v5.1.2 with no build errors (or some insignificant errors), is exported as a Project Interchange (PI) and when imported into a Rational Application Developer v7.0 default workspace has new, sometimes unexplained, build errors. Consider importing the PI into a new Rational Application Developer v7 workspace in which the two J2EE Libraries classpath container preferences are unchecked prior to the import. If this gives an as similar, error free or significantly improved build, consult IBM Rational Application Developer Support, it may be a J2EE Tools migration defect.
It is recommended to use these J2EE runtime Libraries classpath containers when doing builds (incremental or otherwise) in a Rational Application Developer v7.0 IDE (or Eclipse WTP 1.5+) J2EE projects.
Java Build Path should only be used to add items not specified as a J2EE Module Dependencies.
The new J2EE Libraries classpath containers simplify builds by automatically incorporating the runtime manifest dependencies without explicitly listing each runtime manifest dependancy in the Java Build path ( .classpath file).
Overview and Example of .classpath with J2EE class path containers:
J2EE tools/build should not modify .classpath automatically. This especially affects projects with build tools/ant tasks that parse .classpath for the traditional eclipse/java src/output information:
<classpathentry kind={"src"| "output"} path= "... "/>
.
It used to be that .classpath listened on MANIFEST.MF and .project changes in WebSphere Studio Application Developer v5.1.2 or Rational Application Developer v6.0. This is no longer true.
Modifying MANIFEST.MF ( == EAR Libraries) or .project will no longer update .classpath. However, modifying the MANIFEST.MF file's Class-Path entries and saving will cause the EAR Libraries classpath container to recompute and reflect the changes on the project's classpath.
In Rational Application Developer v7/WTP 1.5+, a J2EE build relies on these "J2EE Module Dependencies" project items:
- .MANIFEST file Class-Path entries( == "EAR Libraries" classpath container), shown in .classpath as:
<classpathentry kind="con" path="org.eclipse.jst.j2ee.internal.module.container"/>
and/or
- WEB-INF/lib ( == "Web App Libraries" classpath container: it resolves other java modules in the workspace to WEB-INF/lib at deploy time, shown in .classpath as:
<classpathentry kind="con" path="org.eclipse.jst.j2ee.internal.web.container"/>
This is similar to what a WebSphere Application Server would try to resolve at runtime, but for build purposes.
Note: Physical jar(s) in WEB-INF/lib of a project are not shown automatically in a dynamic web project J2EE Module Dependencies - Web Libraries tab for selection, as they would be under EAR Libraries tab for physical jars located in an EAR project. They will generate an Error "Build path contains duplicate entry: {some jar file}" if you try to add any of those Jar(s) to the Libraries Tab of Java Build Path.
The <classpathentry..../> line are prefixed with (L1) to (L8) for discussion purposes. They would not normally appear:
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
(L1) <classpathentry kind="src" path="src"/>
(L2) <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/WebSphere v6.1 JRE"/>
(L3) <classpathentry kind="con" path="org.eclipse.jst.server.core.container/com.ibm.ws.ast.st.runtime.runtimeTarget.v61/was.base.v61"/>
(L4) <classpathentry kind="con" path="org.eclipse.jst.j2ee.internal.module.container"/>
(L5) <classpathentry kind="con" path="org.eclipse.jst.j2ee.internal.web.container"/>
(L6) <classpathentry combineaccessrules="false" kind="src" path="/LANDSCAPE"/>
(L7) <classpathentry kind="lib" path="WebContent/log4j-1.2.14.jar"/>
(L8) <classpathentry kind="output" path="WebContent/WEB-INF/classes"/>
</classpath>
- (L1) and (L8) are your classical eclipse java "src"/"output", corresponding to the Source Tab in the Java Build Path wizard
- (L7) shows a jar added in the Libraries Tab of the Java Build Path for completeness in this .classpath file example. This is your classical eclipse java "lib" entry
- (L2) and (L3) are the usual WebSphere Application Server (WAS): JRE and runtime target (i.e. server /lib jars) respectively.
No change from Rational Application Developer v6, except Rational Application Developer v7,0/WTP1.5 introduced also the project Facets property, which must correspond to these.
- (L4) and (L5) are the NEW "EAR Libraries" and "Web App Libraries" classpath containers around which the J2EE project builds revolves by default.
Error and Warning Avoidance:
If you have entries in your "Projects" src tab that are the same as in the EAR Libraries or Web App Libraries classpath containers or entries in "Libraries" tab that are the same, the following error or warning may be reported:
"Build path contains duplicate entry: {some jar file} "
To resolve this carry out some combination of these actions:
- Remove the conflicting "Source" project or "Libraries" entry in Java Build Path
- If you add/remove an "EAR Libraries" library under Libraries in the Java Build Path.
Note: In general, as the workspace project structures (such as projects are added/removed, or dependencies between projects are modified (for example, modules added/removed from EARs, or MANIFEST.MF dependencies are changed)), both classpath containers will react to these changes an automatically update. There may, however, be some corner cases where these containers are not updated. To force the update of the containers, then click "Update EAR Libraries" from the Project-right Mouse click-pop up menu. Clicking this on a module project will force the update for only that single project. Doing so on an EAR project, will force the update for every module project contained within the EAR.
Conclusion:
This technote has explained the new Rational Application Developer v7.0.0.1+ J2EE classpath container settings in Window > Preferences > J2EE which "by default" is checked to use the EAR Libraries and Web App Libraries classpath containers and all Classpath Checking (i.e. validation) is set to Warning.
Note: Originally Rational Application Developer v6 only had the option - Perform Incremental Deployment
NEW as of the Rational Application Developer v7.0.0.6 update:
There is a new entry (see previous Preferences > J2EE screenshot) under Classpath containers:
[ ] Use Java Build Path to control EAR Libraries export
This came about because of APAR PK57954 : Rational Application Developer v7 "EAR Libraries" always exported even if unchecked under the Order and Export tab of Java Build Path.
The EAR Libraries classpath container will now honor the JDT export settings. In order to activate this, the user must open Window > Preferences > J2EE and check the new Use Java Build Path to control EAR Libraries export checkbox.
Additional Java Build Path Changes in Rational Application Developer v7.0:
In Rational Application Developer v7.0/Eclipse3.2 the .classpath: ... combineaccessrules="false" ... setting shows for any new project added to the Java Build Path of any java project. This was introduced in Eclipse 3.1 (Rational Application Developer 6.0 was Eclipse 3.0.x).
It is also possible to make use of an empty com.ibm.etools.j2ee.teamshare "flagging" file in the .settingsfolder of an EAR project, to work with ClearCase, since Eclipse would otherwise try to update/checkout J2EE references in EAR Deployment Descriptors, .MANIFEST.MF classpath settings and .classpath among others when doing a close or delete of a project. This is explained in the article: Using binary modules to optimize Rational Application Developer.
For a comprehensive and historical overview of WebSphere Studio Application Developer/Rational Application Developer build, classloading and java utility jar issues see the following item under Related information:
J2EE ClassLoading, Packaging and Module Visibility References and Articles refers to many useful articles. It references the article: J2EE Packaging and Common Code which touches on J2EE packaging strategies and java utility jars. Also of interest under Related Information: Managing Utility JARs in an IBM Rational Application Developer-ClearCase Environment
From a WebSphere Application Server classloading perspective, in this case WebSphere Application Server v6.1, it is useful to consult the Red Paper: WebSphere Application Server V6.1: Classloader Problem Determination. Also the class loader/loading chapters in the System Management and Configuration Handbooks for the various WebSphere Application Server server versions under Related information, provide similar background information.
The technote: Using WebSphere Application Server v6.x Shared Libraries in Rational Application Developer, is useful from the perspective of the use of Shared Libraries by J2EE EAR(s)/Projects in Rational Application Developer v7.0 with WebSphere Application Server v6.x and v5.1.
Related Information
Was this topic helpful?
Document Information
Modified date:
10 September 2020
UID
swg21304802