1.0 Introduction
2.0 Supported software and specifications
3.0 Changes from the previous release
4.0 Limitations
4.1 WebSphere Server must have matching codepage
5.0 Known problems
5.1 Configuring J2C Resource Adapters for WebSphere v5
5.2 WebSphere Application Server cannot be created or started due to invalid characters
5.3 Stopping WebSphere V4.0 test environment may cause log file write error
5.4 Long directory names can cause errors in JSP testing
5.5 Problems using Apache Tomcat when disconnected from the Internet
5.6 Running Java applications that connect to WebSphere Application Server
5.7 Running WebSphere V4.0 Administrative Client with security enabled
5.8 WebSphere Test Environment versions
5.9 Using constructors in the Universal Test Client
5.10 Default DB2 JDBC provider class path on Linux
5.11 WebSphere version 4.0 Application Clients on Linux
5.12 J2EE client cannot access test environment server on a remote machine
5.13 Message when applying WebSphere V4 PTF
5.14 Creating Data Sources and Servers in the WebSphere v5 Administration Console
5.15 Moving Server Configurations and Renaming Server Projects
5.16 Path Options for WebSphere server
5.17 Configuring Cloudscape 5.1
5.18 Republish WebSphere server to AIX machine causes warning message
5.19 Full speed debug and hot method replace support
5.20 Upgrading Cloudscape from Version 5.0 to Version 5.1
5.21 WebSphere MQ migration
5.22 Migration of Deployed Connector Projects from WebSphere Studio v5.0
5.23 Server corruption possible when saving new JAAS Authentication Entry
The Server Tools feature enables you to test and publish J2EE applications on different local and remote run-time environments. This readme file describes limitations, known problems, and workarounds that are associated with the following Server Tools functions:
- Setting up the server using a server and a server configuration. (Servers and server configurations are constructs used by Server Tools for testing and publishing on different run-time environments.)
- Testing J2EE projects on IBM WebSphere Application Server or on Apache Tomcat.
- Testing enterprise beans on the Universal Test Client.
- Static Web project support.
The online help for testing and publishing contains additional information on Server Tools restrictions and on working around problems in Server Tools.
For information on supported run-time environments refer to the product readme.
The Universal Test Client requires the use of Netscape Version 4.6 or Mozilla Version 0.7 or higher
The server tools support testing and publishing projects to WebSphere servers on Windows, Linux and AIX machines.
When testing with remote WebSphere servers, the remote machine must have the same codepage as the local machine. Running the local and remote server with different codepages is not supported and may cause the console to become corrupted.
You may receive an error when you click on the Add button on the J2C page of the WebSphere v5 server configuration editor. To work around this problem, configure the connector module within an EAR instead, or take the following steps:
1. Enable the WebSphere administrative console and start the server.
2. Open and login to the administrative console. Select Resources > Resource Adapters from the left.
3. Click New. Enter the Name of your connector module, and specify the fully qualified path to the connectorModule folder within your project. For instance, C:\workspace\myConnector\connectorModule.
4. Click Apply and then Refresh your server project within the IDE. You can now continue to use the server configuration editor for any further changes.
If you install WebSphere Studio into a directory whose name contains a dollar sign ($) or any odd character such as #, %, +, or *, the WebSphere server may not be created or will not be started successfully. To avoid this, do not install WebSphere Studio into a directory containing any of these characters.
When creating a WebSphere server or server project that will contain a WebSphere server, do not include character #, %, &, or * in the name. WebSphere Application Server does not support these characters.
When stopping the WebSphere V4.0 test environment on Linux, you may get the following errors in the Console view:
Unable to obtain Shared Log Lock file /opt/wsappdev/plugins/com.ibm.etools.websphere.runtime/logs/activity.log.lck
Stack trace:
com.ibm.ejs.ras.SharedLogLockException
at com.ibm.ejs.ras.SharedLogBase.acquireHostLock(SharedLogBase.java:251)
at com.ibm.ejs.ras.SharedLogWriter.log(SharedLogWriter.java:255)
...
Previous exception:
Message:
null
Stack trace:
java.io.IOException: Permission denied
at java.io.UnixFileSystem.createFileExclusively(Native Method)
at java.io.File.createNewFile(File.java:697)
...The problem is caused when the server fails to write to the activity.log file. The server process will be stopped successfully even if you get this error message. You can safely ignore these error messages.
If you use a workspace in a directory with a long path or choose long names for your Enterprise Application project or Web project, you may get the following error message when trying to execute a JSP page:
Error Message: JSPG0113E: JSP file
"Xxx/Yyy_jsp_0.java (Filename too long)" not foundIf you receive this error, you may take any of the following actions:
- Move your workspace to a location with a shorter path, for example c:/workspace.
- Rename your Enterprise Application project and/or Web project to have a shorter name.
- Decrease the folder depth of the JSP page within the Web application. For example, move the JSP pages into a common folder or root of the Web Content folder instead of nesting them further down.
The default web.xml file that ships with Apache Tomcat contains a reference to a DTD file on the Internet. Due to this, Tomcat servers will not start when disconnected from the Internet. In WebSphere Studio, these references have been removed from the Tomcat version 3.2 configuration so that you may work while running standalone. If you import a Tomcat server configuration from outside WebSphere Studio or are using Tomcat version 4.0, you may have problems working while disconnected from the Internet. If this occurs, take the following steps to remove this reference.
If you have problems when starting the server, you may need to connect to the Internet and re-add the DOCTYPE element using the backup web.xml file.
- Backup the web.xml file from your Tomcat server configuration.
- Edit the web.xml file in your Tomcat server configuration using a text editor.
- Remove the entire DOCTYPE element from the file.
- Save and close the editor.
WebSphere Application Server has a restriction that all Java applications that use the WebSphere client to connect to enterprise beans running on a WebSphere server must use the same level of the IBM Java ORB that was used to build the WebSphere client. If you do not use the same ORB level, you may receive an error like the following when running the client application:
java.lang.NoClassDefFoundError: com/ibm/rmi/iiop/GIOPVersionException
To ensure that the correct ORB level is used, you can run the client application using the WebSphere JRE. To do this, take the following steps:
- Open the Launch Configurations dialog using the Run > Run or Run > Debug menu items in the Debug perspective.
- Select the Java Application Launch Configuration that you want to edit.
- Go to the JRE page and select the appropriate WebSphere JRE from the combo box.
- Apply the changes.
Alternatively, you can run the client application with any JRE as long as you ensure that the matching ORB level is used. To do this, take the following steps:
- Open the Launch Configurations dialog using the Run > Run or Run > Debug menu items in the Debug perspective.
- Select the Java Application Launch Configuration that you want to edit.
- Go to the Arguments page and add the following to the VM Arguments field:
-Xbootclasspath/p:WAS_installdir\java\jre\lib\ext\ibmorb.jar
where WAS_installdir is the directory containing the runtime, e.g., c:\Program Files\IBM\WebSphere Studio\runtimes\aes_v4- Apply the changes.
The WebSphere version 4 administrative client cannot be launched directly from the workbench when security is enabled. To launch the administrative client follow these steps:
- Start the WebSphere server.
- Open a Web browser and enter the following URL: http://[localhost:8080]/admin, where [localhost:8080] is the server name and port that you are using.
- Enter the userid and password you used to configure the security. Click Submit.
- In the right hand pane, click Configuration > Open.
- Select "Enter full path to file on server".
- Enter the full path to your server configuration in the text field. For example: C:\studio\eclipse\workspace\Servers\was.wsc\server-cfg.xml.
- Click OK.
The WebSphere version 4 test environment is based on WebSphere version 4.06. The WebSphere version 5 test environment is based on WebSphere version 5.02. When you migrate from a previous version of WebSphere Studio, any e-fixes to the WebSphere test environment will be removed and you must reinstall them manually.
When using the Universal Test Client you will be unable to construct objects that take interfaces as parameters in the parameter page. All objects to be constructed from parameters with interface types must use the class references section.
First load and construct an object of the interface or abstract type. Then load your class that contains the constructor with the abstract/interface type. Now choose the premade object in the parameters page.
The default DB2 JDBC provider class path on Linux is set to ${DB2_JDBC_DRIVER_PATH}/db2java.zip. The DB2 installation location cannot be detected on Linux. Therefore, you need to manually remove this class path entry and add a new entry with the correct path in the server editor if you want to use a DB2 data source on Linux.
To access enterprise beans from an application client running on WebSphere version 4.0, you must specify the correct ORB bootstrap port of the server. You can do this by setting the JNDI Provider URL for the initial context, or if you are using access beans, by specifying the ORB bootstrap port on the command line by adding -CCBootstrapPort=2809 as a Program Argument on the Arguments page of the Launch Configuration wizard.
You may get an org.omg.CORBA.COMM_FAILURE when trying to access a test environment server from a J2EE client running on a remote machine. You have to configure the ORB bootstrap host name defined in the remote server configuration to fix the problem. To edit the ORB bootstrap host name, go the Ports page of the server editor and set the Host name field under the ORB bootstrap port section to the remote host name .
After the change is made, save the changes and restart the test environment server for the changes to take place.
When applying the WebSphere V4 PTF, you may see the message "NOTE: Please regenerate the plugin configuration once the server is started in order to update the plugin-cfg.xml file". You can safely ignore this message.
You may receive a NullPointerException or other errors when adding data sources or creating servers using the WebSphere v5 Administration Console within WebSphere Studio. Use one of the following workarounds:
- If you are creating a data source, use the WebSphere v5 server editor instead. You can open the editor by double clicking on your WebSphere v5 server in either the Servers or Server Configurations view. Go to the Data source page to add, edit, or remove data sources from the server.
- Stop the server.
- Copy the templates directory from the following directory (where WS_installdir is the directory where you have installed WebSphere Studio):
WS_installdir\runtimes\base_v5\config\templates
to your current workspace under:
workspace_ dir\server_ project\server_ name.wsc folder- Restart the server and try again.
The association between a server and its server configuration includes the project that the server configuration resides in. When you rename a server project or move a server configuration to a different project, any servers that use the configurations will have their associations broken. To resolve the problem, in the Servers view, right-click the server and select Switch Configuration > server_configuration_name to re-associate the configuration with the server.
The Path Option functionality on the Environment page of the WebSphere server editor does not work. The path entered in the Java Library Path field will be added to the existing server PATH. You will not have control over where the data is added to, for example, if the data is added to the beginning, end, or replacing the existing server PATH.
To install Cloudscape 5.1, run the installCloudscape51.bat file on Windows or Cloudscape51.sh file on Linux. This file is located in the WS_installdir/runtimes/base_v5/cloudscape51 directory (where WSinstalldir is the directory where you have installed WebSphere Studio. The installer launches a WebSphere-specific Cloudscape installer. When prompted for the Directory name, browse or type your WS_installdir/runtimes/base_v5 directory.
Note: After you install Cloudscape 5.1, you cannot run or have any Cloudscape 5.0 defined data sources. If you want to run Cloudscape 5.0, you must first uninstall Cloudscape 5.1, and then remove Cloudscape 5.1 data sources or change them to Cloudscape 5.0 data sources.
When republishing a WebSphere server to an AIX machine, you may get some warning messages about failing to delete some files in the publishing dialog box. You can safely ignore those warning messages.
Full speed debug and hot method replace is only supported when debugging in the WebSphere V5 test environment. Debugging applications outside of the WebSphere V5 test environment is not supported.
If you upgrade the Cloudscape version from 5.0 to 5.1 then be aware that Cloudscape is included in both the production application server and the test environment application server within WebSphere Studio Site Developer. You should upgrade both instances of Cloudscape to 5.1.
The WebSphere MQ component does not support cross version compatibility. You should ensure that the version of WebSphere MQ that you are using is at the same fixpack level as the WebSphere test environment or WebSphere werver that you are deploying to.
For example, you should not use the WebSphere MQ installed by WebSphere Studio v5.0 with a WebSphere v5.0.2 test environment. Instead, you should uninstall WebSphere MQ and install the version shipped with WebSphere Studio v5.1.
Workspaces created in WebSphere Studio v5.0 containing connector project that are deployed to a WebSphere test environment or WebSphere server are not automatically migrated when moving to a higher release. You may receive errors when you attempt to publish the connector projects to the server.
To work around the problem, in the Servers view, right-click the server and select Add and remove projects. Remove the EAR project from the server and then add it back. This will fix the WebSphere server configuration so that the connector projects are correctly deployed.
If you open a V5 server editor, create and save a new JAAS Authentication Entry without exiting the editor, and then go to the Data source tab and add a V5 data source, a File changed dialog appears. You must click NO to avoid corrupting the server configuration.
Return to the main readme file
(C) Copyright IBM Corporation 2000, 2003. All Rights Reserved.