Documentation for wscompile?

Question

I finally got around to updating to jwsdp-1_0_01 and was surprised to find that xrpcc was replaced by wscompile in many build.xml files. Except for a few very general remarks in the Tutorial, I can't find any documentation for wscompile at all (Google returns only 4 pages for "wscompile"!).
Is xrpcc deprecated? (When my old build.xml runs xrpcc, it gives a warning that "sun.tools.javac.Main is deprecated".) Is there a man page, etc., for wscompile?
Thanks,
Mike

Answer 1

Oops, the format of my last message got munged. Here's anoter try:
Date: 28 Aug 2002
Title: The JAX-RPC wscompile and wsdeploy Tools
1 The wscompile Tool
The wscompile tool generates stubs, ties, serializers,
and WSDL files used in JAX-RPC clients and services.
The tool reads as input a configuration file and either
a WSDL file or an RMI interface that defines the service.
1.1 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.
  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's RMI interface,
                            define a service
  -f:<features>             enable the given features (See the 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: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.)
  -gen:both                 generate both client and server artifacts
  -httpproxy:<host>:<port>  specify a HTTP proxy server (port defaults to 8080)
  -import                   read a WSDL file, generate the service's RMI
                            interface and a template of the class that
                            implements the interface
  -keep                     keep generated files
  -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
  -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.
  Feature                   Description
  datahandleronly           always map attachments to the DataHandler type
  explicitcontext           turn on explicit service context mapping
  infix=<name>              specify an infix to use for generated serializers
  nodatabinding             turn off data binding for literal encoding
  noencodedtypes            turn off encoding type information
  nomultirefs               turn off support for multiple references
  novalidation              turn off full validation of imported WSDL documents
  searchschema              search schema aggressively for subtypes
  serializeinterfaces       turn on direct serialization of interface types
1.2 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.
1.2.1 The <service> Element
If you specify this element, wscompile reads the
RMI interface that describes the service and
generates a WSDL file.
In the <interface> subelement, the name attribute specifies the
service's RMI 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>
1.2.2 The <wsdl> Element
If you specify this element, wscompile
reads the service's WSDL file and generates
the service's RMI 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" />
1.2.3 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"/>
2.0 The wsdeploy Tool
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 which wsdeploy includes
in the generated WAR file.
2.1 Syntax
The syntax for wsdeploy follows:
wsdeploy <options> <input-war-file>
The following table lists the tool's options.
Note that the -o option is required.
  Option                    Description
  -classpath <path>         specify an optional classpath
  -keep                     keep temporary files
  -o <output-war-file>      specify where to place the generated war file
  -tmpdir <directory>       specify the temporary directory to use
  -verbose                  output messages about what the compiler is doing
  -version                  print version information
2.2 The Input WAR File
Typically, you create the input WAR file with a
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's RMI 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.
2.2.2 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" 
        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
port with an element of the endpoint URL path
that follows the urlPatternBase.
3 Advanced Topics
This section is for developers who are familiar with
WSDL, SOAP, and the JAX-RPC specifications.
3.1 Namespace Mappings
Here is a schema type name example:
schemaType="ns1:SampleType"
xmlns:ns1="http://echoservice.org/types"
When generating a Java type from a schema type,
wscompile gets the class name from the local part of
the schema type name.
To specify the package name of the generated
Java classes, you define a mapping between
the schema type namespace and the package name.
You define this mapping by adding a <namespaceMappingRegistry>
element to the config.xml file.  For example:
<service>
    <namespaceMappingRegistry>
            <namespaceMapping            
            namespace="http://echoservice.org/types"
            packageName="echoservice.org.types"/>
     </namespaceMappingRegistry>
</service>
3.5 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.
Examples of handler tasks:
* Encryption and decryption
* Logging and auditing
* Caching
* Application-specific SOAP header processing
A handler chain is a list of handlers.
You may specify one handler chain for the client
and one for the server.
On the client, you include the <handlerChains> element
in the jaxrpc-ri.xml file.  On the server, 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.