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:
- 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. You 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
the functionality of a channel is now 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, but are supported in this version through
a coexistence mediation. Note that you should plan over time to replace your
existing filters with a combination of JAX-RPC handlers and service integration bus mediations.
- Gateway target service identity values are not migrated. If you have filters
that use the Routing interface to select a target service by identity, see
the following troubleshooting tip: You migrate a gateway that contains filters from WebSphere Application Server Version 5 to Version 6, and your routing filters no longer work.
- Web service clients that are generated from the WSDL for the target service,
rather than the gateway service, are flagged by default in Version 6 as an
error. After migration, use the following troubleshooting tip to enable this
approach also to work in Version 6: You choose to generate a Web service client from the WSDL for the target service, rather than the gateway service. When you try to access the target service through the gateway, your client receives the following error message: CWSIF0304E: The message body did not match any of the definitions in the WSDL.
- If you used the Version 5 gateway service WSDL to generate your Web service
clients, and your WSDL binding and encoding style is not document literal,
then after migration to Version 6 you must regenerate the client stubs using
the new gateway service WSDL. For more information see the following troubleshooting
tip: You migrate a gateway from WebSphere Application Server Version 5 to Version 6. When you try to access a gateway service, your client receives one or more error messages stating No response body is available, or Null response message, or The message body did not match any of the definitions in the WSDL.
WS-Security bindings are not migrated, because the final
version (1.0) of the WS-Security specification (implemented in WebSphere Application
Server Version 6) is not compatible with the Draft 13 version of the WS-Security
specification (implemented in WebSphere Application Server Version 5).
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 WebSphere Application Server Version 6) is not compatible with the Draft
13 version, and therefore use of WS-Security Draft 13 is deprecated in WebSphere
Application Server Version 6. Draft 13 bindings are only supported to enable
inter-operation between applications running in WebSphere Application Server
Version 5 and Version 6, and to allow continued use of existing Web services
client applications that are 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 standalone server, or on the machine on which the deployment
manager is running in a Network Deployment configuration.
- Only WS-Security binding objects that are used by a Gateway Service or
Target Service WS-Security configuration are migrated. Any binding objects
that you create but do not use are not migrated. For example: If you 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.
Note: - 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 your configuration the external
Web addresses point to the gateway machine, modify
the endpoint listener configuration after the migration process has
completed.
- WebSphere Application Server Network Deployment allows you to migrate
to a single server running under either configuration profile (standalone
server or deployment manager). However, you should always migrate to a single
server running under a deployment manager profile. If you migrate to a standalone
server profile you cannot use the administrative console to subsequently modify
your gateway configuration. For more information, see the troubleshooting
tip The gateway panels in the administrative console are only available in WebSphere Application Server Network Deployment if you are working with a deployment manager profile.
- The service integration bus Web services enablement (SIBWS) performs more
validation on Web service messages than is done in WebSphere Application Server
Version 5. 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, are identified as poorly-formed in Version 6. For the steps to
take to resolve the problem, see Toleration of poorly-formed SOAP messages.
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:
- 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.
- Check that the SIBWS configuration on the target server includes
every endpoint listener onto which you plan to map a Version 5 gateway channel.
- 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.
- 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.
- 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).
- Start the target (Version 6) application server and (for a single
server managed within a cell) the deployment manager.
- 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.
- Optional: If the gateway being migrated uses JAX-RPC
handlers and handler lists, ensure that the underlying handler classes are
available at run time.
- 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.
- To migrate the exported configuration into a new gateway instance
in the Version 6 application server, complete the following steps:
- Open a command prompt, then change to the install_root/util directory.
- 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.
- 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.