Migrate a Version 5.1 web services gateway configuration

In WebSphere Application Server Version 5.1, the web services gateway was a separable component with its own user interface. In later versions of the product, the gateway is integrated into service integration bus-enabled web services, and re-implemented as a mechanism for extending and linking inbound and outbound services. You use a wsadmin command script to migrate an existing gateway configuration from a Version 5.1 application server to an application server or cluster on a later version.

Consider whether we have to migrate the existing gateways:

• WebSphere Application Server Version 5.0 is no longer supported, so you should migrate any existing gateways that are running in Version 5.0 application servers to run on application servers at the current level of the product.

• Web services gateways running on WebSphere Application Server Version 5.1 can, subject to certain restrictions, coexist with gateway instances running on Version 7.0 or later application servers.

• A Version 7.0 or later cell can contain Version 5.1, Version 6 and Version 7.0 or later application servers.

For more information, see Coexistence: Preserve or migrate a Version 5.1 gateway.

We can migrate a Version 5.1 gateway that is in production use without stopping the gateway; requester applications can then switch over to using the new gateway configuration while the existing Version 5.1 gateway continues to run.

The migration process takes a Version 5.1 gateway application whose configuration has been exported to an XML file and uses the exported XML file to configure the same gateway functions on a single application server or cluster on the later version. To do this you export the Version 5.1 gateway configuration, then run a script to migrate the exported configuration into a new gateway instance in an existing application server or cluster on the later version.

The Version 5.1 configuration is migrated as follows:

• As part of the migration process, a gateway instance is created automatically.

• Gateway services, target services and UDDI references are migrated directly.

• The definitions within the gateway of JAX-RPC handlers and handler lists are also migrated. We must ensure that the underlying handler classes are available at run time.

• Assignments of gateway services to specific channels are replaced by equivalent assignments to specific inbound port and endpoint listener pairs (because in later versions the functions of a channel are shared between an endpoint listener and an inbound port). Any use of an Apache SOAP channel is migrated to a SOAP over HTTP endpoint listener and inbound port.

• Existing filters are not migrated. The use of filters was deprecated in Version 5.1.1 and support for filters was removed in Version 7.0. The role formerly played by filters is now undertaken by a combination of JAX-RPC handlers and service integration bus mediations.

• Web service clients that are generated from the WSDL for the target service, rather than the gateway service, are flagged by default in later versions as an error.

• If we used the Version 5.1 gateway service WSDL to generate the web service clients, and the WSDL binding and encoding style is not document literal, then after migration to a later version you must regenerate the client stubs using the new gateway service WSDL.

• WS-Security bindings are migrated as bindings that comply with the WS-Security Draft 13 specification. However:

  • The final version (1.0) of the WS-Security specification (implemented in WAS v6) is not compatible with the Draft 13 version, and therefore use of WS-Security Draft 13 was deprecated in WAS v6. Use of WS-Security Draft 13 is deprecated, and you should only use it to allow continued use of an existing web services client application that has been written to the WS-Security Draft 13 specification.

  • The WS-Security binding objects are only migrated if the migration process is run on the machine on which the target server is running in the case of a stand-alone server, or on the machine on which the deployment manager is running in a network deployment configuration.

  • Only WS-Security binding objects used by a Gateway Service or Target Service WS-Security configuration are migrated. Any binding objects that we create but do not use are not migrated. For example: If we have a WS-Security configuration that references a Signing Information object, and the Signing Information object references a Trust Anchor, then the Signing Information object and the Trust Anchor object are both migrated along with the WS-Security configuration that references them.

• The migration assumes that the external web addresses for the migrated services are unchanged. This assumption is based on the expectation that these addresses are associated with a web server rather than with the machine on which the gateway is hosted, and that the host name and port number for these addresses are therefore not affected. If in the configuration the external web addresses point to the gateway machine, modify the endpoint listener configuration after the migration process has completed.

• We can use WebSphere Application Server Network Deployment to migrate to a single server running under either configuration profile (stand-alone server or deployment manager). However, IBM recommends that you migrate to a single server running under a dmgr profile. If we migrate to a stand-alone server profile we cannot use the console to subsequently modify the gateway configuration.

• Service integration bus-enabled web services validate web service messages more thoroughly than is done in WebSphere Application Server Version 5.1. As a result, some client applications that use poorly-formed requests or responses (where the message parts are misnamed) and that work when using Version 5.1 are now identified as poorly-formed. For the steps to take to resolve the problem, see Bus-enabled web services: Known restrictions.

To migrate an existing gateway configuration from a Version 5.1 application server to the gateway capability on an application server or cluster on a later version...

1. Optional: Remove any filters from the Version 5.1 gateway.

   We can migrate a gateway containing filters. However filters do not work in later versions, so you might prefer to remove them from the configuration before migration by completing the following steps:

   1. Check whether the Version 5.1 gateway uses filters. For more information, see the WAS Version 5.1 topic: Listing and managing gateway-deployed filters.

   2. Remove any filters. For more information, see the WAS Version 5.1 topic: Remove filters from the web services gateway.
   After migration, we can recreate the filter functions by using a combination of JAX-RPC handlers and service integration bus mediations. If we migrate a web services gateway that includes a routing filter, we can recreate the filter functions.

2. Choose a target server or cluster that is a single server or cluster on the later version, and is part of a network deployment cell.

3. Configure the target server or cluster as a member of a service integration bus.

4. Configure a Service Data Objects (SDO) repository at cell scope for the target server or cluster.

5. If we are migrating any EJB bindings, and we want them to continue to use an RPC-encoded binding or any binding other than document literal, add a binding of the correct type to the EJB binding WSDL. This step is necessary because the Version 5.1 gateway default binding is RPC-encoded, whereas in later versions the default binding is document literal.

6. Ensure that the source (Version 5.1) application server is running, use the Version 5.1 gateway user interface to back up the gateway configuration from the Version 5.1 application server as a private configuration. For more information, see the WAS Version 5.1 topic: Backing up a gateway configuration.

7. Optional: Stop the Version 5.1 application server.

   If we are migrating a gateway that is in production use, keep the Version 5.1 gateway running until the gateway configuration on the later version is complete, then switch the requester applications over to using the new gateway configuration while the existing Version 5.1 gateway continues to run. However both versions of the gateway do not have to be running at the same time, and we might have to stop the Version 5.1 server before you start the server or cluster on the later version (for example if you are installing the server or cluster on the later version as a direct replacement for the Version 5.1 server, on the same machine and using the same port numbers).

8. Start the target application server or cluster on the later version and, for a single server or cluster within a managed cell, the deployment manager for the target cell.

9. Check that all the WSDL documents that were used to define the target services on the Version 5.1 application server are available at their given locations. If the WSDL location is a UDDI reference, check that the referenced UDDI registry is available.

10. Optional: If the gateway being migrated uses JAX-RPC handlers and handler lists, ensure that the underlying handler classes are available at run time.

11. To migrate the exported configuration into a new gateway instance in the application server or cluster on the later version...

    1. Open a command prompt, then change to the app_server_root/util directory.

    2. Run the following command:

       (iseries) Note: The wsadmin scripting client is run from Qshell. For more information, see Configure Qshell to run WebSphere scripts .

       migratewsgw.ext -C=cell_name [-S=server_name -N=node] [-X=cluster_name] -B=bus_name -G=v5_gateway_configuration_file_name [-H=administration_hostname] [-A=administration_port] [-U=gateway_instance_name] [-P=object_prefix] [-username=WAS_user_ID -password=WAS_password]

       where:

       • (dist)(zos) .ext is the file extension .bat for a Windows system, or .sh for a Unix or Linux system.

       • Square brackets ("[ ]") indicate that a parameter or set of parameters is optional in some circumstances.

       • Either server_name and node together (for a single server), or cluster_name (for a cluster), defines the server or cluster to which the gateway configuration is migrated.

       • cell_name, server_name and node (or cluster_name), administration_hostname and administration_port together define the connection to the application server (or cluster) on the later version. server_name or cluster_name specifies the name of the target application server or cluster at which endpoint listeners and outbound port destinations are created. If we are migrating to a server or cluster that is part of a managed cell, then administration_hostname and administration_port define the host name and the SOAP administration port number of the deployment manager. If we are migrating to a server that is not part of a managed cell, then administration_hostname and administration_port define the host name and port number of the stand-alone server, and are optional. If they are omitted, the command assumes that the intended values are localhost:8880 (that is, the WAS default values for a stand-alone server).

         (iseries) Note: administration_hostname is compulsory for the IBM i platform.

       • v5_gateway_configuration_file_name is the full path and file name for the exported Version 5.1 private gateway XML configuration file.

       • bus_name and gateway_instance_name together define the gateway instance that you are creating within this bus. The gateway_instance_name is only required to create more than one gateway instance within this bus. If we omit this optional parameter, then a default name is assigned.

       • object_prefix is a string used to prefix the names of the objects defined by the migration process. If omitted, the namespace URI (default value urn:ibmwsgw) for the migrated services is used instead.

       • WAS_user_ID and WAS_password are required if the target application server or cluster is password-protected.

12. Optional: If the external web addresses for the migrated services are changed by the migration process, modify the endpoint listener configuration to update these addresses. We must do this if the external web addresses point to the gateway machine rather than to a web server, and we have migrated the gateway to a different machine or to a different port on the same machine.

What to do next

• If the Version 5.1 gateway used filters, recreate the filter functions by using a combination of JAX-RPC handlers and service integration bus mediations.

• If the gateway configuration includes any gateway services that have multiple target services, the Version 5.1 configuration might have used a routing filter to choose a particular target service. If this is the case, then you must further configure the migrated gateway to choose a target service and port through a routing mediation.

• A web services gateway on a later version uses more memory to process a message, so if you pass a large attachment through the migrated gateway you might get an out-of-memory error in the JVM. To solve this problem, increase the JVM heap size.