The web service description (WSDL) documents that are
generated
by DFHLS2WS contain some automatically generated content that might
be appropriate for you to change before publishing. Customizing WSDL
documents can result in regenerating the web services binding file
and, in some cases, writing a wrapper program.
About this task
Follow these steps to customize generated web service
description
documents:
Procedure
- If you want to advertise support for HTTPS or communicate
using
WebSphere®
MQ, use
the
URI
parameter in DFHLS2WS to set an absolute
URI. If you have not used the
URI
parameter,
you must change the
<wsdl:service>
and
<wsdl:binding>
elements
at the end of the WSDL document.
The generated WSDL includes
comments to assist you in making these changes. Changing these elements
does not require you to regenerate the web services binding file.
- If you want to supply the network location of your web
service, use the
URI
parameter in DFHLS2WS to
set an absolute URI. If you have not used the
URI
parameter,
add the details to the
soap:address
in the
wsdl:service
element.
- If you are using an HTTP-based protocol, replace
my-server
with
the TCP/IP host name of your
CICS®
region
and
my-port
with the port number of the TCPIPSERVICE
resource.
- If you are using
WebSphere
MQ
as the transport protocol, replace
myQueue
with
the name of the appropriate queue.
You can make these changes without requiring any change to the
web services binding file.
If you are changing the port name and
namespace without regenerating the WSBind file, the monitoring information
might be wrong at runtime level 2.1 onwards.
- Consider whether the automatically generated names in the
WSDL document are appropriate for your purposes. You can
rename these values:
- The
targetNamespace
of the WSDL document
- The
targetNamespace
of the XML schemas within
the WSDL document
- The
<wsdl:portType>
name
- The
<wsdl:operation>
name
- The
<wsdl:binding>
name
- The
<wsdl:service>
name
- The names of the fields in the XML schemas in the WSDL
document.
These values form part of the programmatic interface to which
you code a client program. If the generated names are not sufficiently
meaningful, maintenance of your application code might be more
difficult
over a long period of time. Use the DFHLS2WS
REQUEST-NAMESPACE
and
RESPONSE-NAMESPACE
parameters
to change the
targetNamespace
of the XML schemas,
and the
WSDL-NAMESPACE
parameter to change the
targetNamespace
of
the WSDL document.
If you change any of these
values, you must use DFHWS2LS to regenerate the web services binding
file. The language structures that are produced will not be the
same
as your existing language structures, but are compatible with your
existing application, so no application changes are required.
However,
you can ignore the new language structures and use the new web
services
binding file with the original structures.
- Consider if the COMMAREA fields exposed in the XML schemas
are appropriate. You might consider removing any fields
that are not helpful to a web service client developer:
- Fields that are used only for output values can be removed
from
the schema that maps the input data structures.
- Filler fields.
- Automatically generated annotations.
If you make any of these changes, you must
regenerate the web services binding file using DFHWS2LS. The new language
structures that are generated are not compatible with the original
language structures, so you must write a wrapper program to map
data
from the new representation to the old one. This wrapper program needs
to perform an
EXEC CICS LINK
command to the target
application program and then map the returned data.
This level
of customization requires the most effort, but results in the most
meaningful programmatic interfaces for your web services client
developers.
- If you want to put the generated WSDL document through
DFHWS2LS to create new language structures, decide whether to keep
the annotations in the WSDL document. The annotations override
the normal mapping rules when DFHWS2LS generates the language
structures.
When you override the mapping rules, ensure that the generated language
structures are compatible with the version that was used by
DFHLS2WS.
If you want to use the default mapping rules to produce the language
structures, remove the annotations.
Results
If you want to publish your customized WSDL document
to an
IBM®
WebSphere
Service Registry and Repository
(WSRR) server, you must publish it manually using the WSRR interface.
You can find more information about WSRR at the following location:
WebSphere Service Registry and Repository.