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:

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 Individual Ant Tasks.

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

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 Platform installation If you need to update these Ant variables, make the relevant changes to the appropriate file for your operating system.

Examples of Assembling WebLogic Web Services

WebLogic Server includes examples of assembling WebLogic Web Services in the WL_HOME/samples/server/examples/src/examples/webservices directory, where WL_HOME refers to the main WebLogic Platform directory. For detailed instructions on how to build and run the examples, open the following Web page in your browser:

WL_HOME/samples/server/examples/src/examples/webservices/package-summary.html

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, 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:

Set your environment.

On Windows NT, execute the setEnv.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 setEnv.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.

Create a staging directory to hold the components of your Web Service.

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.

Copy the EJB JAR file and/or Java class files to the staging directory.

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 Creating the Build File That Specifies the servicegen Ant Task.
For general information about creating Ant build files, 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.

If you previously used the autotype Ant task to generate non-built-in data type information from an existing XML Schema file, and then used the typeMappingFile attribute of the servicegen Ant task to specify the types.xml file generated by autotype and merge it with any servicegen-generated information, and the original XML Schema file uses the <include> element to include additional XML Schema files, you must copy these XML Schema files to the root directory of the Web Service Web application WAR file of the generated EAR file. You can use the wspackage Ant task do perform this step.

If you are using the servicegen Ant task exclusively to generate non-built-in data type components, then you do not need to perform this step.
For details, see Running the wspackage Ant task.

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 (if you have created the build.xml file to take arguments):

prompt> ant

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

Creating the Build File That Specifies 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, as specified by the destEar attribute. 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".

Note: BEA recommends that you create an exploded directory, rather than an EAR file, by specifying a value for the destEar attribute of servicegen that does not have an .ear suffix. You can later package the exploded directory into an EAR file when you are ready to deploy the Web Service.

Assembling WebLogic Web Services Using Individual 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.

The following sections describe two ways to assemble a Web Service, based on whether you started with Java or with an XML Schema:

Assembling a Web Service Starting with Java

In the following procedure, it is assumed that you have already implemented your Web Service by writing the Java code of the back-end components and non-built-in data types, and you want to use individual Ant tasks to generate the XML Schema that represents the non-built-in data types, as well as the other Web Service components such as the web-services.xml deployment descriptor file.

Package or compile the Java back-end 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 Developing WebLogic Server Applications.

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

If you implemented your Web Service with a stateless session EJB or 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 details, see Generating a Partial Implementation From a WSDL File.

If your Web Service uses non-built-in data types, create all the needed components, such as the serialization class and the XML Schema, by using the autotype Ant task to generate these components automatically, as described in Running the autotype Ant Task.

Optionally create a client JAR file using the clientgen Ant task.

See Running the clientgen Ant Task.

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

Assembling a Web Service Starting with an XML Schema

In the following procedure, it is assumed that you are starting with an XML Schema that describes the non-built-in data types of your Web Service, and you want to use the individual Ant tasks to generate the equivalent Java representation of the data types. You then use these generated Java classes to write the back-end component that implements your Web Service, then use Ant tasks to generate the remaining components, such as the web-services.xml file. It is assumed that you want to preserve the original XML Schema all the way through the development process, so that at the end, when you deploy the Web Service, the published WSDL contains the exact same XML Schema with which you stared.

Run the autotype Ant task to generate the Java representations of the non-built-in data types in the XML Schema file. The Ant task also generates the serialization class used to convert the data between XML and Java and the data type mapping file. Use the schemaFile attribute of the autotype Ant task to specify the name of the file that contains your XML Schema.

For details, see Running the autotype Ant Task.

Write the Java code for the stateless session EJB or Java class back-end component that implements your Web Service. Use the Java classes generated by the autotype Ant task in the preceding step for the non-built-in data types (originally described in the XML Schema file from which you started) used as parameters or return values of the methods.

For details, see Writing the Java Code for the Components.

If necessary, re-run the autotype Ant task against your EJB or Java class to generate the non-built-in data type components for any new data types you might have created that are not included in the original XML Schema file. Use the javaComponents attribute of the autotype Ant task to specify the back-end component you wrote in Step 2.

Be sure you also use the typeMappingFile attribute to specify the existing data type mapping file, generated from the first execution of the autotype Ant task in Step 1. The autotype Ant task merges the existing XML Schema with any generated one, thus preserving the original XML Schema.
For details, see Running the autotype Ant Task.

Run the source2wsdd Ant task to generate the web-services.xml deployment descriptor. If you re-ran the autotype Ant task to create a merged data type mapping file, be sure you specify this final file with the typesInfo attribute.

For details, see Running the source2wsdd Ant Task.

Optionally create a client JAR file by running the clientgen Ant task.

For details, see Running the clientgen Ant Task.

Package all components into a deployable EAR file by using the wspackage Ant task.

If the original XML Schema file from which you originally started uses one or more <include> elements to include additional XML Schema files, be sure you explicitly copy these files to the root directory of the Web Service Web application WAR file, located by default in the root directory of the EAR file and called web-services.war.
For details and examples of a variety of ways to use the wspackage Ant task, see 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 stateless session EJB or Java source file that implements a Web Service.

To run the source2wsdd Ant task:

Set your environment.

On Windows NT, execute the setEnv.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 setEnv.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.

Create a file called build.xml that contains a call to the source2wsdd Ant task. For details, see the examples later in this section.

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.

The following example shows a simple build.xml file.

Listing 6-1 Simple Source2wsdd build.xml File For a Java Source File

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

When you run the source2wsdd Ant task using the preceding build.xml file, the Ant task generates a web-services.xml file from the Java source file source/MyService.java. It uses non-built-in data type information from the 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 the types.xml file using the autotype Ant task.

The source2wsdd Ant task outputs the generated deployment descriptor information into the file 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.

The following example shows how to generate both a web-services.xml file and the WSDL file (called wsdFiles/Temperature.wsdl) that describes a stateless session EJB-implemented Web Service. Because the ejbLink attribute is specified, the javaSource attribute must point to the EJB source file. The source2wsdd Ant task uses the value of the ejbLink attribute as the value of the <ejb-link> child element of the <stateless-ejb> element in the generated web-services.xml file.

Listing 6-2 Source2wsdd build.xml File for an EJB

<source2wsdd 
	javaSource="source/TemperatureService.java" 
	ejbLink="TemperatureService.jar#TemperatureServiceEJB" 
	ddFile="ddfiles/web-services.xml" 
	typesInfo="autotype/types.xml" 
	serviceURI="/TemperatureService" 
	wsdlFile="wsdlFiles/Temperature.wsdl"
/>

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:

Set your environment.

On Windows NT, execute the setEnv.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 setEnv.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.

Create a file called build.xml that contains a call to the autotype Ant task. For details, see the examples later in this section.

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.

The following example shows a simple build.xml file.

Listing 6-3 Autotype build.xml File For a Java Class

<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="output" />
   </target>
</project>

When you run the autotype Ant task using the preceding build.xml file, the 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 information is generated and placed in the 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

Listing 6-4 Autotype build.xml File For Starting with WSDL

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

The preceding 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.

Similarly, if you want to start from an XML Schema file and generate the corresponding Java components, use the schemaFile attribute, as shown in the following example.

Listing 6-5 Autotype build.xml File for Starting with XML Schema

<autotype  schemaFile="file:/schemas/mySchema.xsd"
           targetNamespace="http://www.foobar.com/autotyper"
           packageName="a.package.name"
           destDir="output" />

In the preceding example, the XML Schema in the mySchema.xsd file is copied, without any changes, to the output/types.xml file that contains the data type mapping information.

The following example shows how to both generate non-built-in data type components for newly implemented Java data types, and carry forward already generated components.

Listing 6-6 Autotype build.xml File That Carries Forward Existing Components

<autotype  javaComponents="my.superService"
           typeMappingFile="file:/mapfiles/types.xml"
           targetNamespace="http://www.foobar.com/autotyper"
           packageName="a.package.name"
           destDir="output" />

In the preceding example, it is assumed that you have previously run the autotype Ant task against an XML Schema file and generated the corresponding Java data types and data type mapping file. It is further assumed that you then used these data types to implement a stateless session EJB back-end component, and during that process, you created additional Java data types and want to use the autotype Ant task to generate the corresponding XML Schema. However, you want to preserve the original XML Schema from which you started, and carry it forward into the newly generated types.xml file. The example uses the javaComponents attribute to specify the EJB which has the new Java data types and the typeMappingFile attribute to specify the existing file that contains the XML Schema for data types that you do not want regenerated. The Ant task merges the existing data type mapping information in the file:/mapfiles/types.xml file with the generated information, and writes the result to the output/types.xml file.

Running the clientgen Ant Task

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

Set your environment.

On Windows NT, execute the setEnv.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 setEnv.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.

Create a file called build.xml that contains a call to the clientgen Ant task. For details, see the examples later in this section.

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.

The following example shows a simple build.xml file.

Listing 6-7 Clientgen build.xml File For Generating Client From EAR File

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

When you run the clientgen Ant task using the preceding build.xml file, the Ant task creates the 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 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 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.

Listing 6-8 Clientgen build.xml File For Generating Client From a WSDL File

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

In the example, the clientgen task creates a client JAR file (called 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 new deployable EAR file or to add additional components to an existing EAR file.

To run the wspackage Ant task, follow these steps:

Set your environment.

On Windows NT, execute the setEnv.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 setEnv.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.

Create a file called build.xml that contains a call to the wspackage Ant task. For details, see the examples later in this section.

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.

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

Listing 6-9 Wspackage build.xml File for a Java Class

<project name="buildWebservice" default="package-up">
   <target name="package-up">
      <wspackage
           output="ears/myWebService.ear"
           contextURI="web_services"
           codecDir="autotype"
           webAppClasses="example.ws2j.service.SimpleTest"
           ddFile="ddfiles/web-services.xml" />

</project>

When you run the wspackage Ant task using the preceding build.xml file, the Ant task creates an EAR file called ears/myWebService.ear. The context URI of the Web Service, used in the full URL that invokes it, is web_services. The class file that contains the serialization class for the non-built-in data types is located in the 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 ddfiles/web-services.xml.

The following example shows another build.xml file for adding additional components to an existing EAR file.

Listing 6-10 Wspackage build.xml File For Adding Additional Components to EAR File

<project name="buildWebservice" default="package-up">
   <target name="package-up">
      <wspackage
           output="ears/myWebService.ear"
           overwrite="false"
           filesToEar="myEJB2.jar"
       />
</project>

In the example, the wspackage Ant task adds the file myEJB2.jar to the root directory of the existing EAR file called ears/myWebService.ear. The overwrite attribute is set to false to ensure that none of the existing components in the ears/myWebService.ear file are overwritten; be sure you always do this when using the wspackage Ant task to add additional files to an EAR file.

The following example is similar to the preceding one in that it adds additional components to an existing EAR, but in this case it adds XML Schema files to the root directory of the existing WAR file. You must use the following syntax if you originally used the autotype Ant task to generate non-built-in data type components from an XML Schema file, and this Schema file contains one or more <include> elements to include additional XML Schema files. When you package the final Web Service into an archive, you must manually add both the original and included XML Schema files to the WAR file.

Listing 6-11 Wspackage build.xml File For Adding Schema Files to the WAR File of an EAR

<project name="buildWebservice" default="package-up">
   <target name="package-up">
      <wspackage
           output="ears/myWebService.ear"
           overwrite="false"
           warName="myservice.war"
           filesToWar="original_schema.xsd,included_schema.xsd"
       />
</project>

In the example, the wspackage Ant task adds the XML Schema files original_schema.xsd and included_schema.xsd to the root directory of the existing WAR file called myservice.war, located in the root directory of the EAR file called ears/myWebService.ear.

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.

Figure 6-1 Hierarchy of WebLogic Web Services EAR File

Hierarchy of 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 serialization 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 Supported 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 serialization 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.

For information on the ways that WebLogic Web Services are non-compliant with the JAX-RPC specification with respect to data types, see Data Type Non-Compliance with JAX-RPC.

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 serialization 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:complexType>` with elements of both simple and complex types.	JavaBean
`<xsd:complexType>` with simple content.	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 serialization 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 supported data type.	SOAP Array.
JavaBean whose properties are any supported 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.util.Stack	SOAP Array.
java.util.Collection	SOAP Array.
java.util.Set	SOAP Array.
java.util.HashSet	SOAP Array.
java.util.SortedSet	SOAP Array.
java.util.TreeSet	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>
JAX-RPC-style enumeration class	<xsd:simpleType> with enumeration facets

Data Type Non-Compliance with JAX-RPC

The autotype Ant task does not comply with the JAX-RPC specification if the XML Schema data type (for which it is generating the Java representation) has all the following characteristics:

The data type is a complexType.
The complexType contains a single sequence.
The sequence contains a single element with maxOccurs greater than 1 or unbounded.

The following example shows such an XML Schema data type:

<xsd:complexType name="Response">
    <xsd:sequence > 
        <xsd:element name="code" type="xsd:string" maxOccurs="10" />  
    </xsd:sequence> 
</xsd:complexType>

The autotype Ant task maps this type of XML Schema data type directly to a Java array of the specified element. In the previous example, the autotype Ant task maps the Response XML Schema data type to a java.lang.String[] Java type. This is similar to the type of mapping that .NET does.

The JAX-RPC specification, in turn, states that this type of XML Schema data type should map to a Java array with a pair of setter and getter methods in a JavaBean class. WebLogic Web Services do not follow this last part of the specification.

Non-Roundtripping of Generated Data Type Components

When you use the servicegen or autotype Ant tasks to create the serialization class and Java or XML representation of non-built-in data types, 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 original and generated Java type will not necessarily look exactly the same. For example, 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 serialization 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 serialization 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 serialization class and code from the WebLogic Web Service EAR file, specify the useServerTypes attribute.

Deploying and Testing 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.

You can use the WebLogic Web Services Home Page to test your Web Services, as described in WebLogic Web Services Home Page and WSDL URLs.

WebLogic Web Services Home Page and WSDL URLs

Every Web Service deployed on WebLogic Server has a Home Page. From the Home page you can:

View the WSDL that describes the service.
Test each operation to ensure that it is working correctly.
View the SOAP request and response messages from a successful test of an operation.

Note: You cannot use two-way SSL when testing a Web Service from its Home Page.

The following URLs show first how to invoke the Web Service Home page and then the WSDL in your browser:

[protocol]://[host]:[port]/[contextURI]/[serviceURI]

[protocol]://[host]:[port]/[contextURI]/[serviceURI]?WSDL

where:

protocol refers to the protocol over which the service is invoked, either HTTP or HTTPS. This value corresponds to the protocol attribute of the <web-service> element that describes the Web Service in the web-servicex.xml file. If you used the servicegen Ant task to assemble your Web Service, this value corresponds to the protocol attribute.
host refers to the computer on which WebLogic Server is running.
port refers to the port number on which WebLogic Server is listening (default value is 7001).
contextURI refers to the context root of the Web application, corresponding to the <context-root> element in the application.xml deployment descriptor of the EAR file. If you used the servicegen Ant task to assemble your Web Service, this value corresponds to the contextURI attribute.

If your application.xml file does not include the <context-root> element, then the value of contextURI is the name of the Web application archive file or exploded directory.

serviceURI refers to the URI of the Web Service. This value corresponds to the uri attribute of the <web-service> element in the web-services.xml file. If you used the servicegen Ant task to assemble your Web Service, this value corresponds to the serviceURI attribute.

For example, assume you used the following build.xml file to assemble a WebLogic Web Service using the servicegen Ant task:

<project name="buildWebservice" default="build-ear">
  <target name="build-ear">
      <servicegen
         destEar="myWebService.ear"
         warName="myWAR.war" 
         contextURI="web_services">
         <service
             ejbJar="myEJB.jar"
             targetNamespace="http://www.bea.com/examples/Trader"
             serviceName="TraderService"
             serviceURI="/TraderService"
             generateTypes="True"
             expandMethods="True" >
         </service>
     </servicegen>
  </target>
</project>

The URL to invoke the Web Service Home Page, assuming the service is running on a host called ariel at the default port number, is:

http://ariel:7001/web_services/TraderService

The URL to get the automatically generated WSDL of the Web Service is:

http://ariel:7001/web_services/TraderService?WSDL

Denying Access to the WSDL and Home Page of a WebLogic Web Service

Because the WSDL defines the public contract of a Web Service, you usually want to make it readily available. By default, the WSDL that describes a WebLogic Web Service is always publicly accessible. The WSDL is also accessible from the Web Service's Home Page.

You might, however, sometimes want to turn off public access to the WSDL or the Home Page. To do this, update the appropriate <web-service> element of the web-services.xml deployment descriptor file that describes the WebLogic Web Service, adding the attribute exposeWSDL="False" or exposeHomePage="False", as shown in the following excerpt:

<web-service targetNamespace="http://example.com"
             name="myorderproc"
             uri="myOrderProcessingService"
             exposeWSDL="False"
             exposeHomePage="False">
...
</web-service>

You must redeploy the Web Service after updating its deployment descriptor for the change to take effect.