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:

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:

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:

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:

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.