    All Examples  XML Examples

# BizTalk server example

About this example
  BizTalk server architecture
  Files included in this example
  Configuring and running BizTalk server
How to use this example
  Build the example
  Configure WebLogic Server
  Configure BizTalk server
  Run the example
  Re-configure BizTalk server and re-run
There's more

# about this example

This example illustrates:

- A prototype BizTalk Server
- Generating XML (BizTalk) documents within a JSP page
- Passing XML (BizTalk) documents via HTTP Post and JMS
- Processing XML (BizTalk) documents within EJBs
- Creating Java wrapper classes for handling XML (BizTalk) documents
- Routing documents for processing based on attributes stored in XML (BizTalk) documents

BizTalk is a platform neutral framework for business-to-business (B2B) communication and is based on XML technology. For additional information on BizTalk, see BizTalk.org. The BizTalk example is a prototype implementation of the BizTalk framework. This is not intended to be a fully functional BizTalk server, rather is presented as a tool to help teach you how XML can be used with WebLogic Server.

The BizTalk server is a server-side handler for incoming BizTalk documents. BizTalk documents are XML documents that are made up of two main parts:

- BizTalk envelope - includes information on the document type, destination, and source. This information is used to route the document to the appropriate handler.
- Payload - the user data to be processed.

In this example, a BizTalk client (BizClient.jsp) generates and sends a BizTalk document to the BizTalk server. This payload of the document defines a stock trade request. The document is received by the BizTalk server and handed to the appropriate EJBs for processing.

## BizTalk server architecture

BizTalk Documents are received by a protocol adapter then placed into the incoming message queue (JMS queue) of the BizTalk server. This example implements an HTTP protocol adapter only, however adapters for other protocols such as SMTP could easily be added to this architecture. The BizTalk server de-queues the BizTalk document and parses it to determine the "To" address and the document type. If the "To" address does not match the BizTalk server's URI (as defined in the configuration file), the document is placed in the Error queue. In this implementation, no additional processing is performed on documents placed in the Error queue. If the document's "To" address matches the BizTalk server's URI, the document is passed to the appropriate EJBs (as defined in the configuration file) for processing through the bean's service method.

## Files included in this example

### BizTalk server files

File | Description
BizServer.java | This class creates and initializes a JMS QueueReceiver to read BizTalk documents as they are queued by the adapters. After verifying that it is the document's intended receiver, this class forwards the document to the appropriate EJBs for processing.
BizHttpProtocolAdapter.java | This HTTP servlet is used to accept BizTalk documents through the HTTP POST method and place the documents in the BizTalk incoming queue.
IncomingMessage.java | Interface that describes a BizTalk document received by a BizTalk server.
OutgoingMessage.java | Interface that describes a BizTalk document that is intended as a response to a received document.
DOMIncomingMessage.java | Implements the IncomingMessage interface and has the ability to parse the document using a DOM parser. This is basically a Java wrapper for incoming BizTalk documents.
DOMOutgoingMessage.java | Implements the OutgoingMessage interface. This a generic builder of BizTalk Documents.
BizAdapter.java | Helper class used by protocol adapters to queue incoming messages.
BizConfig.java | Stores the configuration parameters of the BizTalk server.
BizException.java | Thrown if the BizTalk server fails to read the incoming message.
trade.xml | Configuration file for the "trade" BizTalk server. See Configuring and running BizTalk server

### EJBs

Two EJBs are included with this example to show how a single document type can be mapped to multiple EJBs for processing.

BizBean.java | Interface for EJBs used with the BizTalk server.
BizBeanHome.java | Interface for EJB homes used with the BizTalk server.
BizTraderBean.java | Implements BizBean. Executes the stock trade.
BizTradeJournalBean.java | Implements BizBean. Logs an entry of the trade into the customers 'journal'. The 'journal' is a text file named customerName.log that is added to this directory.
ProcessingErrorException.java | Used by BizTraderBean. Thrown if an error occurs while either buying or selling a stock.

### Clients

These clients are used to Administer Biztalk server and generate BizTalk documents to be processed by BizTalk server.

AdminCLU.java | Administration utility used to start, stop, and configure the BizTalk server. This is a client application that sends commands to the BizTalk server in the form of BizTalk documents.
BizClient.jsp | JSP page used to generate a BizTalk document defining a stock trade and send it to BizHttpProtocolAdapter via the POST method.

## Configuring and running BizTalk server

This architecture allows you to have multiple BizTalk servers running within a single instance of WebLogic Server. Configuration properties for each BizTalk server are stored in an XML file named BizTalkServerName.xml. This example creates a BizTalk server named "trade". The trade.xml file in this directory defines the following properties:

- name - This attribute defines the name of the BizTalk server.
- verbose - If this is true, information will be printed to the command shell running WebLogic Server.
- uri - This attribute defines the address of the BizTalk server. This value is compared to an incoming document's "To" address to verify that this server is the intended recipient. This address defaults to http://localhost:7001/BizTalkServer. If you will be running the browser client (used to load up BizClient.jsp ) on a machine other than the machine running weblogic server, you must change localhost in the URI to the name of the host running WebLogic Server.
- Bean - This element defines the JNDI name of a BizBean home that is deployed in WebLogic Server.
- Mapping - This element maps the EJB defined in the "bean" attribute to the document type defined in the "doc" attribute.

The AdminCLU utility is used to start, stop, and configure a BizTalk server. The utility is run with the following command:

      $ java examples.xml.biztalk.AdminCLU name

where name is the name of the BizTalk server. The AdminCLU utility will look for a configuration file name.xml within the current directory. The properties in this file are used to configure the BizTalk server when it is started or re-configured. The AdminCLU utility will accept the following commands when prompted:

- start - starts the BizTalk server
- stop - stops the BizTalk server
- config - re-configures the BizTalk server with the properties in name.xml
- quit - quits the AdminCLU utility

Additionally, two JMS queues used by the BizTalk server must be configured in your WebLogic Server. BizTalk server expects a certain naming convention for the incoming and error queues. These should be configured in the weblogic.properties file as follows:

      weblogic.jms.queue.nameIncoming=biztalk.jms.nameIncoming
      weblogic.jms.queue.nameError=biztalk.jms.nameError

where name is the name of the BizTalk server.

# how to use this example

## Build the example

1. Set up your development shell, as described in Setting up your environment.
2. This directory contains a pair of shell scripts for building the example under UNIX (build.sh) and Windows NT (build.cmd). Run the appropriate script as shown in this example for Windows NT:

         $ build.cmd

   See BizTalk example build scripts for detailed information on what these scripts are doing.

## Configure WebLogic Server

The following entries are included commented-out in your weblogic.properties file.

1. Verify that the servlet classpath points to the myserver/servletclasses directory in the weblogic.properties file.

         weblogic.httpd.servlet.classpath=weblogic/myserver/servletclasses

   where weblogic is the WebLogic Server installation directory.
2. Register the JMS queues used by the BizTalk Server by un-commenting the following lines in your weblogic.properties file.

         weblogic.jms.queue.tradeIncoming=biztalk.jms.tradeIncoming
         weblogic.jms.queue.tradeError=biztalk.jms.tradeError

3. Register the BizHttpProtocolAdapter servlet by un-commenting the following lines in your weblogic.properties file.

         weblogic.httpd.register.BizTalkServer=examples.xml.biztalk.BizHttpProtocolAdapter
         weblogic.httpd.initArgs.BizTalkServer=bizQueue=biztalk.jms.tradeIncoming

4. Deploy the BizTraderBean and BizTradeJournalBean EJBs by adding the fully qualified path to the xml_biztalk_ejb_bizTrader.jar and xml_biztalk_ejb_bizTradeJournal.jar jar files to the weblogic.ejb.deploy property in the weblogic.properties file. These jar files should have been built into the /weblogic/myserver directory when you ran the build script.
5. Enable JSP pages by un-commenting the following lines in your weblogic.properties file.

         weblogic.httpd.register.*.jsp=\
                weblogic.servlet.JSPServlet
         weblogic.httpd.initArgs.*.jsp=\
                pageCheckSeconds=1,\
                compileCommand=/java/bin/javac.exe,\
                workingDir=/weblogic/myserver/classfiles,\
                verbose=true

   Ensure that compileCommand points to a valid Java compiler that is compatible with your java runtime that you are running the server under (i.e. if you are running the server under Java2, the compileCommand should point to the Java2 compiler).
6. Copy BizClient.jsp to your document root. The document root is the top level directory for files that are publically available on your WebLogic Server, and it is the root directory for JSP files. The default location is at /weblogic/myserver/public_html. For more details, see Setting up a document root.

## Configure BizTalk server

1. The AdminCLU utility configures a BizTalk server with the properties defined in a given XML file. In the trade.xml file in this directory, edit the line that sets the value of the uri attribute to be

       uri="http://hostname:port/BizTalkServer"

   where:
   hostname
     Host name of the WebLogic Server
   port
     Port where the WebLogic Server is listening for connections (weblogic.system.ListenPort).

## Run the example

1. Start the WebLogic Server in a new command shell. For this examples to run properly, you need to start the server using 7001 for the weblogic.system.ListenPort.
2. In your development shell, run the AdminCLU utility with the following command:

         $ java examples.xml.biztalk.AdminCLU trade

   The above command will cause the AdminCLU utility to read the trade.xml file within this directory and configure the BizTalk server based on the properties of this file. In order for AdminCLU to locate the trade.xml file, the command prompt must be at this directory when running the above command. Also note that this command must be run on the host running WebLogic Server.
3. After starting AdminCLU, start the BizTalk Server by entering start at the prompt.
4. Call the BizClient within a browser with a URL like:

       http://hostname:port/BizClient.jsp

   where:
   hostname
     Host name of the WebLogic Server
   port
     Port where the WebLogic Server is listening for connections (weblogic.system.ListenPort).
5. Fill out the form and hit Submit trade. View the output in the command shell running WebLogic Server. A trade.log will also be created in this directory and will contain information on the actions of the BizTalk server.

## Re-configure BizTalk server and re-run

The following steps will re-configure the BizTalk server by adding an additional EJB to the Trade document type mapping. This will cause Trade documents to be process by BizTraderBean -- to execute the trade -- and BizTradeJournalBean -- to log an entry of the trade into the customer's journal. The 'journal' is a text file named customerName.log that is added to this directory.

1. Edit trade.xml by un-commenting out the following lines:

         <Bean>bizTalk.BizTradeJournalHome</Bean>

         <Mapping
             doc="Trade"
             bean="bizTalk.BizTradeJournalHome" />

   This will cause the BizTradeJournalBean to also process each Trade document that the BizTalk server receives.
2. Enter config at the prompt in the shell running AdminCLU. This will re-configure the BizTalk server with the new trade.xml file.
3. Enter another trade in BizClient.jsp and view the results in the command shell running WebLogic Server.

   Note: When running this example, do not bring down WebLogic Server without first stopping the BizTalk server by entering 'stop' in the AdminCLU utility. AdminCLU creates a sub-process to run the BizTalk server. Stopping and starting WebLogic Server while BizTalk server is running will result in exceptions when attempting to create the sockets.

# there's more...

Read more about XML in Using XML with WebLogic Server.

Read more about Servlets in the Developer Guide, Using WebLogic HTTP Servlets.

Read more about JMS in the Developer Guide, Using WebLogic JMS.

Read more about Enterprise JavaBeans in BEA WebLogic Server Enterprise JavaBeans.

Read more about JSP in the Developer Guide, Using WebLogic JSP.

Copyright © 2000 BEA Systems, Inc. All rights reserved.