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 or cluster.
Before you begin
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.
About this task
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 or cluster.
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 or cluster.
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 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 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, it is recommended that you 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.
- service integration bus (SIBus) Web services 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 or cluster, complete
the following steps:
Procedure
- Choose a target server or cluster that
is a Version 6 single server or cluster 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 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 versions of the gateway 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 or
cluster (for example if you are installing the Version 6 server or cluster 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 or cluster 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 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 part of the wsgw enterprise application
that is found in the app_server_root/installableApps directory,
where app_server_root is the
root directory for the installation of IBM WebSphere Application Server,
so you need to install the wsgw enterprise application
(EAR file) on the target server. After installation,
the co-existence mediation 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 or
cluster, complete the following steps:
- Open a command prompt, then change to the app_server_root/util directory.
To access the i5/OS® command
line, use the STRQSH command to launch a Qshell session. For more
information, see the topic "Configure Qshell to run WebSphere Application Server scripts".
- 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] [-Q=shared_filter_correlation_queue_name] [-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 Version 6 application server (or cluster). 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 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).
Note: For the i5/OS platform, you must specify
the
administration_hostname.
- 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 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:
- 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 bus-enabled Web services.
- 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.