Manually Assembling the Web Services Archive File

 

The following sections describe how to assemble a Web service manually into an Enterprise Application *.ear archive file:

• Before You Begin

• Description of the Web Services Archive File

• Assembling an RPC-Style Web Service Archive File Manually

• Assembling a Message-Style Web Service Archive File Manually

• Creating the client.jar File Manually

 

---

Before You Begin

WebLogic Web Services are packaged as standard J2EE Enterprise application archive files (*.ear). Assembling a WebLogic Web Service archive file manually can be complicated. For this reason, BEA highly recommends that you use the wsgen Java Ant task to create an initial *.ear file. Then, if needed, you can customize the components contained within the archive file for your specific application. For details on using wsgen, see Assembling a WebLogic Web Service.

You might need to manually create or edit the Enterprise application archive file if:

• you want to integrate the archive with a J2EE deployment tool.

• you need to perform advanced configuration tasks on components of the archive that are not available through the wsgen Ant task. These tasks include securing the SOAP servlets, securing the EJB, and so on.

• you want to change the default naming conventions and directories that the wsgen Ant task uses.

The following procedures shows how to create an Enterprise application archive similar to the one that the wsgen Java Ant task creates. If you follow the naming conventions exactly, the instructions in other chapters of this guide that describe how to access the WSDL of a Web service, the client.jar file, etc, will continue to work correctly.

 

---

Description of the Web Services Archive File

The Enterprise application archive contains the following components:

• A Web application, packaged in a *.war file that contains, among other items:

  • An HTML Web page that corresponds to the Web Services Home Page that lists all the Web services packaged in this Enterprise application archive.

  • For each Web service, an HTML Web page that includes links to the WSDL and client JAR file of the Web service.

  • For each Web service, a WSDL JSP that returns the WSDL.

  • The web.xml and weblogic.xml deployment descriptor files that contain Web services-specific information, such as references to the SOAP servlets that process the SOAP requests from the client.

• The stateless session EJB *.jar file (for RPC-style Web services).

• Other supporting EJB *.jar files.

 

---

Assembling an RPC-Style Web Service Archive File Manually

This section describes how to assemble an RPC-style Web service manually into an Enterprise application *.ear file that can be deployed on WebLogic Server.

Note: It is assumed that you have already created the stateless session EJB which implements the RPC-style Web service and assembled it into a *.jar EJB archive file. For detailed information about programming and assembling stateless session EJBs, see Programming WebLogic Enterprise JavaBeans.

To assemble an RPC-style Web service archive file manually, follow these steps:

1. Create a temporary staging directory for assembling the Web application component. You can name this directory anything you want.

2. Set up your shell environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory BEA_HOME\config\domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

   On UNIX, execute the setEnv.sh command, located in the directory BEA_HOME/config/domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

3. Execute the following command to automatically generate initial web.xml and weblogic.xml deployment descriptors in the WEB-INF subdirectory:

   java weblogic.ant.taskdefs.war.DDInit staging-dir
   

   where staging-dir refers to the staging directory.

   For more information on the Java-based DDInit utility for generating deployment descriptors, see Developing WebLogic Server Applications.

4. Edit the WEB-INF/web.xml file, adding WebLogic Web Services information, such as references to the SOAP servlets. For details, see Updating the web.xml File for RPC-Style Web Services in this appendix.

5. Edit the WEB-INF/weblogic.xml file, adding WebLogic Web Services information. For details, see Updating the weblogic.xml File for RPC-Style Web Services in this appendix.

6. In the main staging directory, create a sub-directory with the same name as the JNDI name of your stateless session EJB.

   The JNDI name of your EJB corresponds to the jndi-name element in the weblogic-ejb-jar.xml deployment descriptor file for your EJB.

   Note: Using the JNDI name is the wsgen Ant task naming convention, which you do not have to follow.

7. In the jndi-name subdirectory, create the WSDL JSP by running the following utility and redirecting the output to a file:

   java weblogic.soap.wsdl.Remote2WSDL EJB_interface path -protocol protocol > 
   wsdl.jsp
   

   where

   • EJB_interface refers to the fully qualified class name of the Remote interface of your stateless session EJB.

   • path is either context or context/jndi-name, where context refers to the context-root element of the Web application in the application.xml file (to be created in a later step).

   • protocol is either http or https.

     Note: This generated WSDL JSP dynamically sets the host and port of the WebLogic Server upon which the Web service is currently running. This is typically the type of WSDL file you want in your Web service. If, however, you want to statically specify the host and port in the WSDL file, edit the soap:address element in the WSDL JSP, replacing the text <%= request.getServerName() %>:<%= request.getServerPort() %> with hard-coded host and port values.

8. In the jndi-name subdirectory, create an index.html file that contains links to the WSDL JSP you created in the preceding step and the client JAR file that you will create in a later step. The following example shows a simple index.html file:

   <html>
   <body>
   <h3>jndi-name</h3>
   <ul>
   <li><a href='wsdl.jsp'>WSDL</a></li>
   <li><a href='../client.jar'>client.jar</li>
   </ul>
   </body>
   </html>
   

9. Create a client.jar file in the main staging directory. For details on creating this file, refer to Creating the client.jar File Manually in this appendix.

   Note: This step is optional. You only need to create a client.jar file if you are going to use a Java client application to invoke the Web service.

10. Create an index.html file in the main staging directory that lists the Web service in this Enterprise application archive and links to its index.html file that you created in a previous step. The following example shows a simple index.html file:

    <html>
    <body>
    <h3>RPC-Style Web Services</h3>
    <ul>
    <li><a href='/context/jndi-name/index.html'>jndi-name</a></li>
    </ul>
    </body>
    </html>
    

    In the example, context refers to the context-root element of the Web application in the application.xml file (to be created in a later step) and jndi-name refers to the name of sub-directory that contains the WSDL file you created in the previous step.

11. Create the Web application archive (*.war file) using a jar command such as:

    jar cvf web-app-name.war -C staging-dir .
    

    Note: The wsgen Java ant task assigns the default name web-services.war to the Web application *.war file. You do not have to follow this naming convention.

12. Create a second temporary staging directory for assembling the Enterprise application. You can name this directory anything you want.

13. Copy your stateless session EJB *.jar file into the second staging directory.

14. Copy the Web application archive *.war file you created in a previous step into the second staging directory.

15. Execute the following command to automatically generate an initial application.xml deployment descriptor in the META-INF subdirectory:

    java weblogic.ant.taskdefs.ear.DDInit staging-dir
    

    where staging-dir refers to the second staging directory.

    For more information on the Java-based DDInit utility for generating deployment descriptors, see Developing WebLogic Server Applications.

16. Edit the META-INF/application.xml file, adding WebLogic Web Services information. For details, see Updating the application.xml File for RPC-Style Web Services in this appendix.

17. Create the Enterprise Archive (.ear file) for the application, using a jar command such as:

    jar cvf application.ear -C staging-dir .
    

    You can deploy the resulting .ear file as a WebLogic Web Service through the Administration Console or the weblogic.deploy command-line utility.

Updating the web.xml File for RPC-Style Web Services

This section describes the elements you must update or add to the web.xml deployment descriptor for the Web application that references the SOAP servlets in an RPC-style WebLogic Web Services archive file. For the complete example of a web.xml deployment descriptor, see the last example in this section.

It is assumed that you have a basic understanding of Web applications and their deployment descriptors. For more information, see Assembling and Configuring Web Applications.

To update a web.xml file for RPC-style Web services, add the following elements:

• A <servlet> element that references the SOAP servlet that delegates RPC-style SOAP requests to the EJB. Set the <servlet-class> element to weblogic.soap.server.servlet.StatelessBeanAdapter. The servlet takes one <init-param>: a reference to the stateless session EJB which comprises the RPC-style Web service. The following example shows a <servlet> entry for the SOAP servlet:

  <servlet>
    <servlet-name>statelessSession.WeatherHome</servlet-name>
    <servlet-class>
         weblogic.soap.server.servlet.StatelessBeanAdapter
    </servlet-class>
    <init-param>
      <param-name>ejb-ref</param-name>
      <param-value>statelessSession.WeatherHome</param-value>
    </init-param>
  </servlet>
  

• A <servlet> element that references the SOAP servlet that handles all SOAP faults. Set the <servlet-class> element to weblogic.soap.server.servlet.FaultHandler, as shown in the following example:

  <servlet>
     <servlet-name>
       statelessSession.WeatherHomeFault
     </servlet-name>
      <servlet-class>
          weblogic.soap.server.servlet.FaultHandler
     </servlet-class>
  </servlet>
  

• A <servlet> element that references the WSDL JSP, as shown in the following example:

  <servlet>
      <servlet-name>
         statelessSession.WeatherHomeWSDL
      </servlet-name>
      <jsp-file>
          /statelessSession.WeatherHome/wsdl.jsp
      </jsp-file>
  </servlet>
  

  The path to the JSP file, <jsp-file>, is the path in your Web application archive file to the WSDL JSP you created in Assembling an RPC-Style Web Service Archive File Manually in this appendix.

• For each of the preceding <servlet> elements, create a <servlet-mapping> element to map a URL to the servlet, as shown in the following example:

  <servlet-mapping>
    <servlet-name>statelessSession.WeatherHome</servlet-name>
    <url-pattern>/weatheruri</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>
         statelessSession.WeatherHomeFault
    </servlet-name>
    <url-pattern>/weblogic/webservice/fault</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>
          statelessSession.WeatherHomeWSDL
    </servlet-name>
    <url-pattern>
  /statelessSession.WeatherHome/statelessSession.WeatherHome.wsdl
    </url-pattern>
  </servlet-mapping>
  

• An <error-page> element:

  <error-page>
      <exception-type>
         weblogic.soap.FaultException
      </exception-type>
      <location>/weblogic/webservice/fault</location>
    </error-page>
  

• An <ejb-ref> element which references the stateless session EJB that implements the Web service, as shown in the following example:

  <ejb-ref>
    <description>Web Service EJB</description>
    <ejb-ref-name>statelessSession.WeatherHome</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <home>examples.webservices.rpc.weatherEJB.WeatherHome</home>
    <remote>examples.webservices.rpc.weatherEJB.Weather</remote>
  </ejb-ref>
  

The following complete sample web.xml deployment descriptor contains elements for the RPC-style Web service example examples.webservices.rpc:

<!DOCTYPE web-app 
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 
           "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">
<web-app>
  <servlet>
    <servlet-name>statelessSession.WeatherHome</servlet-name>
    <servlet-class>
         weblogic.soap.server.servlet.StatelessBeanAdapter
    </servlet-class>
    <init-param>
      <param-name>ejb-ref</param-name>
      <param-value>statelessSession.WeatherHome</param-value>
    </init-param>
  </servlet>
  <servlet>
    <servlet-name>statelessSession.WeatherHomeFault</servlet-name>
    <servlet-class>weblogic.soap.server.servlet.FaultHandler</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>statelessSession.WeatherHomeWSDL</servlet-name>
    <jsp-file>
         /statelessSession.WeatherHome/wsdl.jsp
    </jsp-file>
  </servlet>
  <servlet-mapping>
    <servlet-name>statelessSession.WeatherHome</servlet-name>
    <url-pattern>/weatheruri</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>statelessSession.WeatherHomeFault</servlet-name>
    <url-pattern>/weblogic/webservice/fault</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>statelessSession.WeatherHomeWSDL</servlet-name>
    <url-pattern>
         /statelessSession.WeatherHome/statelessSession.WeatherHome.wsdl
    </url-pattern>
  </servlet-mapping>
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
  </welcome-file-list>
  <error-page>
    <exception-type>weblogic.soap.FaultException</exception-type>
    <location>/weblogic/webservice/fault</location>
  </error-page>
  <ejb-ref>
    <description>This bean is exported as a WebService</description>
    <ejb-ref-name>statelessSession.WeatherHome</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <home>examples.webservices.rpc.weatherEJB.WeatherHome</home>
    <remote>examples.webservices.rpc.weatherEJB.Weather</remote>
  </ejb-ref>
</web-app>

Updating the weblogic.xml File for RPC-Style Web Services

The weblogic.xml deployment descriptor for RPC-style Web services does not contain any Web services-specific elements. It contains standard references to the stateless session EJB that implements the Web service.

The following sample weblogic.xml deployment descriptor contains elements for the RPC-style Web service example examples.webservices.rpc:

<!DOCTYPE weblogic-web-app 
         PUBLIC "-//BEA Systems, Inc.//DTD Web Application 6.0//EN"
        "http://www.beasys.com/j2ee/dtds/weblogic-web-jar.dtd">

<weblogic-web-app>
  <reference-descriptor>
    <ejb-reference-description>
      <ejb-ref-name>statelessSession.WeatherHome</ejb-ref-name>
      <jndi-name>statelessSession.WeatherHome</jndi-name>
    </ejb-reference-description>
  </reference-descriptor>
</weblogic-web-app>

For more information on the elements of the weblogic.xml deployment descriptor, see Assembling and Configuring Web Applications.

Updating the application.xml File for RPC-Style Web Services

The application.xml deployment descriptor for RPC-style Web service contains standard references to the Web application that references the SOAP servlets and stateless session EJB that comprises the Web service.

The one Web services-related element is the <context-root> sub-element of the <web> element. The value of the <context-root> element is used in all URLs that access either the WSDL, the Home Page, or the Web service itself.

The following sample application.xml deployment descriptor contains elements for the RPC-style Web service example examples.webservices.rpc:

<!DOCTYPE application 
        PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN'
        'http://java.sun.com/j2ee/dtds/application_1_2.dtd'>

<application>
  <display-name>Web-services</display-name>
  <module>
    <web>
      <web-uri>web-services.war</web-uri>
      <context-root>/weather</context-root>
    </web>
  </module>
  <module>
    <ejb>weather.jar</ejb>
  </module>
</application>

See Developing WebLogic Server Applications for descriptions of the elements in the application.xml file.

 

---

Assembling a Message-Style Web Service Archive File Manually

This section describes how to manually assemble a message-style Web service into an Enterprise application *.ear file that can be deployed on WebLogic Server.

It is assumed that you have used the Administration Console to set up the following JMS components:

• The JMS destination (queue or topic) which will either receive the message from a client or from which the message is sent to a client.

• The JMS Connection factory that the WebLogic Web Service uses to create JMS connections.

For detailed information about using the Administration Console to configure JMS components, see the WebLogic Server Administration Guide.

To assemble a message-style Web service archive file manually, follow these steps:

1. Create a temporary staging directory for assembling the Web application component. You can name this directory anything you want.

2. Set up your shell environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory BEA_HOME\config\domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

   On UNIX, execute the setEnv.sh command, located in the directory BEA_HOME/config/domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

3. Execute the following command to automatically generate initial web.xml and weblogic.xml deployment descriptors in the WEB-INF subdirectory:

   java weblogic.ant.taskdefs.war.DDInit staging-dir
   

   where staging-dir refers to the staging directory.

   For more information on the Java-based DDInit utility for generating deployment descriptors, see Developing WebLogic Server Applications.

4. Edit the WEB-INF/web.xml file, adding WebLogic Web Services information, such as references to the SOAP servlets. For details, see Creating the Message-Style Web Service WSDL File in this appendix.

5. Edit the WEB-INF/weblogic.xml file, adding WebLogic Web Services information. For details, see Updating the weblogic.xml File for Message-Style Web Services in this appendix.

6. In the main staging directory, create a sub-directory that will hold the WSDL JSP for the Web service. You can name this sub-directory anything you want. This name will become part of the URL used to invoke the Web service.

   For this procedure, assume the name of this directory is wsdl_dir.

7. In the wsdl_dir subdirectory, create the WSDL JSP. The wsgen Java utility names this JSP wsdl.jsp when generating it automatically; you can follow this naming convention, or follow a convention of your own.

   For details on creating this file, see Creating the Message-Style Web Service WSDL File in this appendix.

8. In the wsdl_dir subdirectory, create an index.html file that contains links to the WSDL JSP you created in the preceding step and the client JAR file that you will create in a later step. The following example shows a simple index.html file:

   <html>
   <body>
   <h3>Web Service Name</h3>
   <ul>
   <li><a href='wsdl.jsp'>WSDL</a></li>
   <li><a href='../client.jar'>client.jar</li>
   </ul>
   </body>
   </html>
   

9. Create a client.jar file in the main staging directory. For details on creating this file, refer to Creating the client.jar File Manually in this appendix.

   Note: This step is optional. You only need to create a client.jar file if you are going to use a Java client application to invoke the Web service.

10. Create an index.html file in the main staging directory that lists the Web service in this Enterprise application archive and links to its index.html file that you created in a previous step. The following example shows a simple index.html file:

    <html>
    <body>
    <h3>Message-Style Web Services</h3>
    <ul>
    <li><a href='/context/wsdl_dir/index.html'>wsdl_dir</a></li>
    </ul>
    </body>
    </html>
    

    In the example, context refers to the context-root element of the Web application in the application.xml file (to be created in a later step) and wsdl_dir refers to the name of sub-directory that contains the WSDL file you created in the previous step.

11. Create the Web application archive (*.war file) using a jar command such as:

    jar cvf web-app-name.war -C staging-dir .
    

    Note: The wsgen Java ant task assigns the default name web-services.war to the Web application *.war file. You do not have to follow this naming convention.

12. Create a second temporary staging directory for assembling the Enterprise application. You can name this directory anything you want.

13. Copy the Web application archive *.war file you created in a previous step into the staging directory you created in step 12.

14. Execute the following command to automatically generate an initial application.xml deployment descriptor in the META-INF subdirectory:

    java weblogic.ant.taskdefs.ear.DDInit staging-dir
    

    where staging-dir refers to the staging directory you created in step 12.

    For more information on the Java-based DDInit utility for generating deployment descriptors, see Developing WebLogic Server Applications.

15. Edit the META-INF/application.xml file, adding WebLogic Web Services information. For details, see Updating the application.xml File for Message-Style Web Services in this appendix.

16. Create the Enterprise Archive (.ear file) for the application, using a jar command such as:

    jar cvf application.ear -C staging-dir .
    

    The resulting .ear file can be deployed as a WebLogic Web Service using the Administration Console or the weblogic.deploy command-line utility.

Creating the Message-Style Web Service WSDL File

The WSDL JSP files for all message-style WebLogic Web Services are very similar, because there are only two operations that these types of Web services ever perform: send or receive data to or from a client application.

To create the WSDL JSP for a message-style Web service, follow these steps:

1. Using your favorite text editor, create a file called wsdl.jsp.

2. Copy and paste the sample WSDL at the end of this section into the wsdl.jsp file, and edit it according to the following steps.

   In the sample WSDL, the sections that you must modify for your specific Web service are in bold.

3. Globally replace references to myService with the name of your Web service.

4. If your Web service is one in which client applications that invoke it receive messages from the service, globally replace the word send with the word receive.

5. Globally replace url:local with the unique namespace for your Web service.

6. Replace the URI used to invoke the Web service from /msg/sendMsg to the following URI:

   /context-root/url-pattern 
   

   where context-root refers to the <context-root> element of the application.xml deployment descriptor and url-pattern refers to the <url-pattern> for the SOAP servlet in the web.xml deployment descriptor.

7. If you want the WSDL file to statically specify the host and port of the WebLogic server hosting your Web service, edit the soap:address element in the WSDL JSP, replacing the text <%= request.getServerName() %>:<%= request.getServerPort() %> with hard-coded host and port values.

Use the following sample WSDL JSP as a starting point for your WSDL JSP.

<?xml version="1.0"?>
<definitions 
    targetNamespace="urn:local"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="urn:local"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/1999/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" >

  <types>
    <schema targetNamespace='urn:local'
            xmlns='http://www.w3.org/1999/XMLSchema'>
    </schema>
  </types>

  <message name="sendRequest">
    <part name="message" type="xsd:anyType" />
  </message>
  <message name="sendResponse">
  </message>

  <portType name="myServicePortType">
    <operation name="send">
      <input message="tns:sendRequest"/>
      <output message="tns:sendResponse"/>
    </operation>
  </portType>

  <binding name="myServiceBinding" type="tns:myServicePortType">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http/"/>
    <operation name="send">
      <soap:operation soapAction="urn:send"/>
      <input>
        <soap:body use="encoded" namespace='urn:myService' 
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </input>
      <output>
        <soap:body use="encoded" namespace='urn:myService' 
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>  
      </output>
    </operation>
  </binding>

  <service name="myService">
    <documentation>todo</documentation>
    <port name="myServicePort" binding="tns:myServiceBinding">
      <soap:address location="http://<%= request.getServerName() %>:<%= 
request.getServerPort() %>/msg/sendMsg"/>
    </port>
  </service>

</definitions>

Updating the web.xml File for Message-Style Web Services

This section describes the elements you must update or add to the web.xml deployment descriptor for the Web application that references the SOAP servlets in a message-style WebLogic Web Services archive file. For the complete example of a web.xml deployment descriptor, see the end of this section.

It is assumed that you have a basic understanding of Web applications and their deployment descriptors. For more information, see Assembling and Configuring Web Applications.

To update a web.xml file for message-style Web services, add the following elements:

• A <servlet> element that references the SOAP servlet that manages the SOAP messages between the message-style Web service and the client application. Set the <servlet-class> sub-element to one of the following servlet classes, depending on whether the JMS destination is a topic or queue and whether the client invoking the service sends or receives messages:

  • weblogic.soap.server.servlet.DestinationSendAdapter—handles SOAP messages between the service and a client application that sends messages to either a JMS topic or queue.

  • weblogic.soap.server.servlet.QueueReceiveAdapter—handles SOAP messages between the service and a client application that receives messages from a JMS queue.

  • weblogic.soap.server.servlet.TopicReceiveAdapter—handles SOAP messages between the service and a client application that receives messages from a JMS topic.

    This <servlet> element contains two <init-params> elements: one that references the JMS destination classes and another that references the JMS connection factory classes.

    The following example shows a <servlet> reference to a SOAP servlet:

      <servlet>
        <servlet-name>myService</servlet-name>
        <servlet-class>
             weblogic.soap.server.servlet.DestinationSendAdapter
        </servlet-class>
        <init-param>
          <param-name>topic-resource-ref</param-name>
          <param-value>myServiceDestination</param-value>
        </init-param>
        <init-param>
          <param-name>connection-factory-resource-ref</param-name>
          <param-value>myServiceFactory</param-value>
        </init-param>
      </servlet>
    

• A <servlet> element that references the SOAP servlet that handles all SOAP faults. Set the <servlet-class> element to weblogic.soap.server.servlet.FaultHandler, as shown in the following example:

    <servlet>
      <servlet-name>myServiceFault</servlet-name>
      <servlet-class>
            weblogic.soap.server.servlet.FaultHandler
      </servlet-class>
    </servlet>
  

• A <servlet> element that references the WSDL JSP, as shown in the following example:

    <servlet>
      <servlet-name>myServiceWSDL</servlet-name>
      <jsp-file>/myService/wsdl.jsp</jsp-file>
    </servlet>
  

  The path to the JSP file, <jsp-file>, is the path in your Web application archive file to the WSDL JSP you created in Assembling a Message-Style Web Service Archive File Manually in this appendix.

• For each of the preceding <servlet> elements, create a <servlet-mapping> element to map a URL to the servlet, as shown in the following example:

    <servlet-mapping>
      <servlet-name>myServiceFault</servlet-name>
      <url-pattern>/weblogic/webservice/fault</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
      <servlet-name>myServiceWSDL</servlet-name>
      <url-pattern>/myService/myService.wsdl</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
      <servlet-name>myService</servlet-name>
      <url-pattern>/sendMsg</url-pattern>
    </servlet-mapping>
  

• An <error-page> element, exactly as shown:

  <error-page>
      <exception-type>
         weblogic.soap.FaultException
      </exception-type>
      <location>/weblogic/webservice/fault</location>
    </error-page>
  

• Two <resource-ref> elements to link the JMS destination and connection factory references in the first <servlet> element to a Java object in JNDI, as shown in the following example:

    <resource-ref>
      <res-ref-name>myServiceDestination</res-ref-name>
      <res-type>javax.jms.Destination</res-type>
      <res-auth>Container</res-auth>
    </resource-ref>
    <resource-ref>
      <res-ref-name>myServiceFactory</res-ref-name>
      <res-type>javax.jms.ConnectionFactory</res-type>
      <res-auth>Container</res-auth>
    </resource-ref>
  

The following complete sample web.xml deployment descriptor contains elements for the message-style Web service example examples.webservices.message:

<!DOCTYPE web-app 
          PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 
          "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">

<web-app>
  <servlet>
    <servlet-name>myService</servlet-name>
    <servlet-class>
         weblogic.soap.server.servlet.DestinationSendAdapter
    </servlet-class>
    <init-param>
      <param-name>topic-resource-ref</param-name>
      <param-value>myServiceDestination</param-value>
    </init-param>
    <init-param>
      <param-name>connection-factory-resource-ref</param-name>
      <param-value>myServiceFactory</param-value>
    </init-param>
  </servlet>
  <servlet>
    <servlet-name>myServiceFault</servlet-name>
    <servlet-class>weblogic.soap.server.servlet.FaultHandler</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>myServiceWSDL</servlet-name>
    <jsp-file>/myService/wsdl.jsp</jsp-file>
  </servlet>
  <servlet-mapping>
    <servlet-name>myServiceFault</servlet-name>
    <url-pattern>/weblogic/webservice/fault</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>myServiceWSDL</servlet-name>
    <url-pattern>/myService/myService.wsdl</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>myService</servlet-name>
    <url-pattern>/sendMsg</url-pattern>
  </servlet-mapping>
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
  </welcome-file-list>
  <error-page>
    <exception-type>weblogic.soap.FaultException</exception-type>
    <location>/weblogic/webservice/fault</location>
  </error-page>
  <resource-ref>
    <res-ref-name>myServiceDestination</res-ref-name>
    <res-type>javax.jms.Destination</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>
  <resource-ref>
    <res-ref-name>myServiceFactory</res-ref-name>
    <res-type>javax.jms.ConnectionFactory</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>
</web-app>

Updating the weblogic.xml File for Message-Style Web Services

The weblogic.xml deployment descriptor for message-style Web services does not contain any Web services-specific elements, but rather, contains standard references to the JMS Destination and JMS Connection Factories.

The following sample weblogic.xml deployment descriptor contains elements for the message-style Web service example examples.webservices.message:

<!DOCTYPE weblogic-web-app 
        PUBLIC "-//BEA Systems, Inc.//DTD Web Application 6.0//EN"
        "http://www.beasys.com/j2ee/dtds/weblogic-web-jar.dtd">

<weblogic-web-app>
  <reference-descriptor>
    <resource-description>
      <res-ref-name>myServiceDestination</res-ref-name>
      <jndi-name>examples.soap.msgService.MsgSend</jndi-name>
    </resource-description>
    <resource-description>
      <res-ref-name>myServiceFactory</res-ref-name>
      <jndi-name>examples.soap.msgService.MsgConnectionFactory</jndi-name>
    </resource-description>
  </reference-descriptor>
</weblogic-web-app>

Updating the application.xml File for Message-Style Web Services

The application.xml deployment descriptor for message-style Web services contains the standard reference to the Web application that contains the SOAP servlets.

The one Web services-related element is the <context-root> sub-element of the <web> element. The value of the <context-root> element is used in all URLs that access either the WSDL, the Home Page, or the Web service itself.

The following sample application.xml deployment descriptor contains elements for the message-style Web service example examples.webservices.message:

<!DOCTYPE application 
         PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN'
         'http://java.sun.com/j2ee/dtds/application_1_2.dtd'>

<application>
  <display-name>Web-services</display-name>
  <module>
    <web>
      <web-uri>web-services.war</web-uri>
      <context-root>/msg</context-root>
    </web>
  </module>
</application>

 

---

Creating the client.jar File Manually

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 an RPC-style Web service. This object is optional and only needed if you are using a static client to invoke the service.

• Class files for JavaBeans that are used as EJB parameters or return values.

BEA recommends that you use the wsgen Java Ant task to create an initial *.ear file and then extract the Java client.jar file contained within the *.ear file and modify it for your specific Web service. For details on using wsgen, see Assembling a WebLogic Web Service.