Java API for XML-Based Web Services
(JAX-WS) tooling supports generating Java artifacts
you need to develop static JAX-WS web services clients when starting
with a Web Services Description Language (WSDL) file.
Before you begin
When you use a top-down development approach to developing
JAX-WS web services by starting with a WSDL file, you must obtain
the Uniform Resource Locator (URL) for the WSDL file.
If the WSDL file is a local file, the URL looks
like this example: file:drive:\path\file_name.wsdl.
If the WSDL file is a local
file, the URL looks like this example: file:/path/file_name.wsdl.
You
can also specify local files using the absolute or relative file system
path.
About this task
The static client programming model for JAX-WS is the
called the dynamic proxy client. The dynamic proxy client invokes
a web service based on a service endpoint interface that is provided.
After you create the proxy, the client application can invoke methods
on the proxy just like a standard implementation of those interfaces.
For JAX-WS web service clients using the dynamic proxy programming
model, use the JAX-WS tool,
wsimport, to process
a WSDL file and generate portable Java artifacts
that are used to create a web service client. Create the following
portable Java artifacts using the
wsimport tool:
- Service endpoint interface (SEI)
- Service class
- Exception class that is mapped from the wsdl:fault class (if any)
- Java Architecture for XML Binding (JAXB) generated
type values which are Java classes
mapped from XML schema types
Supported configurations: The wsimport, wsgen, schemagen and xjc command-line tools are not supported on the z/OS® platform.
This functionality is provided by the assembly tools provided with WebSphere® Application Server running on
the z/OS platform. Read about these command-line
tools for JAX-WS applications to learn more about these tools.sptcfg
Best practice: WebSphere Application Server provides Java API for XML-Based Web Services (JAX-WS) and Java Architecture for XML Binding (JAXB) tooling. The wsimport, wsgen, schemagen and xjc command-line tools are located in the app_server_root\bin\ directory. Similar tooling is provided by the Java SE Development Kit (JDK) 6. On some occasions,
the artifacts generated by both the tooling provided by WebSphere Application Server and the JDK support the same levels of the specifications.
In general, the artifacts generated by the JDK tools are portable
across other compliant runtime environments. However, it is a best
practice to use the tools provided with this product to achieve seamless
integration within the WebSphere Application Server
environment and to take advantage of the features that may be only
supported in WebSphere Application Server. To take advantage
of JAX-WS and JAXB V2.2 tooling, use the tools provided with the application
server that are located in the app_server_root\bin\
directory.bprac
In addition to using the tools from the command-line,
you can invoke these JAX-WS tools from within the Ant build environments.
Use the com.sun.tools.ws.ant.WsImport Ant task from
within the Ant build environment to invoke the wsimport tool. To
function properly, this Ant task requires that you invoke Ant using
the ws_ant script.
Procedure
Run the wsimport command to generate the portable client
artifacts. The
wsimport tool is located
in the
app_server_root\bin\
directory.
app_server_root\bin\wsimport.bat wsdl_URL
app_server_root/bin/wsimport.sh wsdl_URL
(Optional)
Use the following options with the
wsimport command:
- Use the -verbose option to see a list of generated files
when you run the command.
- Use the -keep option to keep generated Java files.
- Use the -wsdlLocation option to specify the location of
the WSDL file.
Best practice: A best practice for ensuring
that you produce a JAX-WS web services client enterprise archive (EAR)
file that is portable to other systems is to package the WSDL document
within the application module such as a web services client Java archive (JAR) file or a web application
archive (WAR) file. You can specify a relative URI for the location
of your WSDL file by using the
-wsdllocation annotation
attribute. For example, if your
MyService.wsdl file
is located in the
META-INF/wsdl/ directory, then
run the
wsimport tool and use the
-wsdllocation option
to specify the value to be used for the location of the WSDL file.
This ensures that the generated artifacts contain the correct
-wsdllocation information
needed when the application is loaded into the administrative console;
for example:
wsimport -keep -wsdllocation /META-INF/wsdl/MyService.wsdl
bprac
- Use the -b option if you are using WSDL
or schema customizations to specify external binding files that contain
your customizations.
You can customize the bindings in your WSDL
file to enable asynchronous mappings or attachment files. To generate
asynchronous interfaces, add the client-side only customization enableAsyncMapping binding
declaration to the wsdl:definitions element or in
an external binding file that is defined in the WSDL file. Use the enableMIMEContent binding
declaration in your custom client or server binding file to enable
or disable the default mime:content mapping rules. For additional
information on custom binding declarations, see chapter 8 the JAX-WS
specification.
Read about the wsimport command to
learn more about this command and additional options that you can
specify.
Results
You have the generated Java artifacts
to create a JAX-WS client that can invoke JAX-WS web services. To
learn more about the usage, syntax, and parameters for the wsimport command,
see the wsimport command for JAX-WS applications
documentation.
Example
The following example illustrates how the
wsimport command
is used to process the sample
ping.wsdl file to generate
portable artifacts.
- Copy the following ping.wsdl file to a temporary
directory.
<?xml version="1.0" encoding="UTF-8"?>
<!--
* This program can be used, run, copied, modified and distributed
* without royalty for the purpose of developing, using, marketing, or distributing.
-->
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://com/ibm/was/wssample/sei/ping/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="PingService"
targetNamespace="http://com/ibm/was/wssample/sei/ping/">
<wsdl:types>
<xsd:schema
targetNamespace="http://com/ibm/was/wssample/sei/ping/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="pingStringInput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="pingInput" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</wsdl:types>
<wsdl:message name="pingOperationRequest">
<wsdl:part element="tns:pingStringInput" name="parameter" />
</wsdl:message>
<wsdl:portType name="PingServicePortType">
<wsdl:operation name="pingOperation">
<wsdl:input message="tns:pingOperationRequest" />
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="PingSOAP" type="tns:PingServicePortType">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="pingOperation">
<soap:operation soapAction="pingOperation" style="document" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="PingService">
<wsdl:port binding="tns:PingSOAP" name="PingServicePort">
<soap:address
location="http://localhost:9080/WSSampleSei/PingService" />
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
- Run the wsimport command from the app_server_root\bin\
directory.
![[Solaris]](../../solaris.gif)
Operating systems such as AIX
® or Linux
® source the
script to the parent shell to inherit the exported variables by running
the following command:
. ./setupCmdLine.sh (Notice the space between the periods.)
from
the
. /app_server_root>/bin directory.
Run the following
wsimport command:
app_server_root/bin/wsimport.sh -keep -verbose ping.wsdl
After generating the template files from the
wsimport command,
the following files are generated:
com\ibm\was\wssample\sei\ping\ObjectFactory.java
com\ibm\was\wssample\sei\ping\package-info.java
com\ibm\was\wssample\sei\ping\PingServicePortType.java
com\ibm\was\wssample\sei\ping\PingService.java
com\ibm\was\wssample\sei\ping\PingStringInput.java
The ObjectFactory.java, PingService.java,
and PingServicePortType.java files are the generated Java class files to use when you package the Java artifacts with your client implementation
inside a Java archive (JAR) or a web application
archive (WAR) file.
What to do next
Complete the client implementation.