WebSphere WebSphere Application Server Network Deployment, Version 6.0.x Operating Systems: AIX, HP-UX, Linux, Solaris, Windows

Migrating a complete gateway configuration

In WebSphere Application Server Network Deployment Version 5, the Web services gateway is a separable component with its own user interface. In Version 6, the gateway is fully integrated within IBM service integration technologies. You use a command line tool to migrate an existing gateway configuration from a Version 5 application server to the new gateway capability on a Version 6 application server.

Consider whether you need to migrate your existing gateways:
  • Web services gateways running on Version 5 application servers can (subject to certain restrictions) coexist with gateway instances running on Version 6 application servers.
  • A Version 6 cell can contain both Version 5 and Version 6 application servers.
For more information, see Coexistence: Preserve or migrate a Version 5 gateway.

You can migrate a Version 5 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 gateway continues to run.

You cannot migrate a gateway to a Version 6 application server that is part of a cluster. To achieve a clustered configuration, first use this topic to migrate your gateway to a single server that is part of a managed cell, then manually convert the Version 6 single server to a cluster.

The migration procedure takes a Version 5 gateway application whose configuration has been exported to an XML file and uses the exported XML file to configure the same gateway functionality on a Version 6 single application server. To do this you export the Version 5 gateway configuration, then run a script to migrate the exported configuration into a new gateway instance in an existing Version 6 application server.

The configuration is migrated as follows:
Note:

To migrate an existing gateway configuration from a Version 5 application server to the new gateway capability on a Version 6 application server, complete the following steps:

  1. Check that the target server is a Version 6 application server, that it is not part of a cluster, and that it is configured to support the service integration bus Web services enablement (SIBWS).
    Note:
    • You need to install a Service Data Objects (SDO) repository, backed by your preferred database. This version of the gateway uses an SDO repository for storing and serving WSDL definitions.
    • You do not need to create a gateway instance. This is done automatically as part of the migration process.
  2. Check that the SIBWS configuration on the target server includes every endpoint listener onto which you plan to map a Version 5 gateway channel.
  3. If you are migrating any EJB bindings, and you 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 gateway default binding is RPC-encoded, whereas in Version 6 the default binding is document literal.
  4. Ensure that the source (Version 5) application server is running, then use the Version 5 gateway user interface to back up the gateway configuration from the Version 5 application server as a private configuration. For more information, see "Preserving an existing gateway configuration" in the WebSphere Application Server Version 5 information center.
  5. Optional: Stop the Version 5 application server.
    Note: If you are migrating a gateway that is in production use, keep the Version 5 gateway running until the Version 6 gateway configuration is complete, then switch the requester applications over to using the new gateway configuration while the existing Version 5 gateway continues to run. However both servers do not have to be running at the same time, and you might need to stop the Version 5 server before you start the Version 6 server (for example if you are installing the Version 6 server as a direct replacement for the Version 5 server, on the same machine and using the same port numbers).
  6. Start the target (Version 6) application server and (for a single server managed within a cell) the deployment manager.
  7. Check that all the WSDL documents that were used to define the target services on the Version 5 application server are available at their given locations. If the WSDL location is a UDDI reference, check that the referenced UDDI registry is available.
  8. Optional: If the gateway being migrated uses JAX-RPC handlers and handler lists, ensure that the underlying handler classes are available at run time.
  9. Optional: If the gateway being migrated uses filters, install the coexistence mediation application.

    This application is in the wsgw.ear file, and is found in the install_root/installableApps directory, where install_root is the root directory for the installation of IBM WebSphere Application Server.

    After installation, this application is displayed in the list of installed applications under the name sibwscoexist.

  10. To migrate the exported configuration into a new gateway instance in the Version 6 application server, complete the following steps:
    1. Open a command prompt, then change to the install_root/util directory.
    2. Run the following command:
      migratewsgw.ext -C=cell_name -S=server_name [-H=administration_hostname]
                                   [-A=administration_port] [-Q=shared_filter_correlation_queue_name]
                                    -G=v5_gateway_configuration_file_name -B=bus_name
                                    -N=node_name [-U=gateway_instance_name] [-P=object_prefix]
      where:
      • .ext is the file extension .bat for a Windows system, or .sh for a Unix or Linux system, or nothing for an i5/OS system (because iSeries commands do not have a file extension).
      • Square brackets ("[ ]") indicate that a parameter is optional in some circumstances.
      • cell_name, server_name, administration_hostname and administration_port together define the connection to the Version 6 application server. server_name specifies the name of the target application server at which endpoint listeners and outbound port destinations are created. If you are migrating to a server 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 you 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 standalone server, and are optional. If they are omitted, the command assumes that the intended values are localhost:8880 (that is, the WebSphere Application server default values for a standalone server).
      • shared_filter_correlation_queue_name determines whether or not filter response processing uses a single correlation queue shared between all the migrated services. For filters that are used for response processing, a correlation queue is sometimes required. If you omit this optional parameter, a queue destination is created for each filtered gateway service. If you use this parameter to specify a queue name, then a single queue destination based on that name is created and shared by all the filtered gateway services.
        Note: These correlation queue destinations are not removed automatically if you subsequently delete the migrated gateway. The task of finding and removing these destinations manually is made easier if you use the -Q parameter to specify a single correlation queue destination during the migration process. For more information see the corresponding troubleshooting tip.
      • v5_gateway_configuration_file_name is the full path and file name for the exported Version 5 private gateway XML configuration file.
      • bus_name, node_name and gateway_instance_name together define the gateway instance that you are creating within this bus. The gateway_instance_name is only required if you want to create more than one gateway instance within this bus. If you 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.
  11. 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. You must do this if the external Web addresses point to the gateway machine rather than to a Web server, and you have migrated the gateway to a different machine or to a different port on the same machine.
Note:
  • For the Version 6 Web services gateway the amount of memory required to process a message has increased, so if you pass a large attachment through the migrated gateway you might get an out-of-memory error in the Java virtual machine. To solve this problem, increase the JVM heap size as described in Tuning the SIBWS.
  • If the gateway configuration that you have migrated includes any gateway services that have multiple target services, the Version 5 configuration might have used a routing filter to choose a particular target service. If this is the case, and if you used the routing bean that is supplied with IBM WebSphere Application Server Version 5, then your routing filter still works in this version. However, if you did not use the supplied routing bean, then you must further configure your migrated gateway to choose a target service and port through a routing mediation.

Task topic

Terms of Use | Feedback

Last updated: 5 Oct 2005
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.pmc.nd.doc\tasks\twsg_coex_migrate.html

© Copyright IBM Corporation 2004, 2005. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)