The Web service description (WSDL) documents that are generated
by DFHLS2WS contain some automatically generated content that it might be
appropriate for you to change before publishing. For example, the WSDL generated
by DFHLS2WS assumes the use of SOAP version 1.1 over HTTP.
Customizing WSDL documents can result in regenerating the Web services
binding file and in some cases, writing a wrapper program.
- If you want to advertise support for SOAP 1.2, HTTPS or communicate
using WebSphere MQ, then you need to change the wsdl:service and wsdl:binding tags
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,
add the details to the soap:address within 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.
These changes can be made without requiring any change to the Web services
binding file.
- Consider if the automatically generated names in the WSDL document
are appropriate for your purposes. The values that you can rename
are:
- 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 within the WSDL document.
These values form part of the programmatic interface to which a client
program must be coded. If the generated names are not sufficiently meaningful,
it could make maintenance of your application code harder over a long period
of time.
It is recommended that you use the DFHLS2WS parameters REQUEST-NAMESPACE and RESPONSE-NAMESPACE to change the targetNamespace of the XML schemas.
If
you change any of these values, you need to regenerate the Web services binding
file using DFHWS2LS. The language structures that are produced will not be
the same as your existing language structure, 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 want to consider removing those fields that
are not helpful to a Web service client developer. For example:
- fields that are only used for output values could be removed from the
schema that maps the input data structures
- filler fields
- automatically generated annotations
If you make any of these changes, you need to 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 need to write a wrapper program to map data from the new representation
to the old one. This wrapper program needs to LINK 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 to work with.
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.
Overriding the mapping rules ensures 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.