Programming Web Services for WebLogic Server
The following sections provide reference information about the WebLogic Web Services Ant tasks:
For detailed information on how to integrate and use these Ant tasks in your development environment to program a Web Service and a client application that invokes the Web Service, see:
Ant is a Java-based build tool, similar to the make
command but much more powerful. Ant uses XML-based configuration files (called build.xml
by default) to execute tasks written in Java. BEA provides a number of Ant tasks that help you generate important Web Service-related artifacts.
The Apache Web site provides other useful Ant tasks for packaging EAR, WAR, and EJB JAR files. For more information, see http://jakarta.apache.org/ant/manual/.
Note: The Apache Jakarta Web site publishes online documentation for only the most current version of Ant, which might be different from the version of Ant that is bundled with WebLogic Server. To determine the version of Ant that is bundled with WebLogic Server, run the following command after setting your WebLogic environment:
prompt> ant -version
To view the documentation for a specific version of Ant, download the Ant zip file from http://archive.apache.org/dist/ant/binaries/ and extract the documentation.
The following table provides an overview of the Web Service Ant tasks provided by BEA.
On Windows NT, execute the setDomainEnv.cmd
command, located in your domain directory. The default location of WebLogic Server domains is BEA_HOME
\user_projects\domains\
domainName
, where BEA_HOME
is the top-level installation directory of the BEA products and domainName
is the name of your domain.
On UNIX, execute the setDomainEnv.sh
command, located in your domain directory. The default location of WebLogic Server domains is BEA_HOME
/user_projects/domains/
domainName
, where BEA_HOME
is the top-level installation directory of the BEA products and domainName
is the name of your domain.
The following example shows a simple build.xml
file with a single target called clean
:
<project name="my-webservice">
<target name="clean">
<delete>
<fileset dir="tmp" />
</delete>
</target>
</project>
This clean
target deletes all files in the temp
subdirectory.
Later sections provide examples of specifying the Ant task in the build.xml
file.
build.xml
file using the <taskdef>
and <target>
elements. The following example shows how to add the jwsc
Ant task to the build file; the attributes of the task have been removed for clarity:<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<target name="build-service">
<jwscattributes go here...
>
...
</jwsc>
</target>
You can, of course, name the WebLogic Web Services Ant tasks anything you want by changing the value of the name
attribute of the relevant <taskdef>
element. For consistency, however, this document uses the names jwsc
, clientgen
, and wsdlc
throughout.
build.xml
file by typing ant
in the same directory as the build.xml
file and specifying the target:prompt> ant build-service
Each WebLogic Ant task accepts a classpath
attribute or element so that you can add new directories or JAR files to your current CLASSPATH environment variable.
The following example shows how to use the classpath
attribute of the jwsc
Ant task to add a new directory to the CLASSPATH variable:
<jwsc srcdir="MyJWSFile.java"
classpath="${java.class.path};my_fab_directory"
...
</jwsc>
The following example shows how to add to the CLASSPATH by using the <classpath
> element:
<jwsc ...>
<classpath>
<pathelement path="${java.class.path}" />
<pathelement path="my_fab_directory" />
</classpath>
...
</jwsc>
The following example shows how you can build your CLASSPATH variable outside of the WebLogic Web Service Ant task declarations, then specify the variable from within the task using the <classpath>
element:
<path id="myClassID">
<pathelement path="${java.class.path}"/>
<pathelement path="${additional.path1}"/>
<pathelement path="${additional.path2}"/>
</path>
<jwsc ....>
<classpath refid="myClassID" />
...
</jwsc>
Note: The Java Ant utility included in WebLogic Server uses the ant
(UNIX) or ant.bat
(Windows) configuration files in the WL_HOME\server\bin
directory to set various Ant-specific variables, where WL_HOME is the top-level directory of your WebLogic Server installation If you need to update these Ant variables, make the relevant changes to the appropriate file for your operating system.
Many WebLogic Web Service Ant tasks have attributes that you can use to specify a file, such as a WSDL or an XML Schema file.
The Ant tasks process these files in a case-sensitive way. This means that if, for example, the XML Schema file specifies two user-defined types whose names differ only in their capitalization (for example, MyReturnType
and MYRETURNTYPE
), the clientgen
Ant task correctly generates two separate sets of Java source files for the Java representation of the user-defined data type: MyReturnType.java
and MYRETURNTYPE.java
.
However, compiling these source files into their respective class files might cause a problem if you are running the Ant task on Microsoft Windows, because Windows is a case insensitive operating system. This means that Windows considers the files MyReturnType.java
and MYRETURNTYPE.java
to have the same name. So when you compile the files on Windows, the second class file overwrites the first, and you end up with only one class file. The Ant tasks, however, expect that two classes were compiled, thus resulting in an error similar to the following:
c:\src\com\bea\order\MyReturnType.java:14:
class MYRETURNTYPE is public, should be declared in a file named MYRETURNTYPE.java
public class MYRETURNTYPE
^
To work around this problem rewrite the XML Schema so that this type of naming conflict does not occur, or if that is not possible, run the Ant task on a case sensitive operating system, such as Unix.
The clientgen
Ant task generates, from an existing WSDL file, the client component files that client applications use to invoke both WebLogic and non-WebLogic Web Services. These files include:
Stub
and Service
interface implementations for the particular Web Service you want to invoke.Two types of client applications use the generated artifacts of clientgen
to invoke Web Services:
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
...
<target name="build_client">
<clientgen
wsdl="http://example.com/myapp/myservice.wsdl"
destDir="/output/clientclasses"
packageName="myapp.myservice.client"
serviceName="StockQuoteService" />
<javac ... />
</target>
When the sample build_client
target is executed, clientgen
uses the WSDL file specified by the wsdl
attribute to generate all the client-side artifacts needed to invoke the Web Service specified by the serviceName
attribute. The clientgen
Ant task generates all the artifacts into the /output/clientclasses
directory. All generated Java code is in the myapp.myservice.client
package. After clientgen
has finished, the javac
Ant task then compiles the Java code, both clientgen
-generated as well as your own client application that uses the generated artifacts and contains your business code.
You typically execute the clientgen
Ant task on a WSDL file that is deployed on the Web and accessed using HTTP. Sometimes, however, you might want to execute clientgen
on a static WSDL file that is packaged in an archive file, such as the WAR or JAR file generated by the jwsc
Ant task. In this case you must use the following syntax for the wsdl
attribute:
wsdl="jar:file:
archive_file
!WSDL_file
"
where archive_file
refers to the full (or relative to the current directory) name of the archive file and WSDL_file
refers to the full pathname of the WSDL file, relative to the root directory of the archive file. For example:
<clientgen
wsdl="jar:file:output/myEAR/examples/webservices/simple/SimpleImpl.war!/WEB-INF/SimpleService.wsdl"
destDir="/output/clientclasses"
packageName="myapp.myservice.client"/>
The preceding example shows how to execute clientgen
on a static WSDL file called SimpleService.wsdl
, which is packaged in the WEB-INF
directory of a WAR file called SimpleImpl.war
, which is located in the output/myEAR/examples/webservices/simple
sub-directory of the directory that contains the build.xml
file.
The following table describes the attributes of the clientgen
Ant task.
Directory into which the You can set this attribute to any directory you want. However, if you are generating the client component files to invoke a Web Service from an EJB, JSP, or other Web Service, you typically set this attribute to the directory of the J2EE component which holds shared classes, such as |
|||
Specifies whether the If you specify Valid values for this attribute are See Using a Client-Side Security WS-Policy File for more information. |
|||
Specifies whether the For example, if you specify See Invoking a Web Service Using Asynchronous Request-Response for full description and procedures about this feature. Note: If the Web Service operation is marked as one-way, the Valid values for this attribute are |
|||
Specifies whether the client component files (source code, WSDL, and deployment descriptor files) generated by this Ant task should be overwritten if they already exist. If you specify If you specify Valid values for this attribute is |
|||
Package name into which the generated JAX-RPC client interfaces and stub files are packaged. If you do not specify this attribute, the If you do specify this attribute, BEA recommends you use all lower-case letters for the package name. |
|||
Name of the Web Service in the WSDL file for which the corresponding client component files should be generated. The Web Service name corresponds to the The generated JAX-RPC mapping file and client-side copy of the WSDL file will use this name. For example, if you set |
This attribute is required only if the WSDL file contains more than one The Ant task returns an error if you do not specify this attribute and the WSDL file contains more than one |
||
Full path name or URL of the WSDL that describes a Web Service (either WebLogic or non-WebLogic) for which the client component files should be generated. The generated stub factory classes in the client JAR file use the value of this attribute in the default constructor. |
|||
Specifies whether the When the Valid values for this attribute are |
|||
Specifies the name of the XML file that describes the client-side SOAP message handlers that execute when a client application invokes a Web Service. Each handler specified in the file executes twice: If you do not specify this clientgen attribute, then no client-side handlers execute, even if they are in your CLASSPATH. See Creating and Using Client-Side SOAP Message Handlers for details and examples about creating client-side SOAP message handlers. |
|||
When the Valid values for this attribute are |
|||
Additions to the CLASSPATH. Use this attribute to add JAR files or directories that contain Java classes to the CLASSPATH used to compile the JWS file. |
|||
Additions to the CLASSPATH, but specified as a reference to a path defined elsewhere in the |
The jwsc
Ant task takes as input a Java Web Service (JWS) file that contains both standard (JSR-181) and WebLogic-specific JWS annotations and generates all the artifacts you need to create a WebLogic Web Service. The generated artifacts include:
JWS_ClassName
PortType.java
, where JWS_ClassName
refers to the JWS class).webservices.xml
and JAX-RPC mapping files, the jwsc
Ant task also generates the WebLogic-specific Web Services deployment descriptor (weblogic-webservices.xml
).After generating all the artifacts, the jwsc
Ant task compiles the Java and JWS files, packages the compiled classes and generated artifacts into a deployable JAR archive file, and finally creates an exploded Enterprise Application directory that contains the JAR file. You then deploy this Enterprise Application to WebLogic Server. If you specify an existing Enterprise Application as the destination directory to jwsc
, the Ant task updates any existing application.xml
file with the new Web Services information.
Note: The jwsc
Ant task typically generates a Java class-implemented Web Service from the specified JWS file and packages it into a Web Application WAR file. In the following cases, however, it creates a stateless session EJB-implemented Web Service and packages it into an EJB JAR file:
You invoke and use Java class- and stateless session EJB-implemented Web Services in exactly the same way, so this implementation detail is typically not important to a programmer. It is mentioned in this section only for the case in which a programmer needs to update the Web Service archive and needs to know if it is a WAR or an EJB JAR.
You specify the JWS file you want the jwsc
Ant task to compile using the <
jws
>
child-element of the Ant task. The <jws>
element includes three optional child-elements for specifying the transports (HTTP/S or JMS) that are used to invoke the Web Service.
See Creating a Web Service With User-Defined Data Types for a complete example of using the jwsc
Ant task.
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
The following examples show how to use the jwsc
Ant task by including it in a build-service
target of the build.xml
Ant file that iteratively develops your Web Service. See Common Web Services Use Cases and Examples, and Iterative Development of WebLogic Web Services, for samples of complete build.xml
files that contain many other targets that are useful when iteratively developing a WebLogic Web Service, such as clean
, deploy
, client
, and run
.
The following sample shows a very simple usage of jwsc
:
<target name="build-service">
<jwsc
srcdir="src"
destdir="output/TestEar">
<jws file="examples/webservices/test/TestServiceImpl.java" />
</jwsc>
</target>
In the example, the JWS file called TestServiceImpl.java
is located in the src/examples/webservices/test
sub-directory of the directory that contains the build.xml
file. The jwsc
Ant task generates the Web Service artifacts in the output/TestEar
sub-directory. In addition to the Web Service JAR file, the jwsc
Ant task also generates the application.xml
file that describes the Enterprise Application in the output/TestEar/META-INF
directory.
The following example shows a more complicated use of jwsc
:
<path id="add.class.path">
<pathelement path="${myclasses-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
...
<target name="build-service2">
<jwsc
srcdir="src" destdir="output/TestEar"
verbose="on" debug="on"
keepGenerated="yes"
classpathref="add.class.path">
<jws file="examples/webservices/test/TestServiceImpl.java" />
<jws file="examples/webservices/test/AnotherTestServiceImpl.java"/>
<jws file="examples/webservices/test/SecondTestServiceImpl.java" />
</jwsc>
</target>
The example shows how to enable debugging and verbose output, and how to specify that jwsc
not regenerate any existing temporary files in the output directory. The example shows how to use classpathref
attribute to add to the standard CLASSPATH by referencing a path called add.class.path
that has been specified elsewhere in the build.xml
file using the standard Ant <path>
target.
The example also shows how to specify multiple JWS files, resulting in separate Web Services packaged in their own JAR files, although all are still deployed as part of the same Enterprise Application.
The following example shows how to specify the transport that is used to invoke the Web Service:
<target name="build-service3">
<jwsc
srcdir="src"
destdir="output/TestEar">
<jws file="examples/webservices/test/TestServiceImpl.java">
<WLHttpTransport
contextPath="TestService" serviceUri="TestService"
portName="TestServicePort1"/>
</jws>
</jwsc>
</target>
The preceding example shows how to specify that the HTTP transport is used to invoke the Web Service.
The jwsc
Ant task has a variety of attributes and one child element: <
jws
>
. The <jws>
element has three optional child elements: <
WLHttpTransport
>
, <
WLHttpsTransport
>
, and <
WLJMSTransport
>
. See Transport Child Elements for common information about using the transport elements.
The following graphic describes the hierarchy of the jwsc
Ant task.
Figure A-1 Element Hierarchy of jwsc Ant Task
The following table describes the attributes of the main jwsc
Ant task.
The <jws>
child element of the jwsc
Ant task specifies the name of a JWS file that implements your Web Service and for which the Ant task should generate Java code and supporting artifacts and then package into a deployable JAR file inside of an Enterprise Application.
You must specify at least one <jws>
element. If you specify more than one, the jwsc
Ant task generates a separate Web Service for each JWS file, each of which is packaged in its own JAR file.
The following table describes the attributes of the <jws>
child element of the jwsc
Ant task.
The name of the JWS file that you want to compile. The |
||
Specifies whether the generated JAR file which contains the deployable Web Service is in exploded directory format or not. Valid values for this attribute are |
||
The name of the generated JAR file (or exploded directory, if the The default value of this attribute is the name of the JWS file, specified by the |
||
The full pathname of the XML Schema file that describes an To specify more than one XML Schema file, use either a comma or semi-colon as a delimiter: This attribute is only supported in the case where the JWS file explicitly uses an Additionally, you can use this attribute only for Web Services whose SOAP binding is document-literal-bare. Because the default SOAP binding of a WebLogic Web Service is document-literal-wrapped, the corresponding JWS file must include the following JWS annotation:
For more information on Note: As of WebLogic Server 9.1, using XMLBeans 1.X data types (in other words, extensions of |
Required if you are using an |
|
Full pathname of the JAR file generated by the You use this attribute only in the "starting from WSDL" use case, in which you first use the wsdlc Ant task to generate the JAR file, along with the JWS file that implements the generated JWS interface. After you update the JWS implementation class with business logic, you run the You do not use the |
||
Specifies that only a WSDL file should be generated for this JWS file. Note: Although the other artifacts, such as the deployment descriptors and service endpoint interface, are not generated, data binding artifacts are generated because the WSDL must include the XML Schema that describes the data types of the parameters and return values of the Web Service operations. The WSDL is generated into the Valid values for this attribute are |
When you program your JWS file, you can use an annotation to specify the transport that clients use to invoke the Web Service, in particular @weblogic.jws.WLHttpTransport
, @weblogic.jws.WLHttpsTransport
, or @weblogic.jws.WLJMSTranspor
t. You can specify only one of these annotations in the JWS file. However, a programmer might not know at the time that they are coding the JWS file which transports best suits their needs. For this reason, it is best to specify the transport at build-time with one of the following transport child-elements of the <jws>
element:
You can specify exactly zero or one of the preceding transport elements for a particular JWS file. If you do not specify any transport, as either one of the transport elements to the jwsc
Ant task or a transport annotation in the JWS file, then the Web Service's default URL corresponds to the default value of the WLHttpTransport
element. Finally, whatever transport you specify to jwsc
overrides any transport annotation in the JWS file.
Use the WLHttpTransport
element to specify the context path and service URI sections of the URL used to invoke the Web Service over the HTTP transport, as well as the name of the port in the generated WSDL.
See Transport Child Elements for guidelines to follow when specifying this element.
The following table describes the attributes of the <WLHttpTransport>
child element of the <jws>
element.
Use the WLHttpsTransport
element to specify the context path and service URI sections of the URL used to invoke the Web Service over the secure HTTPS transport, as well as the name of the port in the generated WSDL.
See Transport Child Elements for guidelines to follow when specifying this element.
The following table describes the attributes of the <WLHttpsTransport>
child element of the <jws>
element.
Use the WLJMSTransport
element to specify the context path and service URI sections of the URL used to invoke the Web Service over the JMS transport, as well as the name of the port in the generated WSDL. You also specify the name of the JMS queue and connection factory that you have already configured for JMS transport.
See Transport Child Elements for guidelines to follow when specifying this element.
The following table describes the attributes of the <WLJMSTransport>
child element of the <jws>
element.
Context root of the Web Service. For example, assume the deployed WSDL of a WebLogic Web Service is as follows:
The contextPath for this Web Service is The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is |
||
Web Service URI portion of the URL. For example, assume the deployed WSDL of a WebLogic Web Service is as follows:
The serviceUri for this Web Service is The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is |
||
The name of the port in the generated WSDL. This attribute maps to the The default value of this attribute is based on the |
||
The JNDI name of the JMS queue that you have configured for the JMS transport. See Using JMS Transport as the Connection Protocol for details about using JMS transport. The default value of this attribute, if you do not specify it, is |
The wsdlc
Ant task generates, from an existing WSDL file, a set of artifacts that together provide a partial Java implementation of the Web Service described by the WSDL file. In particular, the Ant task generates:
@WebService
and @SOAPBinding
) that implement other aspects of the Web Service.The wsdlc
Ant task generates artifacts for the first <service>
element it finds in the WSDL file. You can specify a specific WSDL <binding>
by using the srcBindingName
attribute.
Warning: The JWS interface is generated into a JAR file, neither of which you should ever update. It is discussed in this section only because later you need to specify this JAR file to the jwsc
Ant task when you compile your JWS implementation file into a Web Service.
wsdlc
Ant task. Warning: These artifacts are generated into a JAR file, along with the JWS interface file, none of which you should ever update. It is discussed in this section only because later you need to specify this JAR file to the jwsc
Ant task when you compile your JWS implementation file into a Web Service.
After running the wsdlc
Ant task, (which typically you only do once) you update the generated JWS implementation file, in particular by adding Java code to the methods so that they function as you want. The generated JWS implementation file does not initially contain any business logic because the wsdlc
Ant task obviously does not know how you want your Web Service to function, although it does know the shape of the Web Service, based on the WSDL file.
When you code the JWS implementation file, you can also add additional JWS annotations, although you must abide by the following rules:
@WebService
, @HandlerChain
, @SOAPMessageHandler
, and @SOAPMessageHandlers
. If you specify any other JWS-181 JWS annotations, the jwsc
Ant task will return an error when you try to compile the JWS file into a Web Service.serviceName
and endpointInterface
attributes of the @WebService
annotation. Use the serviceName
attribute to specify a different <service>
WSDL element from the one that the wsdlc
Ant task used, in the rare case that the WSDL file contains more than one <service>
element. Use the endpointInterface
attribute to specify the JWS interface generated by the wsdlc
Ant task.Finally, after you have coded the JWS file so that it works as you want, iteratively run the jwsc
Ant task to generate a complete Java implementation of the Web Service. Use the compiledWsdl
attribute of jwsc
to specify the JAR file generated by the wsdlc
Ant task which contains the JWS interface file and data binding artifacts. By specifying this attribute, the jwsc
Ant task does not generate a new WSDL file but instead uses the one in the JAR file. Consequently, when you deploy the Web Service and view its WSDL, the deployed WSDL will look just like the one from which you initially started.
Note: The only potential difference between the original and deployed WSDL is the value of the location
attribute of the <address>
element of the port(s) of the Web Service. The deployed WSDL will specify the actual hostname and URI of the deployed Web Service, which is most likely different from that of the original WSDL. This difference is to be expected when deploying a real Web Service based on a static WSDL.
See Creating a Web Service from a WSDL File for a complete example of using the wsdlc
Ant task in conjunction with jwsc
.
<taskdef name="wsdlc"
classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>
The following excerpt from an Ant build.xml
file shows how to use the wsdlc
and jwsc
Ant tasks together to build a WebLogic Web Service. The build file includes two different targets: generate-from-wsdl
that runs the wsdlc
Ant task against an existing WSDL file, and build-service
that runs the jwsc
Ant task to build a deployable Web Service from the artifacts generated by the wsdlc
Ant task:
<taskdef name="wsdlc"
classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<target name="generate-from-wsdl">
<wsdlc
srcWsdl="wsdl_files/TemperatureService.wsdl"
destJwsDir="output/compiledWsdl"
destImplDir="output/impl"
packageName="examples.webservices.wsdlc" />
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="output/wsdlcEar">
<jws file="examples/webservices/wsdlc/TemperaturePortTypeImpl.java"
compiledWsdl="output/compiledWsdl/TemperatureService_wsdl.jar" />
</jwsc>
</target>
In the example, the wsdlc
Ant task takes as input the TemperatureService.wsdl
file and generates the JAR file that contains the JWS interface and data binding artifacts into the directory output/compiledWsdl
. The name of the JAR file is TemperatureService_wsdl.jar
. The Ant task also generates a JWS file that contains a stubbed-out implementation of the JWS interface into the output/impl/examples/webservices/wsdlc
directory (a combination of the value of the destImplDir
attribute and the directory hierarchy corresponding to the specified packageName
). The name of the stubbed-out JWS implementation file is based on the name of the <portType>
element in the WSDL file that corresponds to the first <service>
element. For example, if the portType name is TemperaturePortType
, then the generated JWS implementation file is called TemperaturePortTypeImpl.java
.
After running wsdlc
, you code the stubbed-out JWS implementation file, adding your business logic. Typically, you move this JWS file from the wsdlc
-output directory to a more permanent directory that contains your application source code; in the example, the fully coded TemperaturePortTypeImpl.java
JWS file has been moved to the directory src/examples/webservices/wsdlc/
. You then run the jwsc
Ant task, specifying this JWS file as usual. The only additional attribute you must specify is compiledWsdl
to point to the JAR file generated by the wsdlc
Ant task, as shown in the preceding example. This indicates that you do not want the jwsc
Ant task to generate a new WSDL file, because you want to use the original one that has been compiled into the JAR file.
The following table describes the attributes of the wsdlc
Ant task.