bea.com | products | dev2dev | support | askBEA |
![]() |
![]() |
|
![]() |
e-docs > WebLogic Server > Programming WebLogic Web Services > Assembling WebLogic Web Services Using Ant Tasks |
Programming WebLogic Web Services
|
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 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:
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.
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:
Assembling WebLogic Web Services Automatically: Main Steps
To assemble a Web service automatically using the servicegen Ant task:
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.
For detailed information, refer to Developing WebLogic Server Applications.
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/.
prompt> ant
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" >
<client
packageName="examples.webservices.basic.statelessSession"
/>
</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".
Finally, the Ant task creates a client JAR file, called HelloWorldEJB_client.jar (default name) and packages it into the EAR file. Clients that want to invoke the Web service can download this client JAR file, which includes the service-specific client classes, stubs, and interfaces.
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:
For detailed instructions, see WebLogic Server Application Packaging.
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.
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:
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.
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.
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:
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.
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:
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.
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:
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.
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.
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.
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.
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. |
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.
![]() |
![]() |
![]() |
![]() |
||
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |