Introduction

The IBM ® CrossWorlds® system is a suite of software integration products that supply connectivity for leading e-business technologies and enterprise applications. This article describes how to expose IBM CrossWorlds Version 4.1 Collaborations as a message-oriented Web service and deploy it on WebSphere® Application Server Version 4.0. In this way, IBM CrossWorlds Collaborations can use Simple Object Access Protocol (SOAP) messages to interact with other applications.

Familiarity with SOAP services and IBM CrossWorlds Version 4.1 Collaborations is required to follow the procedures described below.

Back to top

Exposing IBM CrossWorlds Collaborations as a Web service

Here are the basic steps for exposing IBM CrossWorlds Collaborations as a Web service:

1. Creating the Child Config Meta Object for the Response Business Object
2. Creating the Parent Config Meta Object for the Response Business Object
3. Creating the Child and Parent Config Meta Objects for the Request Business Object
4. Configuring the CrossWorlds Data Handlers
5. Connecting to the IBM CrossWorlds Web Services Generation Utility

Creating the Child Config Meta Object for the response Business Object

First, let's create the Child Config Meta Object (MO):

1. In the IBM CrossWorlds System Manager, select File=>New=>Business Object to create the Child Config Meta Object for the response Business Object (BO), as shown in Figure 1.
   Figure 1. New Business Object
   
   
2. In the New Business Object dialog panel, enter MO_someName_SOAPToBO as the name of the Child Config MO, where someName uniquely identifies the service being created. We used Personal and PersonalArticle for someName in our examples. Please see Figure 2.
   Figure 2. Entering the name of the Child Config MO in the New Business Object panel
   
   
3. Click OK, and the Business Object Designer panel displays. Right-click, and select Insert Above to define the new attributes.
   Figure 3. Defining new attributes in Business Object Designer
   
   
4. Define these five attributes for the Child Config MO: BodyNS, BodyName, BOName, BOVerb, and MsgPartName. Their values should conform to the following:
   
   Attributes and Default Values:
   
   

   Attribute	Default Value
   BodyNS	Namespace of the first part of the SOAP response message as specified in the WSDL document.
   BodyName	Name of the first part of the SOAP response message as specified in the WSDL document. This will be the name of the method for the proxy class generated in the steps below. This is also the name of the first element of the SOAP message body.
   BOName	Name of the response BO.
   BOVerb	Verb set in the response business object by data handler.
   MsgPartName	Not generally needed. See IBM CrossWorlds documentation for info on when this value might need to be specified.

Now that we've completed these steps, the final Child Config MO of the response BO should look like Figure 4 below. Remember to set the BodyName as the key attribute by checking the corresponding Key box.

Creating the Parent Config Meta Object for the Response Business Object

Next, let's create the Parent Config MO:

1. In the IBM CrossWorlds System Manager, select File=>New=>Business Object to create the Parent Config Meta Object for the response Business Object (BO), as shown in Figure 1 above.
2. In the dialog panel that pops up, enter MO_someName_SOAPToBOConfig as the name of the Parent Config MO, where someName uniquely identifies the service being created. Important: We've used Personal and PersonalArticle for someName in our examples. Please see Figure 2.
3. Click OK, and the Business Object Designer panel appears. Right-click, and select Insert Above to define the new attributes. Please see Figure 3.
4. Define a new attribute, and set its type to the Child Config MO created above (MO_someName_SOAPToBO). The final Parent Config MO is shown in Figure 5.

At this point, we have finished creating the Child Config MO and Parent Config MO for the response BO.

Creating the Child and Parent Config Meta Objects for the Request Business Object

Now, let's create the Child and Parent Config MO for the request BO (MO_someName_BOToSOAP and MO_someName_BOToSOAPConfig):

Important: The Response (Output) and Request (Input) BOs are sometimes different. Make sure that the correct BO name is entered in the BOName field of the two child MOs.

1. In the IBM CrossWorlds System Manager, select File=>New=>Business Object to create both the Child and the Parent Config Meta Objects for the request Business Object (BO), as shown in Figure 1 above.
2. In the dialog panels that pop up, enter MO_someName_BOToSOAP as the name of the Child Config MO and MO_someName_BOToSOAPConfig as the name of the Parent Config MO, where someName uniquely identifies the service being created. Notice that we used Personal and PersonalArticle for someName in our examples. Configure each of these MOs as described in the sections above.

Configuring the IBM CrossWorlds Data Handlers

Now, let's configure IBM CrossWorlds data handlers to use the SOAP MOs created above:

1. Make sure there is a BO named MO_DataHandler_DefaultSOAPConfig. If not, create it with the following fields, each of type String:
   
   Attributes and Default Values:
   
   

   Attribute	Default Value
   ClassName	The name of the SOAP data handler. In almost all instances, this should be com.crossworlds.DataHandlers.xml.soap.
   SOAPToBOConfigMO	The name of the parent (not child) MO for the input message (i.e. MO_someName_SOAPToBOConfig).
   BOToSOAPConfigMO	The name of the parent (not child) MO for the output message (i.e. MO_someName_BOToSOAPConfig).

2. Add an attribute to the MO_Server_DataHandler BO named xml_soap with type MO_DataHandler_DefaultSOAPConfig.
   Please refer to the various IBM CrossWorlds documents on configuring IBM CrossWorlds to handle different incoming SOAP messages.
3. Edit the start_server.bat file found in the <CrossWorlds>\bin directory. Add a variable named WEBSERVICES, and append it to the JCLASSES variable. Set the WEBSERVICES variable as follows:
   Important: This should all be on one line.

   set WEBSERVICES=%CROSSWORLDS%\connectors\SOAP\Dependencies\SOAP.jar;%CROSSWORLDS%\connectors \SOAP\Dependencies\Activation.jar;%CROSSWORLDS%\connectors\SOAP\Dependencies\Mail.jar; %CROSSWORLDS%\connectors\SOAP\Dependencies\Xerces.jar;

   
   
4. Stop, and restart the ICS. It is now ready to handle SOAP requests.

Connecting to the IBM CrossWorlds Web Services Generation Utility

1. Start the IBM CrossWorlds Web Services Generation Utility by running the WSGenUtility.bat file that was installed in the <CrossWorlds>\DevelopmentKits\WebServices directory. Fill in the prompts, as shown in Figure 6 below, to connect to the InterChange Server (ICS), including the target ICS name, ICS username and password, and the location of ICS IOR file.
   Figure 6. Providing information to connect to the InterChange Server
   
   
   Important: In both the Response and Request BOs, the App Spec Info field of all attributes that reference other top-level BOs must be set to type=boName at the end and separated from any other data by a semicolon (;), where boName is the name of the corresponding BO (see Figure 7). This is only required for the Web Services Generation utility to work successfully.
   Figure 7. The Response Business Object
   
   
   
2. Click the Connect button. Once the connection has been established, the utility displays the screen below. This screen prompts us to provide the information required to generate the proxy class.
   Figure 8. Providing the information required to generate the proxy class
   
   
   Important: The values entered in Figures 6 and 8 are hard-coded in the proxy class. However, these values are also output in a CFG file (see Figure 10) that can be deployed on the Web server. The values in the CFG file can be set to point to compatible IBM CrossWorlds Collaborations on different machines. Create an initialization parameter for the SOAP message router servlet with a name that matches the Service Name field in Figure 9 and whose value is the full path name to the customized CFG file. This can easily be done by using the Application Assembly Tool to edit the EAR file that is modified by soapearenabler in step 5 of the deployment section below.
   
3. Click Next. The utility displays the Operation Details table screen as shown in Figure 9.
   Figure 9. The Operation Details Table
   
   
   Important: The Input and Output Message MetaObjects specified in Figure 9 above are the child MOs, not the parent MOs, we created above. Also, make sure the Binding URL field is set appropriately for the Web server to which this Web service will be deployed. The Target Namespace field should be set to the value entered as the BodyNS field for the child MOs from above.
   
4. Enter all the parameters described above and click the Generate button. If an error message appears stating that version *.*.* of BO someBOName cannot be found, the likely problem is that one of the attributes specifying a top-level BO has not had type=boName appended to its App Spec Info section as noted in step 9 above. More than likely, someBOName is the attribute name and not the BO name that the attribute represents. Correct the problem, and click Generate again; there is no need to restart the utility. If the tool generates the files successfully, the panel below will appear.
   Figure 10. Generating the files successfully
   
   
   
5. The utility outputs six files in the /GeneratedFiles/ subfolder under the current directory (see Figure 10).

The Web service is now ready to be deployed on Apache TomCat. Please refer to the Apache SOAP Installation and Configuration (found within this ZIP file) for details. The section below describes how to deploy the Web service in WebSphere Application Server 4.0.

Back to top

Deploying the Web service on WebSphere Application Server

1. Run jar cvf someNameService.jar someNameProxy.class to create a JAR file named someNameService.jar. This JAR file contains the Web service code and will be used in step 5 when running soapearenabler.
2. Start the WebSphere Application Assembly Tool. With the JAR file generated above, create an EAR file. For more information and a step-by-step procedure, please refer to the IBM WebSphere V4.0 Advanced Edition Handbook.
3. Add the following JAR files to the Default Server's classpath:

   SOAP.jar, xerces.jar, log4j.jar, log4j-core.jar, Activation.jar, Mail.jar, ProxyUtil.jar, servlet.jar, CrossWorlds.jar, vbjorb.jar

   
   These JAR files are found in various WebSphere Application Server and IBM CrossWorlds directories.
4. Prepare an XML file named DeploymentDescriptor.xml. In the following example, replace the text in blue with appropriate values. Set the id attribute to the Target Namespace specified in Figure 9, the methods attribute to the service method name (and BodyName specified in Figure 4), and the class attribute to the name of the proxy class generated before.
   

   <isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:someName" checkMustUnderstands="false"> <isd:provider type="java" scope="Application" methods="getResult"> <isd:java class="someNameProxy" static="false"/> </isd:provider> </isd:service>

   
   
5. Add the SOAP Web component to the EAR file created in step 2 by running soapearenabler.
   Figure 11. Running the soapearenabler to deploy the application
   
   
   Important: At the Classpath requirement prompt, choose the number that corresponds to the Web service JAR file. Also, the context root for the Web service should correspond to the value entered as the Binding URL in Figure 9.
   
   
6. Start the WAS Admin Console to deploy the generated EAR file into WebSphere Application Server. Please refer to the IBM WebSphere V4.0 Advanced Edition Handbook for details.
7. Restart the default server in WebSphere; then we are finished!

Back to top

Testing the Web service

Ultimately, we would like to test the Web service by writing simple client code to execute the proxy class.

1. Prepare an incoming SOAP message in advance. Below is an example (msg.xml):
   Figure 12. The incoming XML file
   
   
   Important: The first element of the body must be the service method name (getResult in the figure). This corresponds to the BodyName field of the child config MOs.
2. The xmlns attribute of this first element is the service name space. This corresponds to the BodyNS field of the child config MOs.
3. The Body message part corresponds to the Response Business Object. If the Card field of any attribute in this BO is N, the element standing for that attribute must be doubled (see Figure 12).
4. Create a Java^TM class called SendMessage, and copy the following code to it.

 
 //Program to Test the Web service



        import java.io.*;

        import java.net.*;

        import javax.xml.parsers.*;

        import org.w3c.dom.*;

        import org.xml.sax.*;

        import org.apache.soap.*;

        import org.apache.soap.messaging.*;

        import org.apache.soap.transport.*;

        import org.apache.soap.rpc.*;

        import org.apache.soap.util.xml.*;



        public class SendMessage {     

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

        

             // Destination URL. This should match the Binding 

             // URL specified when creating the proxy class.

             URL url = new 

                 URL("http://localhost/PAservice/servlet/messagerouter");

          

             // Get the envelope to send

             FileReader fr = new FileReader ("msg.xml");

             DocumentBuilder xdb = XMLParserUtils.getXMLDocBuilder();

             Document doc = xdb.parse (new InputSource (fr));

             if (doc == null)

                 throw new SOAPException (Constants.FAULT_CODE_CLIENT, "parsing error");



             Envelope msgEnv = Envelope.unmarshall (doc.getDocumentElement ());



             // Send the message

             Message msg = new Message ();

             msg.send (url, "", msgEnv);



             // Receive whatever from the transport and dump it to the screen

             System.out.println ("RESPONSE:");

             System.out.println ("--------");

             SOAPTransport st = msg.getSOAPTransport ();

             BufferedReader br = st.receive ();

             String line;

             while ((line = br.readLine ()) != null) {

                 System.out.println (line);

             }       

          }  

   

       }    

Before running the class, make sure that all of the parameters are set correctly, including the classpath of the default server, the content of the XML message file, and the attributes of the MOs. If a correct message is not returned, try restarting the ICS and WAS application servers. Also, try adding debugging code to both the Web service and client code to try to determine where the problem is. The Web service and client code would then have to be recompiled, repackaged, and redeployed as outlined in earlier sections.

Back to top

Conclusion

The combination of WebSphere and the IBM CrossWorlds Collaboration described in this article finally provides a message-oriented SOAP service interface for IBM CrossWorlds to interact with other applications. In many cases a message-oriented model provides a better fit to the problem that needs to be solved. It has full control over the SOAP Envelopes; any XML document may be passed as part of the envelope body. This will definitely become another popular access method of IBM CrossWorlds Collaborations in the future.

Resources

• IBM CrossWorlds documentation
  
  
• Apache SOAP Installation and Configuration documentation
  
  
• IBM WebSphere V4.0 Advanced Edition Handbook
  
  

About the authors

Yongjie Zheng is a Software Developer at the IBM Globalization Certification Laboratory. He received his B.S. in Computer Science from Tsinghua University in Beijing in 2000. He can be reached at tprsadm@cn.ibm.com or yongjiezheng@yahoo.com.

Yang Wang is a Software Engineer at the IBM Globalization Certification Laboratory and joined IBM in July 2001. Yang has joined or led many globalization solution projects with various roles including tester, coordinator, developer, and project leader. He can be reached at wangang@cn.ibm.com.

Hanjian Fu is a Software Engineer at the IBM Globalization Certification Laboratory. He joined IBM in September 2000. Hanjian holds a B.S. in Computer Science and Engineering from Shanghai JiaoTong University. He can be reached at fuhj@cn.ibm.com.

Drew Schechter is a Software Engineer with IBM Software Group Integrated Solution Center in RTP, NC (USA). He has worked with IBM since December 1998 and been with the ISC group since September 1999. Drew holds a B.S. in Mathematical Sciences from the University of North Carolina at Chapel Hill and primarily works with Java- and XML-related technologies. He can be reached at adriansc@us.ibm.com.

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Exposing IBM CrossWorlds Collaborations as a Web service
• Deploying the Web service on WebSphere Application Server
• Testing the Web service
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Securing WebSphere Application Server environments

Essential resources to design and develop your WebSphere solutions in ways that will make them more secure.

Special offers