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 refers to writing and compiling the Java code for the back-end components that make up the Web Service and, if necessary, creating SOAP message handlers and Java code for the non-built-in data types. Back-end components include stateless session EJBs and Java classes. 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 back-end 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 automatically generate the Java interface that represents your Web Service, then write the code for the Java implementation class that implements this generated Web Service interface 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.

Note: BEA recommends that you implement your Web Service operation with only a stateless session EJB or a Java class, and not with a JMS consumer or producer. In most of the book, it is assumed that your Web Service is implemented with either an EJB or a Java class. All JMS-specific information is in its own chapter: Creating JMS-Implemented WebLogic Web Services.

 

Examples of Implementing WebLogic Web Services

WebLogic Server includes examples of implementing 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

 

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.

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

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

  4. Compile the Java code into class files.

 

Writing the Java Code for the Components

When you implement a WebLogic Web Service, you write Java code for one of these back-end components:

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 the default 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 the Web Service interface class to use as a starting point. For details about using this Ant task, see Generating a Partial Implementation From a WSDL File.

For information about using SOAP Attachments, see Using SOAP Attachments.

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, with these exceptions:

  • 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.

  • 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 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 Supported Built-In Data Types.

    See Implementing Non-Built-In Data Types.

For an example of how to write a stateless session EJB, see The EJB Java Interfaces and Implementation Class. 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 only a single instance of a Java class that implements a Web Service operation, and each invoke of the Web Service uses this same instance.

Although it is not required, your Java class can extend the JAX-RPC javax.xml.rpc.server.ServiceLifecycle interface, which defines the life cycle for the Web Service endpoint. However, because this version of WebLogic Server does not support servlets as back-end components of WebLogic Web Services, BEA does not provide an implementation of the javax.xml.rpc.server.ServletEndpointContext interface. This means that if your Java class extends the ServiceLifecycle interface, its init() method is passed null rather than an instance of ServletEndpointContext.

For an example of implementing a WebLogic Web Service operation with a Java class, go to the WL_HOME/samples/server/examples/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 and 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 Supported Built-In Data Types.

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

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 generate the data type components automatically, 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 that 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

WebLogic Web Services can be either document-oriented (the SOAP message contains a document) or RPC-oriented (the SOAP message contains parameters and return values). By default, WebLogic Web Services are RPC-oriented. You specify that a Web Service is document-oriented when you assemble it using the servicegen Ant task.

The procedures in this chapter assume that you are creating an RPC-oriented Web Service. If, however, you are creating a document-oriented Web Service, follow these additional guidelines when implementing the back-end component:

  • 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 Using Built-In and Non-Built-In 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

It is assumed in most of this chapter that you are implementing a Web Service by writing the back-end component first. Sometimes, however, you might need to start with an existing WSDL from which you create the implementation. For example, your company might include a corporate architecture group that defines common service descriptions, specifically WSDL files, that must be implemented by different departments. In this case you can use the wsdl2Service Ant task to generate a partial implementation.

The wsdl2Service Ant task takes as input an existing WSDL file and generates:

  • the Java interface that represents the implementation of your Web Service

  • the web-services.xml file that describes the Web Service

The generated Java interface file describes the 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 must then write a Java class that implements this interface so that the methods function as you want, following the guidelines in Implementing a Web Service By Writing a Java Class.

The wsdl2Service Ant task generates a Java interface 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 Java interface for the first <service> element in the WSDL.

Warning: The wsdl2Service Ant task, when generating the web-services.xml file for your Web Service, assumes you use the following convention when naming the Java class that implements the generated Java interface:

Warning: packageName.serviceNameImpl

Warning: where packageName and serviceName are the values of the similarly-named attributes of the wsdl2Service Ant task. The Ant task puts this information in the class-name attribute of the <java-class> element of the web-services.xml file.

Warning: If you name your Java implementation class differently, manually update the generated web-services.xml file accordingly.

 

Running the wsdl2Service Ant Task

To run the wsdl2Service Ant task, follow these steps:

  1. 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.

  2. 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.

  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

  4. Create a Java class implementation for the interface generated in the myService/implementation directory. For details, see Implementing a Web Service By Writing a Java Class.

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="wsdls/myService.wsdl"


         destDir="myService/implementation"


         typeMappingFile="autotype/types.xml"


         packageName="example.ws2j.service" />


 </target>



</project>

In the example, the wsdl2Service Ant task generates a Java interface file for the first <service> element it finds in the WSDL file wsdls/myService.wsdl. It uses data type mapping information for any non-built-in data types from the autotype/types.xml file; typically you have previously run the autotype Ant task to generate this file. The Java interface file and web-services.xml file are generated into the directory myService/implementation.

Assume that value of the name attribute of the first <service> element in the WSDL file is SuperDooperService. The wsdl2Service generates a Java interface called example.ws2j.service.SuperDooperService and assumes that your Java implementation class will be example.ws2j.service.SuperDooperServiceImpl.

 

Using SOAP Attachments

Certain Java data types, if used as parameters or return values of a method that implements a Web Service operation, are automatically transported as SOAP Attachments (rather than elements in the SOAP body) when going over the wire. The following table lists the Java data types and their corresponding MIME type in the SOAP Attachment.

Java Data Type

MIME Type

java.awt.Image image/gif or image/jpeg
java.lang.String text/plain
javax.mail.internet.MimeMultipart multipart/*
javax.xml.transform.Source text/xml or application.xml
javax.activation.DataHandler Depends on the data represented in specific instance of the DataHandler.

If you code the method of the Java class or EJB to use one of the preceding Java data types as a parameter or return value and then use servicegen to assemble the Web Service, the generated web-services.xml deployment descriptor file automatically specifies that the actual data of the parameter or return value is in the SOAP attachment. In particular, the location attribute of the <param> or <return-param> is set equal to attachment. When a client application invokes the Web Service, the WebLogic Web Services runtime automatically looks for the parameter data in the attachment to the SOAP request, or adds the return value data to the attachment in the SOAP response, depending on whether it is the parameter or return value or both that is one of the Java data types listed in the preceding table.

If you want to access and manipulate the SOAP attachment directly, create a SOAP message handler and use the SOAP with Attachments API for Java 1.1 (SAAJ). For details, see Creating SOAP Message Handlers to Intercept the SOAP Message.

 

java.lang.String

The Java data type java.lang.String works a little differently than what is described in the preceding section. By default, if you use java.lang.String in the method that implements a Web Service operation, the servicegen Ant tasks and the WebLogic Web Services runtime treat it as a built-in data type. This means that the data will be part of the SOAP body as an XML Schema string type rather than a text/plain MIME type in a SOAP attachment.

If, however, you want the java.lang.String parameter or return value to be transported as a text/plain MIME encoded SOAP attachment, manually update the web-services.xml deployment descriptor file and change the value of the location attribute of the corresponding <param> or <return-value> element from the default Body to attachment.

For more information on the attributes and elements of the web-services.xml file, see WebLogic Web Service Deployment Descriptor Elements.

 

javax.activation.DataHandler

Use the javax.activation.DataHandler data type to represent data in a SOAP attachment that is not listed in the table in Using SOAP Attachments.

The DataHandler class provides a consistent interface to data available in many different sources and formats. It manages simple stream to string conversions and related operations using javax.activation.DataContentHandlers. The DataHandler class also provides access to commands that can operate on the data. The commands are found using a javax.activation.CommandMap class.

DataHandlers are part of the J2EE JavaBeans Activation Framework standard extension. It is assumed that if you use a DataHandler as a parameter or return type of a WebLogic Web Service operation, you have implemented all the needed components, such as the DataContentHandler.

For general information about DataHandlers and how to implement them, see JavaBeans Activation Framework. See the Javadoc for a description of the JavaBeans Activation Framework APIs.

 

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

  • Define the data type of the return value to be a complex non-built-in type, such as an object with multiple parts or an array. For details about implementing these data types, see Implementing Non-Built-In Data Types.

  • Specify that one or more of the parameters of the Web Service operation be out or in-out parameters. This section describes how to create these types of parameters.

 

Using Out and 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. Out parameters are undefined when the operation is invoked, but are 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, use one of the JAX-RPC Holder classes, listed in the following table.

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, create your own implementation.

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

  • Name your implementation class TypeHolder, 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


 }

}

After you have created the Holder implementation class for your out or in-out parameter, update the Java code for the method that implements your Web Service operation to use this Holder class. When you later use the servicegen Ant task to assemble your Web Service, the generated web-services.xml file will automatically specify that the parameter is an in-out parameter, as shown in the following excerpt: 

<param name="inoutparam" style="inout" 


     type="xsd:Person" />

If you want the parameter to be an out, rather than in-out, parameter, update the generated web-services.xml file manually.

For details about writing a client application that invokes a Web Services that uses out or in-out parameters, see Writing a Client That Uses Out or In-Out Parameters.

 

Throwing SOAP Fault Exceptions

When you write the error-handling Java code for the EJB or Java class that implements your WebLogic Web Service, you can either throw your own exceptions or throw a javax.xml.rpc.soap.SOAPFaultException exception. If you throw a SOAPFaultException, WebLogic Server maps it to a SOAP fault and sends it to the client application that invokes the operation.

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, if you want to control what the client application receives and send it the best possible exception information, you should explicitly throw a SOAPFaultException exception or one that extends the exception.

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() {...}



}

Use the SOAP with Attachments API for Java 1.1 (SAAJ) javax.xml.soap.SOAPFactory.createDetail() method to create the Detail object, which is a container for DetailEntry objects that provide detailed application-specific information about the error.

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

import javax.xml.soap.SOAPFactory; 



import javax.xml.soap.Detail; 

import javax.xml.namespace.QName; 



import javax.xml.rpc.soap.SOAPFaultException; 

...

   Detail detail = null; 


 detail = SOAPFactory.newInstance().createDetail(); 


 detail.addChildElement( "MyDetails" ).addTextNode( "failed" ); 

   throw new SOAPFaultException( 


      new QName( "http://tutorial/sample9/fault";, "ServerFailed" ), 


      "helloSOAPFault method failed", 


       null, 


       detail );

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.

 

Supported 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 back-end 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 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 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.

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.CalendarThe 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.CalendarThe 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.CalendarThe 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.CalendarThe 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.CalendarThe 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.

Java Data Type (lower case indicates a primitive data type)

Equivalent XML Schema 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

Skip navigation bar  Back to Top Previous Next