6 Examples of Developing JAX-WS Web Services
This chapter includes the following sections:
Each example provides step-by-step procedures for creating simple WebLogic web services and invoking an operation from a deployed web service. The examples include basic Java code and Ant build.xml files that you can use in your own development environment to recreate the example, or by following the instructions to create and run the examples in an environment that is separate from your development environment.
The examples do not go into detail about the processes and tools used in the examples; later chapters are referenced for more detail.
Note:
For best practice examples demonstrating advanced web service features, see Roadmap for Developing JAX-WS Web Service Clients and Roadmap for Developing Reliable Web Services and Clients.
Creating a Simple HelloWorld Web Service
This section describes how to create a very simple web service that contains a single operation. The Java Web Service (JWS) file that implements the web service uses just the one required JWS annotation: @WebService. A JWS file is a standard Java file that uses JWS metadata annotations to specify the shape of the web service. Metadata annotations were introduced with JDK 5.0, and the set of annotations used to annotate web service files are called JWS annotations. WebLogic web services use standard JWS annotations. For a complete list of JWS annotations that are supported, see Web Service Annotation Support in WebLogic Web Services Reference for Oracle WebLogic Server.
The following example shows how to create a web service called HelloWorldService that includes a single operation, sayHelloWorld. For simplicity, the operation returns the inputted String value.
You can use the clean, build-service, undeploy, and deploy targets in the build.xml file to iteratively update, rebuild, undeploy, and redeploy the web service as part of your development process.
To run the web service, you need to create a client that invokes it. See Invoking a Web Service from a WebLogic Web Service for an example of creating a Java client application that invokes a web service.
Sample HelloWorldImpl.java JWS File
package examples.webservices.hello_world;
// Import the @WebService annotation
import javax.jws.WebService;
@WebService(name="HelloWorldPortType", serviceName="HelloWorldService")
/**
* This JWS file forms the basis of simple Java-class implemented WebLogic
* Web Service with a single operation: sayHelloWorld
*/
public class HelloWorldImpl {
// By default, all public methods are exposed as Web Services operation
public String sayHelloWorld(String message) {
try {
System.out.println("sayHelloWorld:" + message);
} catch (Exception ex) { ex.printStackTrace(); }
return "Here is the message: '" + message + "'";
}
}
Sample Ant Build File for HelloWorldImpl.java
The following build.xml file uses properties to simplify the file.
<project name="webservices-hello_world" default="all">
<!-- set global properties for this build -->
<property name="wls.username" value="weblogic" />
<property name="wls.password" value="weblogic" />
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="wls.server.name" value="myserver" />
<property name="ear.deployed.name" value="helloWorldEar" />
<property name="example-output" value="output" />
<property name="ear-dir" value="${example-output}/helloWorldEar" />
<property name="clientclass-dir" value="${example-output}/clientclasses" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all" depends="clean,build-service,deploy,client" />
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}">
<jws file="examples/webservices/hello_world/HelloWorldImpl.java"
type="JAXWS"/>
</jwsc>
</target>
<target name="deploy">
<wldeploy action="deploy" name="${ear.deployed.name}"
source="${ear-dir}" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="undeploy">
<wldeploy action="undeploy" name="${ear.deployed.name}"
failonerror="false"
user="${wls.username}" password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/HelloWorldImpl/HelloWorldService?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.hello_world.client"
type="JAXWS"/>
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/hello_world/client/**/*.java"/>
</target>
<target name="run">
<java classname="examples.webservices.hello_world.client.Main"
fork="true" failonerror="true" >
<classpath refid="client.class.path"/>
<arg
line="http://${wls.hostname}:${wls.port}/HelloWorldImpl/HelloWorldService" />
</java> </target>
</project>
Creating a Web Service With User-Defined Data Types
The preceding example uses only a simple data type, String, as the parameter and return value of the web service operation. This next example shows how to create a web service that uses a user-defined data type, in particular a JavaBean called BasicStruct, as both a parameter and a return value of its operation.
There is actually very little a programmer has to do to use a user-defined data type in a web service, other than to create the Java source of the data type and use it correctly in the JWS file. The jwsc Ant task, when it encounters a user-defined data type in the JWS file, automatically generates all the data binding artifacts needed to convert data between its XML representation (used in the SOAP messages) and its Java representation (used in WebLogic Server).The data binding artifacts include the XML Schema equivalent of the Java user-defined type.
The following procedure is very similar to the procedure in Creating a Simple HelloWorld Web Service. For this reason, although the procedure does show all the needed steps, it provides details only for those steps that differ from the simple HelloWorld example.
To run the web service, you need to create a client that invokes it. See Invoking a Web Service from a WebLogic Web Service for an example of creating a Java client application that invokes a web service.
Sample BasicStruct JavaBean
package examples.webservices.complex;
/**
* Defines a simple JavaBean called BasicStruct that has integer, String,
* and String[] properties
*/
public class BasicStruct {
// Properties
private int intValue;
private String stringValue;
private String[] stringArray;
// Getter and setter methods
public int getIntValue() {
return intValue;
}
public void setIntValue(int intValue) {
this.intValue = intValue;
}
public String getStringValue() {
return stringValue;
}
public void setStringValue(String stringValue) {
this.stringValue = stringValue;
}
public String[] getStringArray() {
return stringArray;
}
public void setStringArray(String[] stringArray) {
this.stringArray = stringArray;
}
public String toString() {
return "IntValue="+intValue+", StringValue="+stringValue;
}
}
Sample ComplexImpl.java JWS File
package examples.webservices.complex;
// Import the standard JWS annotation interfaces
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// Import the BasicStruct JavaBean
import examples.webservices.complex.BasicStruct;
// Standard JWS annotation that specifies that the portType name of the Web
// Service is "ComplexPortType", its public service name is "ComplexService",
// and the targetNamespace used in the generated WSDL is "http://example.org"
@WebService(serviceName="ComplexService", name="ComplexPortType",
targetNamespace="http://example.org")
// Standard JWS annotation that specifies this is a document-literal-wrapped
// Web Service
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
/**
* This JWS file forms the basis of a WebLogic Web Service. The Web Services
* has two public operations:
*
* - echoInt(int)
* - echoComplexType(BasicStruct)
*
* The Web Service is defined as a "document-literal" service, which means
* that the SOAP messages have a single part referencing an XML Schema element
* that defines the entire body.
*/
public class ComplexImpl {
// Standard JWS annotation that specifies that the method should be exposed
// as a public operation. Because the annotation does not include the
// member-value "operationName", the public name of the operation is the
// same as the method name: echoInt.
//
// The WebResult annotation specifies that the name of the result of the
// operation in the generated WSDL is "IntegerOutput", rather than the
// default name "return". The WebParam annotation specifies that the input
// parameter name in the WSDL file is "IntegerInput" rather than the Java
// name of the parameter, "input".
@WebMethod()
@WebResult(name="IntegerOutput",
targetNamespace="http://example.org/complex")
public int echoInt(
@WebParam(name="IntegerInput",
targetNamespace="http://example.org/complex")
int input)
{
System.out.println("echoInt '" + input + "' to you too!");
return input;
}
// Standard JWS annotation to expose method "echoStruct" as a public operation
// called "echoComplexType"
// The WebResult annotation specifies that the name of the result of the
// operation in the generated WSDL is "EchoStructReturnMessage",
// rather than the default name "return".
@WebMethod(operationName="echoComplexType")
@WebResult(name="EchoStructReturnMessage",
targetNamespace="http://example.org/complex")
public BasicStruct echoStruct(BasicStruct struct)
{
System.out.println("echoComplexType called");
return struct;
}
}
Sample Ant Build File for ComplexImpl.java JWS File
The following build.xml file uses properties to simplify the file.
<project name="webservices-complex" default="all">
<!-- set global properties for this build -->
<property name="wls.username" value="weblogic" />
<property name="wls.password" value="weblogic" />
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="wls.server.name" value="myserver" />
<property name="ear.deployed.name" value="complexServiceEAR" />
<property name="example-output" value="output" />
<property name="ear-dir" value="${example-output}/complexServiceEar" />
<property name="clientclass-dir" value="${example-output}/clientclass" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all" depends="clean,build-service,deploy,client"/>
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}"
keepGenerated="true"
>
<jws file="examples/webservices/complex/ComplexImpl.java"
type="JAXWS">
<WLHttpTransport
contextPath="complex" serviceUri="ComplexService"
portName="ComplexServicePort"/>
</jws>
</jwsc>
</target>
<target name="deploy">
<wldeploy action="deploy"
name="${ear.deployed.name}"
source="${ear-dir}" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}"/>
</target>
<target name="undeploy">
<wldeploy action="undeploy" failonerror="false"
name="${ear.deployed.name}"
user="${wls.username}" password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}"/>
</target>
<target name="client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.complex.client"
type="JAXWS"/>
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/complex/client/**/*.java"/>
</target>
<target name="run" >
<java fork="true"
classname="examples.webservices.complex.client.Main"
failonerror="true" >
<classpath refid="client.class.path"/>
<arg line="http://${wls.hostname}:${wls.port}/complex/ComplexService"
/>
</java>
</target>
</project>
Creating a Web Service from a WSDL File
Another common example of creating a web service is to start from an existing WSDL file, often referred to as the golden WSDL. A WSDL file is a public contract that specifies what the web service looks like, such as the list of supported operations, the signature and shape of each operation, the protocols and transports that can be used when invoking the operations, and the XML Schema data types that are used when transporting the data. Based on this WSDL file, you generate the artifacts that implement the web service so that it can be deployed to WebLogic Server. You use the wsdlc Ant task to generate the following artifacts.
-
JWS service endpoint interface (SEI) that implements the web service described by the WSDL file.
-
JWS implementation file that contains a partial (stubbed-out) implementation of the generated JWS SEI. This file must be customized by the developer.
-
JAXB data binding artifacts.
-
Optional Javadocs for the generated JWS SEI.
Note:
The only file generated by the
wsdlcAnt task that you update is the JWS implementation file. You never need to update the JAR file that contains the JWS SEI and data binding artifacts.
Typically, you run the wsdlc Ant task one time to generate a JAR file that contains the generated JWS SEI file and data binding artifacts, then code the generated JWS file that implements the interface, adding the business logic of your web service. In particular, you add Java code to the methods that implement the web service operations so that the operations behave as needed and add additional JWS annotations.
After you have coded the JWS implementation file, you run the jwsc Ant task to generate the deployable web service, using the same steps as described in the preceding sections. The only difference is that you use the compiledWsdl attribute to specify the JAR file (containing the JWS SEI file and data binding artifacts) generated by the wsdlc Ant task.
The following simple example shows how to create a web service from the WSDL file shown in Sample WSDL File. The web service has one operation, getTemp, that returns a temperature when passed a zip code.
You can use the clean, build-service, undeploy, and deploy targets in the build.xml file to iteratively update, rebuild, undeploy, and redeploy the web service as part of your development process.
To run the web service, you need to create a client that invokes it. See Invoking a Web Service from a WebLogic Web Service for an example of creating a Java client application that invokes a web service.
Sample WSDL File
<?xml version="1.0"?>
<definitions
name="TemperatureService"
targetNamespace="http://www.xmethods.net/sd/TemperatureService.wsdl"
xmlns:tns="http://www.xmethods.net/sd/TemperatureService.wsdl"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns="http://schemas.xmlsoap.org/wsdl/" >
<types>
<xsd:schema
targetNamespace="http://www.xmethods.net/sd/TemperatureService.wsdl"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" >
<xsd:element name="getTempRequest">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="zip" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="getTempResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="return" type="xsd:float"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</types>
<message name="getTempRequest">
<part name="parameters" element="tns:getTempRequest"/>
</message>
<message name="getTempResponse">
<part name="parameters" element="tns:getTempResponse"/>
</message>
<portType name="TemperaturePortType">
<operation name="getTemp">
<input message="tns:getTempRequest"/>
<output message="tns:getTempResponse"/>
</operation>
</portType>
<binding name="TemperatureBinding" type="tns:TemperaturePortType">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="getTemp">
<soap:operation soapAction=""/>
<input>
<soap:body use="literal"/>
</input>
<output>
<soap:body use="literal"/>
</output>
</operation>
</binding>
<service name="TemperatureService">
<documentation>
Returns current temperature in a given U.S. zipcode
</documentation>
<port name="TemperaturePort" binding="tns:TemperatureBinding">
<soap:address
location="http://localhost:7001/temp/TemperatureService"/>
</port>
</service>
</definitions>
Sample TemperatureService_TemperaturePortImpl Java Implementation File
package examples.webservices.wsdlc;
import javax.jws.WebService;
import javax.xml.ws.BindingType;
/**
* Returns current temperature in a given U.S. zipcode
* This class was generated by the JAX-WS RI.
* JAX-WS RI 2.2.8-b13684
* Generated source version: 2.2
*
*/
@WebService(
portName = "TemperaturePort",
serviceName = "TemperatureService",
targetNamespace="http://www.xmethods.net/sd/TemperatureService.wsdl"
wsdlLocation = "/wsdls/TemperatureService.wsdl",
endpointInterface = "examples.webservices.wsdlc.TemperaturePortType")
@BindingType("http://schemas.xmlsoap.org/wsdl/soap/http")
public class TemperatureService_TemperaturePortImpl implements
TemperaturePortType
{
public TemperatureService_TemperaturePortImpl() { }
/**
*
* @param zip
* @return
* returns float
*/
public float getTemp(String zip) {
return 1.234f;
}
}
Sample Ant Build File for TemperatureService
The following build.xml file uses properties to simplify the file.
<project default="all">
<!-- set global properties for this build -->
<property name="wls.username" value="weblogic" />
<property name="wls.password" value="weblogic" />
<property name="wls.hostname" value="localhost" />
<property name="wls.port" value="7001" />
<property name="wls.server.name" value="myserver" />
<property name="ear.deployed.name" value="wsdlcEar" />
<property name="example-output" value="output" />
<property name="compiledWsdl-dir" value="${example-output}/compiledWsdl" />
<property name="impl-dir" value="${example-output}/impl" />
<property name="ear-dir" value="${example-output}/wsdlcEar" />
<property name="clientclass-dir" value="${example-output}/clientclasses" />
<path id="client.class.path">
<pathelement path="${clientclass-dir}"/>
<pathelement path="${java.class.path}"/>
</path>
<taskdef name="wsdlc"
classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all"
depends="clean,generate-from-wsdl,build-service,deploy,client" />
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="generate-from-wsdl">
<wsdlc
srcWsdl="wsdl_files/TemperatureService.wsdl"
destJwsDir="${compiledWsdl-dir}"
destImplDir="${impl-dir}"
packageName="examples.webservices.wsdlc"
type="JAXWS"/>
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}">
<jws
file="examples/webservices/wsdlc/TemperatureService_TemperaturePortImpl.java"
compiledWsdl="${compiledWsdl-dir}/TemperatureService_wsdl.jar"
type="JAXWS">
<WLHttpTransport
contextPath="temp" serviceUri="TemperatureService"
portName="TemperaturePort"/>
</jws>
</jwsc>
</target>
<target name="deploy">
<wldeploy action="deploy" name="${ear.deployed.name}"
source="${ear-dir}" user="${wls.username}"
password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="undeploy">
<wldeploy action="undeploy" name="${ear.deployed.name}"
failonerror="false"
user="${wls.username}" password="${wls.password}" verbose="true"
adminurl="t3://${wls.hostname}:${wls.port}"
targets="${wls.server.name}" />
</target>
<target name="client">
<clientgen
wsdl="http://${wls.hostname}:${wls.port}/temp/TemperatureService?WSDL"
destDir="${clientclass-dir}"
packageName="examples.webservices.wsdlc.client"
type="JAXWS">
<javac
srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
includes="**/*.java"/>
<javac
srcdir="src" destdir="${clientclass-dir}"
includes="examples/webservices/wsdlc/client/**/*.java"/>
</target>
<target name="run">
<java classname="examples.webservices.wsdlc.client.TemperatureClient"
fork="true" failonerror="true" >
<classpath refid="client.class.path"/>
<arg
line="http://${wls.hostname}:${wls.port}/temp/TemperatureService" />
</java>
</target>
</project>