BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
| WebLogic Server Doc Home | Web Services | Previous Topic | Next Topic | Contents | Index | View as PDF

Invoking WebLogic Web Services

The following sections describe how to invoke WebLogic Web Services from client applications:

- Overview of Invoking WebLogic Web Services

- Invoking the WebLogic Web Services Home Page

- URLs to Invoke WebLogic Web Services and Get the WSDL

- Creating a Client to Invoke an RPC-Style WebLogic Web Service

- Creating a Java Client to Invoke a Message-Style WebLogic Web Service

- Handling Exceptions from WebLogic Web Services

- Initial Context Factory Properties for Invoking Web Services

- Additional Classes Needed by Clients Invoking WebLogic Web Services

Overview of Invoking WebLogic Web Services

Invoking a WebLogic Web Service refers to the actions that a client application performs to use the Web service. Client applications that invoke WebLogic Web Services can be written using any technology: Java, Microsoft SOAP Toolkit, and so on.

The client application assembles a SOAP message that describes the Web service it wants to invoke and includes all the necessary data in the body of the SOAP message. The client then sends the SOAP message over HTTP/HTTPS to WebLogic Server, which executes the Web service and sends a SOAP message back to the client over HTTP/HTTPS.

Note: If you write your client application in Java, WebLogic Server provides an optional Java client JAR file that includes, for your convenience, everything you need to invoke a WebLogic Web Service, such as the WebLogic Web Services Client API and WebLogic FastParser. Unlike other Java WebLogic Server clients, you do not need to include the weblogic.jar file, thus making for a very thin client. For details on downloading this JAR file, see Downloading the Java Client JAR File from the Web Services Home Page.

Each Web service has its own Home Page; Web services that share the same servlet context share this Web page. You use this Web page to get the WSDL and Java client JAR file for a Web service. See Invoking the WebLogic Web Services Home Page for details on this Web page and how to invoke it in your browser.

WebLogic Web Services Client API

WebLogic Server includes a client-side Java SOAP API in a Java client JAR file that you can download from a deployed WebLogic Web Service. Use this API to create Java client applications that invoke WebLogic Web Services. The examples in this book, as well as the examples on the product, use this API.

Warning: A standard client-side Web Service API specification from the W3C or JavaSoft is not yet available. Because the WebLogic Web Services client API has not yet been standardized in the Java community process, BEA Systems reserves the right to change how it works from one release to another, and may not be able to make it backward compatible.

The examples in this chapter briefly describe the main classes, interfaces, and methods of the WebLogic Web Services client API. For detailed documentation on the API, see the WebLogic Server API Reference and search for the weblogic.soap package.

Client Modes Supported by the WebLogic Web Services Client API

The WebLogic Web Services client API supports the following two modes of Java client applications that invoke WebLogic Web Services:

- Static: Static client applications explicitly use the EJB and JavaBean interfaces and classes that make up the Web service. These types of client applications are the most type-safe of the two modes supported by WebLogic Server, and are thus the type recommended by BEA. Additionally, static client applications do not contain any WebLogic-specific Java code. For an example of a static Java client application, see Writing a Static Java Client.

- Dynamic: Dynamic client applications do not explicitly reference the EJB interface of the Web service. For an example of a dynamic client application, see Writing a Dynamic Java Client.

Both the static and dynamic client applications described in this chapter use the WSDL of the Web service. See Invoking Web Services Without Using the WSDL File, for information on creating a client application that does not use the WSDL.

You can use both static and dynamic client applications to invoke either RPC-style or message-style Web services.

Examples of Clients That Invoke WebLogic Web Services

WebLogic Server includes examples of creating both RPC-style and message-style Web services and examples of both Java and Microsoft VisualBasic client applications that invoke the Web services.

The examples are located in the BEA_HOME/samples/examples/webservices directory, where BEA_HOME refers to the main WebLogic Server installation directory. The RPC-style Web service example is in the rpc directory and the message-style Web service example is in the message directory.

For detailed instructions on how to build and run the examples, invoke the Web page BEA_HOME/samples/examples/webservices/package-summary.html in your browser.

Invoking the WebLogic Web Services Home Page

The WebLogic Web Services Home Page lists the Web services defined for a particular servlet context along with the WSDL files and Java client JAR file associated with each Web service.

Use the following template URL to invoke the WebLogic Web Services Home Page in your browser:

>     [protocol]://[host]:[port]/[context]/index.html

where

- protocol refers to the protocol attribute of the <wsgen> element of the build.xml Ant file used to build the Web service. The two valid values are http (default) and https.

- host refers to the hostname of the computer which hosts the Web service.

- port refers to the port number of the WebLogic Server instance that hosts the Web service.

- context refers to the context attribute of the <wsgen> element of the build.xml Ant file used to build the Web service.

For example, assume that you built a Web service using the following build.xml file:

>     <project name="myProject" default="wsgen">
>        <target name="wsgen">
>           <wsgen
>                  destpath="myWebService.ear"
>                  context="/myContext"
>                  protocol="http">
>              <rpcservices path="myEJB.jar">
>                 <rpcservice
>                    bean="statelessSession"
>                    uri="/rpc_URI"/>
>              </rpcservices>
>              <messageservices>
>                <messageservice
>                  name="sendMsgWS"
>                  action="send"
>                  destination="examples.soap.msgService.MsgSend"
>                  destinationtype="topic"
>                  uri="/sendMsg"
>                  connectionfactory="examples.soap.msgService.MsgConnectionFactory"/>
>               <messageservice
>                  name="receiveMsgWS"
>                  action="receive"
>                  destination="examples.soap.msgService.MsgReceive"
>                  destinationtype="topic"
>                  uri="/receiveMsg"
>                  connectionfactory="examples.soap.msgService.MsgConnectionFactory"/>
>           </messageservices>
>           </wsgen>
>        </target>
>     </project>

The URL to invoke the WebLogic Web Services Home Page for the /myContext context on the myHost host at the default port of 7001 is:

>     http://www.myHost.com:7001/myContext/index.html

Getting the WSDL from the Web Services Home Page

To get the WSDL of a Web service from the Web Services Home Page:

1. Invoke the Web Services Home Page for your context in your browser, as described in Invoking the WebLogic Web Services Home Page.

2. Click the name of the Web service.

3. Click the WSDL File link. The WSDL file for the specified Web service appears in your browser in plain text.

Downloading the Java Client JAR File from the Web Services Home Page

WebLogic Server provides a Java client JAR file that contains most of the Java code you need to create a Java client application that invokes a WebLogic Web Service. In particular, the JAR file includes the WebLogic implementation of a client-side SOAP API, which means that you do not have to write the low-level Java code to create and process SOAP messages.

The Java client JAR file contains the following objects:

- WebLogic FastParser (high-performance XML parser)

- WebLogic Web Services Client API

- Remote interface of the stateless session EJB that implements the RPC-style Web service

- Class files for any JavaBeans that are used as EJB parameters or return values

- Additional class files specified by the clientjar element of the build.xml Java Ant build file used to assemble the Web service

Note: BEA does not currently license client functionality separately from the server functionality, so, if needed, you can redistribute this Java client JAR file to your own customers.

To download the Java client JAR file to your computer:

1. Invoke the Web Services Home Page for a given context in your browser, as described in Invoking the WebLogic Web Services Home Page.

2. Click the name of the Web service.

3. Click the Client JAR File link.

4. Specify a directory on your local computer in which to store the Java client JAR file.

5. Save the JAR file to the specified directory.

6. Update your CLASSPATH to include the Java client JAR file.

URLs to Invoke WebLogic Web Services and Get the WSDL

WSDL is used by client applications to describe the Web services they invoke.

The full URL to directly access the WSDL of a WebLogic Web Service is:

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

where

- protocol refers to the protocol attribute of the <wsgen> element of the build.xml Ant file used to build the Web service. By default this value is http.

- host refers to the hostname of the computer which hosts the Web service.

- port refers to the port number of the WebLogic Server instance that hosts the Web service.

- context refers to the context attribute of the <wsgen> element of the build.xml Ant file used to build the Web service.

- WSname is the name of the Web service:

  - For RPC-style Web services, the JNDI name of the stateless session EJB that implements the Web service.

    For example, if the bean attribute in the build.xml file specifies statelessSession, and the weblogic-ejb-jar.xml contains the following entry:

    >     <weblogic-enterprise-bean>
    >       <ejb-name>statelessSession</ejb-name>
    >       <jndi-name>statelessSession.WeatherHome</jndi-name>
    >     </weblogic-enterprise-bean>

    then the WSname value is statelessSession.WeatherHome.

  - For message-style Web services, the name of the Web service is specified by the name attribute of the messageservice element that defines the Web service in the build.xml file.

For example, using the sample build.xml file listed in Invoking the WebLogic Web Services Home Page, the URL to access the WSDL for the RPC-style Web service is:

>     http://www.myHost.com:7001/myContext/statelessSession.WeatherHome/statelessSess
>     ion.WeatherHome.wsdl

Similarly, the URLs to access the WSDL for the two message-style Web services are:

>     http://www.myHost.com:7001/myContext/sendMsgWS/sendMsgWS.wsdl
>     http://www.myHost.com:7001/myContext/receiveMsgWS/receiveMsgWS.wsdl

Creating a Client to Invoke an RPC-Style WebLogic Web Service

This section describes how to invoke an RPC-style Web service from two types of clients: Java and Microsoft SOAP ToolKit.

The examples in this section invoke an RPC-style Web service that is based on the Trader stateless session EJB described in the examples.ejb.basic.statelessSession WebLogic Server example.

Writing a Java Client

Creating a Java client application to invoke a WebLogic Web Service is simple because almost all of the Java code you need is provided by WebLogic Server and packaged in a Java client JAR file that you can download onto your client computer.

This section describes two modes of client applications: static and dynamic. Use a static client if you have the Java interfaces of the EJB and JavaBean parameters and return types, and want to use them directly in your client Java code. Use a dynamic client if you do not have the interfaces.

Writing a Static Java Client

The following example shows a simple static Java client that invokes an RPC-style Web service based on the examples.ejb.basic.statelessSession EJB example in WebLogic Server.

The example uses the URL http://www.myhost.com:7001/myContext/statelessSession/statelessSession.wsdl to get the WSDL of the Web Service. For details on how to construct this URL and an example of the build.xml file used to create the RPC-style Web service, refer to URLs to Invoke WebLogic Web Services and Get the WSDL.

The procedure after the example discusses relevant sections of the example as part of the basic steps you must follow to create this client.

>     import java.util.Properties;
>     import javax.naming.Context;
>     import javax.naming.InitialContext;

>     import examples.ejb.basic.statelessSession.Trader;
>     import examples.ejb.basic.statelessSession.TradeResult;

>     public class Client{

>       public static void main( String[] arg ) throws Exception

>         Properties h = new Properties();

>         h.put(Context.INITIAL_CONTEXT_FACTORY,
>              "weblogic.soap.http.SoapInitialContextFactory");

>         h.put("weblogic.soap.wsdl.interface",
>              Trader.class.getName() );

>         Context context = new InitialContext(h);

>         Trader service = (Trader)context.lookup(
>      "http://www.myHost.com:7001/myContext/statelessSession/statelessSession.wsdl"
>     );

>         TradeResult result = (TradeResult)service.buy( "BEAS", 100 );

>         System.out.print( result.getStockSymbol() );
>         System.out.print( ":" );
>         System.out.println( result.getNumberTraded() );
>       }
>     }

The Java code to statically invoke a WebLogic Web Service is similar to remote method invocation (RMI) client code that invokes EJBs. The main differences are:

- You do not need to look up and invoke the Home interface of the service.

- The Web service client uses a SOAP-specific INITIAL_CONTEXT_FACTORY.

- The Web service client specifies the interface in the parameters to the INITIAL_CONTEXT_FACTORY.

Follow these steps to create a static Java client that invokes an RPC-style WebLogic Web Service:

1. Get the Java client JAR file from the WebLogic Server hosting the WebLogic Web Service.

   For detailed information on this step, refer to Downloading the Java Client JAR File from the Web Services Home Page.

2. Add the Java client JAR file to your CLASSPATH on your client computer.

3. Create the client Java program. The following steps point out the Web service-specific parts of the Java code:

   1. Within the main method of your client application, add the following Java code to initialize the client so it can interact with the Web service:

      >     Properties h = new Properties();

      >     h.put(Context.INITIAL_CONTEXT_FACTORY,
      >          "weblogic.soap.http.SoapInitialContextFactory");

      >     h.put("weblogic.soap.wsdl.interface",
      >          Trader.class.getName() );

      >     Context context = new InitialContext(h);

      >     Trader service = (Trader)context.lookup(
      >     "http://www.myHost.com:7001/myContext/statelessSession/state
      >     lessSession.wsdl" );

      In the example, Trader is the public interface to the EJB. Refer to URLs to Invoke WebLogic Web Services and Get the WSDL for details on how to construct the URL used in the context.lookup() method.

   2. Invoke a Web service operation by executing a public method of the EJB, as shown in the following example:

      >     TradeResult result = (TradeResult)service.buy( "BEAS", 100 );

      The client executes the buy() method of the Trader EJB. The returned value is a TraderResult JavaBean object. To find out the public methods of the Trader EJB, either examine the returned WSDL of the Web service, or un-JAR the downloaded Java client JAR file and use the javap utility to list the methods of the Trader interface.

   3. Use the get methods of the returned TraderResult JavaBean to get the returned results. To find out the methods of the TraderResult class, unJAR the Java client jar file and use the javap utility to list the methods of the TraderResult class.

      >     System.out.print( result.getStockSymbol() );
      >     System.out.print( ":" );
      >     System.out.println( result.getNumberTraded() );

4. Compile and run the client Java program as usual.

Writing a Dynamic Java Client

The following example shows a simple dynamic Java client that invokes an RPC-style Web service based on the examples.ejb.basic.statelessSession EJB example in WebLogic Server.

The example uses the URL http://www.myhost.com:7001/myContext/statelessSession/statelessSession.wsdl to get the WSDL of the Web Service. For details on how to construct this URL and an example of the build.xml file used to create the RPC-style Web service, refer to URLs to Invoke WebLogic Web Services and Get the WSDL.

The procedure after the example discusses relevant sections of the example as part of the basic steps you must follow to create this client.

>     import java.util.Properties;
>     import javax.naming.Context;
>     import javax.naming.InitialContext;

>     import examples.ejb.basic.statelessSession.TradeResult;

>     import weblogic.soap.WebServiceProxy;
>     import weblogic.soap.SoapMethod;

>     public class DynamicClient{

>       public static void main( String[] arg ) throws Exception{

>         Properties h = new Properties();

>         h.put(Context.INITIAL_CONTEXT_FACTORY,
>              "weblogic.soap.http.SoapInitialContextFactory");

>           Context context = new InitialContext(h);

>         WebServiceProxy proxy = (WebServiceProxy)context.lookup(

>     "http://www.myHost.com:7001/myContext/statelessSession/statelessSession.wsdl" );

>         SoapMethod method = proxy.getMethod( "buy" );

>         TradeResult result = (TradeResult)method.invoke(
>              new Object[]{ "BEAS", new Integer(100) } );

>         System.out.print( result.getStockSymbol() );
>         System.out.print( ":" );
>         System.out.println( result.getNumberTraded() );
>       }
>     }

Follow these steps to create a dynamic Java client that invokes an RPC-style WebLogic Web Service:

1. Get the Java client JAR file from the WebLogic Server hosting the WebLogic Web Service.

   For detailed information on this step, refer to Downloading the Java Client JAR File from the Web Services Home Page.

2. Add the Java client JAR file to your CLASSPATH on your client computer.

3. Create the client Java program. The following steps point out the Web service-specific parts of the Java code:

   1. Within the main method of your client application, add the following Java code to initialize the client so it can interact with the Web service:

      >     Properties h = new Properties();

      >     h.put(Context.INITIAL_CONTEXT_FACTORY,
      >          "weblogic.soap.http.SoapInitialContextFactory");

      >     Context context = new InitialContext(h);

      >     WebServiceProxy proxy = (WebServiceProxy)context.lookup(
      >     "http://www.myHost.com:7001/myContext/statelessSession/state
      >     lessSession.wsdl" );

      In the example, the context.lookup() method returns a generic WebServiceProxy object rather than a specific Trader object; this makes the example more dynamic because WebServiceProxy can represent any EJB object. Refer to URLs to Invoke WebLogic Web Services and Get the WSDL for details on how to construct the URL used in the context.lookup() method.

   2. Invoke the Web service operation by executing a public method of the EJB, as shown in the following example:

      >     SoapMethod method = proxy.getMethod( "buy" );

      >     TradeResult result = (TradeResult)method.invoke(
      >          new Object[]{ "BEAS", new Integer(100) } );

      The client indirectly executes the buy() method of the Trader EJB using the invoke() method. The returned value is a TraderResult JavaBean object. To find out the public methods of the Trader EJB, either examine the returned WSDL of the Web service or unJAR the downloaded Java client jar and use the javap utility to list the methods of the Trader interface.

   3. Use the get methods of the returned TraderResult JavaBean to get the returned results. To find out the methods of the TraderResult class, unJAR the Java client jar file and use the javap utility to list the methods of the TraderResult class.

      >     System.out.print( result.getStockSymbol() );
      >     System.out.print( ":" );
      >     System.out.println( result.getNumberTraded() );

4. Compile and run the client Java program as usual.

Writing a Microsoft SOAP Toolkit Client

You can invoke WebLogic Web Services from Microsoft Visual Basic applications by using the client-side components provided by the Microsoft SOAP ToolKit.

Note: WebLogic Server 6.1 supports only version 2.0sp2 of Microsoft SOAP ToolKit

The following sample Visual Basic code shows a simple example of invoking the WebLogic Web Service described by the examples.webservices.rpc example:

>     SET soapclient = CreateObject("MSSOAP.SoapClient")

>     Call soapclient.mssoapinit(

>     "http://myhost:7001/weather/statelessSession.WeatherHome/statelessSession.Weath
>     erHome.wsdl", "Weather", "WeatherPort")

>     wscript.echo soapclient.getTemp(94117)

To invoke a WebLogic Web Service from a Visual Basic application using the Microsoft SOAP ToolKit, follow these main steps:

1. Instantiate a SoapClient object in your Visual Basic application.

2. Initialize the SoapClient object by executing the SoapClient.mssoapinit() method, passing it the following parameters:

   - URL of the WSDL of the WebLogic Web Service. See URLs to Invoke WebLogic Web Services and Get the WSDL for details on constructing this URL.

   - Name of the Web service, identified by the name attribute of the service element in the WSDL file.

   - Port of the Web service, identified by the name attribute of the port element in the WSDL file.

     After the SoapClient object is initialized, all the methods defined in the WSDL are dynamically bound to the SoapClient object.

3. Execute the WebLogic Web Service method.

Creating a Java Client to Invoke a Message-Style WebLogic Web Service

This section describes how to invoke message-style Web services from a Java client application.

Creating a Java client application to invoke a message-style WebLogic Web Service is simple because almost all of the Java code you need is provided by WebLogic Server and packaged in a Java client JAR file that you can download onto your client computer.

This section describes two types of Java clients: one that invokes a message-style Web service that sends data to WebLogic Server and one that invokes a message-style Web service that receives data. Both examples show how to create a dynamic Java client.

Note: The send and receive actions are from the perspective of the client application.

It is assumed that the two message-style Web services in the examples were assembled using the following build.xml file:

>     <project name="myProject" default="wsgen">
>        <target name="wsgen">
>          <wsgen
>            destpath="messageExample.ear"
>            context="/msg"
>            protocol="http" >
>            <messageservices>
>              <messageservice
>                action="send"
>                name="Sender"
>                destination="examples.soap.msgService.MsgSend"
>                destinationtype="topic"
>                uri="/sendMsg"
>                connectionfactory="examples.soap.msgService.MsgConnectionFactory"/>
>              <messageservice
>                action="receive"
>                name="Receiver"
>                destination="examples.soap.msgService.MsgReceive"
>                destinationtype="topic"
>                uri="/receiveMsg"
>                connectionfactory="examples.soap.msgService.MsgConnectionFactory"/>

>              </messageservices>
>           </wsgen>
>        </target>
>     </project>

The build.xml file shows two message-style Web services: one named Sender that client applications use to send data to a JMS topic with the JNDI name examples.soap.msgService.MsgSend and one named Receiver that client applications use to receive data from a JMS topic with the JNDI name examples.soap.msgService.MsgReceive. Both message-style Web services use the same ConnectionFactory to create the JMS connection: examples.soap.msgService.MsgConnectionFactory.

Sending Data to a Message-Style Web Service

This section describes how to create a dynamic Java client application that invokes a Web service to send data to WebLogic Server. For the sake of simplicity, the example sends a String data type that will contain the data.

Note: For a more complex example that shows how to send a org.w3c.dom.Document, org.w3c.dom.DocumentFragment, or org.w3c.dom.Element data type to the send method, see Invoking Web Services Without Using the WSDL File.

Message-style Web services that send data to WebLogic Server define a single method called send; this is the only method you need to invoke from your Java client application. The send method takes a single parameter: the actual data. The data type can be anything you want: a String (used in the example), a DOM tree, an InputStream, etc. The data will eventually end up on the JMS destination you specify in the build.xml file used to assemble the Web service.

The example uses the URL http://localhost:7001/msg/Sender/Sender.wsdl to get the WSDL of the Web Service. For details on how to construct this URL, refer to URLs to Invoke WebLogic Web Services and Get the WSDL.

The procedure after the example discusses relevant sections of the example as part of the basic steps you follow to create this client.

>     package examples.soap;

>     import java.util.Properties;
>     import java.net.URL;
>     import javax.naming.Context;
>     import javax.naming.InitialContext;

>     import weblogic.soap.WebServiceProxy;
>     import weblogic.soap.SoapMethod;
>     import weblogic.soap.SoapType;
>     import weblogic.soap.codec.CodecFactory;
>     import weblogic.soap.codec.SoapEncodingCodec;

>     public class ProducerClient{

>       public static void main( String[] arg ) throws Exception{

>         Properties h = new Properties();

>         h.put(Context.INITIAL_CONTEXT_FACTORY,
>              "weblogic.soap.http.SoapInitialContextFactory");
>         h.put("weblogic.soap.verbose", "true" );

>         CodecFactory factory = CodecFactory.newInstance();
>         factory.register( new SoapEncodingCodec() );
>         h.put( "weblogic.soap.encoding.factory", factory );

>         Context context = new InitialContext(h);

>         WebServiceProxy proxy = (WebServiceProxy)context.lookup(
>         "http://localhost:7001/msg/Sender/Sender.wsdl" );
>         SoapMethod method = proxy.getMethod( "send" );

>         String toSend = arg.length == 0 ? "No arg to send" : arg[0];
>         Object result = method.invoke( new Object[]{ toSend } );

>       }

>     }

Follow these steps to create a dynamic Java client that invokes a message-style WebLogic Web Service that sends data to WebLogic Server:

1. Get the Java client JAR file from the WebLogic Server hosting the WebLogic Web Service.

   For detailed information on this step, refer to Downloading the Java Client JAR File from the Web Services Home Page.

2. Add the Java client JAR file to your CLASSPATH on your client computer.

3. Create the client Java program. The following steps point out the Web service-specific parts of the Java code:

   1. In the main method of your client application, create a Properties object and set some of the initial context properties:

      >        Properties h = new Properties();

      >         h.put(Context.INITIAL_CONTEXT_FACTORY,
      >              "weblogic.soap.http.SoapInitialContextFactory");
      >         h.put("weblogic.soap.verbose", "true" );

   2. Create a factory of encoding styles and register the SOAP encoding style:

      >         CodecFactory factory = CodecFactory.newInstance();
      >         factory.register( new SoapEncodingCodec() );
      >         h.put( "weblogic.soap.encoding.factory", factory );

   3. Create the initial context, use the WSDL to look up the Web service, then get the send method:

      >         Context context = new InitialContext(h);

      >         WebServiceProxy proxy = (WebServiceProxy)context.lookup(
      >         "http://localhost:7001/msg/Sender/Sender.wsdl" );
      >         SoapMethod method = proxy.getMethod( "send" );

   4. Invoke the send method and send data to the Web service. In the example, the client application simply takes its first argument and sends it as a String; if the user does not specify an argument specified, then the client application sends the string No arg to send:

      >         String toSend = arg.length == 0 ? "No arg to send" : arg[0];
      >         Object result = method.invoke( new Object[]{ toSend } );

4. Compile and run the client Java program as usual.

Receiving Data From a Message-Style Web Service

This section describes how to create a dynamic Java client application that invokes a Web service to receive data from WebLogic Server.

Message-style Web services that receive data from WebLogic Server define a single method called receive; this is the only method you need to invoke from your Java client application. The receive method takes no input parameters. It returns a generic Java object that contains the data that the Web service got from the JMS destination you specify in the build.xml file used to assemble the Web service.

The example in this section uses the URL http://localhost:7001/msg/Receiver/Receiver.wsdl to get the WSDL of the Web Service. For details on how to construct this URL, refer to URLs to Invoke WebLogic Web Services and Get the WSDL.

The procedure after the example discusses relevant sections of the example as part of the basic steps you follow to create this client.

>     package examples.soap;

>     import java.util.Properties;
>     import java.net.URL;
>     import javax.naming.Context;
>     import javax.naming.InitialContext;

>     import weblogic.soap.WebServiceProxy;
>     import weblogic.soap.SoapMethod;
>     import weblogic.soap.SoapType;
>     import weblogic.soap.codec.CodecFactory;
>     import weblogic.soap.codec.SoapEncodingCodec;

>     public class ConsumerClient{

>       public static void main( String[] arg ) throws Exception{

>         Properties h = new Properties();
>         h.put(Context.INITIAL_CONTEXT_FACTORY,
>              "weblogic.soap.http.SoapInitialContextFactory");
>         h.put("weblogic.soap.verbose", "true" );

>         CodecFactory factory = CodecFactory.newInstance();
>         factory.register( new SoapEncodingCodec() );
>         h.put( "weblogic.soap.encoding.factory", factory );

>         Context context = new InitialContext(h);

>         WebServiceProxy proxy = (WebServiceProxy)context.lookup(
>         "http://localhost:7001/msg/Receiver/Receiver.wsdl" );
>         SoapMethod method = proxy.getMethod( "receive" );

>         while( true ){
>           Object result = method.invoke( null );
>           System.out.println( result );
>         }
>       }
>     }

Follow these steps to create a dynamic Java client that invokes a message-style WebLogic Web Service that receives data from WebLogic Server:

1. Get the Java client JAR file from the WebLogic Server hosting the WebLogic Web Service.

   For detailed information on this step, refer to Downloading the Java Client JAR File from the Web Services Home Page.

2. Add the Java client JAR file to your CLASSPATH on your client computer.

3. Create the client Java program. The following steps point out the Web service-specific parts of the Java code:

   1. In the main method of your client application, create a Properties object and set some of the initial context properties:

      >         Properties h = new Properties();
      >         h.put(Context.INITIAL_CONTEXT_FACTORY,
      >              "weblogic.soap.http.SoapInitialContextFactory");
      >         h.put("weblogic.soap.verbose", "true" );

   2. Create a factory of encoding styles and register the SOAP encoding style:

      >         CodecFactory factory = CodecFactory.newInstance();
      >         factory.register( new SoapEncodingCodec() );
      >         h.put( "weblogic.soap.encoding.factory", factory );

   3. Create the initial context, use the WSDL to look up the Web service , then get the receive method:

      >         Context context = new InitialContext(h);

      >         WebServiceProxy proxy = (WebServiceProxy)context.lookup(
      >         "http://localhost:7001/msg/Receiver/Receiver.wsdl" );
      >         SoapMethod method = proxy.getMethod( "receive" );

   4. Invoke the receive method to receive data from the Web service. In the example, the client application uses an infinite while loop to continuously invoke the receive method, in essence polling the JMS destination for messages. When the receive method returns data, the client application prints the result to the standard output:

      >         while( true ){
      >           Object result = method.invoke( null );
      >           System.out.println( result );

4. Compile and run the client Java program as usual.

Handling Exceptions from WebLogic Web Services

If an exception occurs while WebLogic Server is executing a Web service, the client application that invoked the Web service receives a run-time weblogic.soap.SoapFault exception that describes a standard SOAP fault.

The following types of exceptions in WebLogic Server could produce a run-time SoapFault exception in the client application:

- An exception from the stateless session EJB that implements an RPC-style Web service

- An exception from the SOAP servlets that handle the SOAP messages between the client application and WebLogic Web Services

- A JMS exception

If your client application receives a SoapFault exception, use the following methods of weblogic.soap.SoapFault to examine it:

- getFaultCode()—returns the SOAP faultcode.

- getFaultString()—returns the name of the class or interface that raised the exception in WebLogic Server. For example, if the stateless session EJB that comprises an RPC-style Web service raised an exception, the getFaultString() method returns the interface of this EJB.

- printStackTrace()—returns the stack trace of the exception.

The following excerpt from a Java client application shows an example of using weblogic.soap.SoapFault to examine any errors that occurred on WebLogic Server:

>     import weblogic.soap.SoapFault;

>     ...

>      try {
>         TradeResult result = (TradeResult)method.invoke(
>            new Object[]{ "BEAS", new Integer(100) } );

>         System.out.print( result.getStockSymbol() );
>         System.out.print( ":" );
>         System.out.println( result.getNumberTraded() );
>      } catch (SoapFault fault){
>         System.out.println( "Ooops, got a fault: " + fault );
>         fault.printStackTrace();
>        }

Initial Context Factory Properties for Invoking Web Services

The following table lists the Java properties you can set with the Properties object when you use the WebLogic-generated Java client JAR file in your Java client applications to invoke a WebLogic Web Service.

Note: The properties are passed to the initial context factory; these are not Java system properties.

Table 3-1 Initial Context Factory Properties for Invoking Web Services

Property | Description
--- | ---
weblogic.soap.wsdl.interface | Specifies the interface of the stateless session EJB upon which the Web service is based.
weblogic.soap.verbose | When set to true, the SOAP packet generated by the Java client to invoke a WebLogic Web Service is output to the client. Valid values are true and false (default).
weblogic.soap.encoding.factory | Specifies the CodecFactory that contains the encoders and decoders to convert between XML and Java data. Valid values are instances of weblogic.soap.codec.CodecFactory.
java.naming.factory.initial | Specifies the initial SOAP context factory. Valid values are instances of weblogic.soap.http.SoapInitialContextFactory
java.naming.security.principal | Specifies the user name when setting HTTP security.
java.naming.security.credentials | Specifies the user password when setting HTTP security.

Additional Classes Needed by Clients Invoking WebLogic Web Services

WebLogic Web Services support the following two encoding styles:

- http://schemas.xmlsoap.org/soap/encoding/

- http://xml.apache.org/xml-soap/literalxml

If your Java client application uses the SOAP encoding, then the Java client JAR file that you download from WebLogic Server includes all the classes you need to invoke a WebLogic Web Service.

However, if your client application uses the Literal XML encoding from Apache, then the Java client JAR file does not include all the files you need. The client JAR file is meant to be small, and adding all these classes to the JAR file would make it very large.

The following list shows some of the additional classes you might need to include:

- weblogic.apache.Xerces.*

- weblogic.xml.jaxp.*

- org.w3c.dom.*

- org.w3c.sax.*

- javax.xml.parsers.*

You can include these classes by either setting your CLASSPATH environment variable to their location when you run the client application or by using the clientjar element in the build.xml file when assembling the Web service using the wsgen Java Ant task.

To get the complete list of classes your client application needs, compile the application and then execute it with the -verbose flag, which will list all the classes it needs.

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.