Overview of the WebLogic Web Service Programming Model

The WebLogic Web Services programming model centers around JWS files (Java files that use JWS annotations to specify the shape and behavior of the Web Service) and Ant tasks that execute on the JWS file. JWS annotations are based on the new metadata feature of Version 5.0 of the JDK (specified by JSR-175), and include both the standard annotations defined by the Web Services Metadata for the Java Platform specification (JSR-181), as well as additional WebLogic-specific ones. For additional detailed information about this programming model, see Anatomy of a WebLogic Web Service.

The following sections describe the high-level steps for iteratively developing a Web Service, either starting from Java or starting from an existing WSDL file:

Iterative development refers to setting up your development environment in such a way so that you can repeatedly code, compile, package, deploy, and test a Web Service until it works as you want. The WebLogic Web Service programming model uses Ant tasks to perform most of the steps of the iterative development process. Typically, you create a single build.xml file that contains targets for all the steps, then repeatedly run the targets, after you have updated your JWS file with new Java code, to test that the updates work as you expect.

Iterative Development of WebLogic Web Services Starting From Java: Main Steps

This section describes the general procedure for iteratively developing WebLogic Web Services starting from Java, if effect, coding the JWS file from scratch and later generating the WSDL file that describes the service. See Common Web Services Use Cases and Examples, for specific examples of this process. The following procedure is just a recommendation; if you have already set up your own development environment, you can use this procedure as a guide for updating your existing environment to develop WebLogic Web Services.

To iteratively develop a WebLogic Web Service starting from Java, follow these steps:

Open a command window and set your WebLogic Server environment by executing the setDomainEnv.cmd (Windows) or setDomainEnv.sh (UNIX) command, located in the bin subdirectory of 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.

Create a project directory that will contain the JWS file, Java source for any user-defined data types, and the Ant build.xml file. You can name this directory anything you want.

In the project directory, create the JWS file that implements your Web Service.

Run the jwsc Ant task against the JWS file to generate source code, data binding artifacts, deployment descriptors, and so on, into an output directory. The jwsc Ant task generates an Enterprise Application directory structure at this output directory; later you deploy this exploded directory to WebLogic Server as part of the iterative development process.

Iterative Development of WebLogic Web Services Starting From a WSDL File: Main Steps

This section describes the general procedure for iteratively developing WebLogic Web Services based on an existing WSDL file. See Common Web Services Use Cases and Examples, for a specific example of this process. The procedure is just a recommendation; if you have already set up your own development environment, you can use this procedure as a guide for updating your existing environment to develop WebLogic Web Services.

It is assumed in this procedure that you already have an existing WSDL file.

To iteratively develop a WebLogic Web Service starting from WSDL, follow these steps.

Open a command window and set your WebLogic Server environment by executing the setDomainEnv.cmd (Windows) or setDomainEnv.sh (UNIX) command, located in the bin subdirectory of 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.

Create a project directory that will contain the generated artifacts and the Ant build.xml file. You can name this directory anything you want.

In the project directory, create a basic Ant build file called build.xml.

Invoke the deployed WSDL of the Web Service to test that the service was deployed correctly.

The URL used to invoke the WSDL of the deployed Web Service is essentially the same as the value of the location attribute of the <address> element in the original WSDL (except for the host and port values which now correspond to the host and port of the WebLogic Server instance to which you deployed the service.) This is because the wsdlc Ant task generated values for the contextPath and serviceURI of the @WLHttpTransport annotation in the JWS implementation file so that together they create the same URI as the endpoint address specified in the original WSDL.

Creating the Basic Ant build.xml File

Ant uses build files written in XML (default name build.xml) that contain a <project> root element and one or more targets that specify different stages in the Web Services development process. Each target contains one or more tasks, or pieces of code that can be executed. This section describes how to create a basic Ant build file; later sections describe how to add targets to the build file that specify how to execute various stages of the Web Services development process, such as running the jwsc Ant task to process a JWS file and deploying the Web Service to WebLogic Server.

The following skeleton build.xml file specifies a default all target that calls all other targets that will be added in later sections:

Running the jwsc WebLogic Web Services Ant Task

The jwsc Ant task takes as input a JWS file that contains both standard (JSR-181) and WebLogic-specific JWS annotations and generates all the artifacts you need to create a WebLogic Web Service. The JWS file can be either one you coded yourself from scratch or one generated by the wsdlc Ant task. The jwsc-generated artifacts include:

Java source files that implement a standard JSR-921 Web Service.

All required deployment descriptors. In addition to the standard webservices.xml and JAX-RPC mapping files, the jwsc Ant task also generates the WebLogic-specific Web Services deployment descriptor (weblogic-wesbservices.xml), the web.xml and weblogic.xml files for Java class-implemented Web Services and the ejb-jar.xml and weblogic-ejb-jar.xml files for EJB-implemented Web Services.

The XML Schema representation of any Java user-defined types used as parameters or return values to the Web Service operations.

The WSDL file that publicly describes the Web Service.

If you are running the jwsc Ant task against a JWS file generated by the wsdlc Ant task, the jwsc task does not generate these artifacts, because the wsdlc Ant task already generated them for you and packaged them into a JAR file In this case, you use an attribute of the jwsc Ant task to specify this wsdlc-generated JAR file.

The required taskdef element specifies the full class name of the jwsc Ant task.

Only the srcdir and destdir attributes of the jwsc Ant task are required. This means that, by default, it is assumed that Java files referenced by the JWS file (such as JavaBeans input parameters or user-defined exceptions) are in the same package as the JWS file. If this is not the case, use the sourcepath attribute to specify the top-level directory of these other Java files. See jwsc for more information.

The following build.xml excerpt shows an example of running the jwsc Ant task on a JWS file:

In the example, the Enterprise Application will be generated, in exploded form, in output/helloWorldEar, relative to the current directory. The JWS file is called HelloWorldImpl.java, and is located in the src/examples/webservices/hello_world directory, relative to the current directory. This implies that the JWS file is in the package examples.webservices.helloWorld.

The following example is similar to the preceding one, except that it uses the compiledWsdl attribute to specify the JAR file that contains wsdlc-generated artifacts (for the "starting with WSDL" use case):

In the preceding example, the TemperaturePortTypeImpl.java file is the stubbed-out JWS file that you previously updated to include the business logic to make your service work as you want. Because the compiledWsdl attribute is specified and points to a JAR file, the jwsc Ant task does not regenerate the artifacts that are included in the JAR.

Running the wsdlc WebLogic Web Services Ant Task

The wsdlc Ant task takes as input a WSDL file and generates artifacts that together partially implement a WebLogic Web Service. These artifacts include:

The JWS interface file that represents the Java implementation of your Web Service.

Data binding artifacts used by WebLogic Server to convert between the XML and Java representations of the Web Service parameters and return values.

A JWS file that contains a stubbed-out implementation of the generated JWS interface.

Optional Javadocs for the generated JWS interface.

The wsdlc Ant task packages the JWS interface file and data binding artifacts together into a JAR file that you later specify to the jwsc Ant task. You never need to update this JAR file; the only file you update is the JWS implementation class.

To run the wsdlc Ant task, add the following taskdef and generate-from-wsdl targets to the build.xml file:

WSDL_file refers to the name of the WSDL file from which you want to generate a partial implementation, including its absolute or relative pathname.

JWS_interface_directory refers to the directory into which the JAR file that contains the JWS interface and data binding artifacts should be generated.

The name of the generated JAR file is WSDLFile_wsdl.jar, where WSDLFile refers to the root name of the WSDL file. For example, if the name of the WSDL file you specify to the file attribute is MyService.wsdl, then the generated JAR file is MyService_wsdl.jar.

JWS_implementation_directory refers to the top directory into which the stubbed-out JWS implementation file is generated. The file is generated into a sub-directory hierarchy corresponding to its package name.

The name of the generated JWS file is PortTypeImpl.java, where PortType refers to the name attribute of the <portType> element in the WSDL file for which you are generating a Web Service. For example, if the port type name is MyServicePortType, then the JWS implementation file is called MyServicePortTypeImpl.java.

Package_name refers to the package into which the generated JWS interface and implementation files should be generated. If you do not specify this attribute, the wsdlc Ant task generates a package name based on the targetNamespace of the WSDL.

The required taskdef element specifies the full class name of the wsdlc Ant task.

Only the srcWsdl and destJwsDir attributes of the wsdlc Ant task are required. Typically, however, you also generate the stubbed-out JWS file to make your programming easier. BEA also recommends you explicitly specify the package name in case the targetNamespace of the WSDL file is not suitable to be converted into a readable package name.

The following build.xml excerpt shows an example of running the wsdlc Ant task against a WSDL file:

In the example, the existing WSDL file is called TemperatureService.wsdl and is located in the wsdl_files subdirectory of the directory that contains the build.xml file. The JAR file that will contain the JWS interface and data binding artifacts is generated to the output/compiledWsdl directory; the name of the JAR file is TemperatureService_wsdl.jar. The package name of the generated JWS files is examples.webservices.wsdld. The stubbed-out JWS file is generated into the impl_output/examples/webservices/wsdlc directory relative to the current directory. Assuming that the port type name in the WSDL file is TemperaturePortType, then the name of the JWS implementation file is TemperaturePortTypeImpl.java.

The wsdlc Ant task generates the stubbed-out JWS implementation file into the directory specified by its destImplDir attribute; the name of the file is PortTypeImpl.java, where PortType is the name of the portType in the original WSDL. The class file includes everything you need to compile it into a Web Service, except for your own business logic in the methods that implement the operations.

The JWS class implements the JWS Web Service endpoint interface that corresponds to the WSDL file; the JWS interface is also generated by wsdlc and is located in the JAR file that contains other artifacts, such as the Java representations of XML Schema data types in the WSDL and so on. The public methods of the JWS class correspond to the operations in the WSDL file.

The wsdlc Ant task automatically includes the @WebService and @WLHttpTransport annotations in the JWS implementation class; the values of the attributes correspond to equivalent values in the WSDL. For example, the serviceName attribute of @WebService is the same as the name attribute of the <service> element in the WSDL file; the contextPath and serviceUri attributes of @WLHttpTransport together make up the endpoint address specified by the location attribute of the <address> element in the WSDL.

When you update the JWS file, you add Java code to the methods so that the corresponding Web Service operations works as you want. Typically, the generated JWS file contains comments where you should add code, such as:

//replace with your impl here

You can also add additional JWS annotations to the file, with the following restrictions:

The only standard JWS annotations (in the javax.jws.* package) you can include in the JWS implementation file are @WebService, @HandlerChain, @SOAPMessageHandler, and @SOAPMessageHandlers. If you specify any other standard JWS annotations, the jwsc Ant task returns error when you try to compile the JWS file into a Web Service.

You can specify only the serviceName and endpointInterface attributes of the @WebService annotation. Use the serviceName attribute to specify a different <service> WSDL element from the one that the wsdlc Ant task used, in the rare case that the WSDL file contains more than one <service> element. Use the endpointInterface attribute to specify the JWS interface generated by the wsdlc Ant task.

You can specify any WebLogic-specific JWS annotation that you want.

After you have updated the JWS file, BEA recommends that you move it to an official source location, rather than leaving it in the wsdlc output location.

The following example shows the wsdlc-generated JWS implementation file from the WSDL shown in Sample WSDL File; the text in bold indicates where you would add Java code to implement the single operation (getTemp) of the Web Service:

Deploying and Undeploying WebLogic Web Services

Because Web Services are packaged as Enterprise Applications, deploying a Web Service simply means deploying the corresponding EAR file or exploded directory.

There are a variety of ways to deploy WebLogic applications, from using the Administration Console to using the weblogic.Deployer Java utility. There are also various issues you must consider when deploying an application to a production environment as opposed to a development environment. For a complete discussion about deployment, see Deploying WebLogic Server Applications.

This guide, because of its development nature, discusses just two ways of deploying Web Services:

Using the wldeploy Ant Task to Deploy Web Services

The easiest way to quickly deploy a Web Service as part of the iterative development process is to add a target that executes the wldeploy WebLogic Ant task to your build.xml file that contains the jwsc Ant task. You can add tasks to both deploy and undeploy the Web Service so that as you add more Java code and regenerate the service, you can redeploy and test it iteratively.

To use the wldeploy Ant task, add the following target to your build.xml file:

DeploymentName refers to the deployment name of the Enterprise Application, or the name that appears in the Administration Console under the list of deployments.

Source refers to the name of the Enterprise Application EAR file or exploded directory that is being deployed. By default, the jwsc Ant task generates an exploded Enterprise Application directory.

AdminUser refers to administrative username.

AdminPassword refers to the administrative password.

AdminServerURL refers to the URL of the Administration Server, typically t3://localhost:7001.

ServerName refers to the name of the WebLogic Server instance to which you are deploying the Web Service.

For example, the following wldeploy task specifies that the Enterprise Application exploded directory, located in the output/ComplexServiceEar directory relative to the current directory, be deployed to the myServer WebLogic Server instance. Its deployed name is ComplexServiceEar.

The URL to view the WSDL of the Web Service, assuming the service is running on a host called ariel at the default port number (7001), is:

http://ariel:7001/complex/ComplexService?WSDL

Testing the Web Service

The WebLogic Web Services test client allows for convenient testing of WebLogic Web Services through a Web user interface without writing code. You can quickly and easily test any Web Service, including those with complex types and those using advanced features of WebLogic Server such as converations. The test client automatically maintains a full log of requests allowing you to return to previous call to to view the results. The test client is packaged as a J2EE application in an EAR archive.

To use the WebLogic Web Services test client to test your Web Services, you must first download a ZIP file from the BEA dev2dev Web site and install the EAR file on your WebLogic Server. After you have started the test client Enterprise application (called wlstestclient by default), you can invoke it by typing the following URL in your browser:

http://host:port/wls_utc

Enter the WSDL of the Web Service you want to test in the text field, then click Go. A list of the operations of the Web Service is displayed, along with text fields where you can enter relevant test data.

See the instructions on the dev2dev site for additional detailed information about downloading, installing, and using the test client.

Integrating Web Services Into the WebLogic Split Development Directory Environment

This section describes how to integrate Web Services development into the WebLogic split development directory environment. It is assumed that you understand this WebLogic feature and have already set up this type of environment for developing standard J2EE applications and modules, such as EJBs and Web applications, and you want to update the single build.xml file to include Web Services development.

For detailed information about the WebLogic split development directory environment, see Creating a Split Development Directory for an Application and the splitdir/helloWorldEar example installed with WebLogic Server, located in the BEA_HOME/weblogic90/samples/server/examples/src/examples directory, where BEA_HOME refers to the main installation directory for BEA products, such as c:/bea.

In the main project directory, create a directory that will contain the JWS file that implements your Web Service.

For example, if your main project directory is called /src/helloWorldEar, then create a directory called /src/helloWorldEar/helloWebService:

prompt> mkdir /src/helloWorldEar/helloWebService

Create a directory hierarchy under the helloWebService directory that corresponds to the package name of your JWS file.

For example, if your JWS file is in the package examples.splitdir.hello package, then create a directory hierarchy examples/splitdir/hello:

The jwscsrcdir attribute should point to the top-level directory that contains the JWS file (helloWebService in this example). The jwscdestdir attribute should point to the same destination directory you specify for wlcompile, as shown in the following example:

Warning: When you actually build your Enterprise Application, be sure you run the jwsc Ant task before you run the wlappc Ant task. This is because wlappc requires some of the artifacts generated by jwsc for it to execute successfully. In the example, this means that you should specify the build-helloWebService target before the appc target.

If you use the wlcompile and wlappc Ant tasks to compile and validate the entire Enterprise Application, be sure to exclude the Web Service source directory for both Ant tasks. This is because the jwsc Ant task already took care of compiling and packaging the Web Service. For example:

Caution: Although the jwsc Ant task typically generates a Web Application WAR file from the JWS file that implements your Web Service, the task sometimes generates an EJB JAR file, depending on the JWS annotations specified in the JWS file. In that case you must add an <ejb> module element to the application.xml file instead. For more information about when the jwsc Ant task generates an EJB JAR file, see jwsc.

Your split development directory environment is now updated to include Web Service development. When you rebuild and deploy the entire Enterprise Application, the Web Service will also be deployed as part of the EAR. You invoke the Web Service in the standard way described in Browsing to the WSDL of the Web Service.