bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic Web Services

Implementing WebLogic Web Services

The following sections describe how to implement WebLogic Web services:

- Overview of Implementing a WebLogic Web Service

- Implementing a WebLogic Web Service: Main Steps

- Writing the Java Code for the Components

- Using Built-In Data Types

Overview of Implementing a WebLogic Web Service

Implementing a WebLogic Web service refers to writing the Java code for the backend components that make up the Web service and optionally creating SOAP message handlers. Backend components include stateless session EJBs, Java classes, and JMS message consumers and producers. A Web service can be implemented with multiple combinations of these components.

A single WebLogic Web service consists of one or more operations; you can implement each operation using methods of different backend components and SOAP message handlers. For example, an operation might be implemented with a single method of a stateless session EJB or with a combination of SOAP message handlers and a method of a stateless session EJB.

If you are implementing a WebLogic Web service from an existing WSDL file, you can use the WebLogic Server wsdl2Service Ant task to generate much of the needed Java source code. You can use this generated file as a starting point, then add the rest of the Java code needed to make the Web service behave as you want.

It is assumed that you have read and understood the design issues discussed in Designing WebLogic Web Services, designed your Web service and that you know the types of components you need to create.

Implementing a WebLogic Web Service: Main Steps

The following procedure describes the high-level steps to implement a WebLogic Web service. Later parts of this document describe the steps in more detail. Although some of the steps are mandatory, others are optional, depending on the type of Web service you are implementing.

1. Write the Java code for the back-end components that make up the Web service.

   See Writing the Java Code for the Components.

2. If you need to process information in the SOAP request or response or access the SOAP attachments, create SOAP message handlers and handler chains.

   See Creating SOAP Message Handlers to Intercept the SOAP Message.

3. If your backend components use non-built-in data types as parameters or return values, generate or create the serialization class that converts the data between XML and Java.

   See Implementing Non-Built-In Data Types.

Writing the Java Code for the Components

When you implement a WebLogic Web service, you write Java code for one of these backend components:

- A stateless session EJB.

  See Implementing a Web Service By Writing a Stateless Session EJB for information on writing the Java code. For an example, see Writing the Java Code for the EJB.

- A Java class.

  See Implementing a Web Service By Writing a Java Class for information on writing the Java code.

- A JMS message consumer or producer, typically a message-driven bean.

  See Creating JMS-Implemented WebLogic Web Services.

If your Web service operations use non-built-in data types as parameters or return values, see Implementing Non-Built-In Data Types.

If you are implementing a Web service that uses document-oriented operations, rather than RPC-oriented, see Implementing a Document-Oriented Web Service.

If you are implementing a WebLogic Web service based on an existing WSDL file, and you want to implement the Web service with a Java class, use the WebLogic Server wsdl2Service Ant task to generate much of the needed Java code. For details about using this Ant task, see Generating a Partial Implementation From a WSDL File.

For information on throwing exceptions from your Web service implementation, see Throwing SOAP Fault Exceptions.

If you want your Web service operation to return multiple values, see Implementing Multiple Return Values.

Implementing a Web Service By Writing a Stateless Session EJB

Writing the Java code for the stateless session EJB for a Web service is no different from writing a stand-alone EJB, except for the following issues:

- You can specify in the web-services.xml deployment descriptor that a Web service operation is one-way, which means that the client application that invokes the Web service does not wait for a response. When you write the Java code for the EJB method that implements this type of operation, you must specify that it return void.

  For more information on specifying in the web-services.xml file that a Web service operation is one-way, see "operation" on page A-8.

- If the data type of the parameters or return value of an EJB method are not part of the set of built-in data types, then you must generate or create the serialization class that converts these data types between their XML and Java representations. For the list of built-in data types, see Using Built-In Data Types

  See Implementing Non-Built-In Data Types.

For an example of how to write a stateless session EJB, see Writing the Java Code for the EJB. For general information, see Programming WebLogic Enterprise JavaBeans.

Implementing a Web Service By Writing a Java Class

You can implement a Web service operation using a Java class as long as you follow these rules:

- Do not start any threads. This rule applies to all Java code that runs on WebLogic Server.

- Define a default no-argument constructor.

- Define as public the methods of the Java class that are going to be exposed as Web service operations.

- Write thread safe Java code, because WebLogic Server maintains just a single instance of a Java class that implements a Web service operation, and each invoke of the Web service uses this same instance.

For an example of implementing a WebLogic Web service operation with a Java class, go to the WL_HOME\samples\server\src\examples\webservices\basic\javaclass directory, where WL_HOME refers to the main directory of your WebLogic Server installation.

Implementing Non-Built-In Data Types

Stateless session EJBs or Java classes do not necessarily take built-in data types as parameters and return values, but rather, might use a Java data type that you create yourself. An example of a non-built-in data type is TradeResult, which has two fields: a String stock symbol and an integer number of shares traded. For the list of built-in data types, see Using Built-In Data Types.

If your backend components use non-built-in data types as parameters or return values, you must generate or create the serialization class that converts the data between XML and Java.You can do this in one of two ways:

- Use WebLogic Server servicegen or autotype Ant tasks to introspect your EJB and automatically generate the serialization class. These Ant tasks also create the corresponding XML Schema to represent your data in XML format and update your web-services.xml deployment descriptor file with the relevant data type mapping information. You will run these Ant tasks as part of assembling of the Web service, described in Running the servicegen Ant Task and Running the autotype Ant Task.

  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.

- Create the serialization class and XML and Java representations of your data type manually. This method is more complex and time-consuming than generating them using the Ant task. For details on handling non-built-in data types manually, see Using Non-Built-In Data Types.

If you are going to create the XML representation of your Java data type manually, along with the serialization class, you can code the Java class any way you want, because you will be writing all the conversion code yourself.

If you are going to use the servicegen or autotype Ant tasks to automatically generate the data type components, follow these requirements when writing the Java class for your data type:

- Define a default constructor, which is a constructor that takes no parameters.

- Define both getXXX() and setXXX() methods for each member variable which you want to expose.

- Make the data type of each exposed member variable one of the built-in data types, or a non-built-in data type that consists of built-in data types and has the corresponding serialization class and XML Schema representation.

The servicegen and autotype Ant tasks can generate data type components for most common XML and Java data types. For the list of supported non-built-in data types, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks.

Implementing a Document-Oriented Web Service

When creating a WebLogic Web service, you can specify whether the Web service is document-oriented (the SOAP message contains a document) or RPC-oriented (the SOAP message contains parameters and return values).

If you create a document-oriented Web service:

- the methods that implement each operation of the Web service can have only one parameter. This single parameter can be of any supported data type; see Data Types for more information.

- the methods that implement each operation cannot use out and in-out parameters.

Generating a Partial Implementation From a WSDL File

The wsdl2Service Ant task takes as input an existing WSDL file, and generates a Java source file that partially implements the Web service.

The Java source file contains a template for the full Java class-implemented WebLogic Web service. The template includes full method signatures that correspond to the operations in the WSDL file. You write the actual code for these methods so that they function as you want, following the guidelines in Implementing a Web Service By Writing a Java Class.

The wsdl2Service Ant task generates a partial implementation for only one Web service in a WSDL file (specified by the <service> element.) Use the serviceName attribute to specify a particular service; if you do not specify this attribute, the wsdl2Service Ant task generates a partial implementation for the first <service> element in the WSDL.

Running the wsdl2Service Ant Task

To run the wsdl2Service Ant task, follow these steps:

1. Create a file called build.xml that contains a call to the wsdl2Service Ant task. For details, see Sample build.xml Files for the wsdl2Service Ant Task.

2. Set your environment.

   On Windows NT, execute the setWLSEnv.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 setWLSEnv.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 wsdl2Service Ant task, see wsdl2Service.

Sample build.xml Files for the wsdl2Service Ant Task

The following example shows a simple build.xml file:

>     <project name="buildWebservice" default="generate-from-WSDL">
>        <target name="generate-from-WSDL">
>           <wsdl2service
>                wsdl="c:\wsdls\myService.wsdl"
>                destDir="c:\myService\implementation"
>                typeMappingFile="c:\autotype\types.xml"
>                packageName="example.ws2j.service" />
>        </target>
>     </project>

In the example, the wsdl2Service Ant task generates a Java source file for the first <service> element it finds in the WSDL file c:\wsdls\myService.wsdl. It uses data type mapping information for any non-built-in data types from the c:\autotype\types.xml file; typically you have previously run the autotype Ant task to generate this file. The generated Java source file is in the package example.ws2j.service.

Implementing Multiple Return Values

WebLogic Web service operations typically return a single value: the return value of the EJB or Java class method that implements the Web service operation. If you want a Web service operation to return multiple values, you can:

- define the data type of the return value to be a complex type, such as an object with multiple parts or an array.

- specify that one or more of the parameters of the Web service operation be out or in-out parameters.

Out and in-out parameters are a mechanism whereby parameters to an operation can act as both standard in parameters and return values. The Out parameters are undefined when the operation is invoked but defined by the method that implements the operation when the operation completes; in-out parameters are defined when invoked and when completed. For example, assume a Web service operation contains one out parameter, and the operation is implemented with an EJB method. The EJB method sets the value of the out parameter and sends this value back to the client application that invoked it. The client application can then access the value of this out parameter as if it were a return value. An in-out parameter is one that acts as both a standard input parameter for sending information to the method and an out parameter. This section discusses how to implement a Web service operation with an EJB or Java class method that uses out or in-out parameters.

The following example shows a method whose second parameter is an in-out parameter:

>     public String myMethod( String param1,
>             javax.xml.rpc.holders.IntHolder intHolder ) {

>     System.out.println ("The input value is: " + intHolder.value );
>     intHolder.value = 20;  // the new value of the out parameter

>     return param1;
>     }

You invoke the method with two parameters, a String and an integer. The method returns two values: a String (the standard return value) and an integer (via the IntHolder holder parameter).

Out and in-out parameters must implement the javax.xml.rpc.holders.Holder interface. Use the Holder.value field to first access the input value of an in-out parameter and then set the value of out and in-out parameters. In the preceding example, assume the method was invoked with a value of 40 as the second parameter; when the method completes, the value of intHolder is now 20.

Using Holder Classes to Implement Multiple Return Values

If the out or in-out parameter is a standard data type, you can use one of the JAX-RPC Holder classes, listed in the following table.

Table 5-1 Built-In Holder Classes Provided by WebLogic Server

Built-In Holder Class | Java Data Type That It Holds
--- | ---
javax.xml.rpc.holders.BooleanHolder | boolean
javax.xml.rpc.holders.ByteHolder | byte
javax.xml.rpc.holders.ShortHolder | short
javax.xml.rpc.holders.IntHolder | int
javax.xml.rpc.holders.LongHolder | long
javax.xml.rpc.holders.FloatHolder | float
javax.xml.rpc.holders.DoubleHolder | double
javax.xml.rpc.holders.BigDecimalHolder | java.math.BigDecimal
javax.xml.rpc.holders.BigIntegerHolder | java.math.BigInteger
javax.xml.rpc.holders.ByteArrayHolder | byte[]
javax.xml.rpc.holders.CalendarHolder | java.util.Calendar
javax.xml.rpc.holders.QnameHolder | javax.xml.namespace.QName
javax.xml.rpc.holders.StringHolder | java.lang.String

If, however, the data type of the parameter is not provided, you must create your own implementation.

To create your own implementation of the javax.xml.rpc.holders.Holder interface, follow these guidelines:

- Name your implementation class Type Holder, where Type is the name of the complex type. For example, if your complex type is called Person, then your implementation class is called PersonHolder.

- The Holder implementation class should be packaged in a holders sub-package below the package of the class it is holding.

  For example, if your complex type Person is in the examples.webservices package, then the PersonHolder implementation class should be in the examples.webservices.holders package.

- Create a public field called value, whose data type is the same as that of the parameter.

- Create a default constructor that initializes the value field to a default value.

- Create a constructor that sets the value field to the value of the passed parameter.

The following example shows the outline of a PersonHolder implementation class:

>     package examples.webservices.holders;

>     public final class PersonHolder implements
>                 javax.xml.rpc.holders.Holder {

>        public Person value;

>        public PersonHolder() {

>            // set the value variable to a default value
>        }

>        public PersonHolder (Person value) {

>            // set the value variable to the passed in value
>        }

>     }

Throwing SOAP Fault Exceptions

If you throw a javax.xml.rpc.soap.SOAPFaultException exception in your stateless session EJB or Java class, WebLogic Server maps it to a SOAP fault and sends it to the client application that invokes the operation.

The following excerpt describes the SOAPFaultException class:

>     public class SOAPFaultException extends java.lang.RuntimeException {
>         public SOAPFaultException (QName faultcode,
>                                    String faultstring,
>                                    String faultactor,
>                                    javax.xml.soap.Detail detail ) {...}
>         public Qname getFaultCode() {...}
>         public String getFaultString() {...}
>         public String getFaultActor() {...}
>         public javax.xml.soap.Detail getDetail() {...}
>     }

If your EJB or Java class throws any other type of Java exception, WebLogic Server tries to map it to a SOAP fault as best it can. However, to ensure that the client application receives the best possible exception information, you should explicitly throw a SOAPFaultException exception or one that extends the exception.

Use the weblogic.webservice.util.FaultUtil.newDetail() WebLogic Web Service API to create the javax.xml.soap.Detail object, which is a JAX-RPC container for DetailEntry objects that provide detailed application-specific information about the error. You can use the javax.xml.soap.Detail.addDetailEntry() method to add a DetailEntry to the Detail object.

The following excerpt shows an example of creating and throwing a SOAPFaultException from within the implementation of your Web Service:

>         throw new SOAPFaultException(
>             new QName( "http://schemas.xmlsoap.org/soap/envelope/", "Server" ),
>             "info on the fault",
>             "info on the actor",
>             weblogic.webservice.util.FaultUtil.newDetail() );
>       }

Warning: If you create and throw your own exception (rather than use SOAPFaultException) and two or more of the properties of your exception class are of the same data type, then you must also create setter methods for these properties, even though the JAX-RPC specification does not require it. This is because when a WebLogic Web Service receives the exception in a SOAP message and converts the XML into the Java exception class, there is no way of knowing which XML element maps to which class property without the corresponding setter methods.

Using Built-In Data Types

The following sections describe the built-in data types supported by WebLogic Web services and the mapping between their XML and Java representations. As long as the data types of the parameters and return values of the backend components that implement your Web service are in the set of built-in data types, WebLogic Server automatically converts the data between XML and Java.

If, however, you use non-built-in data types, then you must create the serialization class to convert the data between XML and Java. WebLogic Server includes the servicegen and autotype Ant tasks that can generate the serialization class for most non-built-in data types. See Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks for a list of supported XML and Java data types. For more information about using servicegen and autotype, see Assembling WebLogic Web Services Using Ant Tasks.

If your data type is not supported, then you must create your serialization class manually. For details, see Using Non-Built-In Data Types.

XML Schema-to-Java Mapping for Built-In Data Types

The following table lists the defined mappings for all built-in data types defined by XML Schema (target namespace http://www.w3.org/2001/XMLSchema) and the corresponding SOAP data types (target namespace http://schemas.xmlsoap.org/soap/encoding/).

For a list of the supported non-built-in XML data types, see Supported XML Non-Built-In Data Types.

Table 5-2 XML Schema-to-Java Mapping for Built-In Data Types

XML Schema Data Type | Equivalent Java Data Type (lower case indicates a primitive data type)
--- | ---
boolean | boolean
byte | byte
short | short
int | int
long | long
float | float
double | double
integer | java.math.BigInteger
decimal | java.math.BigDecimal
string | java.lang.String
dateTime | java.util.Calendar
base64Binary | byte[]
hexBinary | byte[]
duration | weblogic.xml.schema.binding.util.Duration
time | java.util.Calendar
date | java.util.Calendar
gYearMonth | java.util.Calendar The java.util.Calendar Java data type contains more fields than the gYearMonth data type. This additional information is not meaningful and is not generated from the actual XML data, but rather created by the data binding facility.
gYear | java.util.Calendar The java.util.Calendar Java data type contains more fields than the gYearMonth data type. This additional information is not meaningful and is not generated from the actual XML data, but rather created by the data binding facility.
gMonthDay | java.util.Calendar The java.util.Calendar Java data type contains more fields than the gYearMonth data type. This additional information is not meaningful and is not generated from the actual XML data, but rather created by the data binding facility.
gDay | java.util.Calendar The java.util.Calendar Java data type contains more fields than the gYearMonth data type. This additional information is not meaningful and is not generated from the actual XML data, but rather created by the data binding facility.
gMonth | java.util.Calendar The java.util.Calendar Java data type contains more fields than the gYearMonth data type. This additional information is not meaningful and is not generated from the actual XML data, but rather created by the data binding facility.
anyURI | java.lang.String
NOTATION | java.lang.String
token | java.lang.String
normalizedString | java.lang.String
language | java.lang.String
Name | java.lang.String
NMTOKEN | java.lang.String
NCName | java.lang.String
NMTOKENS | java.lang.String[]
ID | java.lang.String
IDREF | java.lang.String
ENTITY | java.lang.String
IDREFS | java.lang.String[]
ENTITIES | java.lang.String[]
nonPositiveInteger | java.math.BigInteger
nonNegativeInteger | java.math.BigInteger
negativeInteger | java.math.BigInteger
unsignedLong | java.math.BigInteger
positiveInteger | java.math.BigInteger
unsignedInt | long
unsignedShort | int
unsignedByte | short
Qname | javax.xml.namespace.QName

Java-to-XML Mapping for Built-In Data Types

For a list of the supported non-built-in Java data types, see Supported Java Non-Built-In Data Types.

Table 5-3 Java-to-XML Mapping for Built-In Data Types

Java Data Type (lower case indicates a primitive data type) | Equivalent XML Data Type
--- | ---
int | int
short | short
long | long
float | float
double | double
byte | byte
boolean | boolean
char | string (with facet of length=1)
java.lang.Integer | int
java.lang.Short | short
java.lang.Long | long
java.lang.Float | float
java.lang.Double | double
java.lang.Byte | byte
java.lang.Boolean | boolean
java.lang.Character | string (with facet of length=1)
java.lang.String | string
java.math.BigInteger | integer
java.math.BigDecimal | decimal
java.lang.String | string
java.util.Calendar | dateTime
java.util.Date | dateTime
byte[] | base64Binary
weblogic.xml.schema.binding.util.Duration | duration
javax.xml.namespace.QName | Qname