Skip navigation.

Programming WebLogic Web Services

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

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, optionally generate an empty implementation Java class file, then write the business-logic code for the Java implementation class 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. See Writing the Java Code for the Components.

  3. 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.
  4. See Creating SOAP Message Handlers to Intercept the SOAP Message.

  5. 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.
  6. See Implementing Non-Built-In Data Types.

  7. Compile the Java code into class files. For details, see Compiling Java Code.

 


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, and optional implementation, 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:

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:

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

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:

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 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. You can generate a skeleton of the implementation class by specifying the generateImpl="True" attribute; add the business logic Java code to this class to complete the implementation.

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:

packageName.serviceNameImpl

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.

If you name your Java implementation class differently, you must 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.
  2. 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.

  3. 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.
  4. Execute the Ant task or tasks specified in the build.xml file by typing ant in the same directory as the build.xml file:
  5. prompt> ant
  6. 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.

Table 5-1 Mapping Java Data Types to MIME Types

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, you must 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, you must 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

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

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.

Table 5-2 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:

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, you must 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 class 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.soap.SOAPException;
import javax.xml.namespace.QName;
import javax.xml.rpc.soap.SOAPFaultException;
public class HelloWorldService{
  public void helloSOAPFault(){
    Detail detail = null; 
    try{
detail = SOAPFactory.newInstance().createDetail();
detail.addChildElement( "MyDetails" ).addTextNode( "failed" );
}catch( SOAPException e ){
e.printStackTrace();
}
    throw new SOAPFaultException( 
new QName( "http://tutorial/sample9/fault", "ServerFailed" ),
"helloSOAPFault method failed",
"http://foo/bar/baz/",
detail );
}
  public void helloCustomFault() throws HelloWorldException{
throw new HelloWorldException( "This is my error message, " +
"client should get this" );
}
}

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 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-3 Mapping XML Schema Data Types to Java 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-4 Mapping Java Data Types to XML Schema 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