Programming Web Services for WebLogic Server
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
The following sections describe how to upgrade a WebLogic Server 8.1 Web Service to run in the 9.0 Web Service runtime environment:
This section describes how to upgrade an 8.1 WebLogic Web Service to use the new Version 9.0 Web Services runtime environment. This runtime is based on the Implementing Enterprise Web Services 1.1 specification (JSR-921, which is the 1.1 maintenance release of JSR-109). The 9.0 programming model uses standard JDK 1.5 metadata annotations, as specified by the Web Services Metadata for the Java Platform specification (JSR-181).
Note: 8.1 WebLogic Web Services will continue to run, without any changes, on Version 9.0 of WebLogic Server because the 8.1 Web Services runtime is still supported in 9.0, although it is deprecated and will be removed from the product in future releases. For this reason, BEA highly recommends that you follow the instructions in this chapter to upgrade your 8.1 Web Service to 9.0.
Upgrading your 8.1 Web Service includes the following high-level tasks; the procedures in later sections go into more detail:
Version 9.0 WebLogic Web Services are implemented using JWS files, which are Java files that contains JWS annotations. You do not specify whether the underlying implementation of the Web Service is a Java class or a stateless EJB; this decision is left up to the jwsc
Ant task. This programming model differs from that of 8.1, where you did specify the type of backend component (Java class or EJB).
jwsc
instead of the 8.1 servicegen
task.In the sections that follow it is assumed that:
servicegen
to generate your 8.1 Web Service and that, more generally, you use Ant scripts in your development environment to iteratively develop Web Services and other J2EE artifacts that run on WebLogic Server. The procedures in this section direct you to update existing Ant build.xml
files.This section does not discuss the following topics:
To upgrade an 8.1 Java class-implemented Web Service to use the 9.0 WebLogic Web Services runtime:
setDomainEnv.cmd
(Windows) or setDomainEnv.sh
(UNIX) script, located in the bin
subdirectory of your 9.0 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.
prompt> mkdir /myExamples/upgrade_pojo
src
directory under the project directory, as well as sub-directories that correspond to the package name of the new 9.0 JWS file (shown later in this procedure) that corresponds to the old 8.1 Java class:prompt> cd /myExamples/upgrade_pojo
prompt> mkdir src/examples/webservices/upgrade_pojo
src/examples/webservices/upgrade_pojo
directory of the working directory. Rename the file, if desired.@WebService
annotation at the Java class level to specify that the JWS file implements a Web Service.@SOAPBinding
annotation at the class-level to specify the type of Web Service, such as document-literal-wrapped or RPC-encoded.@WLHttpTransport
annotation at the class-level to specify the context and service URIs that are used in the URL that invokes the deployed Web Service.@WebMethod
annotation at the method-level for each method that is exposed as a Web Service operation.See Programming the JWS File, for general information about using JWS annotations in a Java file.
servicegen
. See Mapping of servicegen Attributes to JWS Annotations or jwsc Attributes for a table that lists equivalent JWS annotation, if available, for features you enabled in 8.1 using servicegen
attributes.build.xml
file to execute the jwsc
Ant task, along with other supporting tasks, instead of servicegen
. BEA recommends that you create a new target, such as build-service
, in your Ant build file and add the jwsc
Ant task call to compile the new JWS file you created in the preceding steps. Once this target is working correctly, you can remove the old servicegen
Ant task.
The following procedure lists the main steps to update your build.xml
file; for details on the steps, see the standard iterative development process outlined in Iterative Development of WebLogic Web Services.
See Example of an 8.1 and Updated 9.0 Ant Build File for Java Class-Implemented Web Services for specific examples of the steps in the following procedure.
build-service
target and add the tasks needed to build the 9.0 Web Service, as described in the following steps.jwsc
task to the build file. Set the srdir
attribute to the src directory (/myExamples/upgrade_pojo/src
, in this example) and the destdir
attribute to the root Enterprise application directory you created in the preceding step.Set the file
attribute of the <jws>
child element to the name of the new JWS file, created earlier in this procedure.
You may need to specify additional attributes to the jwsc
task, depending on the 8.1 Web Service features you want to carry forward to 9.0. In 8.1, many of these features were configured using attributes of servicegen
. See Mapping of servicegen Attributes to JWS Annotations or jwsc Attributes for a table that describes if there is an equivalent jwsc
attribute for features you enabled using servicegen
attributes.
See Deploying and Undeploying WebLogic Web Services and Browsing to the WSDL of the Web Service for additional information about deploying and testing your Web Service.
Based on the sample Java code shown in the following sections, the URL to invoke the WSDL of the upgraded 9.0 Web Service is:
http://
host
:port
/upgradePOJO/HelloWorld?WSDL
Assume that the following sample Java class implemented a 8.1 Web Service:
package examples.javaclass;
/**
* Simple Java class that implements the HelloWorld Web service. It takes
* as input an integer and a String, and returns a message that includes these
* two parameters.
*
* @author Copyright (c) 2005 by BEA Systems. All Rights Reserved.
*/
public final class HelloWorld81 {
/**
* Returns a text message that includes the integer and String input
* parameters.
*
*/
public String sayHello(int num, String s) {
System.out.println("sayHello operation has been invoked with arguments " + s + " and " + num);
String returnValue = "This message brought to you by the letter "+s+" and the number "+num;
return returnValue;
}
}
An equivalent JWS file for a 9.0 Java class-implemented Web Service is shown below, with the differences shown in bold. Note that some of the JWS annotation values are taken from attributes of the 8.1 servicegen
Ant task shown in Example of an 8.1 and Updated 9.0 Ant Build File for Java Class-Implemented Web Services:
package examples.webservices.upgrade_pojo;
// Import standard JWS annotations
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.soap.SOAPBinding;
// Import WebLogic JWS anntoation
import weblogic.jws.WLHttpTransport;
/**
* Simple Java class that implements the HelloWorld90 Web service. It takes
* as input an integer and a String, and returns a message that includes these
* two parameters.
*
* @author Copyright (c) 2005 by BEA Systems. All Rights Reserved.
*/
@WebService(name="HelloWorld90PortType", serviceName="HelloWorld",
targetNamespace="http://example.org")
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
@WLHttpTransport(contextPath="upgradePOJO", serviceUri="HelloWorld",
portName="HelloWorld90Port")
public class HelloWorld90Impl {
/**
* Returns a text message that includes the integer and String input
* parameters.
*
*/
@WebMethod()
public String sayHello(int num, String s) {
System.out.println("sayHello operation has been invoked with arguments " + s + " and " + num);
String returnValue = "This message brought to you by the letter "+s+" and the number "+num;
return returnValue;
}
}
The following simple build.xml
file shows the 8.1 way to build a WebLogic Web Service using the servicegen
Ant task; in the example, the Java file that implements the 8.1 Web Service has already been compiled into the examples.javaclass.HelloWorld81 class:
<project name="javaclass-webservice" default="all" basedir=".">
<!-- set global properties for this build -->
<property name="source" value="."/>
<property name="build" value="${source}/build"/>
<property name="war_file" value="HelloWorldWS.war" />
<property name="ear_file" value="HelloWorldApp.ear" />
<property name="namespace" value="http://examples.org" />
<target name="all" depends="clean, ear"/>
<target name="clean">
<delete dir="${build}"/>
</target>
<!-- example of old 8.1 servicegen call to build Web Service -->
<target name="ear">
<servicegen
destEar="${build}/${ear_file}"
warName="${war_file}">
<service
javaClassComponents="examples.javaclass.HelloWorld81"
targetNamespace="${namespace}"
serviceName="HelloWorld"
serviceURI="/HelloWorld"
generateTypes="True"
expandMethods="True">
</service>
</servicegen>
</target>
</project>
An equivalent build.xml
file that calls the jwsc
Ant task to build a 9.0 Web Service is shown below, with the relevant tasks discussed in this section in bold. In the example, the new JWS file that implements the 9.0 Web Service is called HelloWorld90Impl.java
:
<project name="webservices-upgrade_pojo" 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="upgradePOJOEar" />
<property name="example-output" value="output" />
<property name="ear-dir" value="${example-output}/upgradePOJOEar" />
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all" depends="clean,build-service,deploy" />
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}">
<jws file="examples/webservices/upgrade_pojo/HelloWorld90Impl.java" />
</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>
</project>
The following procedure describes how to upgrade an 8.1 EJB-implemented Web Service to use the 9.0 WebLogic Web Services runtime.
The 9.0 Web Services programming model is quite different from the 8.1 model in that it hides the underlying implementation of the Web Service. Rather than specifying up front that you want the Web Service to be implemented by a Java class or an EJB, you let the jwsc Ant task decide which is the best implementation. For this reason, the following procedure does not show how to import EJB classes or use EJBGen, even though the 8.1 Web Service was explicitly implemented with an EJB. Instead, the procedure shows how to create a standard JWS file that is the 9.0 equivalent to the 8.1 EJB-implemented Web Service.
setDomainEnv.cmd
(Windows) or setDomainEnv.sh
(UNIX) script, located in the bin
subdirectory of your 9.0 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.
prompt> mkdir /myExamples/upgrade_ejb
src
directory under the project directory, as well as sub-directories that correspond to the package name of the new 9.0 JWS file (shown later on in this procedure) that corresponds to your 8.1 EJB implementation:prompt> cd /myExamples/upgrade_ejb
prompt> mkdir src/examples/webservices/upgrade_ejb
javax.ejb.SessionBean
to the src/examples/webservices/upgrade_ejb
directory of the working directory. Rename the file, if desired.Note: You do not need to copy over the 8.1 Home and Remote EJB files.
import
statements that import the EJB classes (javax.ejb.*
). These classes are no longer needed in the upgraded JWS file.@WebService
annotation at the Java class level to specify that the JWS file implements a Web Service.@SOAPBinding
annotation at the class-level to specify the type of Web Service, such as document-literal-wrapped or RPC-encoded.@WLHttpTransport
annotation at the class-level to specify the context and service URIs that are used in the URL that invokes the deployed Web Service.@WebMethod
annotation at the method-level for each method that is exposed as a Web Service operation.See Programming the JWS File, for general information about using JWS annotations in a Java file.
servicegen
. See Mapping of servicegen Attributes to JWS Annotations or jwsc Attributes for a table that lists equivalent JWS annotation, if available, for features you enabled in 8.1 using servicegen
attributes.build.xml
file to execute the jwsc
Ant task, along with other supporting tasks, instead of servicegen
. BEA recommends that you create a new target, such as build-service
, in your Ant build file and add the jwsc
Ant task call to compile the new JWS file you created in the preceding steps. Once this target is working correctly, you can remove the old servicegen
Ant task.
The following procedure lists the main steps to update your build.xml
file; for details on the steps, see the standard iterative development process outlined in Iterative Development of WebLogic Web Services.
See Example of an 8.1 and Updated 9.0 Ant Build File for an 8.1 EJB-Implemented Web Service for specific examples of the steps in the following procedure.
build-service
target and add the tasks needed to build the 9.0 Web Service, as described in the following steps.jwsc
task to the build file. Set the srdir
attribute to the src directory (/myExamples/upgrade_ejb/src
, in this example) and the destdir
attribute to the root Enterprise application directory you created in the preceding step.Set the file
attribute of the <jws>
child element to the name of the new JWS file, created earlier in this procedure.
You may need to specify additional attributes to the jwsc
task, depending on the 8.1 Web Service features you want to carry forward to 9.0. In 8.1, many of these features were configured using attributes of servicegen
. See Mapping of servicegen Attributes to JWS Annotations or jwsc Attributes for a table that indicates whether there is an equivalent jwsc
attribute for features you enabled using servicegen
attributes.
See Deploying and Undeploying WebLogic Web Services and Browsing to the WSDL of the Web Service for additional information about deploying and testing your Web Service.
Based on the sample Java code shown in the following sections, the URL to invoke the WSDL of the upgraded 9.0 Web Service is:
http://
host
:port
/upgradeEJB/HelloWorldService?WSDL
Assume that the Bean, Home, and Remote classes and interfaces, shown in the next three sections, implemented the 8.1 stateless session EJB which in turn implemented an 8.1 Web Service.
The equivalent 9.0 JWS file is shown in Equivalent 9.0 JWS File. The differences between the 8.1 and 9.0 classes are shown in bold. Note that some of the JWS annotation values are taken from attributes of the 8.1 servicegen
Ant task shown in Example of an 8.1 and Updated 9.0 Ant Build File for an 8.1 EJB-Implemented Web Service.
package examples.statelessSession;
import javax.ejb.CreateException;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
/**
* HelloWorldBean is a stateless session EJB. It has a single method,
* sayHello(), that takes an integer and a String and returns a String.
* <p>
* The sayHello() method is the public operation of the Web service based on
* this EJB.
*
* @author Copyright (c) 2005 by BEA Systems. All Rights Reserved.
*/
public class HelloWorldBean81 implements SessionBean {
private static final boolean VERBOSE = true;
private SessionContext ctx;
// You might also consider using WebLogic's log service
private void log(String s) {
if (VERBOSE) System.out.println(s);
}
/**
* Single EJB business method.
*/
public String sayHello(int num, String s) {
System.out.println("sayHello in the HelloWorld EJB has "+
"been invoked with arguments " + s + " and " + num);
String returnValue = "This message brought to you by the "+
"letter "+s+" and the number "+num;
return returnValue;
}
/**
* This method is required by the EJB Specification,
* but is not used by this example.
*
*/
public void ejbActivate() {
log("ejbActivate called");
}
/**
* This method is required by the EJB Specification,
* but is not used by this example.
*
*/
public void ejbRemove() {
log("ejbRemove called");
}
/**
* This method is required by the EJB Specification,
* but is not used by this example.
*
*/
public void ejbPassivate() {
log("ejbPassivate called");
}
/**
* Sets the session context.
*
* @param ctx SessionContext Context for session
*/
public void setSessionContext(SessionContext ctx) {
log("setSessionContext called");
this.ctx = ctx;
}
/**
* This method is required by the EJB Specification,
* but is not used by this example.
*
*/
public void ejbCreate () throws CreateException {
log("ejbCreate called");
}
}
package examples.statelessSession;
import java.rmi.RemoteException;
import javax.ejb.EJBObject;
/**
* The methods in this interface are the public face of HelloWorld.
* The signatures of the methods are identical to those of the EJBean, except
* that these methods throw a java.rmi.RemoteException.
*
* @author Copyright (c) 2005 by BEA Systems. All Rights Reserved.
*/
public interface HelloWorld81 extends EJBObject {
/**
* Simply says hello from the EJB
*
* @param num int number to return
* @param s String string to return
* @return String returnValue
* @exception RemoteException if there is
* a communications or systems failure
*/
String sayHello(int num, String s)
throws RemoteException;
}
package examples.statelessSession;
import java.rmi.RemoteException;
import javax.ejb.CreateException;
import javax.ejb.EJBHome;
/**
* This interface is the Home interface of the HelloWorld stateless session EJB.
*
* @author Copyright (c) 2005 by BEA Systems. All Rights Reserved.
*/
public interface HelloWorldHome81 extends EJBHome {
/**
* This method corresponds to the ejbCreate method in the
* HelloWorldBean81.java file.
*/
HelloWorld81 create()
throws CreateException, RemoteException;
}
The differences between the 8.1 and 9.0 files are shown in bold. The value of some JWS annotations are taken from attributes of the 8.1 servicegen
Ant task shown in Example of an 8.1 and Updated 9.0 Ant Build File for an 8.1 EJB-Implemented Web Service
package examples.webservices.upgrade_ejb;
// Import the standard JWS annotations
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// Import the WebLogic specific annotation
import weblogic.jws.WLHttpTransport;
// Class-level annotations
@WebService(name="HelloWorld90PortType", serviceName="HelloWorldService",
targetNamespace="http://example.org")
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
@WLHttpTransport(contextPath="upgradeEJB", serviceUri="HelloWorldService",
portName="HelloWorld90Port")
/**
* HelloWorld90Impl is the JWS equivalent of the HelloWorld81 EJB that
* implemented the 8.1 Web Service. It has a single method,
* sayHello(), that takes an integer and a String and returns a String.
* <p>
* @author Copyright (c) 2005 by BEA Systems. All Rights Reserved.
*/
public class HelloWorld90Impl {
/** the sayHello method will become the public operation of the Web
* Service.
*/
@WebMethod()
public String sayHello(int num, String s) {
System.out.println("sayHello in the HelloWorld90 Web Service has "+
"been invoked with arguments " + s + " and " + num);
String returnValue = "This message brought to you by the "+
"letter "+s+" and the number "+num;
return returnValue;
}
}
The following simple build.xml
file shows the 8.1 way to build an EJB-implemented WebLogic Web Service using the servicegen
Ant task. Following this example is an equivalent build.xml
file that calls the jwsc
Ant task to build a 9.0 Web Service.
<project name="ejb-webservice" default="all" basedir=".">
<!-- set global properties for this build -->
<property name="source" value="."/>
<property name="build" value="${source}/build"/>
<property name="ejb_file" value="HelloWorldWS.jar" />
<property name="war_file" value="HelloWorldWS.war" />
<property name="ear_file" value="HelloWorldApp.ear" />
<property name="namespace" value="http://examples.org" />
<target name="all" depends="clean,ear"/>
<target name="clean">
<delete dir="${build}"/>
</target>
<!-- example of old 8.1 servicegen call to build Web Service -->
<target name="ejb">
<delete dir="${build}" />
<mkdir dir="${build}"/>
<mkdir dir="${build}/META-INF"/>
<copy todir="${build}/META-INF">
<fileset dir="${source}">
<include name="ejb-jar.xml"/>
</fileset>
</copy>
<javac srcdir="${source}" includes="HelloWorld*.java"
destdir="${build}" />
<jar jarfile="${ejb_file}" basedir="${build}" />
<wlappc source="${ejb_file}" />
</target>
<target name="ear" depends="ejb">
<servicegen
destEar="${build}/${ear_file}"
warName="${war_file}">
<service
ejbJar="${ejb_file}"
targetNamespace="${namespace}"
serviceName="HelloWorldService"
serviceURI="/HelloWorldService"
generateTypes="True"
expandMethods="True">
</service>
</servicegen>
</target>
</project>
An equivalent build.xml
file that calls the jwsc
Ant task to build a 9.0 Web Service is shown below, with the relevant tasks discussed in this section in bold:
<project name="webservices-upgrade_ejb" 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="upgradeEJB" />
<property name="example-output" value="output" />
<property name="ear-dir" value="${example-output}/upgradeEJB" />
<taskdef name="jwsc"
classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="wldeploy"
classname="weblogic.ant.taskdefs.management.WLDeploy"/>
<target name="all" depends="clean,build-service,deploy" />
<target name="clean" depends="undeploy">
<delete dir="${example-output}"/>
</target>
<target name="build-service">
<jwsc
srcdir="src"
destdir="${ear-dir}">
<jws file="examples/webservices/upgrade_ejb/HelloWorld90Impl.java" />
</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>
</project>
The following table maps the attributes of the 8.1 servicegen
Ant task to their equivalent 9.0 JWS annotation or jwsc
attribute.
The attributes listed in the first column are a mixture of attributes of the main servicegen
Ant task and attributes of the four child elements of servicegen
(<service>
, <client>
, <handlerChain>
, and <security>
)
See JWS Annotation Reference, and jwsc for more information about the 9.0 JWS annotations and jwsc
Ant task.
|
|
|
|
No direct equivalent, because the Indirect equivalent is the |
|
No direct equivalent, because the Indirect equivalent is the |
|
No equivalent because JMS-implemented Web Services are not supported in the 9.0 release. |
|
No equivalent because JMS-implemented Web Services are not supported in the 9.0 release. |
|
No equivalent because JMS-implemented Web Services are not supported in the 9.0 release. |
|
No equivalent because JMS-implemented Web Services are not supported in the 9.0 release. |
|
No equivalent because JMS-implemented Web Services are not supported in the 9.0 release. |
|
No equivalent because JMS-implemented Web Services are not supported in the 9.0 release. |
|
|
|
|
|
|
|
Use the |
|
Use WebLogic-specific |
|
Use WebLogic-specific |
|
Use WebLogic-specific See Configuring Message-Level Security (Digital Signatures and Encryption). |
|
Use WebLogic-specific See Configuring Message-Level Security (Digital Signatures and Encryption) |
|
Use WebLogic-specific See Configuring Message-Level Security (Digital Signatures and Encryption) |
|
Use WebLogic-specific See Configuring Message-Level Security (Digital Signatures and Encryption) |
|
Use WebLogic-specific See Configuring Message-Level Security (Digital Signatures and Encryption) |
|
Use WebLogic-specific See Configuring Message-Level Security (Digital Signatures and Encryption) |
|
Use WebLogic-specific See Configuring Message-Level Security (Digital Signatures and Encryption) |
![]() ![]() |
![]() |
![]() |