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 metadata feature, introduced in Version 5.0 of the JDK (specified by JSR-175 at http://www.jcp.org/en/jsr/detail?id=175) and include standard annotations defined by Web Services Metadata for the Java Platform specification (JSR-181), described at http://www.jcp.org/en/jsr/detail?id=181, the JAX-WS specification (JSR-224), described at http://jax-ws.java.net, as well as additional ones. For a complete list of JWS annotations that are supported, see "Web Service Annotation Support" in WebLogic Web Services Reference for Oracle WebLogic Server. For additional detailed information about this programming model, see The Programming Model—Metadata Annotations.

Web services can be created using two development methods: bottom-up or top-down. Bottom-up development refers to the process of developing a Web service from the underlying Java implementation using SOAP. Top-development describes the development of a Web service from the WSDL source.

The following sections describe the high-level steps for iteratively developing a Web service, either starting from Java (bottom-up) or starting from an existing WSDL file (top-down):

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.

In addition to the command-line tools described in this section, you can use an IDE, such as Oracle JDeveloper or Oracle Enterprise Pack for Eclipse (OEPE), to develop Web services. For more information, see "Using Oracle IDEs to Build Web Services" in Understanding WebLogic Web Services for Oracle WebLogic Server.

Configuring Your Domain For Advanced Web Services Features

When creating or extending a domain, you can apply the WebLogic Advanced Web Services for JAX-WS Extension template (wls_webservice_jaxws.jar) to configure automatically the resources required to support the following advanced Web service features:

Use of the WebLogic Advanced Web Services for JAX-WS Extension template is only required when you need to ensure recoverability of advanced Web services. By default, the state of an advanced Web service is stored in memory; in the event of server failure, the data will be lost. The extension template configures the following resources that support recoverability by enabling WebLogic Server to retain critical state information in the event of a server failure:

If you do not apply the WebLogic Advanced Web Services for JAX-WS Extension template to support recoverability, you must ensure that buffering is disabled for Web services reliable messaging on the destination server. For more information, see Configuring a Non-buffered Destination for a Web Service.

Although use of this extension template is not required, it makes the configuration of the required resources much easier. Alternatively, you can manually configure the resources required for these advanced features using the Oracle WebLogic Administration Console or WLST.

The following procedures describe how to configure a domain automatically for the advanced Web services features. For more detailed instructions about using the Configuration Wizard to create and update WebLogic Server domains, see Creating Domains Using the Configuration Wizard.

Resources Required by Advanced Web Service Features

Table 3-1 lists the resources that are defined automatically when using the WebLogic Advanced Web Services for JAX-WS Extension template.

If you do not apply the extension template, you need to configure the resources manually using the Oracle WebLogic Administration Console or WLST. Be sure to configure JMS targeting according to best practices defined in "Best Practices for JMS Beginners and Advanced Users" in Administering JMS Resources for Oracle WebLogic Server. Specifically:

Configure a JMS server, Store-and-forward (SAF) service agent, and persistent store on each WebLogic Server. In a cluster, target each to a local migratable target (not the server). The host server's "default migratable target" is sufficient in most cases.

Target JMS modules to a cluster (or single server if not using a clustered environment).

Create exactly one subdeployment per module, and populate the subdeployment with the applicable JMS servers or SAF agents only, not the servers.

Target JMS destinations to the subdeployment (referred to as Advanced Targeting in the Administration Console). JMS destinations must never use the default targeting option.

The following variables are used in the table:

server_designator specifies an ID that is generated automatically by the configuration framework. Typically, this ID is of the format auto_number.

uniqueID specifies unique numeric ID that is generated automatically by the configuration framework. Typically, this ID is a numeric value, such as 1234.

server_name specifies the user-specified name of the server.

Note:

At runtime, you should not change the name of resources; otherwise, you may experience runtime errors or data loss.

Table 3-1 Resources Required by Advanced Web Services Features

Resource Name

Resource Type

Description

WseeJaxwsJmsModule

JMS Module

Defines a JMS module that defines the JMS resources needed for advanced Web services. All associated targets (JMS servers targeted to a server) on this JMS module will be used to support JAX-WS Web services. All servers to which this module is targeted must have the proper Web services resources configured.

Oracle recommends that you target this module to all servers in the domain.

Note: You must configure the JMS module as a Uniform Distributed Destination (UDD). Any queues that are used by Web services on JAX-WS must be Uniform Distributed Queues. Otherwise, an exception is thrown.

To configure distributed destinations manually and for more information, see "Using Distributed Destination" in Developing JMS Applications for Oracle WebLogic Server.

WseeJaxwsFileStore_server_designator

File store

Specifies the file store, or physical store, used by the WebLogic Server to handle the I/O operations to save and retrieve data from the physical storage (such as file, DBMS, and so on).

A separate file store is configured on each Managed Server targeted by the WseeJaxwsJmsModule, as specified by server_designator. In a single server domain, the file store is named WseeJaxwsFileStore.

Specifies the JMS server management container. A separate JMS Server is configured on each Managed Server targeted by WseeJaxwsJmsModule, as specified by server_designator. The JMS server uses WseeFileStore_server_designator as the file store.

When configuring the JMS server, Oracle recommends the following:

Target the JMS server to a migratable target.

Set realistic quotas on each JMS server. For more information, see "Tuning WebLogic JMS" in Tuning Performance of Oracle WebLogic Server.

Enables an application to execute multiple work items concurrently within a container. One Work Manager is generated for the domain and targeted to all servers to which the WseeJaxwsJmsModule is targeted.

Provides highly available JMS message production. A separate SAF agent is configured on each Managed Server, as specified by server_name. The SAF agent uses WseeFileStore_server_name as the file store.

In a single server domain, the SAF agent is named ReliableWseeJaxwsSAFAgent.

When configuring the SAF agent, Oracle recommends that you set realistic quotas on each JMS server. For more information, see "Tuning WebLogic JMS" in Tuning Performance of Oracle WebLogic Server.

Specifies the error queue used for WseeBufferedRequestQueue for buffered requests that cannot be processed within the maximum number of retries. A separate queue is configured on each Managed Server, as specified by server_name.

In a single server domain, the queue is named WseeBufferedRequestErrorQueue. In a clustered domain, each JMS queue is prefixed by dist_.

Specifies the error queue used for WseeBufferedResponseQueue for buffered responses that cannot be delivered within the maximum number of retries. A separate queue is configured on each Managed Server, as specified by server_designator.

In a single server domain, the queue is named WseeBufferedResponseErrorQueue. In a clustered domain, each JMS queue is prefixed by dist_.

Defines the logical store. A separate logical store is configured on each Managed Server targeted by WseeJaxwsJmsModule. The logical store points to the WseeBufferedRequestQueue queue for its configuration and file store.

Scripts for Extending a Domain for Advanced Web Service Features

The WebLogic Advanced Web Services for JAX-WS Extension template (wls_webservice_jaxws.jar) JAR file includes the following two Python scripts to assist you when extending an existing domain to use the WebLogic Advanced Web Services for JAX-WS Extension template.

Note:

Before running either script, you need to ensure that the JMS Module is targeted to all servers in the domain.

Table 3-2 Scripts for Extending a Domain for Advanced Web Service Features

Using WLST to Extend a Domain With the Web Services Extension Template

The following provides an example of how to use WLST to extend a domain using the Web services extension template. Specifically, this example demonstrates how to extend a single server domain. It is assumed that you have already created a single server domain. You can add additional servers and clusters to the domain in the location noted in the example script below.

After updating the script and executing it against your domain, all resources will be configured for advanced Web service features.

Updating Resources Added After Extending Your Domain

Once you have created or extended a domain using the Weblogic Advanced Web Services for JAX-WS Extension template, if you then modify the resources in your domain, you can update the configuration of those resources quickly and easily using the following WLST script.

After updating the script and executing it against your domain, all resources will be configured for advanced Web service features.

Note:

The wls_webservice_complete_update_utils.py script used at the end of this example is added to the domain directory when you extend the domain using the Web services extension template.

When creating or extending a domain using the WebLogic Advanced Web Services for JAX-WS Extension template (wls_webservice_jaxws.jar), you may encounter an exception during the execution of the final.py script, similar to the following:

Developing WebLogic Web Services Starting From Java: Main Steps

This section describes the general procedure for developing WebLogic Web services starting from Java—in effect, coding the JWS file from scratch and later generating the WSDL file that describes the service. See Chapter 6, "Examples of Developing JAX-WS Web Services" for specific examples of this process.

The following procedure is just a recommendation; if you have set up your own development environment, you can use this procedure as a guide for updating your existing environment to develop WebLogic Web services.

Open a command window and execute 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 ORACLE_HOME/user_projects/domains/domainName, where ORACLE_HOME is the directory you specified as Oracle Home when you installed Oracle WebLogic Server and domainName is the name of your domain.

2

Create a project directory.

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

The jwsc Ant task generates 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. See Running the jwsc WebLogic Web Services Ant Task.

The procedure is just a recommendation; if you have 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.

Open a command window and execute 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 ORACLE_HOME/user_projects/domains/domainName, where ORACLE_HOME is the directory you specified as Oracle Home when you installed Oracle WebLogic Server and domainName is the name of your domain.

2

Create a project directory.

The project directory will contain the generated artifacts and the Ant build.xml file.

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 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.

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.

WebService_type specifies the type of Web service. This value can be set to JAXWS or JAXRPC.

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" in the WebLogic Web Services Reference for Oracle WebLogic Server for complete documentation and examples about the jwsc Ant task.

Specifying the Transport Used to Invoke the Web Service

The <jws> child element of jwsc includes the following optional child elements for specifying the transports (HTTP/S or JMS) that are used to invoke the Web service:

WLHttpTransport—Specifies the context path and service URI sections of the URL used to invoke the Web service over the HTTP/S transport, as well as the name of the port in the generated WSDL. For more information, see "WLHttpTransport" in WebLogic Web Services Reference for Oracle WebLogic Server.

The following guidelines describe the usage of the transport elements for the jwsc Ant task:

The transports you specify to jwscalwaysoverride any corresponding transport annotations in the JWS file. In addition, all attributes of the transport annotation are ignored, even if you have not explicitly specified the corresponding attribute for the transport element, in which case the default value of the transport element attribute is used.

You can specify both transport elements for a particular JWS file. However, you can specify only one instance of a particular transport element. For example, although you cannot specify two different <WLHttpTransport> elements for a given JWS file, you can specify one <WLHttpTransport> and one <WLJmsTransport> element.

The value of the serviceURI attribute can be the same when you specify both <WLJMSTransport> and <WLHttpTransport>.

All transports associated with a particular JWS file must specify the samecontextPath attribute value.

If you specify more than one transport element for a particular JWS file, the value of the portName attribute for each element must be unique among all elements. This means that you must explicitly specify this attribute if you add more than one transport child element to <jws>, because the default value of the element will always be the same and thus cause an error when running the jwsc Ant task.

If you do not specify any transport as either one of the transport elements to the jwsc Ant task or a transport annotation in the JWS file, then the Web service's default URL corresponds to the default value of the WLHttpTransport element.

Defining the Context Path of a WebLogic Web Service

There are a variety of places where the context path (also called context root) of a WebLogic Web service can be specified. This section describes how to determine which is the true context path of the service based on its configuration, even if it is has been set in multiple places.

In the context of this discussion, a Web service context path is the string that comes after the host:port portion of the Web service URL. For example, if the deployed WSDL of a WebLogic Web service is as follows:

http://hostname:7001/financial/GetQuote?WSDL

The context path for this Web service is financial.

The following list describes the order of precedence, from most to least important, of all possible context path specifications:

The contextPath attribute of the <module> element and <jws> element (when used as a direct child of the jwsc Ant task.)

The contextPath attribute of the <WLHttpTransport> child elements of <jws>.

The default value of the context path, which is the name of the JWS file without any extension.

Assume that you update the build.xml file and add a <WLHttpTransport> child element to the <jws> element that specifies the JWS file and set its contextPath attribute to finance. The context path of the Web service would now be finance. If, however, you then group the <jws> element (including its child <WLHttpTransport> element) under a <module> element, and set its contextPath attribute to money, then the context path of the Web service would now be money.

If you do not specify anycontextPath attribute in either the JWS file or the jwsc Ant task, then the context path of the Web service is the default value: the name of the JWS file without its *.java extension.

If you group two or more <jws> elements under a <module> element and do not set the context path using any of the other options listed above, then you must specify the contextPath attribute of <module> to specify the common context path used by all the Web services in the module. Otherwise, the default context paths for all the Web services in the module are going to be different (due to different names of the implementing JWS files), which is not allowed in a single WAR file.

Examples of Using jwsc

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

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.

A JAX-WS Web service is generated.

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 updated to include your business logic. 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.

To actually run this task, type at the command line the following:

prompt> ant build-service

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:

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.

The wsdlc Ant task packages the JWS SEI 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:

WSDLFile 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 SEI 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 subdirectory hierarchy corresponding to its package name.

The name of the generated JWS file is Service_PortTypeImpl.java, where Service and PortType refer to the name attribute of the <service> element and its inner <port> element, respectively, in the WSDL file for which you are generating a Web service. For example, if the service name is MyService and the port name is MyServicePortType, then the JWS implementation file is called MyService_MyServicePortTypeImpl.java.

Package_name refers to the package into which the generated JWS SEI 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.

WebService_type specifies the type of Web service. This value can be set to JAXWS or JAXRPC.

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 generate the stubbed-out JWS file to make your programming easier. Oracle 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:

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 SEI 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 service and port type names in the WSDL file are TemperatureService and TemperaturePortType, then the name of the JWS implementation file is TemperatureService_TemperaturePortTypeImpl.java.

A JAX-WS Web service is generated.

To actually run this task, type the following at the command line:

prompt> ant generate-from-wsdl

See "wsdlc in WebLogic Web Services Reference for Oracle WebLogic Server for more information.

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 Service_PortTypeImpl.java, where Service is the name of the service and PortType is the name of the port type in the original WSDL. The class file includes everything you need to compile it into a Web service, except for your own business logic.

The JWS class implements the JWS Web service endpoint interface that corresponds to the WSDL file; the JWS SEI 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 annotation in the JWS implementation class; the value corresponds to the equivalent value 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.

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

//replace with your impl here

In addition, you can add additional JWS annotations to the file, with the following restrictions:

You can include the following annotations from the standard (JSR-181) javax.jws package in the JWS implementation file: @WebService, @HandlerChain, @SOAPMessageHandler, and @SOAPMessageHandlers. If you specify any other JWS annotation from the javax.jws package, the jwsc Ant task returns error when you try to compile the JWS file into a Web service. For example, if you specify the @Policy annotation in a your JWS implementation file, the jwsc Ant task throws a compilation error.

You can specify only the serviceName, endpointInterface, and targetNamespace 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 SEI generated by the wsdlc Ant task. Use the targetNamespace attribute to specify the namespace of a WSDL service, which can be different from the on in JWS SEI.

You can specify JAX-WS—JSR 224, JAXB (JSR 222)—or Common (JSR 250) annotations, as required. For more information about the annotations that are supported, see "JWS Annotation Reference" in WebLogic Web Services Reference for Oracle WebLogic Server.

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

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 Applications to Oracle WebLogic Server.

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 deploy a Web service as part of the iterative development process is to add a target that executes the wldeploy WebLogic Ant task to the same 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.

Browsing to the WSDL of the Web Service

You can display the WSDL of the Web service in your browser to ensure that it has deployed correctly.

The following URL shows how to display the Web service WSDL in your browser:

http://[host]:[port]/[contextPath]/[serviceUri]?WSDL

where:

host refers to the computer on which WebLogic Server is running (for example, localhost).

port refers to the port number on which WebLogic Server is listening (default value is 7001).

contextPath refers to the context root of the Web service. There are many places to set the context root (the <WLHttpTransport>, <module>, or <jws> element of jwsc) and certain methods take precedence over others. See "Defining the Context Path of a WebLogic Web Service".

serviceUri refers to the value of the serviceUri attribute of the <WLHttpTransport> child element of the jwsc Ant task. If you do not specify anyserviceUri attribute in the jwsc Ant task, then the serviceUri of the Web service is the default value: the serviceName element of the @WebService annotation if specified; otherwise, the name of the JWS file, without its extension, followed by Service.

For example, assume that you specified the following <WLHttpTransport> child element in the jwsc task that you use to build your Web service:

Then 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

Configuring the Server Address Specified in the Dynamic WSDL

The WSDL of a deployed Web service (also called dynamic WSDL) includes an <address> element that assigns an address (URI) to a particular Web service port. For example, assume that the following WSDL snippet partially describes a deployed WebLogic Web service called ComplexService:

The preceding example shows that the ComplexService Web service includes a port called ComplexServicePort, and this port has an address of http://myhost:7101/complex/ComplexService.

WebLogic Server determines the complex/ComplexService section of this address by examining the contextPath and serviceURI attributes of the jwsc elements, as described in Browsing to the WSDL of the Web Service. However, the method WebLogic Server uses to determine the protocol and host section of the address (http://myhost:7101, in the example) is more complicated, as described below. For clarity, this section uses the term server address to refer to the protocol and host section of the address.

The server address that WebLogic Server publishes in a dynamic WSDL of a deployed Web service depends on whether the Web service can be invoked using HTTP/S or JMS, whether you have configured a proxy server, whether the Web service is deployed to a cluster, or whether the Web service is actually a callback service.

The following sections reflect these different configuration options, and provide links to procedural information about changing the configuration to suit your needs.

If none of the above items are set, the Cluster Addressmust be set for the cluster, as described in "Configure Clusters" in Oracle WebLogic Server Administration Console Online Help. The server channel for the specified protocol from the request URL (for example, http) will be used to generate the cluster address that is displayed in the WSDL.

If the Web service is deployed to an individual server, the Frontend Host, Frontend HTTP Port, and Frontend HTTPS Port configured for the local server are used in the server address of the dynamic WSDL, as described in "Configure HTTP Protocol" in Oracle WebLogic Server Administration Console Online Help.

Web service is a callback service

If the callback service is deployed to a cluster, the following values are used in the server address of the dynamic WSDL, in order of precedence:

Cluster Address for the cluster, as described in "Configure Clusters" in Oracle WebLogic Server Administration Console Online Help. The Cluster Address is required if no other values are set.

If the callback service is deployed to an individual server, the Frontend Host, Frontend HTTP Port, and Frontend HTTPS Port configured for the local server are used in the server address of the dynamic WSDL, as described in "Configure HTTP Protocol" in Oracle WebLogic Server Administration Console Online Help.

If none of the preceding values are set, but the Listen Address of the server to which the callback service is deployed is set, then WebLogic Server uses this value in the server address.

Web service is invoked using a proxy server

Although not required, Oracle recommends that you explicitly set the Frontend Host, FrontEnd HTTP Port, and Frontend HTTPS Port of either the cluster or individual server to which the Web service is deployed to point to the proxy server.

Testing the Web Service

After you have deployed a WebLogic Web service, you can test basic and advanced features of your Web service, such as security, quality of service (QoS), HTTP headers, and so on. You can also perform stress testing of the security features. For information about testing Web services using the Web Services Test Client or Fusion Middleware Control Test Web Service page, see "Testing Web Services" in Administering Web Services.

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 set up this type of environment for developing standard Java Platform, Enterprise Edition (Java EE) Version 5 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 Environment" in Developing Applications for Oracle WebLogic Server and the splitdir/helloWorldEar example installed with WebLogic Server, located in the EXAMPLES_HOME/wl_server/examples/src/examples directory, where EXAMPLES_HOME represents the directory in which the WebLogic Server code examples are configured. For more information about the WebLogic Server code examples, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.

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:

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:

The jwsc Ant task always generates a Web Application WAR file from the JWS file that implements your Web service, unless you JWS file defines an EJB via the @Stateless annotation. In that case you must add an <ejb> module element to the application.xml file instead.

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.

Scripting on this page enhances content navigation, but does not change the content in any way.