Java(TM) API for XML-based RPC (JAX-RPC) Tools

Revised: 7 October, 2003

Contents

wscompile

The wscompile tool generates stubs, ties, serializers, and WSDL files used in JAX-RPC clients and services. The tool reads a configuration file, which specifies either a WSDL file, a model file, or a compiled service endpoint interface.

Syntax 

wscompile [options] <configuration-file>

By convention, the configuration file is named config.xml, but this is not a requirement. The following table lists the wscompile options. Note that exactly one of the -import, -define, or -gen options must be specified.

Table 1-1 wscompile Options
Option
Description
-classpath <path>
specify where to find input class files
-cp <path>
same as -classpath <path>
-d <directory>
specify where to place generated output files
-define
read the service endpoint interface, define a service
-f:<features>
enable the given features (See the below below table for a list of features. When specifying multiple features, separate them with commas.)
-features:<features>
same as -f:<features>
-g
generate debugging info
-gen
same as -gen:client
-gen:both
generate both client and server artifacts
-gen:client
generate client artifacts (stubs, etc.)
-gen:server
generate server artifacts (ties, etc.) and the WSDL file (If you are using wsdeploy you do not specify this option.)
-httpproxy:<host>:<port>
specify a HTTP proxy server (port defaults to 8080 on JWSDP)
-import
read a WSDL file, generate the service endpoint interface and a template of the class that implements the interface
-keep
keep generated files
-mapping <file>
generate a J2EE mapping.xml file (This option is not available in JWSDP.)
-model <file>
write the internal model to the given file
-nd <directory>
specify where to place non-class generated files
-O
optimize generated code
-s <directory>
specify where to place generated source files
-source <version>
Generate code for the specified JAX-RPC SI version. Supported versions are: 1.0.1, 1.0.3, and 1.1 (default).
-verbose
output messages about what the compiler is doing
-version
print version information

The following table lists the features (delimited by commas) that may follow the -f option. The wscompile tool reads as input either a WSDL file, compiled service endpoint interface (SEI), or model file. The Type of File column indicates which of these files can be used with a particular feature.

Table 1-2 wscompile -f Features
Feature
Description
Type of File
datahandleronly
always map attachments to the DataHandler type
WSDL
documentliteral
use document literal encoding
SEI
donotoverride
do not regenerate classes that already exist in the classpath
WSDL, SEI
donotunwrap
disable unwrapping of document/literal wrapper elements in WSI mode (default)
WSDL
explicitcontext
turn on explicit service context mapping
WSDL
infix:<name>
specify an infix to use for generated ties and serializers
WSDL, SEI
infix=<name>
same as infix:<name> (not for Windows)
WSDL, SEI
jaxbenumtype
Map anonymous enumeration to its base type
WSDL
nodatabinding
turn off data binding for literal encoding
WSDL
noencodedtypes
turn off encoding type information
WSDL, SEI, model
nomultirefs
turn off support for multiple references
WSDL, SEI, model
norpcstructures
do not generate RPC structures (-import only)
WSDL
novalidation
turn off full validation of imported WSDL documents
WSDL
resolveidref
resolve xsd:IDREF
WSDL
rpcliteral
use rpc literal encoding
SEI
searchschema
search schema aggressively for types
WSDL
serializeinterfaces
turn on direct serialization of interface types
WSDL, SEI, model
strict
generate code strictly compliant with JAXRPC spec
WSDL, SEI
unwrap
enable unwrapping of document/literal wrapper elements in WSI mode
WSDL
useonewayoperations
allow generation of one-way operations
SEI
wsi
enable WSI-Basic Profile features, to be used for document/literal and rpc/literal
WSDL

Configuration File

The wscompile tool reads the configuration file (config.xml), which contains information that describes the web service. The basic structure of config.xml follows: 

<?xml version="1.0" encoding="UTF-8"?> 
<configuration 
    xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config"> 
        <service> or <wsdl> or <modelfile> 
</configuration>

The <configuration> element may contain exactly one <service>, <wsdl>, or <modelfile> element.

The <service> Element

If you specify this element, wscompile reads the service endpoint interface that describes the service and generates a WSDL file. In the <interface> subelement, the name attribute specifies the service endpoint interface, and the servantName attribute specifies the class that implements the interface. For example: 

<service name="CollectionIF_Service"  
targetNamespace="http://echoservice.org/wsdl"  
      typeNamespace="http://echoservice.org/types"  
      packageName="stub_tie_generator_test">  
    <interface name="stub_tie_generator_test.CollectionIF"  
          servantName="stub_tie_generator_test.CollectionImpl"/>  
</service>

The <wsdl> Element

If you specify this element, wscompile reads the service's WSDL file and generates the service endpoint interface. The location attribute specifies the URL of the WSDL file, and the packageName attribute specifies the package of the classes generated by wscompile. For example: 

<wsdl 
    location="http://tempuri.org/sample.wsdl" 
    packageName="org.tempuri.sample" />

The <modelfile> Element

This element is for advanced users.

If config.xml contains a <service> or <wsdl> element, wscompile generates a model file that contains the internal data structures that describe the service. If you've already generated a model file in this manner, then you can reuse it the next time you run wscompile. For example: 

<modelfile location="mymodel.xml.gz"/>

wsdeploy

The wsdeploy tool reads a WAR file and the jaxrpc-ri.xml file and then generates another WAR file that is ready for deployment. Behind the scenes, wsdeploy runs wscompile with the -gen:server option. The wscompile command generates classes and a WSDL file that wsdeploy includes in the generated WAR file.

On JWSDP, the wsdeploy tool must be run. However, on J2EE you don't have to run wsdeploy because the functions it performs are done automatically when you deploy a WAR with deploytool or asadmin.

Syntax

The syntax for wsdeploy follows: 

wsdeploy -o <output-war-file> <input-war-file> <options>

The following table lists the tool's options. Note that the -o option is required.

Table 1-3 wsdeploy Options
Option
Description
-classpath <path>
specify an optional classpath
-keep
keep temporary files
-o <output WAR file>
specify where to place the generated WAR file
-source <version>
Generate code for the specified JAX-RPC SI version. Supported versions are: 1.0.1, 1.0.3, and 1.1 (default).
-tmpdir <directory>
specify the temporary directory to use
-verbose
output messages about what the compiler is doing
-version
print version information

The Input WAR File

Typically, you create the input WAR file with a GUI development tool or with the ant war task. Here are the contents of a simple input WAR file: 

META-INF/MANIFEST.MF 
WEB-INF/classes/hello/HelloIF.class 
WEB-INF/classes/hello/HelloImpl.class 
WEB-INF/jaxrpc-ri.xml 
WEB-INF/web.xml

In this example, HelloIF is the service endpoint interface and HelloImpl is the class that implements the interface. The web.xml file is the deployment descriptor of a web component. The jaxrpc-ri.xml file is described in the next section.

The jaxrpc-ri.xml File

The listing that follows shows a jaxrpc-ri.xml file for a simple HelloWorld service. 

<?xml version="1.0" encoding="UTF-8"?>  
<webServices  
       xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/dd"  
       version="1.0"  
       targetNamespaceBase="http://com.test/wsdl"  
       typeNamespaceBase="http://com.test/types"  
       urlPatternBase="/ws">  
       <endpoint  
           name="MyHello"  
           displayName="HelloWorld Service"  
           description="A simple web service"  
           wsdl="/WEB-INF/<wsdlame>  
           interface="hello.HelloIF"  
           implementation="hello.HelloImpl"/>  
       <endpointMapping  
           endpointName="MyHello"  
           urlPattern="/hello"/>  
</webServices>

The <webServices> element must contain one or more <endpoint> elements. In this example, note that the interface and implementation attributes of <endpoint> specify the service's interface and implementation class. The <endpointMapping> element associates the service name with a URL.

Advanced Topics

This section is for developers who are familiar with WSDL, SOAP, and the JAX-RPC specifications.

Namespace Mappings

For the below namespaceMappingRegistry element in the config.xml file, wscompile behaves as follows. When going from WSDL types to Java types, for all types defined in the http://echoservice.org/types namespace, wscompile will generate Java classes in the echoservice.org.types package. Likewise, for all schema types defined in the http://echoservice.org/types2 namespace, wscompile generate Java classes in the echoservice.org.types2 package. 

<namespaceMappingRegistry>  
  <namespaceMapping  
    namespace="http://echoservice.org/types"  
    packageName="echoservice.org.types"/>  
  <namespaceMapping  
    namespace="http://echoservice.org/types2"  
    packageName="echoservice.org.types2"/>  
</namespaceMappingRegistry>

Handlers

A handler accesses a SOAP message that represents an RPC request or response. A handler class must implement the javax.xml.rpc.handler interface. Because it accesses a SOAP message, a handler can manipulate the message with the APIs of the javax.xml.soap package.

A handler chain is a list of handlers. You may specify one handler chain for the server and one for the client. On the server, you include the <handlerChains> element in the jaxrpc-ri.xml file. On the client , you include this element in the config.xml file. Here is an example of the <handlerChains> element in config.xml: 

<handlerChains> 
  <chain runAt="server" 
     roles= 
      "http://acme.org/auditing 
       http://acme.org/morphing" 
       xmlns:ns1="http://foo/foo-1"> 
    <handler className="acme.MyHandler" 
      headers ="ns1:foo ns1:bar"/> 
      <property  
        name="property" value="xyz"/> 
    </handler> 
  </chain> 
</handlerChains>

For more information on handlers, see the SOAP Message Handlers chapter of the JAX-RPC specifications.

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.