Programming WebLogic Web Services
The following sections describe how to implement WebLogic Web Services:
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.
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
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.
When you implement a WebLogic Web Service, you write Java code for one of these back-end components:
See Implementing a Web Service By Writing a Stateless Session EJB for information on writing the Java code. For an example, see The EJB Java Interfaces and Implementation Class.
See Implementing a Web Service By Writing a Java Class for information on writing the Java code. For an example, see the WL_HOME/samples/server/examples/src/examples/webservices/basic/javaclass
directory, where WL_HOME
refers to the main WebLogic Platform installation directory:
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.
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:
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.
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.
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.
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:
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 the Web Service, described in Creating the Build File That Specifies the servicegen Ant Task and Running the autotype Ant Task.Warning: The serialization class and Java and XML representations generated by the autotype
and servicegen
Ant tasks cannot be round-tripped. For more information, see Non-Roundtripping of Generated Data Type Components.
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:
getXXX()
and setXXX()
methods for each member variable that you want to expose.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.
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:
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:
web-services.xml
file that describes the Web ServiceThe 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:
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.
To run the wsdl2Service
Ant task, follow these steps:
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.
build.xml
that contains a call to the wsdl2Service
Ant task. For details, see Sample build.xml Files for the wsdl2Service Ant Task. build.xml
file by typing ant
in the same directory as the build.xml
file:prompt> ant
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.
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
.
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.
Depends on the data represented in specific instance of the |
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.
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.
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.
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:
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.
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.
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:
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
.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.
value
, whose data type is the same as that of the parameter.value
field to a default value.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, 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.
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.
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.
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.
For a list of the supported non-built-in Java data types, see Supported Java Non-Built-In Data Types.