Installing the WASCE WTP Server Adapter

The WASCE Web Tools Platform (WTP) server adapter is a tool for deploying and testing Java EE assets to a WASCE server. Use the Eclipse Update Manager to install the WASCE WTP server adapter from the Eclipse Update Site for IBM WebSphere Application Server Community Edition.

Information about this tool can be obtained from the Geronimo development tools site, the Geronimo 2.1 wiki and from the tool's on-line help. The following tips supplement that information.

See Developing portable Java EE assets using Eclipse for information about the JEE Profiling feature.

See Administering a server in Eclipse and Deploying in Eclipse for instructions on using the WTP Server Adapter after installing it.

See Troubleshooting the WASCE WTP Server Adapter if you have problems.

About the WASCE WTP Server Adapters

WASCE 2.1 provides a new WASCE WTP server adapter which supports WASCE 2.1.x.x and WASCE 2.0.0.x servers. These server runtimes can be downloaded from within Eclipse after the appropriate WTP server adapter is installed. If you choose to install WASCE WTP server adapter for WASCE 2.1, the server adapter for WASCE 2.0 will also be installed automatically. The WASCE 2.1 WTP server adapter may also be used to run Apache Geronimo 2.1 and 2.0.x servers, although IBM does not provide support for these features.

Compatible platforms

IBM has tested the WASCE WTP server adapter on Windows and Linux development environments supported by the Server runtime, running on Intel and AMD platforms with the provided IBM 32-bit Java software development kits (SDKs). The Eclipse IDE does support other platforms, which were not tested and therefore, cannot be recommended.

The tool may be compatible with other system platforms and operating system levels, but to obtain support for a suspected defect, you must demonstrate the defect on one of the recommended development platforms.

Installing the WTP Server Adapter for WASCE

There are four options for installing the WASCE WTP Server Adapter:

• the "Download additional server adapters" link
• the Eclipse remote update site
• the updatesite.zip file
• the deployable.zip file

Note: Be sure to install the Prerequisite Software before you attempt to install the WASCE WTP server adapter.

Prerequisite Software

For WASCE 2.1.0.0, the WASCE WTP server adapter can only depend on Eclipse Europa Winter, Version: 3.3.2, Build id: M20080221-1800. Before you can use this tool, you must download and install the prerequisite software:

• Eclipse (Europa) IDE for Java EE Developers

For WASCE 2.1.0.1 and above, the WASCE WTP server adapter also supports Eclipse Ganymede, Version 3.4.0, Build id: I20080617-2000.

• Eclipse (Ganymede) 3.4.0 IDE for Java EE Developers

Note:

• You will follows different steps to install WASCE WTP server adapter in Eclipse Europa and Ganymede (only WASCE 2.1.0.1 or above) if you are using the remote update site, the updatesite.zip file or the deployable.zip file.
• In Eclipse Ganymede, don't attempt to manually delete the WASCE WTP server adapters if they are installed using the Eclipse Update Manager; don't attempt to uninstall WASCE WTP server adapters in the Update Manager if they are installed using the deployable.zip file. See Eclipse Ganymede p2 getting started for more information about this feature of Eclipse Ganymede.

Installing the WASCE WTP Server Adapter using the "Download additional server adapters" link

1. In the Servers view panel at the bottom of the screen, right-click, select New and click Server.
   • To show the Servers View panel:
     1. On the Eclipse menu bar, click on Window, select Show View, and click Other....
     2. In the Show View panel, expand Server, select Servers and click OK.
2. In the New Server panel, click the Download additional server adapters link.
3. In the Install New Server Adapter panel, select WASCE v2.1 Server Adapter, and click Next>.
4. Read and accept the license agreement, and click Finish.
5. Click OK to install the server adapter, and restart Eclipse for the changes to take effect.

Note: In Eclipse Ganymede, if WASCE WTP server adapters are installed with "Download additional server adapters" link, uninstalling them with the Update Manager is not supported. To uninstall them, don't delete them manually from your Eclipse/plugins directory, where Eclipse is the installation directory of your Eclipse Ganymede. Instead, uninstall Eclipse Ganymede and reinstall it for your changes to take effect. More information can be found in Eclipse bugs.

Installing the WASCE WTP Server Adapter using the remote update site

Use the Eclipse Update Manager to install the WASCE WTP server adapter.

Review the welcome page from the Eclipse Update Site for IBM WebSphere Application Server Community Edition.

Note: Be sure to install the Prerequisite Software before you attempt to install the WASCE WTP server adapter.

Instructions for those familiar with Eclipse

• Add the URL of the WASCE Eclipse Update site (http://download.boulder.ibm.com/ibmdl/pub/software/websphere/wasce/updates/) as a remote site in your Eclipse update manager, and search for features to install from it.
• To install the Eclipse WTP server adapter for WASCE 2.1 server, select WASCE Server Adapters:
  • WASCE v2.1 Server Adapter 2.1.1

Detailed Instructions for Eclipse Europa

1. Open the Eclipse Update Manager as follows:
   1. Click Help->Software Updates, and then Find and Install....
   2. Select Search for new features to install and click Next.
2. On the Update sites to visit panel, create a WASCE Eclipse Update Site as follows:
   1. Click the New Remote Site... button in the upper right corner.
   2. Type WASCE Eclipse Update Site (or other suitable unique name) in the Name: field.
   3. Put the URL of the WASCE Eclipse Update site (http://download.boulder.ibm.com/ibmdl/pub/software/websphere/wasce/updates/) in the URL: field.
   4. Click OK.
3. Select only the WASCE Eclipse Update Site in the Sites to include in search selection box and click Finish.
4. Select a mirror and click OK if prompted to do so.
5. Expand WASCE Eclipse Update Site, and WTP Server Adapters.
6. Select the WTP server adapters you want.
   • To install the Eclipse WTP server adapter for WASCE 2.1, select WASCE Server Adapters:
     • WASCE v2.1 Server Adapter 2.1.1
   • It is not necessary or recommended to install a server for development and test from the IBM WASCE Runtimes in the update manager list. The appropriate server will be downloaded the first time you click the Download and install button when you define a new server. However, the recommended way to get and install a WASCE server is to follow the first two steps on the Setup page.
   • Click Next.
7. Accept the license agreement and click Next.
8. Verify your installation as follows:
   1. Verify the location and click Finish.
   2. Verify the feature name, feature identifier, provider, file identifier and click Install or Install All.
   3. Starting from WASCE 2.1.1.2, if you don't choose to Install All, you will be prompted in a Verification page to verify whether you trust the certificates associated with the WASCE WTP server adapter. You can choose to click Continue or Install All to install or Cancel to cancel this installation.
9. Click Yes to restart Eclipse for the changes to take effect.

Detailed Instructions for Eclipse Ganymede

1. Open the Update Manager as follows:
   1. Click Help->Software Updates, and then Available Software.
   2. Click Add site.
2. On the Add site panel, put the URL of the WASCE Eclipse Update site (http://download.boulder.ibm.com/ibmdl/pub/software/websphere/wasce/updates/) in the Location: field, and click OK.
3. Expand http://download.boulder.ibm.com/ibmdl/pub/software/websphere/wasce/updates/ and WTP server adapters.
4. Install the WTP server adapters you want.
   • To install the Eclipse WTP server adapter for WASCE 2.1, select WASCE Server Adapters:
     • WASCE v2.1 Server Adapter 2.1.1
   • Click Install.
   • Click Next.
5. Read and accept the license agreement. Click Finish.
6. Starting from WASCE 2.1.1.2, you will be prompted to decide whether you trust the certificates associated with the WASCE WTP server adapter. You can find the details of the certificates by clicking on Details. If you trust these certificates, select the checkboxes on the left, and click OK for the installation to continue. Otherwise, the installation will fail.
7. You may need to to restart Eclipse for the changes to take effect.

You can uninstall WASCE server adapters in the Update Manager if they are installed using the Update Manager, although it's not recommended:

1. Click Help->Software Updates, and then Available Software.
2. Expand http://download.boulder.ibm.com/ibmdl/pub/software/websphere/wasce/updates/ and WTP server adapters.
3. Select the WTP server adapter that you would like to uninstall and click Uninstall.

Note: Uninstalling WASCE server adapters using the Update Manager will only cause the removal of the WTP server adapters from your Eclipse Ganymede user interface. See Troubleshooting for more information about how to remove them completely.

Installing the WASCE WTP Server Adapter using the updatesite.zip file

1. Visit the welcome page from the Eclipse Update Site for IBM WebSphere Application Server Community Edition.
2. Find the updatesite.zip package and click the linkage to download it.
3. Follow the instructions in Installing the WASCE WTP Server Adapter using the Eclipse Update Manager, and create the update site as follows:
   • Extract this package to a directory on your machine. In Eclipse Europa, on the Update sites to visit panel, click New Local Site... and create a new local update site to which you extracted the updatesite.zip package. In Eclipse Ganymede, on the Add Site panel, click Local... and create a new local update site to which you extracted the updatesite.zip package.
   • Or you can create a new local archived site from the .zip package. In Eclipse Europa, on the Update sites to visit panel, click New Archived Site... and create a new archived update site from the updatesite.zip package. In Eclipse Ganymede, on the Add Site panel, click Archive... and create a new archived update site from the updatesite.zip package.
4. Install the WTP server adapters you want.
   • To install the Eclipse WTP server adapter for WASCE 2.1 server, select IBM WAS Community Edition:
     • WASCE v2.1 Server Adapter 2.1.1
5. Complete installation following the same instructions in Installing the WASCE WTP Server Adapter using the Eclipse remote update site.

Installing the WASCE WTP Server Adapter using the deployable.zip file

Installing in Eclipse Europa

1. Visit the welcome page from the Eclipse Update Site for IBM WebSphere Application Server Community Edition.
2. Find the deployable.zip package and click the linkage to download it.
3. Make sure Eclipse is not running.
4. Extract this package to your Eclipse directory.
5. Use the Eclipse -clean option after installing the WTP server adapter.

Note: In Eclipse Europa, to uninstall WASCE WTP server adapters that are installed using the deployable.zip file, don't try to uninstall them using the Update Manager. Instead, close Eclipse and delete them manually from your Eclipse Europa installation directory. Use the -clean option for the changes to take effect.

Installing in Eclipse Ganymede

1. Visit the welcome page from the Eclipse Update Site for IBM WebSphere Application Server Community Edition.
2. Find the deployable.zip package and click the linkage to download it.
3. Make sure Eclipse is not running.
4. Extract this package to your <ECLIPSE_HOME>/dropins directory, where <ECLIPSE_HOME> is the installation directory of your Eclipse Ganymede.
5. Use the Eclipse -clean option after installing the WTP server adapter.

Note: In Eclipse Ganymede, to uninstall WASCE WTP server adapters that are installed using the deployable.zip file, don't try to uninstall them using the Update Manager. Instead, close Eclipse and delete them manually from your Eclipse/dropins directory, where Eclipse is the installation directory of your Eclipse Ganymede.

Troubleshooting the WASCE WTP Server Adapter

Use the Eclipse -clean option after installing the WTP server adapter

After installing the WTP server adapter, whether it is the first installation or a subsequent installation of a newer version, start Eclipse with the -clean option. This allows Eclipse to recognize and use the newest version of the WTP server adapter.

Views synchronize when saved

While using the WTP server adapter to customize deployment plans, you may want to use both the form view and the source view. When you are using both views, remember that changes made in one view will not be reflected in the other view until the changes are saved. Be sure to save your changes before switching to a different view.

An IP address change can orphan the server

If the server is running on a host where the IP address has been assigned using DHCP, be sure to stop the server before the IP address changes. For example, you are using a laptop with an Ethernet connection, stop the server before you disconnect and switch to a wireless connection. If you don't, Eclipse will not be able to send a shutdown request to the hidden process where the server is running and if the server is not stopped gracefully, some of the server's configuration changes may be lost.

If the IP address changes while the server is running, you will need to stop the javaw process that contains the server or restart the host. In either case, you will have to repeat any configuration changes that were not saved correctly.

Unable to open Deployment plan editor in Eclipse

This error can occur when opening a WASCE- or Geronimo-specific deployment plan without having a WASCE server specified as a "Targeted Runtime". An "IllegalArgumentException" may be thrown. To fix the problem, specify a WASCE runtime as the "Targeted Runtime" for the asset as described in Deploying in Eclipse.

Unable to uninstall WASCE WTP server adapters with Eclipse Ganymede

Currently, you can uninstall WASCE server adapter in Eclipse Ganymede using the software update manager, but this will only cause the removal of the WTP server adapters from your user interface. To completely remove the WASCE server adapters, uninstall Eclipse Ganymede and reinstall it.

Question about an possibly invalid software item blocks the installation

This error can sometimes occur when you select a WASCE WTP server adapter and click Install in the Update Manager of Eclipse Ganymede. You are warned that the software items you select may not be valid with your current installation, and are prompted to decide whether you want to open the wizard anyway. If you click Yes and continue to view the wizard, you will get some errors. To fix this problem, make the following changes:

1. On the Software Updates and Add-ons panel, click the Available Software Sites tab and then click Manage Sites....
2. Deselect the software sites with check marks other than the WASCE Eclipse update site (http://download.boulder.ibm.com/ibmdl/pub/software/websphere/wasce/updates/).
3. Click OK and install the WASCE WTP server adapter again.