Creating a Web Service Using JWS Metadata Annotations

Files Prepare Run Troubleshooting Related Topics

About the Example

This example shows how to create a simple WebLogic Web Service using JWS metadata annotations.

Metadata annotations are a new J2SE 5.0 feature that provides the ability to associate additional data alongside Java classes, interfaces, methods, and fields. The set of annotations used to annotate Web Service files are called JWS annotations. WebLogic Web Services use standard JWS annotations, as defined by the Web Services Metadata for the Java Platform specification (JSR-181) as well as WebLogic-specific ones for added value.

The generated Web Service in this example, called Simple, has a single operation, sayHello(String), that returns the input String parameter.

The SimpleImpl.java Java source file (also called JWS file) forms the basis of the Web Service. The file uses both standard (defined by JSR-181) and WebLogic-specific JWS annotations to define the shape and behavior of the Web Service.

In particular, the JWS file uses the following standard JWS annotations:

@WebService to specify the name of the generated Web Service and the target namespace used in the generated WSDL. This annotation is used at the Java class level.
@SoapBinding to specify that the SOAP messages are of style document-literal-wrapped. This annotation is used at the Java class level.
@WebMethod to specify that the single method of the Java class should be exposed as a public Web Service operation. This annotation is used at the method level.

The JWS file uses the following WebLogic-specific JWS annotation:

@WLHttpTransport to specify the name of the port in the generated WSDL, as well as the context path and service URI used in the full URI of the deployed Web Service. This annotation is used at the Java class level.

To use the various JWS annotations, you must first import the annotation interfaces into your JWS file:

//Standard JWS annotations
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
//WebLogic-specific JWS annotation
import weblogic.jws.WLHttpTransport;

The SimpleImpl.java file defines a single public method that is exposed as a Web Service operation: sayHello(String). Because the @WebMethod annotation on the method does not specify the operationName attribute, the public name of the operation in the WSDL will be the same as the name of the method: sayHello.

To generate a Web Service from the JWS file, use the jwsc WebLogic Web Service Ant task, as shown in the build.xml file. This Ant task compiles the JWS file, and generates the additional files needed to implement a standard Java EE Web Service: the Web Service deployment descriptors, the WSDL file, and so on. The Ant task automatically generates all the components into an Enterprise Application directory structure, which you can then deploy to WebLogic Server. This example uses the wldeploy WebLogic Ant task to deploy the Web Service.

The Client.java class is a standalone Java application that invokes the sayHello operation of the Simple Web Service. It uses the JAX-RPC Stubs generated by the clientgen WebLogic Web Service Ant task, based on the WSDL of the Simple Web Service.

Files Used in the Example

Directory Location:

BEA_HOME/wlserver_10.3/samples/server/examples/src/examples/webservices/jws_basic/simple/

(where BEA_HOME is the directory containing your WebLogic Server installation)

File Click source files to view code.	Description
SimpleImpl.java	Java source file that contains the JWS metadata annotations (both standard and WebLogic-specific) that define the JWS-implemented Web Service.
Client.java	Standalone client application that invokes the deployed Web Service. Uses the JAX-RPC Stubs generated by clientgen, based on the WSDL of the Web Service.
JWS_WebService.jsp	JSP file that is invoked when you click on the Run the example link for this example from the main Examples Server JSP.
build.xml	Ant build file that contains targets for building and running the example.

Prepare the Example

Prerequisites

Before working with this example:

Install WebLogic Server, including the examples.
Start the Examples server.
Set up your environment.

Configure WebLogic Server

There are no server configurations for this example.

Build and Deploy the Example

Change to the SAMPLES_HOME\server\examples\src\examples\webservices\jws_basic\simple directory, where SAMPLES_HOME refers to the main WebLogic Server examples directory, such as d:\bea\wlserver_10.0\samples.
Execute the following command from the shell where you set your environment:

prompt> ant build

This command compiles and stages the example.
Execute the following command from the shell where you set your environment:

prompt> ant deploy

This command deploys the example on the wl_server domain of your WebLogic Server installation.

Run the Example

To run the example, follow these steps:

Complete the steps in the "Prepare the Example" section.
In your development shell, run the Client Java application by using the following command from the main example directory (SAMPLES_HOME\server\examples\src\examples\webservices\jws_basic\simple):
prompt> ant run
After building and running the example, you can view the WSDL of the Web Service by browsing to the following URL in your Web browser:
http://host:port/jws_basic_simple/SimpleService?WSDL

where
- host refers to the machine on which WebLogic Server is running.
- port refers to port on which WebLogic Server is listening.

Check the Output

If your example runs successfully, you will get the following message in the command shell from which you ran the client application:

Buildfile: build.xml

run:
       [java] Got result: Here is the message: 'Hi there!'

BUILD SUCCESSFUL

       Total time: 7 seconds

Troubleshooting

General Troubleshooting Tips for Examples

document.write(document.title);