Assembling WebLogic Web Services Using Ant Tasks

The following sections describe how to assemble and deploy WebLogic Web Services using a variety of Ant tasks:

• Overview of Assembling WebLogic Web Services Using Ant Tasks
• Assembling WebLogic Web Services Using the servicegen Ant task
• Assembling WebLogic Web Services Using Other Ant Tasks
• The Web Service EAR File Package
• Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks
• Non-Roundtripping of Generated Data Type Components
• Deploying WebLogic Web Services

 

---

Overview of Assembling WebLogic Web Services Using Ant Tasks

Assembling a WebLogic Web Service refers to gathering all the components of the service (such as the EJB JAR file, the SOAP message handler classes, and so on), generating the web-services.xml deployment descriptor file, and packaging everything into an Enterprise Application Archive (EAR) file that can be deployed on WebLogic Server.

There are two ways to assemble a WebLogic Web Service using Ant tasks:

• Using the servicegen Ant task, which performs all assembly steps for you.

The servicegen Ant takes as input an EJB JAR file (for EJB-implemented Web Services) or a list of Java classes (for Java class-implemented Web Services), and based on information after introspecting the Java code and the attributes of the Ant task, it automatically generates all the components that make up a WebLogic Web Service and packages them into an EAR file.

For detailed information, see Assembling WebLogic Web Services Using the servicegen Ant task.

• Using a variety of narrowly-focused Ant tasks, such as autotype, source2wsdd, and so on.

Typically, the servicegen Ant task is adequate for assembling most WebLogic Web Services. If, however, you want more control over how your Web Service is assembled, you can use a set of narrowly-focused Ant tasks instead. For example, you can use the source2wsdd to generate the web-services.xml file, and then you can update this file manually if you want to add more information.

For detailed information, see Assembling WebLogic Web Services Using Other Ant Tasks.

For detailed reference information on the Web Services Ant tasks, see Web Service Ant Tasks and Command-Line Utilities.

 

---

Assembling WebLogic Web Services Using the servicegen Ant task

The servicegen Ant task takes as input an EJB JAR file or list of Java classes and creates all the needed Web Service components and packages them into a deployable EAR file.

What the servicegen Ant Task Does

In particular, the servicegen Ant task:

• Introspects the Java code, looking for public methods to convert into Web Service operations and non-built-in data types used as parameters or return values of the methods.
• Creates a web-services.xml deployment descriptor file, based on the attributes of the servicegen Ant task and introspected EJB or Java class information.
• Optionally creates the serialization class that convert the non-built-in data between its XML and Java representations. It also creates XML Schema representations of the Java objects and updates the web-services.xml file accordingly. For the list of supported non-built-in data types, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks.
• Packages all the Web Service components into a Web application WAR file, then packages the WAR and EJB JAR files into a deployable EAR file.

Assembling WebLogic Web Services Automatically: Main Steps

To assemble a Web Service automatically using the servicegen Ant task:

1. Set your environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

   On UNIX, execute the setEnv.sh command, located in the directory WL_HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

2. Create a staging directory to hold the components of your Web Service.
3. If the Web Service operations are implemented with EJBs, package them, along with any supporting EJBs, into an EJB JAR file. If the operations are implemented with Java classes, compile them into class files.

   For detailed information, refer to Developing WebLogic Server Applications.

4. Copy the EJB JAR file and/or Java class files to the staging directory.
5. In the staging directory, create the Ant build file (called build.xml by default) that contains a call to the servicegen Ant task.

   For details about specifying the servicegen Ant task, see Running the servicegen Ant Task.

   For general information about creating Ant build files, see http://jakarta.apache.org/ant/manual/.

6. Execute the Ant task or tasks specified in the build.xml file by typing ant in the staging directory, optionally passing the command a target argument:

   prompt> ant

   The Ant task generates the Web Services EAR file in the staging directory which can then deploy on WebLogic Server.

Running the servicegen Ant Task

The following sample build.xml, file taken from the examples.webservices.basic.statelessession product example, specifies that you will run the servicegen Ant task:

<project name="buildWebservice" default="ear">
  <target name="ear">
    <servicegen
       destEar="ws_basic_statelessSession.ear"
       contextURI="WebServices" >
       <service
         ejbJar="HelloWorldEJB.jar"
         targetNamespace="http://www.bea.com/webservices/basic/statelesSession"
         serviceName="HelloWorldEJB"
         serviceURI="/HelloWorldEJB"
         generateTypes="True"
         expandMethods="True"
         style="rpc" >
       </service>
     </servicegen>
  </target>
</project>

In the example, the servicegen Ant task creates one Web Service called HelloWorldEJB. The URI to identify this Web Service is /HelloWorldEJB; the full URL to access the Web Service is

http://host:port/WebServices/HelloWorldEJB

The servicegen Ant task packages the Web Service in an EAR file called ws_basic_statelessSession.ear. The EAR file contains a WAR file called web-services.war (default name) that contains all the Web Service components, such as the web-services.xml deployment descriptor file.

Because the generateTypes attribute is set to True, the WAR file also contains the serialization class for any non-built-in data types used as parameters or return values to the EJB methods. The Ant task introspects the EJBs contained in the HelloWorldEJB.jar file, looking for public operations and non-built-in data types, and updates the web-services.xml operation and data type mapping sections accordingly. Because the expandMethods attribute is also set to True, the Ant task lists each public EJB method as a separate operation in the web-services.xml file.

The style="rpc" attribute specifies that the operations in the Web Service are all RPC-oriented. If the operations in your Web Service are document-oriented, specify style="document".

 

---

Assembling WebLogic Web Services Using Other Ant Tasks

Typically, the servicegen Ant task is adequate for assembling most WebLogic Web Services. If, however, you want more control over how your Web Service is assembled, you can use a set of narrowly-focused Ant tasks instead. For example, you can use the source2wsdd to generate the web-services.xml file, and then you can update this file manually if you want to add more information.

To assemble a WebLogic Web Service using Ant tasks other than servicegen:

1. Package or compile the backend components that implement the Web Service into their respective packages. For example, package stateless session EJBs into an EJB JAR file and Java classes into class files.

   For detailed instructions, see WebLogic Server Application Packaging.

2. Create the Web Service deployment descriptor file (web-services.xml).

   If you implemented your Web Service with a Java class, you can use the source2wsdd Ant task to generate a web-services.xml file. For details, see Running the source2wsdd Ant Task. If you used the wsdl2Service Ant task to generate a partial implementation of a Web Service from an existing WSDL file, then the Ant task already generated a web-services.xml file for you.

   For all other cases, such as EJB-implemented Web Services, you might have to create the web-services.xml file manually. See Creating the web-services.xml File Manually: Main Steps.

3. If your Web Service uses non-built-in data types, create all the needed components, such as the serialization class, by using the autotype Ant task to generate these components automatically, as described in Running the autotype Ant Task.
4. Optionally create a client JAR file using the clientgen Ant task.

   See Running the clientgen Ant Task.

5. Package all components into a deployable EAR file by using the wspackage Ant task, as described in Running the wspackage Ant task.

Running the source2wsdd Ant Task

Use the source2wsdd Ant task to generate a web-services.xml deployment descriptor file from the Java source file that implements a Web Service.

Note: You cannot use this Ant task to generate the web-services.xml file for an EJB-implemented Web Service; you can only use it for Java class-implemented Web Service.

To run the source2wsdd Ant task, follow these steps:

1. Create a file called build.xml that contains a call to the source2wsdd Ant task. See Sample build.xml Files for the source2wsdd Ant Task.
2. Set your environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

   On UNIX, execute the setEnv.sh command, located in the directory WL_HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

3. Execute the Ant task or tasks specified in the build.xml file by typing ant in the same directory as the build.xml file:

   prompt> ant

For reference information about the source2wsdd Ant task, see source2wsdd.

Sample build.xml Files for the source2wsdd Ant Task

The following example shows a simple build.xml file:

<project name="buildWebservice" default="generate-typeinfo">
   <target name="generate-typeinfot">
      <source2wsdd
           javaSource="c:\source\MyService.java"
           typesInfo="c:\autotype\types.xml"
           ddFile="c:\ddfiles\web-services.xml"
           serviceURI="/MyService" />
</project>

In the example, the source2wsdd Ant task generates a web-services.xml file from the Java source file called c:\source\MyService.java. It uses non-built-in data type information from the c:\autotype\types.xml file; this information includes the XML Schema representation of non-built-in data types used as parameters or return values in your Web Service, as well as data type mapping information that specifies the location of the serialization class, and so on. You typically generate this file using the autotype Ant task.

The source2wsdd Ant task outputs the generated deployment descriptor information into the file c:\ddfiles\web-services.xml. The URI of the Web Service is /MyService, used in the full URL that invokes the Web Service once it is deployed.

Running the autotype Ant Task

Use the autotype Ant task to generate non-built-in data type components, such as the serialization class. For the list of supported non-built-in data types, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks.

To run the autotype Ant task, follow these steps:

1. Create a file called build.xml that contains a call to the autotype Ant task. For details, see Sample build.xml Files for the Autotype Ant Task.
2. Set your environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

   On UNIX, execute the setEnv.sh command, located in the directory WL_HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

3. Execute the Ant task or tasks specified in the build.xml file by typing ant in the same directory as the build.xml file:

   prompt> ant

For reference information about the autotype Ant task, see autotype.

Sample build.xml Files for the Autotype Ant Task

The following example shows a simple build.xml file:

<project name="buildWebservice" default="generate-typeinfo">
   <target name="generate-typeinfot">
     <autotype  javatypes="mypackage.MyType"
                targetNamespace="http://www.foobar.com/autotyper"
                packageName="a.package.name"
                destDir="d:\output" />
   </target>
</project>

In the example, the autotype Ant task creates the non-built-in data type components for a Java class called mypackage.MyType. The package name used in the generated serialization class is a.package.name. The serialization Java class and XML schema inforamtion is generated and placed in the d:\output directory. The generated XML Schema and type-mapping information are in a file called types.xml in this output directory.

The following excerpt from a sample build.xml file shows another way to use the autotype task:

<autotype  wsdl="file:\wsdls\myWSDL"
           targetNamespace="http://www.foobar.com/autotyper"
           packageName="a.package.name"
           destDir="d:\output" />

This example is similar to the first, except that instead of starting with a Java representation of a data type, the example starts with an XML Schema representation embedded within the WSDL of a Web Service. In this case, the task generates the corresponding Java representation.

Running the clientgen Ant Task

To run the clientgen Ant task and automatically generate a client JAR file:

1. Create a file called build.xml that contains a call to the clientgen Ant task. For details, see Sample build.xml Files for the clientgen Ant Task.
2. Set your environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

   On UNIX, execute the setEnv.sh command, located in the directory WL_HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

3. Execute the Ant task or tasks specified in the build.xml file by typing ant in the same directory as the build.xml file:

   prompt> ant

For reference information about the clientgen Ant task, see clientgen.

Sample build.xml Files for the clientgen Ant Task

The following example shows a simple build.xml file:

<project name="buildWebservice" default="generate-client">
   <target name="generate-client">
      <clientgen ear="c:/myapps/myapp.ear"
                 serviceName="myService"
                 packageName="myapp.myservice.client"
                 useServerTypes="True" 
                 clientJar="c:/myapps/myService_client.jar" />
   </target>
</project>

In the example, the clientgen Ant task creates the c:/myapps/myService_client.jar client JAR file that contains the service-specific client interfaces and stubs and the serialization class used to invoke the WebLogic Web Service called myService contained in the EAR file c:/myapps/myapp.ear. It packages the client interface and stub files into a package called myapp.myservice.client. The useServerTypes attribute specifies that the clientgen Ant task should get the Java implementation of all non-built-in data types used in the Web Service from the c:/myapps/myapp.ear file rather than generating Java code to implement the data types.

The following excerpt from a sample build.xml file shows another way to use the clientgen task:

<clientgen wsdl="http://example.com/myapp/myservice.wsdl"
           packageName="myapp.myservice.client"
           clientJar="c:/myapps/myService_client.jar"
/>

In the example, the clientgen task creates a client JAR file (called c:/myapps/myService_client.jar) to invoke the Web Service described in the http://example.com/myapp/myservice.wsdl WSDL file. It packages the interface and stub files in the myapp.myservice.client package.

Running the wspackage Ant task

Use the wspackage Ant task to package the various components of a Web Service into a deployable EAR file.

To run the wspackage Ant task, follow these steps:

1. Create a file called build.xml that contains a call to the wspackage Ant task. For details, see Sample build.xml Files for the wspackage Ant Task.
2. Set your environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

   On UNIX, execute the setEnv.sh command, located in the directory WL_HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

3. Execute the Ant task or tasks specified in the build.xml file by typing ant in the same directory as the build.xml file:

   prompt> ant

For reference information about the wspackage Ant task, see wspackage.

Sample build.xml Files for the wspackage Ant Task

The following example shows a simple build.xml file for creating a deployable EAR file for a Java class-implemented Web Service:

<project name="buildWebservice" default="generate-typeinfo">
   <target name="generate-typeinfot">
      <wspackage
           output="c:\myWebService.ear"
           contextURI="web_services"
           codecDir="c:\autotype"
           webAppClasses="example.ws2j.service.SimpleTest"
           ddFile="c:\ddfiles\web-services.xml" />

</project>

In the example, the wspackage Ant task creates an EAR file called c:\myWebService.ear. The context URI of the Web Service, used in the full URL that invokes it, is web_services. The serializer class that contains the serializer class for the non-built-in data types is located in the c:\autotype directory. The Java class that implements the Web Service is called example.ws2j.service.SimpleTest and will be packaged in the WEB-INF/classes directory of the Web application. Finally, the existing deployment descriptor file is c:\ddfiles\web-services.xml.

 

---

The Web Service EAR File Package

Web Services are packaged into standard Enterprise Application EAR files that contain a Web application WAR file along with the EJB JAR files.

The following graphic shows the hierarchy of a typical WebLogic Web Services EAR file.

 

---

Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks

The tables in the following sections list the non-built-in XML and Java data types for which the servicegen and autotype Ant tasks can generate data type components, such as the serializer class, the Java or XML representation, and so on.

If your XML or Java data type is not listed in these tables, and it is not one of the built-in data types listed in Using Built-In Data Types, then you must create the non-built-in data type components manually. For details, see Using Non-Built-In Data Types.

Warning: The serializer class and Java and XML representations generated by the autotype, servicegen, and clientgen Ant tasks cannot be round-tripped. For more information, see Non-Roundtripping of Generated Data Type Components.

Supported XML Non-Built-In Data Types

The following table lists the supported XML Schema non-built-in data types. If your XML data type is listed in the table, then the servicegen and autotype Ant tasks can generate the serializer class to convert the data between its XML and Java representations, as well as the Java representation and type mapping information for the web-services.xml deployment descriptor.

For details and examples of the data types, see the JAX-RPC specification.

Table 6-1 Supported Non-Built-In XML Schema Data Types

XML Schema Data Type	Equivalent Java Data Type or Mapping Mechanism
Enumeration	Typesafe enumeration pattern. For details, see Section 4.2.4 of the JAX-RPC specification.
<xsd:compleType> with elements of both simple and complex types.	JavaBean
<xsd:attribute> in <xsd:complexType>	Property of a JavaBean
Derivation of new simple types by restriction of an existing simple type.	Equivalent Java data type of simple type.
Facets used with restriction element. Note: The base primitive type must be one of the following: string, decimal, float, or double. Pattern facet is not enforced.	Restriction enforced during serialization and deserialization.
<xsd:list>	Array of the list data type.
Array derived from soapenc:Array by restriction using the wsdl:arrayType attribute.	Array of the Java equivalent of the arrayType data type.
Array derived from soapenc:Array by restriction.	Array of Java equivalent.
Derivation of a complex type from a simple type.	JavaBean with a property called simpleContent of type String.
<xsd:anyType>	java.lang.Object.
<xsd:nil> and <xsd:nillable> attribute	Java null value. If the XML data type is built-in and usually maps to a Java primitive data type (such as int or short), then the XML data type is actually mapped to the equivalent object wrapper type (such as java.lang.Integer or java.lang.Short).
Derivation of complex types by extension	Mapped using Java inheritance.
Abstract types	Abstract Java data type.

Supported Java Non-Built-In Data Types

The following table lists the supported Java non-built-in data types. If your Java data type is listed in the table, then the servicegen and autotype Ant tasks can generate the serializer class to convert the data between its Java and XML representations.

Table 6-2 Supported Non-Built-In Java Data Types

Java Data Type	Equivalent XML Schema Data Type
Array of any built-in Java data type.	SOAP Array.
JavaBean whose properties are any built-in Java data type.	<xsd:sequence>
java.util.List	SOAP Array.
java.util.ArrayList	SOAP Array.
java.util.LinkedList	SOAP Array.
java.util.Vector	SOAP Array.
java.lang.Object Note: The data type of the runtime object must be a known type: either a built-in data type or one that has type mapping information.	<xsd:anyType>

 

---

Non-Roundtripping of Generated Data Type Components

When you use the servicegen or autotype Ant tasks to create the serializer class and Java or XML representation of non-built-in data types, it is very important to note that the process cannot be round-tripped. This means that if, for example, you use the autotype Ant task to generate the Java representation of an XML Schema data type, and then use autotype to create an XML Schema data type from the generated Java type, the original and generated XML Schema data type will not necessarily look the same, although they both describe the same XML data. This is also true if you start from Java, generate an XML Schema, then generate a new Java data type from the generated XML Schema: the origianal and generated Java type will not necessarily look exactly the same. One possible difference, for example, is that the original and generated Java type might list the parameters of the constructor in a different order.

This behavior has a variety of repercussions. For example, assume you are developing a Web Service from an existing stateless session EJB that uses non-built-in data types. You use the autotype Ant task to generate the serializer class and Java and XML representation of the data types and you use this generated code in your server-side code that implements your Web Service. Later you use the clientgen Ant task to generate the Web Service-specific client JAR file, which also includes a serializer class and the Java representation of the non-built-in data types. However, because clientgen by default generates these components from the WSDL of the Web Service (and thus from an XML Schema), the clientgen-generated client-side Java representation might look different from the autotype-generated server-side Java code. This means that you might not necessarily be able to reuse any server-side code that handles the data type in your client application. If you want the clientgen Ant task to always use the generated serializer class and code from the WebLogic Web Service EAR file, specify the userServerTypes attribute.

 

---

Deploying WebLogic Web Services

Deploying a WebLogic Web Service refers to making it available to remote clients. Because WebLogic Web Services are packaged as standard J2EE Enterprise applications, deploying a Web Service is the same as deploying an Enterprise application.

For detailed information on deploying Enterprise applications, see Deploying WebLogic Server Applications.