bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic Web Services

Upgrading 6.1 WebLogic Web Services to 7.0

The following sections describe how to upgrade a 6.1 WebLogic Web service to 7.0:

- "Overview of Upgrading 6.1 WebLogic Web Services" on page -1

- "Upgrading 6.1 WebLogic Web Services to 7.0 Automatically" on page -2

- "Upgrading 6.1 WebLogic Web Services to 7.0 Manually" on page -4

- "Converting a 6.1 build.xml file to 7.0" on page -4

- "Updating the URL Used to Access the Web Service" on page -7

Overview of Upgrading 6.1 WebLogic Web Services

Due to changes in the Web service runtime system between Versions 6.1 and 7.0 of WebLogic Server, you should upgrade Web services created in version 6.1 to run on version 7.0. This chapter describes the upgrade process.

There are two ways to upgrade a 6.1 Web service:

- Automatically, using the wsgen Ant task. The Ant task uses default values for any required 7.0 web-services.xml attributes that have no corresponding 6.1 attribute.

  For details, see "Upgrading 6.1 WebLogic Web Services to 7.0 Automatically" on page -2.

- Manually, by rewriting the build.xml file you used to create a 6.1 Web service to now call the servicegen Ant task rather than the wsgen Ant task

  For details, see "Upgrading 6.1 WebLogic Web Services to 7.0 Manually" on page -4.

Note: You cannot deploy a 6.1 Web service on a 7.0 WebLogic Server instance.

The WebLogic Web services client API included in version 6.1 of WebLogic Server has been deprecated and you should not use it to invoke 7.0 Web services. Version 7.0 includes a new client API, based on the Java API for XML based RPC (JAX-RPC). You should rewrite client applications that used the 6.1 Web services client API to now use the JAX-RPC APIs. For details, see Invoking Web Services.

For more detailed information on the differences between 6.1 and 7.0 Web services, see Overview of WebLogic Web Services.

Upgrading 6.1 WebLogic Web Services to 7.0 Automatically

Use the wsgen Ant task to automatically upgrade a Web service from 6.1 to 7.0. It takes as input the build.xml file you used to assemble the 6.1 Web service, and based on the values in this file, the task:

- Generates a web-services.xml file that describes the Web service. The task uses default values for any required elements or attributes in the deployment descriptor that do not apply to 6.1 Web services. For details on these default values, see WebLogic Web Service Deployment Descriptor Elements.

- Optionally creates a client JAR file that includes the Web service-specific classes, stubs, and interfaces needed by client applications that invoke the Web service. The classes, stubs, and interfaces are based on the JAX-RPC API.

- Packages all the Web service components into a Web application WAR file, then packages the WAR and EJB JAR files into a deployable EAR file.

To upgrade a 6.1 WebLogic Web service to 7.0 automatically, follow these steps:

1. Create a temporary staging directory.

2. If you are upgrading a 6.1 RPC-style Web service, copy the EJB JAR file that contains the EJB that implements the service, along with any supporting EJBs, to the staging directory.

3. Copy the 6.1 build.xml file that contains a call to the wsgen Ant task to the staging directory.

4. If, in your 6.1 build.xml file, you explicitly declared the wsgen Ant task using the <taskdef> element, as shown in the following example:

>     <taskdef name="wsgen" classname="weblogic.ant.taskdefs.ejb.WSGen"/>

remove this <taskdef> element from the build.xml file.

1. Optionally add the targetNameSpace and packageName attributes to the <wsgen> element of the build.xml file. For descriptions of these optional attributes, see "wsgen" on page B-36.

2. Set your WebLogic Server 7.0 environment.

   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.

3. Execute the wsgen Ant task in the build.xml file by typing ant in the same directory as the build.xml file:

   >     prompt> ant

   The Ant task generates an EAR file that you can deploy on WebLogic Server 7.0.

4. In your client application, update the URL you use to access the Web service or the WSDL of the Web service from that used in 6.1 to 7.0. For details, see "Updating the URL Used to Access the Web Service" on page -7.

Upgrading 6.1 WebLogic Web Services to 7.0 Manually

To upgrade a 6.1 WebLogic Web service to 7.0 manually, follow these steps:

1. Convert the build.xml Ant build file used to assemble 6.1 Web services with the wsgen Ant task to the 7.0 version that calls the servicegen Ant task.

   For details see "Converting a 6.1 build.xml file to 7.0" on page -4.

2. Un-jar the 6.1 Web services EAR file and extract the EJB JAR file that contains the stateless session EJBs (for 6.1 RPC-style Web services) or message-driven beans (for 6.1 message-style Web services), along with any supporting class files.

3. If your 6.1 Web service was RPC-style, seeAssembling WebLogic Web Services Using the servicegen Ant task for instruction on using the servicegen Ant task.

   If your 6.1 Web service was message-style, you must assemble the 7.0 Web service manually. For detailed instructions, see Creating JMS-Implemented WebLogic Web Services.

4. In your client application, update the URL you use to access the Web service or the WSDL of the Web service from that used in 6.1 to 7.0. For details, see "Updating the URL Used to Access the Web Service" on page -7.

Converting a 6.1 build.xml file to 7.0

The main difference between the 6.1 and 7.0 build.xml files used to assemble a Web service is the Ant task: in 6.1 the task was called wsgen and in 7.0 it is called servicegen. The servicegen Ant task uses many of the same elements and attributes of wsgen, although some do not apply anymore. The servicegen Ant task also includes additional configuration options. The table at the end of this section describes the mapping between the elements and attributes of the two Ant tasks.

Note: Although in 6.1 you were able to use the wsgen Ant task to assemble a message-style Web service, the servicegen Ant task does not have equivalent 7.0 functionality for JMS implemented backend components. Therefore, if you are upgrading a 6.1 message-style Web service, there is no need to convert the old build.xml file.

The following build.xml excerpt is from the 6.1 RPC-style Web services example:

>     <project name="myProject" default="wsgen">
>             <target name="wsgen">
>                <wsgen destpath="weather.ear"
>                       context="/weather">
>                     <rpcservices path="weather.jar">
>                        <rpcservice bean="statelessSession"
>                                    uri="/weatheruri"/>
>                        </rpcservices>
>                </wsgen>
>             </target>
>     </project>

The following example shows an equivalent 7.0 build.xml file:

>     <project name="myProject" default="servicegen">
>         <target name="servicegen">
>            <servicegen
>                destEar="weather.ear"
>                contextURI="weather" >
>                <service
>                    ejbJar="weather.jar"
>                    serviceURI="/weatheruri"
>                    includeEJBs="statelessSession" >
>                </service>
>            </servicegen>
>         </target>
>     </project>

For detailed information on the WebLogic Web service Ant tasks, see Web Service Ant Tasks and Command-Line Utilities.

The following table maps the 6.1 wsgen elements and attributes to their equivalent 7.0 servicegen elements and attributes.

Table 0-1 6.1 to 7.0 wsgen Ant Task Mapping

6.1 wsgen Element | Attribute | Equivalent 7.0 servicegen element | Attribute
--- | --- | --- | ---
wsgen | basepath | No equivalent. | No equivalent
destpath | servicegen | destEar
context | servicegen | contextURI
protocol | servicegen.service | protocol
host | No equivalent. | No equivalent
port | No equivalent. | No equivalent
webapp | servicegen | warName
classpath | servicegen | classpath
rpcservices | module | No equivalent. | No equivalent
path | servicegen.service | ejbJar
rpcservice | bean | servicegen.service | includeEJBS, excludeEJBs
uri | servicegen.service | serviceURI
messageservices | N/A | No equivalent. | No equivalent
messageservice | All attributes. | No equivalent. | No equivalent
clientjar | path | servicegen.service.client | clientJarName

Updating the URL Used to Access the Web Service

The default URL used by client applications to access a WebLogic Web service and its WSDL has changed between versions 6.1 and 7.0 of WebLogic Server.

In Version 6.1, the default URL was:

>     [protocol]://[host]:[port]/[context]/[WSname]/[WSname].wsdl

as described in URLs to Invoke WebLogic Web Services and Get the WSDL.

For example, the URL to invoke a 6.1 Web service built with the build.xml file shown in "Converting a 6.1 build.xml file to 7.0" on page -4, is:

>     http://host:port/weather/statelessSession.WeatherHome/statelessSession.WeatherHome.wsdl

In 7.0, the default URL is:

>     [protocol]://[host]:[port]/[contextURI]/[serviceURI]?WSDL

as described in The WebLogic Web Services Home Page and WSDL URLs.

For example, the URL to invoke the equivalent 7.0 Web service after converting the 6.1 build.xml file shown in "Converting a 6.1 build.xml file to 7.0" on page -4 and running wsgen is:

>     http://host:port/weather/weatheruri?WSDL