1.0 Introduction
2.0 Known problems
2.1 Adding module files to an Enterprise Application project
2.2 Alternate deployment descriptor (alt-dd) elements in enterprise applications
2.3 Java build path settings for EJB/Web/Application Client projects
2.4 Spaces not supported in JAR URIs within an EAR
2.5 Enterprise application project names should not contain DBCS characters
2.6 Binary projects are read-only
2.7 Creating examples multiple times
2.8 Java build path updates when removing the dependency on a Utility JAR file
2.9 Java JAR Dependencies page fails to update Java build path
2.10 Automatic removal of WebSphere bindings with delete
2.11 J2EE ANT task support
2.12 Resource locking due to JSP validation
2.13 Automatic checkout from ClearCase when importing and overwriting existing files
2.14 'Invalid project description' error when using a non-default project location for a new J2EE project
2.15 J2EE headless Ant support: com.ibm.etools.j2ee.ant.RunAnt application
The J2EE perspective contains the views that you would typically use when you develop resources for Enterprise Application, EJB, Web, and Application Client projects. This readme file describes some known problems, limitations, and workarounds that are associated with J2EE development tools in WebSphere Studio. Some other items related to J2EE views and J2EE Web projects are documented in the readme file for Web tools.
When importing one of the module file types (EJB JAR, WAR, RAR, and Application Client JAR file) into an Enterprise Application project, you must use the correct import wizard and import the module file into the appropriate project type. Do not import into the Enterprise Application project. If the module file is imported into the Enterprise Application project, you will not be able to add the module to the application using the Application deployment descriptor editor.
The use of alt-dd's is currently not supported in WebSphere Studio. The workaround is to edit the deployment descriptors of the contained modules.
It is recommended that whenever possible, you accept the default settings of the Java build path for the J2EE project types. To set up dependencies between projects contained in an Enterprise Application, use the JAR Dependencies editor or the Java JAR Dependencies property page instead. This will keep the Class-Path attribute of the MANIFEST.MF file (used for server runtime) sychronized with the project Java build path (used for Java compilation).
In general, libraries required by a module must be either contained in the Enterprise Application, or visible to the server. Therefore caution should be used adding external libraries to the project build path, because the project may not run on the server. For example, suppose you have a library off_the_shelf.jar that you want to reference in an WEB module. You can either:
- Add off_the_shelf.jar to the Enterprise Application using the file system import wizard; then use the JAR Dependecy editor to make the WEB module depend on the JAR, or
- Use the Java build path properties for the WEB project to add the JAR to the build path; the server must then have visibility to the JAR.
To accomplish this for unit test, edit the server configuration and add the JAR to the classpath.
Spaces are not supported in the URI for modules or utility JARs in an enterprise application. The "Class-Path:" attribute of a MANIFEST.MF file in a JAR or module is a space delimited list of relative paths within an EAR. A JAR would not be able to reference another JAR in the EAR if the URI of the referenced JAR contained spaces.
When you create an enterprise application project, it is recommended that you do not give it a name that contains DBCS characters.
Binary projects created by EAR import (available as an option on the import wizard) are intended to be read-only. You should not try to modify the contents of a binary project. You can, however, delete the binary project and replace it with a source version from a repository. Most actions should be disabled for binary projects. If you use binary projects, try to avoid any actions which modify the contents of the project or JAR.
In order to create multiple instances of the built-in Enterprise Application Examples, you need to rename the existing example project and all its module projects before importing the example again. If you do not follow these steps the second import will overwrite the module projects without warning.
In the J2EE Hierarchy view, right click each module that needs to be renamed, and select Rename. In the dialog that opens, type the new name and select both Rename module in all Enterprise Applications and Rename module dependencies referencing selected project. It is important to use the rename from the J2EE Hierarchy view and to select these two options so that module interdependencies remain intact.
When removing the dependency on a Utility JAR, the corresponding Java project will be removed from the Java build path only if the dependent JAR is still referenced by the EAR project.
For example, suppose you create a J2EE 1.3 Web project and EAR along with the JUnit Java Example project. Next, add the JUnit project as a Utility JAR in the EAR, then add JUnit as a Java JAR Dependency of the Web project.
If you then wanted to remove the dependency between JUnit and the Web project, remove the Java JAR Dependency from the Web project first, then remove the Utility JAR from the EAR. Follow this order to ensure that this works correctly.
The Java JAR Dependencies page is not synchronized with the Java build path page in the project properties dialog. Therefore a change applied in one may not be reflected in the other within the same dialog session.
There are also some instances where flipping back and forth between the pages will cause the update from one to cancel out the update from another, when the OK button is pressed, or if the apply button is pressed prior to the OK button. Typically this will appear as if a JAR dependency was added, but the project did not get added to the Java build path.
The workaround is to reopen the properties dialogs, switch to the JAR dependency page, de-select and re-select the dependent JAR(s), and press OK.
When you delete an object that contains WebSphere bindings, the binding object is also automatically deleted. For example, if you delete a security role with bindings in the Security page of the application deployment descriptor editor, the security role bindings are also deleted. If you a security role with the same name, be sure to re-bind it if necessary.
In version 4.x, additional workspace Ant tasks and J2EE tasks for export were available by downloading a zip file (com.ibm.ant.extras.zip) from the Web. These additional tasks are now provided in the base product in the com.ibm.etools.j2ee.ant plugin.
If you have existing ANT builds based off the old plugin, you will need to migrate these builds due to the following changes from 4.0.x:
- Because plugins have been renamed from the downloadable "extra" that was available for 4.0.x, the example runAnt.bat file used for running headless has been updated. Specifically, the id of the startup application has changed from "com.ibm.ant.extras.RunAnt" to "com.ibm.etools.j2ee.ant.RunAnt". Any existing .bat files used to startup the headless workspace must be modified.
- The utilJAR task is now deprecated. It remains only for compatibility; however, the util JAR support in the application editor should be used instead. Also note that the task has been simplified and some parameters are no longer applicable. Please refer to the task documentation for more information.
- A parameter was added to the ear export task, to include the new flag supported by the wizard, which includes the project meta files during export. This is useful for binary projects Refer to the product documentation for more information on optimizing development with binary projects.
- The "use35rules" parameter of the EJBDeploy task has been renamed to "compatible35".
If a Web project has recently been validated by the JSP Validator, it is possible that any library JAR files or class files referenced by that project may still be in use. As a result, it may not be possible to delete or move individual JAR or class files (for example, if you chose to delete the /WEB-INF/lib directory). If a JAR file in EAR project is referenced by a Web project as a Java JAR dependency, it may not be possible to delete the EAR project or JAR within it. To "release" these resources for file-management activities, close the Web project and then re-open it.
When you import a J2EE module and choose to overwrite existing files that are checked in to ClearCase, the files must be checked out before they can be overwritten. As soon as the import detects a file or files that are checked in to ClearCase, a warning box asks whether you want to attempt to check out the specific file or files. If you click the "Yes to All" button, WebSphere Studio will attempt to silently check out the specified files plus any other checked-in files that it later encounters during the import operation.
When you create a new J2EE project (including Java, enterprise application, Web, EJB, application client, and connector projects), you cannot use a project location that is already used by another project in the workbench. If you choose a project location that is used by another project, the wizard displays an "Invalid project description" error dialog or message. If after you receive this message you then select a valid project location by clicking the Browse button, the project creation will still not finish. The workaround is to click Cancel and reopen the project creation wizard.
When you run any J2EE or EJB Ant tasks, use the com.ibm.etools.j2ee.ant.RunAnt application instead of the org.eclipse.ant.core.antRunner application.
Using RunAnt has two advantages:
- The workspace is saved after executing the specified buildfile.
- Autobuild is disabled during Ant script execution as a performace enhancement and to fix a known limitation with org.eclipse.ant.core.antRunner on Linux.
Return to the main readme file
(C) Copyright IBM Corporation 2000, 2003. All Rights Reserved.