IBM WebSphere Everyplace Client Toolkit 6.0 Release Notes

Contents

About this release

WebSphere® Everyplace® Client Toolkit 6.0 provides a complete, integrated set of tools that allows you to develop, debug, test, package and deploy client applications that use WebSphere Everyplace Deployment for Windows® and Linux® services. Both Rich Client Platform (RCP) local GUI-based applications and Web Container Servlet/JavaServer Pages (JSP) applications are supported. Built on IBM® Eclipse SDK (IES) 3.0.2, this toolset extends the robust Rational® suite of development tools so that you can leverage your existing skills and software components.

Note: WebSphere Everyplace Client Toolkit is the new name of the Micro Edition Toolkit for WebSphere Studio previously shipped with IBM Workplace Client Technology®, Micro Edition - Enterprise Offering (WCTME EO). The new name for WCTME EO is IBM WebSphere Everyplace Deployment for Windows and Linux.

What's new? What's new?

The IBM WebSphere Everyplace Client Toolkit includes the following new features and functions necessary for the development and deployment of the applications for WebSphere Everyplace Deployment for Windows and Linux:

General
Web Application Development
Develop, test, and deploy Web applications for WebSphere Everyplace Deployment for Windows and Linux platforms, Java® Servlet 2.4 and 2.3, and JSP 2.0 and 1.2. Develop Struts and JavaServer Faces (JSF) applications for WebSphere Everyplace Deployment for Windows and Linux.
Embedded Transaction Application Development
Develop or convert Rational Application Developer (RAD) or Rational Software Architect (RSA) 6.0 Enterprise JavaBeans® (EJB) projects into Client Services Embedded Transaction Projects for use with WebSphere Everyplace Deployment for Windows and Linux.
Platform Building
Create client runtime images, containing a JVM, WebSphere Everyplace Deployment for Windows and Linux runtime components, and user-selected components.
Web Services

Software compatibility Software compatibility

The following products can communicate with IBM WebSphere Everyplace Client Toolkit 6.0:

Backward compatibility Backward compatibility

Compatibility with previous versions of this offering is as follows:

General
WebSphere Studio Device Developer (WSDD) V5.7.1 and V5.6
IBM Workplace Client Technology, Micro Edition - Enterprise Offering (WCTME EO) V5.8.1
IBM Workplace Client Technology V6.0 - Technical Preview

Installation requirements

Installation requirements are as follows:

Hardware requirements Hardware requirements

Minimum hardware requirements for WebSphere Everyplace Client Toolkit 6.0 are as follows:

Software requirements Software requirements

Minimum software requirements for WebSphere Everyplace Client Toolkit 6.0 are as follows:

Notes:

Limitations, known problems, and updates

The following updates, limitations, and problems are known at the time of this release. Future updates about WebSphere Everyplace Client Toolkit are documented in the form of Technotes on the IBM Software Support Web site at: http://www.ibm.com/software/pervasive/ws_everyplace_client_toolkit/support

As limitations and problems are discovered and resolved, the IBM Software Support team updates the knowledge base. By searching the knowledge base, you can quickly find workarounds or solutions to problems that you experience. To create your own query, go to the Advanced search page.

New samples New samples

In addition to the WebSphere Everyplace Deployment for Windows and Linux samples in the Samples Gallery, the following sample applications are available for download on the WebSphere Everyplace Client Toolkit Web site at:

http://www.ibm.com/software/pervasive/ws_everyplace_client_toolkit/

Simply go to the "Highlights" section to download the zip files and follow the setup instructions provided (MobileAdjuster-InstallAndConfig.pdf and Bankdemo_install.pdf).

To install and run a sample, locate the "Highlights" section on the Web page, download the zip file, and follow these basic steps:

Important: For detailed setup instructions, see the MobileAdjuster-InstallAndConfig.pdf and Bankdemo_install.pdf files, located in their respective zip files.

  1. Log on to your system with an administrator ID that has write permission to the installation location and start the Rational SDP.
  2. From the main menu, click Help > Software Updates > Find and Install. The Install/Update wizard is displayed.
  3. Select Search for new features to install and click Next.
  4. In the "Update sites to visit" window, select the New Local Site button.
  5. Browse to select the drive and directory where you downloaded the sample zip file and click OK.
  6. Select the check box next to the site name and click Next.
  7. In the Search Results window, select the sample feature and click Next.
  8. In the Feature License window, read the licensing information, select to accept the license and click Next.
  9. In the Install Location window, the directory location where this feature will be installed is displayed. Click Finish to begin the installation.
  10. In the Feature verification window, verify that the feature information is correct and click Install.
  11. When installation completes, you are prompted to restart your Rational program for changes to take effect. Click Yes to continue.
  12. To confirm that the installation was successful, start the Rational SDP and select Help > Samples Gallery. Expand Showcase samples > WebSphere Everyplace Deployment to view installed samples.

Software limitations Software limitations

Platform Builder software limitations:

knownprobs Known problems and workarounds

Deploying and testing Web applications on Linux:

For Web application developers to use the packaged WebSphere Everyplace Deployment for Windows and Linux runtime to deploy and test their applications on Linux, Mozilla libraries must be added to the LD_LIBRARY_PATH.

The IBM 1.4.2 VM erroneously removes certain entries of the environment variable LD_LIBRARY_PATH that start with /usr/lib. Mozilla is, in most instances, installed into /usr/lib/mozilla-1.x.x. The workaround (provided by Eclipse) is to add /usr/../usr/lib/mozilla-1.x.x (1.x.x is your Mozilla version, e.g. /usr/../usr/lib/mozilla-1.4.3) to the LD_LIBRARY_PATH or set an environment variable MOZILLA_FIVE_HOME to /usr/../usr/lib/mozilla-1.x.x and add it to the LD_LIBRARY_PATH.

To add Mozilla libraries to LD_LIBRARY_PATH for the WebSphere Everyplace Deployment launcher, do one of the following:

Synchronizing the bundle server, the workspace and the target platform:

At times, it is possible for the bundle server, the workspace and the target platform to get out of sync. This is indicated by entries in the error log view, such as: "CWPBD0010E:DMSInterfaceAPI: bundle failed to register". To resynchronize the environment, follow these steps:

  1. Restart the Rational Software Development Platform.
  2. Select Window > Preferences > Plug-in Development > Target Platform.
  3. Click the Reload button.
  4. Click OK.

This starts the Bundle Server Registration job. After the job is completed, the tooling functions correctly again.

Adding projects to secondary dependency list:

After adding a plug-in (for example, com.ibm.eswe.help.webapp) to a project's secondary dependency list, you might encounter an error message similar to the following:

Required library cannot denote external folder: '[toolkit_install_directory]\plugins\com.ibm.pvc.wct.runtimes_6.0.0\rcp\eclipse\plugins\com.ibm.eswe.help.webapp_6.0.0\WEB-INF\classes' for project [project_name]

To resolve the compilation error, you must remove the plug-in that caused the error (for example, com.ibm.eswe.help.webapp) from the project's secondary dependency list. To do so, use the Bundle manifest editor's resource page, and save the manifest file.

This resolves the error and allows you to launch and deploy the project.

If you want to program against this plug-in, follow these steps:

  1. Import the com.ibm.eswe.help.webapp plug-in to the workspace.
  2. Add com.ibm.eswe.help.webapp to the project's secondary dependency list, and save the manifest file.

Error installing/uninstalling the WebSphere Everyplace Client Toolkit:

When you install or uninstall the WebSphere Everyplace Client Toolkit, you may receive the following error message: "The current configuration contains errors and this operation can have unpredictable results. Do you want to continue?"

Workaround: Ignore this error and select OK to continue installing or uninstalling.

Arabic character sets:

For WebSphere Everyplace Deployment Client 6.0 to display the Arabic character set correctly on Linux, install the appropriate Arabic font package to the Linux system.

BYTE_ENCODING and KEY_VAL_FULLY_QUALIFIED:

If you are developing Mobile Web Services clients using the information and sample code in the "Deploying Mobile Web Services clients" section of the Developers Guide, change the package name of the properties BYTE_ENCODING and KEY_VAL_FULLY_QUALIFIED from javax.xml.rpc.Stub to com.ibm.pvcws.jaxrpc.rpc.Properties. The same applies to the BYTE_ENCODING values BYTE_UNBOUNDED ("byteUnbounded") and BYTE_BASE64BIN ("byte64Binary")."

Convert Project to Client Services Project wizard:

If you use the 'Convert Project to Client Services Project wizard', and the target project has other workspace projects listed in its Java Build Path, these projects will be removed from the Java Build Path after conversion, causing project errors. This happens if the "Update Java build path for required bundles" option is selected. However, this option should be selected in most cases. Refer to Developer's Guide for more information on this option.

In order to remove the error, you need to complete the following steps:

  1. Convert the dependent project into a Client Services project.
  2. Open the project's manifest editor, and add the dependent project to the Dependencies page as a required plug-in.

Platform Builder - Add Required Plug-ins:

Platform Builder offers the user the option to validate that their configuration contains the required plug-ins and plug-in fragments for all of the chosen plug-ins. The Add Required Plug-ins button in the Plug- in/Bundles panel does this resolution for all selected plug-ins.

The algorithm searches plug-ins for all OSGi services, operating system fragments, appropriate language fragments, and other available plug-in fragments. In some cases, there will be plug-in fragments intended to provide additional levels of functionality for a plug-in, but are not required for your particular operation. The algorithm cannot determine this use, and always adds the fragments. If this occurs, you can remove the selection for the fragment from the selection list and continue.

An example where this occurs in the WebSphere Everyplace Deployment Client technology space, is the relationship between the com.ibm.osg.service.http plug-in and the fragments defined for it. In particular, the com.ibm.pvc.webhttpservice plug-in may not be needed when the user wants the com.ibm.osg.service.http plug-in.

Changing Platform Branding:

You can change the image of the Open button to an image of your choice. You must provide a 32 X 32 and 16 X 16 image. To replace the default Open button images, add your images to the following directory:

[installation_directory]/rcp/eclipse/plugins/com.ibm.pvc.wct.platform_[version_no]/images

and then modify the 'openImage' setting in the plugin_customization.ini (for example, openImage=/images/myimage_32x32.gif).

NOTE: The name of the images must be suffixed with the size of the image - 32x32 or 16x16. If the system is unable to locate the image you have specified, the default Open button images are used.

[requires] section of the feature.xml file:

When creating a feature project that includes Client Services projects or PDE Plug-in projects, the PDE calculates prerequisites and adds them to the [requires] section of the feature.xml file. Because it is necessary for the WebSphere Everyplace Deployment for Windows and Linux runtime to export java and javax packages from the JRE plugin, the JRE plug-in may be added to the list of prerequisites. Because this plug-in is platform specific, it prevents your features from being deployed to some clients. When installing applications in WebSphere Everyplace Deployment for Windows and Linux, the following error message is displayed:

XYZ (1.0.0) requires plug-in "com.ibm.rcp.j2se.linux.x86" or XYZ (1.0.0) requires plug-in "com.ibm.rcp.j2se.win32.x86"

To resolve this problem, remove "com.ibm.rcp.j2se.linux.x86," "com.ibm.rcp.j2se.win32.x86," or both entries from the [requires] section of the feature.xml file and re-export your feature.

Embedded Transaction Deployment Descriptor:

The deployment package, which is specified for a bean relationship in the Embedded Transaction Deployment Descriptor, is automatically added to the project's manifest file by the Deploy operation. Specifically, it is added to both the Provide-Package and Export-Package fields in the manifest. However, changing the deployment package in the descriptor does not automatically remove the package from the manifest file. If the package no longer exists in the project, you are informed through errors on the manifest stating that the package does not exist in the project. You can remove the package from the manifest as follows:

  1. Open the manifest editor for the project
  2. On the Runtime tab, remove the package from the Library exporting list.
  3. On the Bundle Resources tab, remove the package from the Export Packages list.

Support for JAVA_HIGH_ZIPFDS:

In Linux, for the IBM JRE to create a high number of file descriptors for later use in a separate area of memory, you must create an environment variable called JAVA_HIGH_ZIPFDS. If you encounter the following errors, you must set the value manually: 

SWTError: No more handles

or...

_X11TransSocketOpen: socket() failed for local _X11TransSocketOpenCOTSClient: 
Unable to open socket for local _X11TransOpen: transport open failed for 
local/localhost.localdomain:0

Run On Server:

When using the WebSphere Everyplace Client Toolkit 'Run On Server' mechanism to debug your Web application project, you may see the following error message printed to the console:

SEVERE: Webcontainer:com.ibm.ws.webcontainer.WebContainer SRVEO255E: A 
WebGroup/Virtual Host to handle /[webApp_context_root]/ has not been defined. 
Thread [HttpServer : 1,5,main]

This error indicates a timing problem between when the Web application was started and when the Web application request occurred. The request occurred before the Web application was registered with the Web container. This error has no impact on the actual running of the Web application and can be ignored.

Exporting a Client Services Web Project or a Client Services Embedded Transaction Project:

When exporting a Client Services Web Project or a Client Services Embedded Transaction Project, the build.properties file is not used. Therefore, entries in this file will be ignored by this process, and the exported project will be in a format suitable for use in the WebSphere Everyplace Deployment for Windows and Linux runtime.

INPUT type=file element:

The WebSphere Everyplace Deployment for Windows and Linux embedded browser may not support the INPUT type=file element in HTML forms. This problem only occurs when Mozilla is used as the embedded browser - the problem does not occur in Internet Explorer.

Deploying projects with large number Embedded Transaction Applications:

When deploying a project containing a very large number of Embedded Transaction applications, deployment might fail. To work around this problem, split the project into multiple projects and try to deploy each one.

Shutting down the WebSphere Everyplace Deployment for Windows and Linux test environment:

When the stop functions provided on the WebSphere Everyplace Deployment for Windows and Linux launch and server views are used to stop the test environment, the test environment JVM will be terminated. Therefore, proper shutdown processed will not be run. It is recommended that the WebSphere Everyplace Deployment test environment be shut down by selecting File > Exit on the WebSphere Everyplace Deployment user interface.

Documentation updates Documentation updates: Developer's Guide

JSF development has been simplified from the instructions currently documented in the WebSphere Everyplace Deployment Developer's Guide. The required JSF libraries are now part of the client platform runtime, and do not have to be packaged in the Web application's WEB-INF/lib directory. Therefore, you do not have to follow the project creation and conversion restrictions outlined in the documentation.

Depending on whether your project was created as a Client Services Web project, or converted from an existing Dynamic Web project, the tooling may have added JSF and JSTL specific libraries to your project's WEB-INF/lib directory. If you are converting an existing Web project that has already been tested with JSF support libraries contained in the application, you can leave these in place, and the application will run. Otherwise, you should delete these JSF and JSTL libraries to use the JSF and JSTL libraries in the runtime, and reduce the application's footprint. The one exception is library jsf-ibm.jar, which has IBM specific JSF extensions that may be required by your application if you use the tool's editor to generate content for your JSF pages.

The following JSF and JSTL libraries can be safely deleted from your application's WEB-INF/lib directory:

The following libraries may automatically be added to your Web application by the tooling, and can be removed if your application is not explicitly using them:

If you target a project using JSF to both the WebSphere Application Server and WebSphere Everyplace Deployment runtimes, you need to make the following adjustment when switching to the WebSphere Application Server runtime.

Edit the project's Web deployment descriptor, and make sure that the value for the context parameter com.ibm.ws.jsf.JSP_UPDATE_CHECK is set to true similar to the following example:

[param-name]com.ibm.ws.jsf.JSP_UPDATE_CHECK[/param-name]
[param-value]true[/param-value]

The WebSphere Everyplace Deployment for Windows and Linux runtime requires this parameter value to be false, and the tooling will automatically update its value to false when you run the project on the WebSphere Everyplace Deployment for Windows and Linux platform. However the tooling does not automatically set the value back to true if you then switch to run the project on WebSphere Application Server. For that reason, you must make the adjustment described above.

In the section Reference > JNDI Binding > com.ibm.pvc.jndi.provider.java.binding, there is an incorrect line in the code sample box under the title Examples. The line:

objectFactory-id="com.ibm.pvc.jndi.provider.java.genericobjectfactory">

should be updated to:

objectFactory-id="com.ibm.pvc.jndi.provider.java.GenericObjectFactory">

In the section Reference > JNDI generic object > com.ibm.pvc.jndi.provider.java.genericobject, there is an incorrect line in the code sample box under the title Examples. The line:

extension point="com.ibm.pvc.jndi.provider.java.genericobjectfactory">

which should be replaced with:

extension point="com.ibm.pvc.jndi.provider.java.genericobject">

In the section Using Platform Services > Configuring Enterprise Definitions (JNDI) > Using declarative JNDI, there is an incorrect line in the provided sample code. The line: 

objectFactory-id="com.ibm.pvc.jndi.provider.java.genericobjectfactory">

should be updated to:

objectFactory-id="com.ibm.pvc.jndi.provider.java.GenericObjectFactory">

In the section Using the IBM WebSphere Everyplace Client Toolkit > Getting started with the IBM WebSphere Everyplace Client Toolkit > Setting up the WebSphere Everyplace Client Toolkit, step 3b has been updated to include additional problem types:

3b. In the problem type checklist, ensure that the following types are selected:

In the section Developing Embedded Transaction applications > Embedded Transaction specific considerations, the following additional consideration should be taken into account when developing Embedded Transactions:

Adding an Assembly Descriptor to the EJB Deployment Descriptor

Embedded Transaction applications are required to have an assembly descriptor in their EJB deployment descriptor. While this is not required by the WebSphere Application Server EJB container, it is required by the Embedded Transaction container. Failure to add the assembly descriptor will result in the following error from the deploy operation:

java.lang.IllegalArgumentException: CWPEC6112E: assembly-descriptor element not defined in XML deployment descriptor

System administrator's guide documentation updates Documentation updates: System Administrator's Guide

In the section Registering Order Entry with a Device Management server, step 3f is incorrect. It should read:

Select all of the operations for the appropriate Device Class, OSGi, Win32, or Linux, depending on the type of client you selected in step 3b.

In the section Managing applications with WebSphere Everyplace Deployment > Configuring enterprise definitions (JNDI) > Using declarative JNDI, there is an incorrect line in the provided sample code. The line: 

objectFactory-id="com.ibm.pvc.jndi.provider.java.genericobjectfactory">

should be updated to:

objectFactory-id="com.ibm.pvc.jndi.provider.java.GenericObjectFactory">

In the section Changing the splash screen , the file name "spash.bmp" is incorrect. The correct file name is "splash.bmp".

In the section Changing the About dialog , the file name "about.bmp" is incorrect. The correct file name is "productAbout.bmp".

Additional Information

For updates, please visit http://www.ibm.com/software/pervasive/ws_everyplace_client_toolkit/support

Contacting IBM Software Support

IBM Software Support provides assistance with product defects.

Before you submit the problem to IBM Software Support, ensure that your company has an active IBM software maintenance contract, and that you are authorized to submit problems to IBM. The type of software maintenance contract that you need depends on the type of product you have:

If you are not sure what type of software maintenance contract you need, call 1-800-IBMSERV (1-800-426-7378) in the United States. From other countries, go to the "Contacts" page of the IBM Software Support Handbook at http://techsupport.services.ibm.com/guides/contacts.html and click the name of your geographic region for phone numbers of people who provide support for your location.

To contact IBM Software support, follow these steps:

Determine the business impact Determine the business impact of the problem

When you report a problem to IBM, you are asked to supply a severity level. Therefore, you need to understand and assess the business impact of the problem that you are reporting. Use the following criteria:

Severity 1 The problem has a critical business impact: You are unable to use the program, resulting in a critical impact on operations. This condition requires an immediate solution.
Severity 2 This problem has a significant business impact: The program is usable, but it is severely limited.
Severity 3 The problem has some business impact: The program is usable, but less significant features (not critical to operations) are unavailable.
Severity 4 The problem has minimal business impact: The problem causes little impact on operations, or a reasonable circumvention to the problem was implemented.

Describe the problem Describe the problem

When describing a problem to IBM, be as specific as possible. Include all relevant background information so that IBM Software Support specialists can help you solve the problem efficiently. To save time, know the answers to these questions:

Submit the problem Submit the problem

You can submit your problem to IBM Software Support in one of three ways:

If the problem you submit is for a software defect or for missing or inaccurate documentation, IBM Software Support creates an Authorized Program Analysis Report (APAR). The APAR describes the problem in detail.

Whenever possible, IBM Software Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the Software Support Web site daily, so that other users who experience the same problem can benefit from the same resolution. You can also search APARs with the IBM Support Assistant. To do so, click Help > IBM Support Assistant. From the Search tab, select IBM Software Support Documents > specific document type > IBM APARs. To limit the APAR search, also select specific product check boxes in the right-hand pane.

Notices

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and\or changes in the product(s) and\or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

Third party licenses Third party licenses

Refer to the notices.txt file for important legal information, copyright, and third party notices. The notices.txt file is located on the product CD.

Trademarks Trademarks

The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both:

Intel and Pentium are trademarks or registered trademarks of Intel Corporation in the United States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Other company, product, and service names may be trademarks or service marks of others.

(c) Copyright International Business Machines Corporation 2005. All rights reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.