Last Modified: 04/04/05
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.
apt <apt and javac options> <source files>
The following table lists the apt
options.
Table 1-1 apt Options
Option |
Description |
---|---|
|
Specifies where to find user class files and annotation processor factories |
|
Same as |
|
Specifies where to place processor and |
|
Specifies where to place processor generated source files |
|
Provide source compatibility with the specified release |
|
Version information |
|
Print a synopsis of standard options; use |
|
Print a synopsis of non-standard options |
|
Pass <flag> directly to the runtime system |
|
Options to pass to annotation processors JAX-RPC uses JAX-RPC uses |
|
Do not compile source files to class files |
|
Print out a textual representation of the specified types |
|
Specify where to find annotation processor factories |
|
Name of |
|
Generate all debugging info |
|
Generate no debugging info |
|
Generate only some debugging info |
|
Generate no warnings |
|
Output messages about what |
|
Output source locations where deprecated APIs are used |
|
Specify where to find input source files |
|
Override location of bootstrap class files |
|
Override location of endorsed standards path |
|
Specify character encoding used by source files |
|
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.
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.
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 |
---|---|
|
Specify where to find input class files |
|
Same as |
|
Specify where to place generated output files |
|
Specify external JAX-RPC or JAXB binding files (Each |
|
Read the service endpoint interface, define a service |
|
Do not strictly follow the JAX-RPC 2.0 specification |
|
Enable the given features (See the below below table for a list of features. When specifying multiple features, separate them with commas.) |
|
Same as |
|
Generate debugging info |
|
Same as |
|
Generate client artifacts (stubs, etc.) |
|
Generate server artifacts (ties, etc.) and the WSDL file. (If you are using |
|
Display help |
|
Specify an HTTP proxy server (port defaults to 8080) |
|
Read a WSDL file, generate the service endpoint interface, and a template of the class that implements the interface |
|
Keep generated files |
|
Write the internal model to the given file |
|
Specify where to place non-class generated files |
|
Specify where to place generated source files |
|
Generate code for the specified JAX-RPC SI version. |
|
Output messages about what the compiler is doing |
|
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.
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.
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 |
---|---|
|
Specify an optional classpath |
|
Keep temporary files |
|
Specify where to place the generated WAR file |
|
Generate code for the specified JAX-RPC SI version. Supported versions are: 1.0.1, 1.0.3, 1.1, and 2.0 (default). |
|
Specify the temporary directory to use |
|
Output messages about what the compiler is doing |
|
Print version information |
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.
jaxrpc-ri.xml
FileThe 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:
model
is not required in the WAR, and in jaxrpc-ri.xml
interfacevalue needs to be the endpoint class itself.
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.
The following lists the process to create a web service starting from Java sources, classes, and a WSDL file (server side):
apt
to generate the artifacts: a WSDL file, schema documents, and other Java artifacts.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.wsdeploy
to generate a cooked WAR.wscompile
to generate portable artifacts: the WSDL file, schema documents, and other artifacts.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.wsdeploy
to generate a cooked WAR.wscompile
to generate portable artifacts: the WSDL file, schema documents, and other artifacts.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.wsdeploy
to generate a cooked WAR.The following lists the process to invoke a web service (client side):
wscompile
to generate the client-side artifacts.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 |
|
Forks the |
n/a |
|
Output messages about what the compiler is doing |
|
|
Specify where to find user class files and annotation processor factories |
|
|
Specify where to place processor and |
|
|
Specify where to place processor generated source files |
|
|
Do not compile source files to class files |
|
|
Print out a textual representation of the specified types |
|
|
Specify where to find annotation processor factories |
|
|
Name of the |
|
|
List the found annotation types |
|
|
List specified and included declarations |
|
|
Print information about initial and recursive |
|
|
Print information about which annotations a factory is asked to process |
|
|
Treat both class and source files as declarations to process |
|
|
Generate all debugging info |
|
|
Debug level: lines, vars, sources |
|
|
Generate no warnings |
|
|
Output source locations where deprecated APIs are used |
|
|
Override location of bootstrap class files |
|
|
Override location of installed extensions |
|
|
Override location of endorsed standards path |
|
|
Specify where to find input source files |
|
|
Specify character encoding used by source files |
|
|
Generate class files for a specific virtual machine version |
|
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.
<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.
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 |
|
Forks the |
n/a |
|
Arguments to pass to the forked virtual machine |
n/a |
|
WSDL file |
WSDL |
|
Service endpoint implementation class |
SEI class |
|
Specify where to place output generated classes |
|
|
Specify where to find input class files |
|
|
Same as |
|
|
Do not strictly follow the JAX-RPC 2.0 specification |
|
|
Define a service |
|
|
Generate portable artifacts only |
|
|
Generate client-side artifacts |
|
|
Generate client-side artifacts |
|
|
Senerate server-side artifacts |
|
|
Comma seperated list of features |
|
|
Same as |
|
|
Specify an HTTP proxy server (port defaults to 8080) |
|
|
Write the internal model file to a given file |
|
|
Generate code for the specified JAX-RPC SI version. Supported versions are: 1.0.1, 1.0.3, 1.1, and 2.0 (default) |
|
|
Specify where to place non-class generated files |
|
|
Specify where to place generated source files |
|
|
Optimize generated code |
|
|
Generate debugging info |
|
|
Keep generated files |
|
|
Output messages about what the compiler is doing |
|
|
Specify external JAX-RPC or JAXB binding files |
|
|
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.
<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.
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 |
|
Forks the |
n/a |
|
Specify where to find input class files |
|
|
Keep generated files |
|
|
Output cooked WAR file name |
|
|
Input raw WAR file name |
|
|
Temporary directory to use |
|
|
Output messages about what the compiler is doing |
|
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.
<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.