JAX-RPC 2.0 Early Access Tools


Last Modified: 04/04/05

Contents

Command-line Tools

apt

The apt tool provides a facility for programmatically processing the annotations added to Java by JSR 175, Metadata Facility for the JavaTMProgramming Language. In brief, JSR 175 allows programmers to declare new kinds of structured modifiers that can be associated with program elements, fields, methods, classes, etc.

The apt tool generates the portable artifacts (WSDL file, schema files, JavaBeans) used in JAX-RPC services. 

Syntax

apt <apt and javac options> <source files>

The following table lists the apt options.

Table 1-1 apt Options

Option

Description

-classpath <path>

Specifies where to find user class files and annotation processor factories

-cp <path>

Same as -classpath <path>

-d <path>

Specifies where to place processor and javac generated class files

-s <path>

Specifies where to place processor generated source files

-source <release>

Provide source compatibility with the specified release

-version

Version information

-help

Print a synopsis of standard options; use javac -help for more options

-X

Print a synopsis of non-standard options

-J<flag>

Pass <flag> directly to the runtime system

-A[key[=value]]

Options to pass to annotation processors

JAX-RPC uses -And=<directory> to specify the directory to generate the WSDL and schema files

JAX-RPC uses -Averbose=true to dump verbose messages from its AnnotationProcessor

-nocompile

Do not compile source files to class files

-print

Print out a textual representation of the specified types

-factorypath <path>

Specify where to find annotation processor factories

-factory <class>

Name of AnnotationProcessorFactory to use; bypasses default discovery process

-g

Generate all debugging info

-g:none

Generate no debugging info

-g:{lines,vars,source}

Generate only some debugging info

-nowarn

Generate no warnings

-verbose

Output messages about what apt and javac are doing

-deprecation

Output source locations where deprecated APIs are used

-sourcepath <path>

Specify where to find input source files

-bootclasspath <path>

Override location of bootstrap class files

-endorseddirs <dirs>

Override location of endorsed standards path

-encoding <encoding>

Specify character encoding used by source files

-target <release>

Generate class files for a specific virtual machine version

It is important when using apt with JAX-RPC to specify all of the JAR files in the distributed JAX-RPC bundle in the classpath passed to apt. The -sourcepath <path> option must also be provided so that apt and the JAX-RPC annotation processor can find all types referenced by a web service endpoint implementation class.

For more information on apt please refer to the apt documentation here.

wscompile

The wscompile tool generates JAX-RPC portable (service endpoint interface, Service, etc.) and non-portable artifacts (stubs, ties, etc.), JAXB artifacts, and WSDL files used in JAX-RPC clients and services. The tool reads a WSDL or a web service endpoint class and generates all the required artifacts for web service development, deployment, and invocation.

Syntax

wscompile [options] <wsdl> | <SEI class>

The following table lists the wscompile options. Note that exactly one of the -import, -define, or -gen options must be specified.

Table 1-2 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

-b <path>

Specify external JAX-RPC or JAXB binding files (Each <file> must have its own -b)

-define

Read the service endpoint interface, define a service

-extension

Do not strictly follow the JAX-RPC 2.0 specification

-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: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.)

-help

Display help

-httpproxy:<host>:<port>

Specify an HTTP proxy server (port defaults to 8080)

-import

Read a WSDL file, generate the service endpoint 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

-s <directory>

Specify where to place generated source files

-source <version>

Generate code for the specified JAX-RPC SI version.

-verbose

Output messages about what the compiler is doing

-version

Print version information

The features currently shown by wscompile tool are for future use. wscompile -source 1.1.2 -help gives the help message for JAX-RPC 1.1.

Multiple JAX-RPC and JAXB binding files can be specified using -b option and they can be used to customize various things like package names, bean names, etc. More information on JAX-RPC and JAXB binding files can be found in the customization documentation.

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, modifies the deployment descriptors that wsdeploy includes in the generated WAR file.

Syntax

The syntax for wsdeploy is as 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, 1.1, and 2.0 (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, one creates the input WAR file with a GUI development tool or with the ant war task from the generated artifacts from wscompileor apt tools.

For example, a sample input WAR file starting from a WSDL file will generate:

WEB-INF/classes/hello/HelloIF.class          SEI
WEB-INF/classes/hello/HelloImpl.class        Endpoint
WEB-INF/jaxrpc-ri.xml                        JAX-RPC deployment descriptor
WEB-INF/web.xml                              Web deployment descriptor
WEB-INF/HelloService.wsdl                    WSDL
schema.xsd                                   WSDL imports this Schema
WEB-INF/model-hello.xml.gz                   wscompile generated JAX-RPC model file

The model file is not required in the WAR when the web service is developed from Java.

The jaxrpc-ri.xml File

The following 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/HelloService.wsdl"
           model="/WEB-INF/model-hello.xml.gz"
           interface="hello.HelloIF"
           implementation="hello.HelloImpl"/>
       <endpointMapping
           endpointName="MyHello"
           urlPattern="/hello"/>
</webServices>

Remember these requirements when building an input WAR:

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.

How do I pick a tool?

The following lists the process to create a web service starting from Java sources, classes, and a WSDL file (server side):

  1. Starting from Java sources:
    1. Use apt to generate the artifacts: a WSDL file, schema documents, and other Java artifacts.
    2. Package the WSDL file, schema documents, web.xml, jaxrpc-ri.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file, called a raw WAR.
    3. Feed the raw WAR file to wsdeploy to generate a cooked WAR.
    4. Deploy the cooked WAR to a web container.
  2. Starting from Java classes:
    1. Use wscompile to generate portable artifacts: the WSDL file, schema documents, and other artifacts.
    2. Package the WSDL, schema documents, web.xml, jaxrpc-ri.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file, called a raw WAR.
    3. Feed the raw WAR file to wsdeploy to generate a cooked WAR.
    4. Deploy the cooked WAR to a web container.
  3. Starting from a WSDL file:
    1. Use wscompile to generate portable artifacts: the WSDL file, schema documents, and other artifacts.
    2. Implement the service endpoint.
    3. Package the WSDL file, schema documents, web.xml, jaxrpc-ri.xml, service endpoint interface and implementation class, model file, value types, and generated classes, if any, into a WAR file, called a raw WAR.
    4. Feed the raw WAR file to wsdeploy to generate a cooked WAR.
    5. Deploy the cooked WAR to a web container.

The following lists the process to invoke a web service (client side):

  1. Starting from deployed web service's WSDL
    1. Use wscompile to generate the client-side artifacts.
    2. Implement the client to invoke the web service.

Ant Tasks

apt

An Ant task for the apt tool is provided with JAX-RPC 2.0 EA. The attributes and elements supported by the Ant task are listed below:

<apt
    fork="true|false"
    verbose="true|false"
    classpath="classpath"
    base="directory for generated class files"
    sourceBase="directory for generated source files"
    noCompile="true|false"
    print="true|false"
    factoryPath="<path>"
    factory="name of AnnotationProcessorFactory to use"
    xListAnnotationTypes="true|false"
    xListDeclarations="true|false"
    xPrintAptRounds="true|false"
    xPrintFactoryInfo="true|false"
    xClassesAsDecls="true|false"
    debug="true|false"
    debugLevel="lines|vars|source"
    nowarn="true|false"
    deprecation="true|false"
    bootclasspath="<path>"
    extdirs="<path>"
    endorseddirs="<path>"
    sourcePath="<path>"
    encoding="specify character encoding used by source files"
    target="generate class files for specific virtual machine version">
    <source ... > ... </source>
    <classpath ... > ... </classpath>
</apt>

Attribute

Description

Command line

fork

Forks the wscompile process into another virtual machine

n/a

verbose

Output messages about what the compiler is doing

-verbose

classpath

Specify where to find user class files and annotation processor factories

-classpath or -cp

base

Specify where to place processor and javac generated class files

-d <path>

sourceBase

Specify where to place processor generated source files

-s <path>

noCompile

Do not compile source files to class files

-nocompile

print

Print out a textual representation of the specified types

-print

factoryPath

Specify where to find annotation processor factories

-factorypath <path>

factory

Name of the AnnotationProcessorFactory to use; bypasses default discovery process

-factory <class>

xListAnnotationTypes

List the found annotation types

-XListAnnotationTypes

xListDeclarations

List specified and included declarations

-XListDeclarations

xPrintAptRounds

Print information about initial and recursive apt rounds

-XPrintAptRounds

xPrintFactoryInfo

Print information about which annotations a factory is asked to process

-XPrintFactoryInfo

xClassesAsDecls

Treat both class and source files as declarations to process

-XclassesAsDecls

debug

Generate all debugging info

-g

debugLevel

Debug level: lines, vars, sources

-g:{lines,vars,source}

nowarn

Generate no warnings

-nowarn

deprecation

Output source locations where deprecated APIs are used

-deprecation

bootclasspath

Override location of bootstrap class files

-bootclasspath <path>

extdirs

Override location of installed extensions

-extdirs <dirs>

endorseddirs

Override location of endorsed standards path

-endorseddirs <dirs>

sourcePath

Specify where to find input source files

-sourcepath <path>

encoding

Specify character encoding used by source files

-encoding <encoding>

target

Generate class files for a specific virtual machine version

-target <release>

The list of source files to be processed are specified via a nested <source> element. That is, a path-like structure. The classpath attribute is a path-like structure and can also be set via nested <classpath> elements. Before this task can be used, a <taskdef> element needs to be added to the project as given below:

<taskdef name="wscompile" classname="com.sun.xml.rpc.tools.ant.Apt">

 <classpath refid="jaxrpc.classpath"/>

</taskdef>

where jaxrpc.classpath is a reference to a path-like structure, defined elsewhere in the build environment, and contains the list of classes required by the JAX-RPC runtime.

Examples

<apt
    base="${build.classes.home}"
    sourceBase="${build.classes.home}"
    sourcePath="${basedir}/src">
    <classpath refid="jaxrpc.classpath"/>
    <source dir="${basedir}/src" includes="*.java"/>
    </source>
</apt>

The above example processes the Java source files in the ${basedir}/src directory and generates the source and class files in ${build.classes.home}. ${basedir}/src is directory used to search for source files for multiple apt rounds. The classpath is a reference to a path-like structure jaxrpc.classpath, defined elsewhere in the build environment.

<apt
    fork="true"
    debug="true"
    verbose="true"
    base="${build.classes.home}"
    sourceBase="${build.classes.home}"
    sourcePath="${basedir}/src">
    <classpath refid="jaxrpc.classpath"/>
    <option key="nd" value="${build.home}"/>
    <option key="verbose" value="${verbose}"/>
    <source dir="${basedir}/src">
      <include name="**/server/*.java"/>
    </source>
</apt>

The above example processes the Java source files in ${basedir}/src/**/server, generates the source and class files in ${build.classes.home}, compiles with debug information on, prints a message about what the compiler is doing, and passes the -Dnd=${build.home} and -Dverbose=${verbose} options to the annotation processor(s). ${basedir}/src is the directory used to search for source files for multiple apt rounds. The classpath is a reference to a path-like structure jaxrpc.classpath, defined elsewhere in the build environment. This will also fork off the apt process using the default java executable.

wscompile

An Ant task for the wscompile tool is provided along with the tool. Currently it has both version 1.1 and 2.0 options. The 1.1 options are shown in a different color in the table. The attributes and elements supported by the Ant task are listed below:

  <wscompile
      fork= "true|false"
      jvmargs="..."
      wsdlFile="..."
      endpointImplementationClass="..."
      base="directory for generated class files"
      classpath="classpath" | cp="classpath"
      extension="true|false"
      define="true|false"
      import="true|false" | gen="true|false" | client="true|false" | server="true|false"
      features="wscompile-features"
      HTTPProxy="proxy host and port"
      model="model file name"
      source="1.0.1"|"1.0.3"|"1.1"|"2.0"(default)
      nonClassDir="directory for non-class generated files"
      sourceBase="directory for generated source files"
      optimize="true|false"
      debug="true|false"
      keep="true|false"
      verbose="true|false"
      version="true|false"
      config="configuration file">
      <binding dir="..." includes="..." />
      <classpath refid="..."/>
  </wscompile>


Attribute

Description

Command line

fork

Forks the wscompile process into another virtual machine

n/a

jvmargs

Arguments to pass to the forked virtual machine

n/a

wsdlFile

WSDL file

WSDL

endpointImplementationClass

Service endpoint implementation class

SEI class

base

Specify where to place output generated classes

-d

classpath

Specify where to find input class files

-classpath

cp

Same as -classpath

-cp

extension

Do not strictly follow the JAX-RPC 2.0 specification

-extension

define

Define a service

-define

import

Generate portable artifacts only

-import

gen

Generate client-side artifacts

-gen

client

Generate client-side artifacts

-gen:client

server

Senerate server-side artifacts

-gen:server

features

Comma seperated list of features

-features

f

Same as -features

-f

HTTPProxy

Specify an HTTP proxy server (port defaults to 8080)

-httpproxy

model

Write the internal model file to a given file

-model

source

Generate code for the specified JAX-RPC SI version. Supported versions are: 1.0.1, 1.0.3, 1.1, and 2.0 (default)

-source

nonClassDir

Specify where to place non-class generated files

-nd

sourceBase

Specify where to place generated source files

-s

optimize

Optimize generated code

-O

debug

Generate debugging info

-g

keep

Keep generated files

-keep

verbose

Output messages about what the compiler is doing

-verbose

binding

Specify external JAX-RPC or JAXB binding files

-b

config

Configuration file

configuration file

The classpath and binding attributes are a path-like structure and can also be set via nested <classpath> and <binding> elements, respectively. Before this task can be used, a <taskdef> element needs to be added to the project as given below:

  <taskdef name="wscompile" classname="com.sun.xml.rpc.tools.ant.Wscompile">
      <classpath path="jaxrpc.classpath"/>
  </taskdef>


where jaxrpc.classpath is a reference to a path-like structure, defined elsewhere in the build environment, and contains the list of classes required by the JAX-RPC runtime.

Examples

  <wscompile
      gen="true"
      base="${build.classes.home}"
      classpath="xyz.jar"
      debug="true"
      wsdlFile="AddNumbers.wsdl"
      binding="custom.xml">


The above example generates client-side artifacts for AddNumbers.wsdl, stores .class files in the ${build.classes.home} directory using the custom.xml customization file. The classpath used is xyz.jar and compiles with debug information on.

  <wscompile
      import="true"
      keep="true"
      sourceBase="${source.dir}"
      base="${build.classes.home}"
      model="model.xml.gz"
      wsdlFile="AddNumbers.wsdl">
      <classpath refid="jaxrpc.classpath"/>
      <binding dir="${basedir}/etc" includes="custom.xml"/>
  </wscompile>


The above example generates portable artifacts for AddNumbers.wsdl, stores .java files in the ${source.dir} directory, stores .class files in the ${build.classes.home} directory, and generates the model file model.xml.gz in the current directory. The classpath is a reference to a path-like structure jaxrpc.classpath, defined elsewhere in the build environment.

  <wscompile
      fork="true"
      define="true"
      nonClassDir="${wsdl.dir}"
      endpointImplementationClass="fromjava.server.AddNumbersImpl"/>


The above example generates a WSDL in the ${wsdl.dir} directory for the fromjava.server.AddNumbersImpl service endpoint implementation class. This will fork off the wscompile process using the default java executable.

  <wscompile
      define="true"
      source="1.1"
      features="documentliteral, useonewayoperations"
      config="config.xml"/>


The above example uses JAX-RPC 1.1 to generate a document/literal WSDL in for the service endpoint interface and implementation specified in config.xml, and maps methods with a void return type as one-way operations.

wsdeploy

An Ant task for the wsdeploy tool is provided along with the tool. The attributes and elements supported by the Ant task are listed below:

  <wsdeploy
      fork= "true|false"
      classpath="classpath" | cp="classpath"
      outWarFile="output WAR file name"
      keep="true|false"
      tmpDir="temporary directory name"
      verbose="true|false"
      inWarFile="input WAR file name">
  </wsdeploy>


Attribute

Description

Command line

fork

Forks the wsdeploy process into another virtual machine

n/a

classpath

Specify where to find input class files

-classpath

keep

Keep generated files

-keep

outWarFile

Output cooked WAR file name

-o

inWarFile

Input raw WAR file name

<WAR file>

tmpDir

Temporary directory to use

-tmpdir

verbose

Output messages about what the compiler is doing

-verbose

The classpath attribute is a path-like structure and can also be set via nested <classpath> elements. Before this task can be used, a <taskdef> element needs to be added to the project as given below:

  <taskdef name="wsdeploy" classname="com.sun.xml.rpc.tools.ant.Wsdeploy">
      <classpath path="jaxrpc.classpath"/>
  </taskdef>


where jaxrpc.classpath is a reference to a path-like structure, defined elsewhere in the build environment, and contains the list of classes required by the JAX-RPC runtime.

Examples

  <wsdeploy
      classpath="xyz.jar"
      tmpdir="${tmp}"
      outWarFile="stock.war"
      inWarFile="stock-raw.war"/>


This example processes a raw WAR file named stock-raw.war and generates a cooked WAR file named stock.war. The classpath includes xyz.jar, and the temporary directory used is ${tmp}.

  <wsdeploy
      keep="true"
      outWarFile="stock.war"
      inWarFile="stock-raw.war">
      <classpath refid="compile.classpath"/>
  </wsdeploy>


This example processes a raw WAR file named stock-raw.war and generates a cooked WAR file named stock.war. The classpath is a reference to a path-like structure compile.classpath, defined elsewhere in the build environment, and the cooked WAR file contains server-side artifact source code.

  <wsdeploy
      fork="true"
      source="1.0.3"
      outWarFile="stock.war"
      inWarFile="stock-raw.war">
  </wsdeploy>


This example processes a raw WAR file named stock-raw.war and generates a cooked WAR file named stock.war compatible with JAX-RPC version 1.0.3. This will fork off the wsdeploy process using default java executable.


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