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.
Before you begin
Consider whether you have to migrate your 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 application servers.
- A Version 7.0 cell can contain Version 5.1, Version 6 and Version 7.0 application servers.
For more information, see
Coexistence: Preserve or migrate a Version 5.1 gateway.
You
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.
About this task
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. 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 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. After migration, use the following troubleshooting
tip to enable this approach to work in later versions: 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.1 gateway
service WSDL to generate your web service clients, and your WSDL binding
and encoding style is not document literal, then after migration to
a later version you must regenerate the client stubs by using the
new gateway service WSDL. For more information, see the following
troubleshooting tip: You migrate a gateway from WebSphere Application Server Version 5.1 to a later version. 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 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 was
deprecated in WebSphere Application Server Version 6. You should only use Draft 13 bindings to enable interoperation between applications running in WebSphere Application Server Version 5.1 and Version 7.0, or to allow continued use of an existing web services client application that is 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 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.
- You 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, it is recommended
that you migrate to a single server running under a deployment manager
profile. If you migrate to a stand-alone 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.
- 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 Toleration of poorly-formed SOAP messages.
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, complete the following steps:
Procedure
- Remove any filters from your Version 5.1 gateway.
- 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.
- Configure the target server or cluster as a member of a
service integration bus. For more information, see Configuring the members of a bus.
- Configure
a Service Data Objects (SDO) repository at cell scope for the
target server or cluster.
- 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.1 gateway default binding
is RPC-encoded, whereas in later versions the default
binding is document literal.
- Ensure that the source (Version 5.1) application server is
running, then 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 WebSphere Application Server Version 5.1 topic: Backing up a
gateway configuration.
- Optional: Stop the Version 5.1 application server.
Note: If you 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 you 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).
- 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.
- 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.
- Optional: If the gateway being migrated uses
JAX-RPC handlers and handler lists, ensure that the underlying handler
classes are available at run time.
- To migrate the exported configuration into a new gateway
instance in the application server or cluster on the later version,
complete the following steps:
- Open a command prompt, then change to the app_server_root/util directory.
- Run the following command:
migratewsgw.ext -C=cell_name [-S=server_name -N=node_name]
[-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:
.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_name 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_name (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 you 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 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 stand-alone 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 stand-alone
server).
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 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.
- WAS_user_ID and WAS_password are
required if the target application server or cluster is password-protected.
- 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.
What to do next
Note:
- If your Version 5.1 gateway
used filters, recreate your 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 your 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 Java™ virtual
machine. To solve this problem, increase the JVM heap size as described
in Tuning bus-enabled web services.