<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!ENTITY metainfo SYSTEM "metainfo.sgm">
<!ENTITY Date "22 Dec 2004">
<!ENTITY SectDesc "User Commands">
<!ENTITY Software "J2EE SDK 1.4">
<!ENTITY arch "generic">
<!ENTITY copyright "Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved">
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
<!ENTITY Dash "&ndash;">
]>
<?Pub UDT _bookmark _target>
<?Pub Inc>
<refentry id="wscompile-1m">
<refmeta><refentrytitle>wscompile</refentrytitle><manvolnum>1M</manvolnum>&metainfo;
</refmeta>
<refnamediv><indexterm><primary sortas="wscompile">wscompile &mdash; generates
stubs, ties, serializers, and WSDL files used in JAX-RPC clients and services
</primary></indexterm><indexterm><primary sortas=" generates stubs, ties, serializers, and WSDL files used in JAX-RPC clients and services">
generates stubs, ties, serializers, and WSDL files used in JAX-RPC clients
and services &mdash; wscompile</primary></indexterm><refname>wscompile</refname>
<refpurpose>generates stubs, ties, serializers, and WSDL files used in JAX-RPC
clients and services</refpurpose></refnamediv>
<refsynopsisdiv><title>&synp-tt;</title>
<cmdsynopsis><command>wscompile</command><arg><replaceable>options</replaceable></arg>
<command><replaceable>configuration_file</replaceable></command>
</cmdsynopsis></refsynopsisdiv>
<refsect1><title>&desc-tt;</title>
<para>Generates the client stubs and server-side ties for the service definition
interface that represents the web service interface. Additionally, it generates
the WSDL description of the web service interface which is then used to generate
the implementation artifacts.</para>
<para>In addition to supporting the generation of stubs, ties, server configuration,
and WSDL documents from a set of RMI interfaces, <command>wscompile</command>
also supports generating stubs, ties and remote interfaces from a WSDL document.
</para>
<para>You must specifiy one of the <option role="nodash">gen</option> options
in order to use <command>wscompile</command> as a stand alone generator. You
must use either <option role="nodash">import</option> (for WSDL) or <option
role="nodash">define</option> (for an RMI interface) along with the <option
role="nodash">model</option> option in order to use <command>wscompile</command>
in conjunction with <command>wsdeploy</command>.</para>
<para>Invoking the <command>wscompile</command> command without specifying
any arguments outputs the usage information.</para>
</refsect1>
<refsect1><title>&opts-tt;</title>
<variablelist termlength="medium">
<varlistentry><term><option role="nodash">&Dash;cp <replaceable>path</replaceable> 
</option><option role="nodash">&Dash;classpath <replaceable>path</replaceable></option></term>
<listitem><para>location of the input class files.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;d <replaceable>directory</replaceable> 
</option></term><listitem><para>where to place the generated output files.
</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;define</option></term><listitem>
<para>read the service's RMI interface, define a service. Use this option
with the <option role="nodash">model</option> option in order to create a
model file for use with the <command>wsdeploy</command> command.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;f:<replaceable>features</replaceable></option><option
role="nodash">&Dash;features:<replaceable>features</replaceable></option></term>
<listitem><para>enables the given features. Features are specified as a comma
separated list of features. See the list of supported features below.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;g </option></term><listitem>
<para>generates the debugging information.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;gen</option><option role="nodash">&Dash;gen:client
</option></term><listitem><para>generates the client-side artifacts.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;gen:server</option></term>
<listitem><para>generates the server-side artifacts and the WSDL file. If
you are using <command>wsdeploy</command>, you do not specify this option.
</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;httpproxy:<replaceable>host:port
</replaceable> </option></term><listitem><para>specifies an HTTP proxy server;
defaults to port 8080.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;import </option></term><listitem>
<para>reads a WSDL file, generates the service RMI interface and a template
of the class that implements the interface. Use this option with the <option
role="nodash">model</option> option in order to create a model file for use
with the <command>wsdeploy</command> command.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;mapping <replaceable>file
</replaceable></option></term><listitem><para>writes the mapping file to the
specified file.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;model</option></term><listitem>
<para>write the internal model for the given file name. Use this option with
the <option role="nodash">import</option> option in order to create a model
file for use with the <command>wsdeploy</command> command.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;keep </option></term><listitem>
<para>keeps the generated files.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;nd <replaceable>directory
</replaceable> </option></term><listitem><para>directory for the non-class
generated files are stored.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;O </option></term><listitem>
<para>optimizes the generated code.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;s <replaceable>directory</replaceable> 
</option></term><listitem><para>directory for the generated source files.
</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;source <replaceable>version
</replaceable></option></term><listitem><para>generate code for the specified
JAX-RPC version. Supported versions are 1.0.1, 1.0.3, 1.1, 1.1.1, and 1.1.2
(the default).</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;verbose </option></term><listitem>
<para>output messages about what the compiler is doing.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;version </option></term><listitem>
<para>prints version information.</para>
</listitem></varlistentry>
</variablelist><para>Exactly one of the <option role="nodash">&Dash;input
</option>, <option role="nodash">define</option>, <option role="nodash">gen
</option> options must be specified.</para>
</refsect1>
<refsect1><title>SUPPORTED FEATURES</title>
<para><?Pub Caret1>The <option role="nodash">-f</option> option requires a
comma-separated list of features. The following are the supported features.
</para>
<variablelist termlength="medium">
<varlistentry><term>datahandleronly</term><listitem><para>always map attachments
to <classname>data handler</classname> type</para>
</listitem></varlistentry>
<varlistentry><term>documentliteral</term><listitem><para>use document literal
encoding</para>
</listitem></varlistentry>
<varlistentry><term>donotoverride</term><listitem><para>do not regenerate
classes that already exist in the classpath.</para>
</listitem></varlistentry>
<varlistentry><term>donotunwrap</term><listitem><para>disable unwrapping of
document/literal wrapper elements in WSI mode (default).</para>
</listitem></varlistentry>
<varlistentry><term>explicitcontext</term><listitem><para>turn on explicit
service context mapping.</para>
</listitem></varlistentry>
<varlistentry><term>infix:<replaceable>name</replaceable></term><listitem>
<para>specify an <command>infix</command> to use for generated serializers
(Solaris).</para>
</listitem></varlistentry>
<varlistentry><term>infix=<replaceable>name</replaceable></term><listitem>
<para>specify an <command>infix</command> to use for generated serializers
(Windows).</para>
</listitem></varlistentry>
<varlistentry><term>jaxbenumtype</term><listitem><para>map anonymous enumeration
to its base type.</para>
</listitem></varlistentry>
<varlistentry><term>nodatabinding</term><listitem><para>turn off data binding
for literal encoding.</para>
</listitem></varlistentry>
<varlistentry><term>noencodedtypes</term><listitem><para>turn off encoding
type information.</para>
</listitem></varlistentry>
<varlistentry><term>nomultirefs</term><listitem><para>turn off support for
multiple references.</para>
</listitem></varlistentry>
<varlistentry><term>norpcstructures</term><listitem><para>do not generate
RPC structures (<option role="nodash">import</option> only).</para>
</listitem></varlistentry>
<varlistentry><term>novalidation</term><listitem><para>turn off validation
for the imported WSDL file.</para>
</listitem></varlistentry>
<varlistentry><term>resolveidref</term><listitem><para>resolve <literal>xsd:IDREF
</literal>.</para>
</listitem></varlistentry>
<varlistentry><term>rpclietral</term><listitem><para>use the RPC literal encoding.
</para>
</listitem></varlistentry>
<varlistentry><term>searchschema</term><listitem><para>search schema aggresively
for subtypes.</para>
</listitem></varlistentry>
<varlistentry><term>serializeinterfaces</term><listitem><para>turn on direct
serialization of interface types.</para>
</listitem></varlistentry>
<varlistentry><term>strict</term><listitem><para>generate code strictly compliant
with JAX-RPC 1.1 specification.</para>
</listitem></varlistentry>
<varlistentry><term>unwrap</term><listitem><para>enable unwrapping of document/literal
wrapper elements in WSI mode.</para>
</listitem></varlistentry>
<varlistentry><term>useonewayoperations</term><listitem><para>allow generation
of one-way operations.</para>
</listitem></varlistentry>
<varlistentry><term>wsi</term><listitem><para>enable WS-I Basic Profile features,
to be used for <literal>document/literal</literal>, and <literal>RPC/literal
</literal>.</para>
</listitem></varlistentry>
<varlistentry><term>donotoverride</term><listitem><para>do not regenrate the
classes</para>
</listitem></varlistentry>
<varlistentry><term>donotunwrap</term><listitem><para>disables unwrapping
of <literal>document/literal</literal> wrapper elements in WS-I mode. This
is on by default.</para>
</listitem></varlistentry>
</variablelist><para>Note: the <option role="nodash">gen</option> options
are not compatible with <command>wsdeploy</command>.</para>
</refsect1>
<refsect1><title>CONFIGURATION FILE</title>
<para>The <command>wscompile</command> command reads the configuration file <filename>
config.xml</filename> which contains information that describes the web service.
The structure of the file is as follows:</para>
<para><literal>&lt;?xml version=&rdquo;1.0&rdquo; encoding=&rdquo;UTF-8&rdquo;?>
</literal></para>
<para><literal>&lt;configuration </literal></para>
<para><literal>    xmlns=&rdquo;http://java.sun.com/xml/ns/jax-rpc/ri/config&rdquo;>
</literal></para>
<para><literal>      &lt;service> or &lt;wsdl> or &lt;modelfile></literal></para>
<para><literal> &lt;/configuration> </literal></para>
<para>The <filename>configuration</filename> element may contain exactly one <filename>
&lt;service></filename>, <filename>&lt;wsdl></filename> or <filename>&lt;modelfile>
</filename>.</para>
</refsect1>
<refsect1><title>SERVICE ELEMENT</title>
<para>If the <filename>&lt;service></filename> element is specified, <command>
wscompile</command> reads the RMI interface that describes the service and
generates a WSDL file. In the <filename>&lt;interface></filename> subelement,
the <command>name</command> attribute specifies the service's RMI interface,
and the <filename>servantName</filename> attribute specifies the class that
implements the interface. For example:</para>
<para><literal>&lt;service name="CollectionIF_Service"</literal></para>
<para><literal>      targetNamespace="http://echoservice.org/wsdl"</literal></para>
<para><literal>      typeNamespace="http://echoservice.org/types"</literal></para>
<para><literal>      packageName="stub_tie_generator_test"></literal></para>
<para><literal>    &lt;interface name="stub_tie_generator_test.CollectionIF"
</literal></para>
<para><literal>      servantName="stub_tie_generator_test.CollectionImpl"/>
</literal></para>
<para><literal>&lt;/service></literal></para>
</refsect1>
<refsect1><title>WSDL ELEMENT</title>
<para>If the <filename>&lt;wsdl></filename> element is specified, <command>
wscompile</command> reads the WSDL file and generates the service's RMI interface.
The <command>location</command> attribute specifies the URL of the WSDL file,
and the <command>packageName</command> attribute specifies the package of
the classes to be generated. For example:</para>
<para><literal>&lt;wsdl</literal></para>
<para><literal>  location="http://tempuri.org/sample.wsdl"</literal></para>
<para><literal>  packageName="org.tempuri.sample"/></literal></para>
</refsect1>
<refsect1><title>MODELFILE ELEMENT</title>
<para>This element is for advanced users.</para>
<para>If <command>config.xml</command> contains a <filename>&lt;service></filename>
or <filename>&lt;wsdl></filename> element, <command>wscompile</command> can
generate a model file that contains the internal data structures that describe
the service. If a model file is already generated, it can be reused next time
while using <filename>wscompile</filename>. For example:</para>
<para><literal>&lt;modelfile location="mymodel.xml.gz"/></literal></para>
</refsect1>
<refsect1><title>&exam-tt;</title>
<example>
<title>Using <command>wscompile</command> to generate client-side artifacts
</title>
<screen>wscompile -gen:client -d outputdir -classpath classpathdir config.xml
</screen>
<para>Where a client side artifact is generated in the <filename>outputdir
</filename> for running the service as defined in the <filename>config.xml
</filename> file.</para>
</example>
<example>
<title>Using <command>wscompile</command> to generate server-side artifacts
</title>
<screen>wscompile -gen:server -d outputdir -classpath classpathdir -model modelfile.Z config.xml
</screen>
<para>Where a server side artifact is generated in the <filename>outputdir
</filename> and the <filename>modelfile</filename> in <filename>modelfile.Z
</filename> for services defined in the <filename>config.xml</filename> file.
</para>
</example>
</refsect1>
<refsect1><title>&also-tt;</title>
<para><link linkend="wsdeploy-1m"><citerefentry><refentrytitle>wsdeploy</refentrytitle>
<manvolnum>1M</manvolnum></citerefentry></link></para>
</refsect1>
</refentry>
<?Pub *0000015091>
