|
 |
| e-docs > WebLogic Server > Programming WebLogic Web Services > Implementing WebLogic Web Services |
|
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 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.
Writing the Java Code for the Components
When you implement a WebLogic Web service, you write Java code for one of these backend components:
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.
See Implementing a Web Service By Writing a Java Class for information on writing the Java code.
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:
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.
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:
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:
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.
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:
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:
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:
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.
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:
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.
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
}
}
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.
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.
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.
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||