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
- Set up your development shell, as described in
Setting up
your environment.
- 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.
- 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.
- 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
- 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
- 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.
- 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).
- 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
- 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
-
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.
-
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.
- After starting AdminCLU, start the BizTalk Server by entering start at the
prompt.
- 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).
- 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.
- 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.
- Enter config at the prompt in the shell running
AdminCLU. This will re-configure the BizTalk server
with the new trade.xml file.
- 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.