AdapterforeMatrixUserGuide - PDF Free Download

IBM WebSphere Business Integration Adapters AdapterforeMatrixUserGuide V1.0.x

Note! Before using this information and the product it supports, read the information in Notices on page 35. 18April2003 This edition of this document applies to connector version 1.0.x and to all subsequent releases and modifications until otherwise indicated in new editions. To send us your comments about this document, e-mail doc-comments@us.ibm.com. We look forward to hearing from you. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. Copyright International Business Machines Corporation 2002, 2003. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Integration broker compatibility Supported on IBM WebSphere Business Integration Adapter Framework version 2.2.0, IBM CrossWorlds Infrastructure version 4.1.1 and 4.2 (if the environment uses ISO Latin-1 data only), WebSphere MQ Integrator version 2.1.0, and WebSphere MQ Integrator Broker, version 2.1.0. See Release Notes for any exceptions. Copyright IBM Corp. 2002, 2003 iii

iv Adapter for ematrix User Guide

Contents Integration broker compatibility......................... iii Preface................................... vii Audience.................................... vii Prerequisites for this document............................. vii Related documents................................. vii Typographic conventions.............................. viii New in this release............................... ix New in release 1.0.x................................. ix Chapter 1. Overview of the WebSphere Business Integration Adapter for ematrix.... 1 Terminology................................... 1 Components of WebSphere adapter for ematrix........................ 1 Architecture of adapter for ematrix............................ 3 Chapter 2. Installation and startup........................ 7 Prerequisites................................... 7 Overview of installation tasks............................. 8 Loading files into the repository............................ 10 Overview of configuration tasks............................ 10 Starting the connector................................ 11 Chapter 3. Configuring the ematrix request servlet................. 13 About configuring the ematrix request servlet........................ 13 Usage..................................... 14 Error handling.................................. 15 Logging and tracing................................ 15 Chapter 4. Configuring the XML servlet for ICS.................. 17 About configuring the XML servlet for ICS......................... 17 Usage..................................... 18 Error handling.................................. 19 Logging and tracing................................ 19 Chapter 5. Configuring the request-response data handler............. 21 About configuring the request-response data handler..................... 21 Sample data handler meta-objects............................ 22 Top-level business object requirements.......................... 27 Data handler logic................................. 28 Synchronous event notification............................. 28 Error handling.................................. 29 Logging and tracing................................ 29 Appendix. Connector feature list........................ 31 Business object request handling features......................... 31 Event notification features.............................. 31 General features.................................. 32 Notices................................... 35 Programming interface information........................... 36 Trademarks and service marks............................. 36 Copyright IBM Corp. 2002, 2003 v

vi Adapter for ematrix User Guide

Preface IBM (R) WebSphere (R) Business Integration Adapters supply integration connectivity for leading e-business technologies and enterprise applications. This document describes the installation, configuration, and business object development for the adapter for ematrix. Audience This document is for IBM customers, consultants, developers, and anyone who is implementing the WebSphere Business Integration Adapter for ematrix. Prerequisites for this document Related documents A variety of prerequisites are cited throughout this book. Some of these consist of references to resources for ematrix. You should also be familiar with implementing the WebSphere business integration system. A good place to start is the Technical Introduction to IBM WebSphere InterChange Server, which contains cross-references to more detailed documentation. You should also be familiar with the technical material covered in the Access Development Guide. You must have access to the XML data handler and the Data Handler Guide. The WebSphere business integration system documentation describes the features and components common to all installations, and includes reference material on specific collaborations and connectors. This document contains many references to two other documents: the System Installation Guide for Windows or for UNIX and the System Implementation Guide for WebSphere InterChange Server. If you choose to print this document, you may want to print these documents as well. The WebSphere business integration system documentation describes the features and components common to all installations, and includes reference material on specific collaborations and connectors. To access the documentation, go to the directory where you installed the WebSphere business integration system product and open the documentation subdirectory. If a welcome.html file is present, open it for hyperlinked access to all documentation. If no documentation is present, you can install it or read it directly online at one of the following sites: v v If you are using MQ Integrator Broker as your integration broker: http://www.ibm.com/websphere/integration/wbiadapters/infocenter If you are using InterChange Server as your integration broker: http://www.ibm.com/websphere/integration/wicserver/infocenter The WebSphere business integration system documentation consists primarily of Portable Document Format (PDF) files, with some additional files in HTML format. To read it, you need an HTML browser such as Netscape Navigator or Internet Copyright IBM Corp. 2002, 2003 vii

Typographic conventions Explorer, and Adobe Acrobat Reader 4.0.5 or higher. For the latest version of Adobe Acrobat Reader for your platform, go to the Adobe website (www.adobe.com). This document uses the following conventions: courier font Indicates a literal value, such as a command name, filename, information that you type, or information that the system prints on the screen. bold Indicates a new term the first time that it appears. italic italic Indicates a variable name or a cross-reference. blue text Blue text, which is visible only when you view the manual online, indicates a cross-reference hyperlink. Click any blue text to jump to the object of the reference. ProductDir Product family is WBIA: Represents the directory where the IBM WebSphere Business Integration Adapters product is installed. The CROSSWORLDS environment variable contains the ProductDir directory path, which is IBM\WebSphereAdapters by default. { } In a syntax line, curly braces surround a set of options from which you must choose one and only one. [] In a syntax line, square brackets surround an optional parameter.... In a syntax line, ellipses indicate a repetition of the previous parameter. For example, option[,...] means that you can enter multiple, comma-separated options. <> In a naming convention, angle brackets surround individual elements of a name to distinguish them from each other, as in <server_name><connector_name>tmp.log. /, \ In this document, backslashes (\) are used as the convention for directory paths. For UNIX installations, substitute slashes (/) for backslashes. All product pathnames are relative to the directory where the product is installed on your system. ----UNIX/Windows----- Paragraphs beginning with either of these indicate notes listing operating system differences. %text% and $text Text within percent (%) signs indicates the value of the Windows text system variable or user variable. The equivalent notation in a UNIX environment is $text, indicating the value of the text UNIX environment variable. viii Adapter for ematrix User Guide

New in this release New in release 1.0.x Updated in March, 2003. The CrossWorlds name is no longer used to describe an entire system or to modify the names of components or tools, which are otherwise mostly the same as before. For example CrossWorlds System Manager is now System Manager, and CrossWorlds InterChange Server is now WebSphere InterChange Server. The ematrix adapter is now globalized but the messages are not translated. Copyright IBM Corp. 2002, 2003 ix

x Adapter for ematrix User Guide

Chapter 1. Overview of the WebSphere Business Integration Adapter for ematrix v Terminology v Components of WebSphere adapter for ematrix v Architecture of adapter for ematrix on page 3 The WebSphere Business Integration Adapter for ematrix allows businesses to integrate MatrixOne processes with IBM WebSphere software. The product implements connectivity tools and software to bi-directionally exchange business data between ematrix and WebSphere using the XML and HTTP protocols and the InterChange Server (ICS) integration broker. This chapter describes the scope, components, and architecture that IBM WebSphere uses to implement its ematrix integration solution. For information about installing and configuring the components, see Chapter 2, Installation and startup, on page 7. Terminology The following terms are used in this Guide: v XML (EXtensible Markup Language) An open standard for describing data from the W3C. This standard defines data elements on Web pages and business-to-business documents. It uses a tag structure like that of HTML; however, whereas HTML defines how elements are displayed, XML defines what those elements contain. v ADK (Application Development Kit) A MatrixOne ematrix library that enables external applications to interact with ematrix. v RMI (Remote Method Invocation) An industry standard from Sun Microsystems, Inc., for distributed objects written in Java. RMI is a remote procedure call (RPC), that allows Java objects (software components) stored in the network to be run remotely. Components of WebSphere adapter for ematrix The integration broker for the WebSphere Business Integration Adapter for ematrix is InterChange Server (ICS). For hub information see the Technical Introduction to IBM WebSphere InterChange Server. The integration broker brings together the following components, which are described in sections below: v v v XML connector Receives and sends business objects to and from the ematrix environment. IBM ematrix request servlet Enables a collaboration to invoke programs within ematrix. The servlet returns any data generated by the invoked ematrix program to the collaboration. IBM XML servlet for ICS Enables ematrix programs to issue requests to collaborations and to retrieve data from those collaborations. The servlet returns any data generated by the collaborations. Copyright IBM Corp. 2002, 2003 1

v v Request-Response Data Handler Allows the WebSphere integration broker to post one business object type to a collaboration port and receive a different business object in return. Server Access Interface An API that allows an external process to execute a collaboration inside InterChange Server. In addition, the WebSphere Business Integration Adapter for ematrix comes with sample business object definitions and ematrix programs to verify the installed configuration. Note: None of the integration components described in this document modify or query the ematrix data layer directly. Instead, the WebSphere Adapter software enables collaborations to communicate with ematrix programs to coordinate business processes. The WebSphere Business Integration Adapter for ematrix requires that ematrix programs accept XML for input and or generate XML for output. IBM XML connector The IBM XML connector performs the following tasks: v v v v v Receives service call requests from collaborations running on ICS Converts request objects into XML messages with business object data (received from the service call request) in the body of the message Posts the request via HTTP to the IBM ematrix request servlet Incorporates the XML response into a request object Returns the modified request object to the collaboration For further information, see the Adapter for XML User Guide. Note: In this document, any mention of a connector is a reference to the XML connector, unless specified otherwise. IBM ematrix request servlet The IBM ematrix request servlet runs on a WebSphere application server and performs the following tasks: v v v v Allows WebSphere-based collaborations to issue requests to ematrix programs Reads the top-level tag name in a request object to determine the ematrix program to invoke Invokes a target ematrix program via ematrix ADK and passes a child XML document to the target program. Passes the response returned by the target program back to the XML connector For more information, see Chapter 3, Configuring the ematrix request servlet, on page 13. IBM XML servlet for ICS The IBM XML servlet for ICS runs on the WebSphere application server and performs the following tasks: v v Enables ematrix programs to issue synchronous requests to collaborations Accepts XML documents posted by ematrix programs and routes the documents via the Server Access Interface 2 Adapter for ematrix User Guide

v Returns XML documents containing response values to the requesting ematrix process For more information see Chapter 4, Configuring the XML servlet for ICS, on page 17. Request-response data handler The request-response data handler allows the integration broker to receive one type of object as an event and return a different object as a response to the synchronous event using a single collaboration port. As a result, ematrix requests can exchange a single business object with ICS, which can then accept and return an array of different response document structures. You can configure the request-response data handler to invoke any format-specific data handler. For the adapter for ematrix, the request-response data handler is configured to manage and invoke the XML data handler to perform the following tasks: v Receives ematrix XML request messages from the ICS Server Access Interface v Converts incoming ematrix request messages to business objects v Converts response business objects (returned by collaboration) to strings v Returns XML response messages to ematrix programs via Server Access Interface For more information see Chapter 5, Configuring the request-response data handler, on page 21. Server access interface Server Access Interface is an API that allows an external process to execute a collaboration inside the ICS integration broker. The external process, or access client, initiates a call-triggered flow inside the integration broker. system. For more information see the Access Development Guide. IBM business objects for ematrix Sample business object definitions and DTDs that describe XML messages in the definitions are included with the Adapter for ematrix. For more information on usage see the readme.txt files accompanying the samples and see also Chapter 2, Installation and startup, on page 7. Request business objects must be compatible with the XML data handler. Business object events must be compatible with the Request Response data handler. For more information about the business objects, see the XML Connector Guide. Architecture of adapter for ematrix To show the architecture of the adapter for ematrix components at a high level, this section describes two data flows one that characterizes a request process that is initiated from a collaboration and one that shows an event notification initiated by an ematrix program. Request processing Figure 1 illustrates the IBM hub-initiated request process, which is described below. Chapter 1. Overview of the WebSphere Business Integration Adapter for ematrix 3

IBM InterChange Server Collaboration 1 2 6 IBM WebSphere Business Integration Adapter for XML Request object Response object Top-level object (TLO) A request for a child object This object defines the XML message to send to the servlet. 5 MatrixOne ematrix Business objects A response to a child object This object acts as a container for the XML response (optionally) returned by the servlet IBM WebSphere Application Server XML-enabled ematrix program IBM ematrix request servlet 3 4 MatrixOne database Figure 1. Flow of a request process 1. A collaboration issues a service request the business object shown in Figure 1 to the connector. 2. The XML connector converts the request object to XML and performs an HTTP post to the servlet. The connector waits to receive an XML response from the IBM ematrix request servlet. It maps this XML to the response object. 3. The servlet assumes that the top-level XML tag name in the business object corresponds to a program in ematrix. The servlet uses ematrix ADK to invoke this program. 4. The ematrix program queries or modifies the MatrixOne data layer as necessary 5. The value returned by the ematrix program is passed by the servlet back to the XML Connector. 6. Once the request is completed, the connector returns the entire wrapper object to the collaboration. Event notification Figure 2 illustrates the sequence of events that occurs when an ematrix program generates an XML-encoded event of interest to the WebSphere integration broker. 4 Adapter for ematrix User Guide

MatrixOne ematrix Business objects 1 IBM WebSphere Application Server IBM WebSphere InterChange Server HTTP handler program 7 IBM XML servlet for ICS 6 2 CORBA server access interface 5 XML-enabled ematrix program 3 Request XML Response XML XML data-handler Response-Request data-handler TLO TLO Request Response 4 Request Response Collaboration Figure 2. Flow of an event notification 1. The ematrix program generates an XML document (an event) and posts it to the IBM XML servlet for ICS via HTTP. 2. The IBM XML servlet for ICS sends the XML document to Server Access Interface via CORBA. 3. Server Access Interface routes the XML document to the XML data handler, which parses the document, converts it to a request business object, and posts it to a subscribing collaboration. 4. The collaboration examines the request object, invokes other collaborations as needed, and populates response object accordingly. 5. The request-response data handler examines objects returned by collaborations to determine which child is the response object.; the request-response data handler posts them to Server Access Interface. 6. Server Access Interface returns the XML document containing the response generated by the collaboration. 7. The response from the WebSphere collaboration is returned to the ematrix program as an XML document. Chapter 1. Overview of the WebSphere Business Integration Adapter for ematrix 5

6 Adapter for ematrix User Guide

Chapter 2. Installation and startup v Prerequisites v Overview of installation tasks on page 8 v Overview of configuration tasks on page 10 v Starting the connector on page 11 Prerequisites This chapter describes how to install components for implementing the adapter for ematrix. For information regarding installation of the ICS integration broker system generally, see the System Installation Guide appropriate for your platform. To install the XML connector, see the XML Connector Guide. Review the following assumptions and software requirements before you install the connector for web services. WebSphere software requirements To implement the adapter for ematrix, you must install InterChange Server (ICS) release 4.2. Third-party software and platform requirements This product requires the following: v Windows environment (NT or 2000); Unix environment (Solaris or AIX) IBM ematrix request servlet requirements The IBM ematrix request servlet communicates with ematrix via RMI. It operates on any platform for which ematrix provides RMI ADK support. For the 9.5.0.2 release of ematrix, supported platforms include Windows (NT or 2000), Solaris, AIX, and HP. In addition, this servlet requires the following: v v The 9.5.0.2 release of the MatrixOne ematrix system using the ematrix RMI collaboration server. Include ematrixserrvletrmi.jar in addition to the native client libraries installed with ematrix. The servlet does not require direct access to those client libraries, but the ematrix ADK (used by the servlet) does. These libraries are provided by MatrixOne and must be available to the servlet from its web server. In addition, the ematrix RMI daemon must be installed and running on the machine hosting the ematrix server. IBM XML servlet for ICS Requirements The Java-based IBM XML servlet for ICS communicates with ICS via Server Access Interface and runs on any platform for which a compatible JVM is available. It requires the following: v v Access to the Java servlet classes. These are normally included with the application server or servlet containers in which the servlet is deployed. An installed and running WebSphere-compatible Object Request Broker (ORB) service. Copyright IBM Corp. 2002, 2003 7

Overview of installation tasks To install the adapter for ematrix, you must perform the following tasks: Install ICS This task, which includes installing and starting the ICS integration broker, is described in the System Installation Guide. You must install release 4.1.0 the integration broker. To load files into the integration broker repository, consult both Loading files into the repository on page 10, and the System Installation Guide. Install the XML connector and related files This task includes installing the files for the XML connector (and related components such as the XML data handler) onto your system. See XML Connector Guide. Install the adapter for ematrix files This task includes installing the IBM ematrix Request and XML servlets, the request-response data handler, and using the samples and DTD s to verify system installation. You deploy the servlets on WebSphere application servers. Table 1 and Table 2 describe the Windows and UNIX files included with the adapter for ematrix. Table 1. Installed Windows file structure for the adapter Subdirectory of %ProductDir% connectors\ematrix\cwematrix.war DataHandlers\CWRequestResponseDataHandler.jar connectors\ematrix\samples\readme.txt connectors\ematrix\samples\ematrixsample_admin_programs.exp connectors\ematrix\samples\dtds\xmlservleterror.dtd connectors\ematrix\samples\dtds\ematrixrequestservleterror.dtd connectors\ematrix\samples\ematrixsample_admin_widget.exp connectors\ematrix\samples\ematrixsample_mo_serverdatahandler.in connectors\ematrix\samples\ematrixsample_objects.in connectors\ematrix\samples\ematrixsample_collabs.in Description A WAR file (Web-application ARchive) containing the XML servlet for ICS, the ematrix request servlet, and a web.xml deployment descriptor. An updated data handler library containing the request-response data handler. Instructions for deploying the samples Sample ematrix objects (see readme.txt for usage) DTD describing the error message generated by the XML servlet DTD describing the error message generated by the ematrix request servlet Sample ematrix objects (see readme.txt for usage) Sample definitions (see readme.txt for usage) Sample definitions (see readme.txt for usage) Sample definitions (see readme.txt for usage) 8 Adapter for ematrix User Guide

Table 1. Installed Windows file structure for the adapter (continued) Subdirectory of %ProductDir% Description connectors\ematrix\samples\ematrixsample_templates.in Sample definitions (see readme.txt for usage) connectors\ematrix\samples\ematrixsample_widgetevent_template.class Sample CrossWorlds template class (see readme.txt for usage) connectors\ematrix\samples\ematrixsample_widgetsearchrequest_ Sample CrossWorlds template class Template.class (see readme.txt for usage) connectors\ematrix\samples\dtds\widgetretrieveinventoryevent.dtd DTDs describing the XML messages exchanged in the sample connectors\ematrix\samples\dtds\widgetretrieveinventoryeventresponse.dtd DTDs describing the XML messages exchanged in the sample connectors\ematrix\samples\dtds\widgetsearchrequest.dtd DTDs describing the XML messages exchanged in the sample connectors\ematrix\samples\dtds\widgetsearchrequestresponse.dtd DTDs describing the XML messages exchanged in the sample Note: All IBM pathnames are relative to the directory where the product is installed on your system. Table 2. Installed UNIX file structure for the connector Subdirectory of ${ProductDir} connectors/ematrix/cwematrix.war DataHandlers/CWRequestResponseDataHandler.jar connectors/ematrix/samples/readme.txt connectors/ematrix/samples/ematrixsample_admin_programs.exp connectors/ematrix/samples/dtds/xmlservleterror.dtd connectors/ematrix/samples/dtds/ematrixrequestservleterror.dtd connectors/ematrix/samples/ematrixsample_admin_widget.exp connectors/ematrix/samples/ematrixsample_mo_serverdatahandler.in connectors/ematrix/samples/ematrixsample_objects.in connectors/ematrix/samples/ematrixsample_collabs.in connectors/ematrix/samples/ematrixsample_templates.in connectors/ematrix/samples/ematrixsample_widgetevent_template.class connectors/ematrix/samples/ematrixsample_widgetsearchrequest_ Template.class connectors/ematrix/samples/dtds/widgetretrieveinventoryevent.dtd Description A WAR file (Web-application ARchive) containing the XML servlet for ICS, the ematrix request servlet, and a web.xml deployment descriptor. An updated data handler library containing the request-response data handler. Instructions for deploying the samples Sample ematrix objects (see readme.txt for usage) DTD describing the error message generated by the XML servlet DTD describing the error message generated by the ematrix request servlet Sample ematrix objects (see readme.txt for usage) Sample definitions (see readme.txt for usage) Sample definitions (see readme.txt for usage) Sample definitions (see readme.txt for usage) Sample definitions (see readme.txt for usage) Sample CrossWorlds template class (see readme.txt for usage) Sample CrossWorlds template class (see readme.txt for usage) DTDs describing the XML messages exchanged in the sample Chapter 2. Installation and startup 9

Table 2. Installed UNIX file structure for the connector (continued) Subdirectory of ${ProductDir} Description connectors/ematrix/samples/dtds/widgetretrieveinventoryeventresponse.dtd DTDs describing the XML messages exchanged in the sample connectors/ematrix/samples/dtds/widgetsearchrequest.dtd DTDs describing the XML messages exchanged in the sample connectors/ematrix/samples/dtds/widgetsearchrequestresponse.dtd DTDs describing the XML messages exchanged in the sample Note: All IBM product pathnames are relative to the directory where the product is installed on your system. Loading files into the repository If you are installing the adapter as part of an initial installation, follow the procedures in the System Installation Guide for starting InterChange Server and loading the repository. If you are adding the connector to an existing installation, use the repos_copy command to load the ematrix content. Procedures for using the repos_copy command are in the System Administration Guide. To implement the adapter for ematrix, you must load the following files into the repository: v Overview of configuration tasks The MO_Server_DataHandler_Default.txt file. In a new installation, select the DevelopmentKits option from the Installer menu. This creates the MO_Server_DataHandler business object in the \repository\edk directory. If you are adding the connector to an existing installation that does not already have the Development\edk files loaded, you need to install these files and use the repos_copy command to load them into the repository. After loading this file, you must modify it. See Chapter 5, Configuring the request-response data handler, on page 21. After installation and before startup, you must configure components as follows: Configuring the ematrix request servlet The IBM ematrix request servlet, which is contained in CWEmatrix.war, requires a working installation of ematrix and the RMI-based collaboration server, details of which are beyond the scope of this document. For an explanation of how the servlet is configured to communicate with the ematrix RMI-based collaboration server, see Chapter 3, Configuring the ematrix request servlet, on page 13. You can also use the ready-made deployment descriptor web.xml contained in the CWEmatrix.war. Configuring the XML servlet for ICS For information on configuring the XML servlet for ICS contained in CWEmatrix.war, see Chapter 4, Configuring the XML servlet for ICS, on page 17. You can also use the ready-made deployment descriptor web.xml contained in the war file. Note: This guide does not document how to deploy a servlet on a web-server. 10 Adapter for ematrix User Guide

Configuring the connector This task includes setting up and configuring the XML connector and XML data handler. See the XML Connector Guide. Configuring business objects The steps for configuring business objects depend on how you elect to implement the adapter for ematrix. You must create the business objects that correspond to v v Request messages Each possible response, including faults To configure business objects for requests, see the XML Connector Guide. For event business objects, see Chapter 5, Configuring the request-response data handler, on page 21. Configuring the data handler To configure the request-response data handler you must: Starting the connector 1. Add the request-response data handler to your server-side ICS installation. 2. Copy the CWRequestResponseDataHandler.jar file to the %ProductDir%\DataHandlers directory (Windows) or the ${ProductDir}/DataHandlers directory (UNIX). 3. Open \bin\start_server.bat and update the server classpath as follows: Change set DATAHANDLER="%CROSSWORLDS%"\DataHandlers\CwDataHandler.jar; "%CROSSWORLDS%"\DataHandlers\CustDataHandler.jar to the following: set DATAHANDLER="%CROSSWORLDS%"\DataHandlers\CwDataHandler.jar; "%CROSSWORLDS%"\DataHandlers\CustDataHandler.jar; "%CROSSWORLDS%"\DataHandlers\RequestResponseDataHandler.jar 4. Modify your server data handler configuration meta-object and define a mime-type that correlates to this data-handler. For more information, see Chapter 5, Configuring the request-response data handler, on page 21. See the Adapter for XML User Guide. Chapter 2. Installation and startup 11

12 Adapter for ematrix User Guide

Chapter 3. Configuring the ematrix request servlet v About configuring the ematrix request servlet v Usage on page 14 v Error handling on page 15 v Logging and tracing on page 15 The IBM ematrix request servlet enables collaborations in ICS to invoke ematrix programs within a MatrixOne environment. The servlet, which communicates with ematrix via the ematrix ADK, accepts XML documents that define: v a program in ematrix to invoke v content to pass as a parameter The IBM ematrix request servlet returns any data generated by the ematrix program. This chapter describes how to configure and use the IBM ematrix request servlet. About configuring the ematrix request servlet Note: The IBM ematrix request servlet, which is contained in CWEmatrix.war, requires a working installation of ematrix and the RMI-based collaboration server. You can also modify and use the ready-made deployment descriptor web.xml contained in the CWEmatrix.war. For information on compile and run time requirements for the IBM ematrix request servlet as well as how to install it and where to store its source code, see Chapter 2, Installation and startup, on page 7. The IBM ematrix request servlet extends class com.matrixone.servlet.frameworkservlet provided by MatrixOne. 1 This parent class handles the majority of steps involved in establishing a connection to ematrix. This class retrieves its configuration information from the file framework.properties, which is included in the ematrix collaboration server installation. The framework.properties file defines the host, the RMI port, and other parameters for the ematrix server. You must ensure that the configuration properties specified in this file match those of your installation. The structure of the framework.properties file is a series of name-value pairs. The following is an excerpt: ematrix.server.host=//localhost:1099 ematrix.server.name=:bos ematrix.page.path=/ematrix ematrix.servlet.ui=true ematrix.load.program=eservicelistschemanames.tcl Note: When using the RMI ADK, ensure that property ematrix.server.host is of the format //<host>:<port> where host is the machine on which your ematrix RMI daemon is running and port is the port on which the daemon is listening. 1. The MatrixOne XML Exchange Servlet extends the same class. Copyright IBM Corp. 2002, 2003 13

In order for the servlet to find this information, the fully-qualified path of the properties file must be specified in the servlet parameter properties in the deployment descriptor of the application server or servlet container where it is deployed. Here is a sample entry showing how the properties file should be specified for the servlet (see web.xml included in CWEmatrix.war): <servlet> <servlet-name>matrixexchangeservlet</servlet-name> <servlet-class>com.matrixone.servlet.matrixexchangeservlet</servlet-class> <init-param> <param-name>properties</param-name> <param-value>c:\ematrix\java\properties\framework.properties</param-value> </init-param> </servlet> Table 3 summarizes the servlet initialization parameters and values For more information, see the ematrix documentation that discusses the FrameworkServlet. Table 3. Servlet initialization parameters and values Property name Property value Required properties The fully-qualified path to Yes file framework.properties. This is normally located in the \java\properties directory of your ematrix collaboration server installation. username The name of the user to use No when logging into ematrix. userpassword The password to use when logging into ematrix No Usage You post XML documents to the IBM ematrix request servlet to invoke programs in ematrix. The ematrix programs invoked through this servlet must accept XML and respond with XML. The structure of XML documents accepted by the servlet are as follows: 1. The top-level element of any XML document that is posted is treated as the name of the target program. 2. All child elements and text are passed as a string to the target program in the first program parameter. For example, sending this document to the servlet: <RetrievePrice> <item> <id>123</id> </item> </RetrievePrice> This would be equivalent to invoking the program RetrievePrice using the following MQL command in ematrix: execute program RetrievePrice {<item><id>123</id></item>} The data that RetrievePrice generates is returned by the servlet to the posting application. 14 Adapter for ematrix User Guide

Error handling Logging and tracing If an error occurs while the IBM ematrix request servlet is parsing the XML message or invoking the ematrix program, the servlet returns an XML message describing the problem. For the exact message structure, see the ematrixrequestservleterror.dtd included with installation. Here is a sample: <?xml version="1.0"?> <!DOCTYPE ematrixrequestservleterror> <error>failed to execute program RetrievePrice : program not found.</error> You must take additional steps to ensure that error messages are detected. When a request is issued to the servlet via the XML connector, the connector returns a response regardless of whether the servlet successfully invokes the target ematrix program. Since the XML connector places no semantic value on the content of this response, the connector populates the appropriate child object in the TLO and the servlet returns an XML response even when it encounters errors. Because this servlet returns well-formed XML regardless of whether it executes the program, additional steps must be taken to identify when errors occur. 1. Ensure that the top-level object (TLO) to be sent to the XML connector has at least two response objects defined: one designed to return data from the ematrix program and another to contain the servlet error message. 2. The collaboration must check explicitly which response object (the expected response or an error response) is populated in the TLO. This same error detection design applies to ematrix programs invoked through the servlet. If an ematrix program fails while running, it returns an XML message describing the failure. You must create a response BO that corresponds to this error message and add it to the TLO. The servlet logs all tracing and error messages using the log methods available in the javax.servlet.servletcontext instance. This allows the application server or other servlet container to manage the tracking and recording of messages (as configured by an administrator). The servlet does not write messages directly to the console through the System.out or System.err streams. Chapter 3. Configuring the ematrix request servlet 15

16 Adapter for ematrix User Guide

Chapter 4. Configuring the XML servlet for ICS v About configuring the XML servlet for ICS v Usage on page 18 v Error handling on page 19 v Logging and tracing on page 19 This IBM XML servlet for ICS enables programs in ematrix to synchronously issue requests to ICS collaborations and to retrieve data from those collaborations. From a WebSphere perspective, the servlet enables synchronous event notification. The servlet accepts posted XML documents and sends them to specific collaborations in ICS via the Server Access Inter Interface. The servlet returns any data generated by the collaborations. This chapter describes how to configure and use the IBM XML servlet for ICS. About configuring the XML servlet for ICS Note: The Java-based IBM XML servlet for ICS is contained in CWEmatrix.war.You can also modify and use the ready-made deployment descriptor web.xml contained in the.war file. For information on compile and run time requirements for the IBM ematrix request servlet as well as how and where to install it, see Chapter 2, Installation and startup, on page 7. The IBM XML servlet for ICS requires access to crossworlds.jar and vbjorb.jar via the web server on which the servlet is deployed. Both of these files are included in the standard Adapter for ematrix installation. Refer to your web server documentation for more information about making external libraries available to servlets. In many cases, these jar files can simply be added to the classpath of your web server or dropped in a common library folder that is made available to all web applications. In order to communicate with ICS, the servlet must have the following information during initialization: the ICS name, the ICS IOR file location, the default user name and the default user password. To configure these properties, you must add the initialization parameters shown in Table 4 to the deployment descriptor for the servlet. Table 4. Servlet initialization parameters and values Property name Property value Required iorfile The fully-qualified path to Yes your ICS IOR file. This file is normally located in the \ProductDir top-level directory and named <server_name>.ior. defaultuser The name of the user to use when logging into the ICS. No. This property can be specified on a per-request basis in the HTTP POST header. The default is admin. Copyright IBM Corp. 2002, 2003 17

Table 4. Servlet initialization parameters and values (continued) Property name Property value Required defaultpassword The password to use when logging into ICS. No. This property can be specified on a per-request basis in the HTTP POST header. The default is null. ORBClassName ORBSingletonClassName ORB class that will be initialized for use in establishing a CORBA session with ICS. ORB class that will be initialized for use in establishing a CORBA session with ICS. No. The default is com.inprise.vbroker.orb.orb No. The default is com.inprise.vbroker.orb.orbsingleton The following excerpt from the web.xml deployment descriptor (included in the CWEmatrix.war file) shows how to specify initialization parameters for a servlet: <servlet> <servlet-name>cw_xmlservlet</servlet-name> <init-param> <param-name>iorfile</param-name> <param-value>c:\crossworlds\myserver.ior</param-value> </init-param> </servlet> For specific details on the syntax of the deployment descriptor, refer to the documentation included with your application server or servlet container. Usage Once deployed, an application can send requests to ICS by posting documents to the servlet. Please note the following requirements: 1. The content of the posted message (excluding the HTTP header) is what is sent to ICS. 2. The mime-type of the posted message (as specified in the HTTP header) is passed to ICS and determines which data handler ICS uses to convert the document to a business object. ICS looks up the mime-type in the meta-object MO_Server_DataHandler and uses the data handler configured therein to convert the document to a business object. The mime-type passed should, in most instances, be associated with the request-response data-handler described in Chapter 5, Configuring the request-response data handler, on page 21. 3. The application must specify the target collaboration and verb to the servlet in the servlet URL. The parameter names to specify the collaboration and verb are collab and verb, respectively. For example, if an ematrix program posted a request to: http://servlet_url?collab=targetcollab&verb=retrieve&port=from, the servlet would infer that the request must be sent to port From of collaboration TargetCollab to perform the scenario associated with the Retrieve verb. 4. Rather than specify the user name and password in the deployment descriptor, the user can pass the user name and password to logon to ICS in the Authorization parameter of the HTTP header. The servlet accepts the 18 Adapter for ematrix User Guide

HTTP/1.0 BASIC authorization scheme in which the user name and password are separated by a colon (<username>:<password>) and encoded with base 64. Error handling If an error occurs while the servlet is processing the document, converting the posted document to a valid BO, or while ICS is executing the target collaboration, the servlet returns a valid XML error message. For the exact structure of error messages, see XMLServletError.DTD, which is included in the standard installation. Here is a sample error message: <?xml version="1.0"?> <!DOCTYPE XMLServletError> <error> Logging and tracing  <rc>-1</rc>  <message>verb "Retrieve" not supported for collaboration "CustomerSync"</message> </error> The servlet logs all tracing and error messages using the log methods available in the javax.servlet.servletcontext instance. This allows the application server or other servlet container to manage the tracking and recording of messages (as configured by an administrator). The servlet does not write messages directly to the console through the System.out or System.err streams. Chapter 4. Configuring the XML servlet for ICS 19

20 Adapter for ematrix User Guide

Chapter 5. Configuring the request-response data handler v About configuring the request-response data handler v Sample data handler meta-objects on page 22 v Top-level business object requirements on page 27 v Data handler logic on page 28 v Synchronous event notification on page 28 v Error handling on page 29 v Logging and tracing on page 29 The request-response data handler is used when an ematrix program generates an XML document (an event) and posts it to the IBM XML servlet for ICS. The request-response data handler enables the ICS integration broker to post one business object type to a collaboration port and receive one or more different business objects in return. For example, an ematrix user can send a customer object to a collaboration and receive an array of pending order objects for that customer in return. This chapter describes how to configure the request-response data handler and how it processes messages. About configuring the request-response data handler Note: The request-response data handler is contained in CwDataHandler.jar. For information on requirements for the request-response data handler as well as how to install it and where to store its source code, see Chapter 2, Installation and startup, on page 7. The request-response data handler retrieves its configuration properties from a hierarchy of meta-objects. The parent meta-object allows a connector or Server Access Interface to instantiate a data handler based on the mime-type of the document. The child meta-object contains all the information needed to process the data in the document, including the class name of the data handler, the prefix of the business object to create, and more. The adapter for ematrix includes a business object definition for a child meta-object, MO_DataHandler_DefaultRequestResponse. Since the request-response data handler is configured to interact with an access client the IBM XML servlet for ICS MO_DataHandler_DefaultRequestResponse must be placed in the parent meta-object, MO_Server_DataHandler. This top-level meta-object is used by Server Access Interface to determine which data handler to instantiate. The mime-type of the configured data handler must match the mime-type specified by the ematrix application when it posts requests to the IBM XML servlet for ICS. Parent meta-object configuration requirements The MIME type contained in the parent meta-object, MO_Server_DataHandler, determines which data handler to use. Server Access Interface uses this meta-object to create instances of the data handlers. Accordingly, the MO_Server_DataHandler object must include an attribute named text_requestresponse that is of type MO_DataHandler_DefaultRequestResponseConfig. See Sample data handler meta-objects on page 22 for a sample that is shipped with the adapter for ematrix. Copyright IBM Corp. 2002, 2003 21

Child meta-object configuration requirements Table 5 shows a list of attributes that can be specified in the child meta-object for the request-response data-handler, MO_DataHandler_DefaultRequestResponse. Table 5. MO_DataHandler_DefaultRequestResponse attributes Attribute Description Default value ClassName Name of the data handler class to load for use with the specified MIME type. For more information, see the Data Handler com.crossworlds. DataHandlers.text.requestresponse Guide. BOPrefix Prefix used by the default NameHandler REQUESTTEST class to build the top-level business object name. For more information, see the Data Handler Guide. NameHandlerClass Name of the class to use to determine the name of the top-level business object from the content of a request document. Change the default value of this attribute if you create your own custom name handler. For more information, see the Data Handler Guide. RequestMimeType ResponseMimeType By default, the request-response data handler will prepend the value of BOPrefix to the name of the top-level business object generated by the data handler that is configured for requests. For example, if the user specifies a BOPrefix of REQUESTTEST and the data handler that is configured for requests generates object Customer, the request-response data handler creates top-level object REQUESTTEST_Customer and attempts to populate one of its child objects with the Customer object. Mime-type of requests processed by this data-handler. The request-response data handler uses this mime-type to create a data handler instance to process any request business objects or documents. Mime-type of responses processed by this data-handler. The request-response data handler uses this mime-type to create a new data-handler to process any response business objects or documents. text/xml text/xml Sample data handler meta-objects Here is the data handler meta-object that is included in the samples directory of the adapter for ematrix. It contains three data handler meta-object definitions as follows: MO_Server_DataHandler MO_DataHandler_DefaultXMLConfig MO_DataHandler_DefaultRequestResponseConfig 22 Adapter for ematrix User Guide

[ReposCopy] Version = 4.0.0 RepositoryID = KZKMSXX3EDQ= [BusinessObjectDefinition] Name = MO_DataHandler_DefaultXMLConfig Version = 1.0.0 [Attribute] Name = SubType Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = true DefaultValue = XML IsRequiredServerBound = false [Attribute] Name = BOPrefix Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false DefaultValue = EMatrixSample IsRequiredServerBound = false [Attribute] Name = EntityResolver Type = String Cardinality = 1 MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [Attribute] Name = DTDPath Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [Attribute] Name = NameHandlerClass Type = String Cardinality = 1 Chapter 5. Configuring the request-response data handler 23

MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [Attribute] Name = Parser Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [Attribute] Name = ClassName Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false DefaultValue = com.crossworlds.datahandlers.text.xml IsRequiredServerBound = false [Attribute] Name = DummyKey Type = String Cardinality = 1 MaxLength = 1 IsKey = true IsForeignKey = false IsRequired = false DefaultValue = 1 IsRequiredServerBound = false [Attribute] Name = ObjectEventId Type = String Cardinality = 1 MaxLength = 255 IsKey = false IsForeignKey = false IsRequired = false IsRequiredServerBound = false [Verb] Name = Create [Verb] Name = Delete 24 Adapter for ematrix User Guide