JNBridge JMS Adapter for BizTalk Server
User’s Guide
Version 4.0
www.jnbridge.com
JNBridge, LLC
www.jnbridge.com
COPYRIGHT © 2007-2016 JNBridge, LLC. All rights reserved.
JNBridge is a registered trademark and JNBridgePro and the JNBridge logo are trademarks of JNBridge, LLC.
Oracle and Java are registered trademarks of Oracle and/or its aliates.
Microsoft, Windows, Windows Vista, Windows Server, BizTalk and the Windows logo are trademarks, or registered
trademarks of Microsoft Corporation in the United States and/or other countries.
All other marks are the property of their respective owners.
This product includes software developed by the Apache Software Foundation (www.apache.org).
3
USERS’ GUIDE
Version 4.0
Contents
How to use this guide ............................................................................................................ 5
Additional resources .............................................................................................................. 5
Overview of the JNBridge JMS Adapter for BizTalk Server ................................................... 6
How it works ....................................................................................................................................6
Installing, Licensing and Conguring the JMS Adapter ......................................................... 8
Supported Platforms for JNBridge JMS Adapter for BizTalk Server ................................................8
Target Machine Prerequisites ..........................................................................................................8
Installing the JMS Adapter ...............................................................................................................8
Troubleshooting installation exceptions........... .......................................................................................... 9
Licensing .........................................................................................................................................9
License les ............................................................................................................................................. 10
Licensing and application conguration les ........................................................................................... 10
Evaluation licenses ...................................................................................................................................11
On-line activation ......................................................................................................................................11
O-line activation ..................................................................................................................................... 12
License managers ................................................................................................................................... 12
64-bit vs. 32-bit platforms ..............................................................................................................13
32-bit platforms ........................................................................................................................................ 13
64-bit platforms ........................................................................................................................................ 13
BizTalk Conguration of the JMS Adapter ........................................................................... 13
Adding the JMS Adapter to BizTalk Server ....................................................................................14
Conguring Send and Receive Adapter Handler Properties .........................................................15
JMS Properties Category ......................................................................................................................... 15
JNBridge Properties Category ................................................................................................................. 17
Security Properties Category ................................................................................................................... 18
Batch Properties Category ....................................................................................................................... 18
Debugging Properties .............................................................................................................................. 19
Removing or Nullifying Property Values ........................................................................................19
Conguring Send Ports and Receive Locations .................................................................. 20
Creating and Conguring Send Ports ............................................................................................20
Adapter Behavior Category ..................................................................................................................... 21
Connection Properties Category .............................................................................................................. 22
JMS Operation Properties Category ........................................................................................................ 23
Override Transmit Handler Properties Category ...................................................................................... 23
4
USERS’ GUIDE
Version 4.0
Creating and Conguring Receive Ports and Locations ................................................................24
Adapter Behavior Category ..................................................................................................................... 25
Connection Properties Category .............................................................................................................. 26
JMS Operation Properties Category ........................................................................................................ 26
Override Transmit Handler Properties Category ...................................................................................... 28
Receive Polling Properties ....................................................................................................................... 28
Messaging Patterns ............................................................................................................. 29
Request Response receive ports ..................................................................................................29
Solicit Response send ports ..........................................................................................................29
Using Message Properties and Map Messages .................................................................. 30
Properties, XML Schema and .NET namespaces .........................................................................30
JMS Receive Properties .......................................................................................................................... 30
JMS Send Properties ............................................................................................................................... 32
JMS Congure Properties ........................................................................................................................ 34
Using Map Messages ....................................................................................................................36
Trouble Shooting ................................................................................................................. 37
Deploy JMS Header Schema to BizTalk Application .....................................................................37
5
USERS’ GUIDE
Version 4.0
How to use this guide
This guide contains information about installing, conguring, and using the JNBridge JMS Adapter for
BizTalk Server. It is organized according to the particular task or tasks you wish to perform with the JMS
Adapter.
Please read the section, Installing, Licensing and Conguring the JMS Adapter, before attempting to
install and congure the adapter.
All users are encouraged to read the section, Overview of the JNBridge JMS Adapter for BizTalk
Server. It gives information on the architecture of the JMS Adapter, how it works and the various
scenarios in which it can be used.
Users who have purchased licenses or are planning a deployment of the JNBridge JMS Adapter for
BizTalk Server, should read the section, Licensing, which describes the various licensing mechanisms,
and discusses the various ways of deploying license les.
Additional resources
For specic conguration of several popular JMS implementations, please see the individual
conguration guides, e.g. UsingBTSAdapterActiveMQ.pdf.
The JNBridge knowledge base, www.jnbridge.com/jn/kb, can also be searched for issues, work-
arounds and general information.
6
USERS’ GUIDE
Version 4.0
Overview of the JNBridge JMS Adapter for BizTalk Server
The JNBridge JMS Adapter for BizTalk Server is a BizTalk Adapter Framework implementation that
encapsulates the Java Message Service client capabilities into a standard BizTalk adapter. Within BizTalk
Server, the adapter can be congured as endpoints bound to receive and send ports allowing a BizTalk
Orchestration to consume and produce messages to and from JMS queues and topics.
The JMS Adapter uses interoperability technology from JNBridge to integrate any vendor’s JMS 2.0
compliant implementation into BizTalk Server. This includes ActiveMQ, JBoss, IBM WebSphere, Tibco
Enterprise Message Service, Oracle WebLogic, Oracle AQ, SonicMQ, Sun Glasssh and Open MQ.
The JNBridge JMS Adapter exposes a simple interface for conguring send and receive handler and
location properties. The JMS Adapter requires no modication to the JMS server. Nor does it require
any vendor specic native support for the Windows platform—all that is required is a vendor’s standard
Java implementation. The support for any vendor’s JMS implementation is accomplished through the
JNBridge Java and .NET interoperability product, JNBridgePro. For more information on JNBridgePro,
visit www.jnbridge.com/jnbpro.
How it works
The JNBridge JMS Adapter integrates any Java Message
Service (JMS) client into BizTalk Server.
As part of the deployment of a BizTalk Server
Orchestration, the adapter can be congured as endpoints
bound to send and receive ports, allowing the BizTalk
orchestration to produce and consume messages to and
from JMS queues and topics. The binding congures the
ports to connect to specic JMS queues and topics on a
specic JMS server, shown in Figure 1.
Once the conguration and binding is completed, the
orchestration is started. Any document directed to a send
port bound to the adapter will be sent to the corresponding
JMS queue or topic as a JMS message. Any JMS message
appearing on a queue or topic bound to a receive port
will be received from that queue or topic and enter the
orchestration as a document at that receive port.
The underlying technology that supports any JMS
implementation is JNBridgePro, JNBridge’s Java and .NET
interoperability product. JNBridgePro can be used to access
any Java API from .NET, or any .NET API from Java. The
JMS adapters implement JNBridgePro’s interoperability
Figure 1. A receive location showing the
JMS Adapter conguration
7
USERS’ GUIDE
Version 4.0
Figure 2. Architecture of the JNBridge JMS Adapter for BizTalk Server
technology to access the JMS API automatically for you. Figure 2 shows the architecture of the JNBridge
JMS Adapter for BizTalk Server.
The adapter contains both a .NET side running in a CLR and a Java side running in a JVM, where
the CLR and the JVM are running in the same process. JNBridgePro manages the inter-platform
communications. The JMS client classes are those provided by the vendor, which guarantees that the
adapter will work with any vendor’s JMS server. The adapter utilizes the BizTalk Adapter Framework to
communicate with the BizTalk Server.
8
USERS’ GUIDE
Version 4.0
Installing, Licensing and Conguring the JMS Adapter
The JNBridge JMS Adapter for BizTalk can be installed and congured on any machine running BizTalk
Server 2006, BizTalk Server 2006 R2, BizTalk Server 2009, BizTalk Server 2010 or BizTalk Server 2013/
R2.
Supported Platforms for JNBridge JMS Adapter for BizTalk Server
Windows Vista. Both x86 and x64 platforms supported.
Windows 7. Both x86 and x64 platforms supported.
Windows Server 2008. Both x86 and x64 platforms supported.
Windows Server 2008 R2 x64.
Windows Server 2012/R2
Target Machine Prerequisites
The following prerequisites are needed for either the x86 or x64 platforms.
A Java Run-time Environment (JRE) must be installed on the target machine. The JNBridge JMS
Adapter supports the Standard Edition JRE 7 or above. The JRE may be download from www.oracle.
com/technetwork/java. For 64-bit platforms, if the BTS host instance is 64-bit, a x64 JRE 7 must be
installed.
For any given JMS implementation, the JMS Java client environment must be installed including all
JAR les as well as any additional conguration such as environment variables or J2EE conguration
les.
Microsoft BizTalk Server 2006, 2006 R2, 2009, 2010, 2013/R2.
Installing the JMS Adapter
The installation of the JMS Adapter requires administrator privileges on the target machine. The
installation consists of a single installation.
Start the installation by executing the Windows Installer, e.g.
InstallBizTalkJMSAdapter_40.exe. This is a
simple installation allowing the user to accept the EULA (End User License Agreement) and to choose a
target installation directory.
If updating from version greater than or equal to 1.2, it is not necessary to uninstall the previous version
before installing version 4.0. If updating a version previous to 1.2, it is necessary to uninstall that version.
If updating, all BizTalk host instances must be shut down.
9
USERS’ GUIDE
Version 4.0
The following runtime components are installed:
● The assemblies J
NBridgeBTS2006JMSAdapter.dll, and JNBridgeBTS2006JMSProperties.dll, are
placed in the adapter’s installation \bin directory. The second assembly is also placed in the GAC.
There are two
jnbproxies.dll assemblies, one for JMS 1.1, the other for JMS 2.0. They are installed
under the \bin directory.
● The assemblies,
JNBShare.dll, JNBSharedMem_x86.dll (and JNBSharedMem_x64.dll on a 64-bit
platform) and JNBridgeJMSCore.dll, provide the .NET-to-Java bridge between the Java Virtual
Machine and the Common Language Runtime. They are installed in the GAC.
● The library,
jnbauth_x86.dll and/or jnbauth_x64.dll, contains licensing functionality and is placed in
the \bin directory.
● The assembly
Microsoft.Samples.BizTalk.Adapter.Common.dll, is part of the BizTalk Adapter
Framework and is installed in the \bin directory.
● The assembly,
JNBridgeBTS2006JMSAdapterManagement.dll, provides conguration capabilities. It
is placed in the
\bin directory.
Troubleshooting installation exceptions
If updating from version 1.2 to 4.0, it is not necessary to uninstall version 1.2. Any version prior to
1.2 will have to be uninstalled. However, uninstalling a previous version does not require removing
the adapter from BizTalk (though all host instances must be shut down).
If updating to 4.0 from a previous version, the new request/response and solicit/response capabilities
must be enabled. This can be done by removing the adapter from BizTalk and then re-adding it back
in. However, this is a real pain as all send and receive ports congured for the adapter will have to be
removed. A simpler solution is to update the BizTalk Management Database, BizTalkMgmtDb, using
this SQL statement:
UPDATE adm_Adapter SET Capabilities=15755 WHERE
MgmtCLSID=’A72F4E84-CFF0-4CF6-AC49-1E995BD36AAD’
! The the adapter will install and work on a 64-bit platform using either 32-bit or 64-bit
BTS host instances. A 32-bit host instance requires a x86 JRE. A 64-bit host instance
requires a x64 JRE.
Licensing
The JMS adapter must be licensed on each machine on which it is installed. JNBridge supports a variety
of license types. For more information, please visit www.jnbridge.com/JMS-BizTalk-Adapter-licensing.
!If you have used versions of the JMS adapter older than version 3.0, note that
starting with v3.0 we have introduced a new licensing mechanism. The concepts and
components described below will be dierent from those you might have used in
previous versions.
10
USERS’ GUIDE
Version 4.0
License les
For most types of licenses, the license is encapsulated in a license le, which is a text le whose sux is
.lic. (The le’s name is generally assigned by JNBridge’s license tracking mechanism.) When a license
le is present, the adapter will look for the license le in the adapter’s root installation directory, e.g.
C:\Program Files\JNBridge\JMSAdapters\BTS2006.
If an invalid license le is found, an InvalidLicenseException is thrown. The adapter will register
the exception in the system application event log. If error logging is enabled in the adapter, the
InvalidLicenseException will also be logged. A license le can be invalid for a number of reasons,
including:
● It has been tampered with.
● It is time-limited and has expired.
● It is node-locked, and is being used on a machine other than the one to which the original license was
locked.
Licensing and application conguration les
You have the option of specifying the location of your license le, or, if you are using a license server, the
location (host and port) of the license server. This can be done by modifying the conguration le for the
BizTalk host process,
BTSNTSvc.exe.cong or BTSNTSvc64.exe.cong.
Inside the <conguration> section of the BizTalk conguration le, add the following section if it is not
already there:
<congSections>
<sectionGroup name=”jnbridge”>
<section name=”licenseLocation” type=”System.Conguration.SingleTagSectionHandler”/>
</sectionGroup>
</congSections>
Inside the <jnbridge> section, add the following line:
<licenseLocation directory=”absolute/relative path to directory containing license le”/>
or
<licenseLocation host=”license server machine” port=”license server port”/>
Choose the rst variant if you are using a license le; choose the second variant if you are using a
license server. Again, specifying this information is optional. If you omit it, the licensing mechanism
will continue looking for the license in the adapter’s root installation directory. Here, it is also possible to
place the license manager’s host name and port number into a license le. The format of the le must be
the following and the le must end in ‘.lic’:
HOST [hostname] [port]
ISV jnbridge
11
USERS’ GUIDE
Version 4.0
Evaluation licenses
As part of the download process, you will be emailed an activation key for a 30-day evaluation license.
When you receive this key, enter it in the JMS adapter’s registration tool, shown in Figure 3, under the
Online License Activation tab and click on the Activate License button. This will allow you to use the JMS
adapter on a trial basis for 30 days. (See the section, On-line activation, below, for additional details.) You
must perform this action before you can begin your evaluation.
The evaluation license le that is obtained through this activation is node-locked, and cannot be copied
to other machines. If do you wish to place evaluation installations of the adapter on additional BizTalk
machines, you can enter the same activation key into the registration tool on the new machines at any
time and receive 30-day evaluation licenses on those machines. Please note that any deployments and
installations using evaluation licenses obtained through this activation key will stop working after the 30-
day evaluation period expires. Also note that, under the terms of your JNBridge JMS adapter for BizTalk
Server license, you may not use your evaluation license to run production applications.
It is important to note that this activation key cannot be used twice on any given machine. If you need an
extension to your 30-day evaluation period, please visit www.jnbridge.com/bin/swreg or click the button
Modify Current License and follow the instructions.
In the event that your deployment does not have Internet
connectivity, please follow the instructions in the section
“O-line activation,” below.
On-line activation
Once you have purchased adapter licenses, you will
receive an activation key. If the machines on which
you will be licensing the adapters have access to the
Internet, you can use this activation key to claim your
licenses. To do so, you must use the adapter registration
tool (RegistrationTool.exe) on each of the machines
to be licensed. The registration tool will be part of the
installation. Launch the registration tool, and select the
Online License Activation tab (Figure 3).
Paste the activation key into the
Enter Activation Key
slot and click on the Activate License button. If you have
licenses left to activate, the operation will succeed and
your installation will be licensed. The license le will be
placed in the adapter’s root installation directory.
If you have no more licenses, or the operation otherwise
fails, you will see an error message indicating the reason
for the failure. The failure may be the result of using a
proxy server to access the internet. If this is the case,
please use the button
Proxy Server URL to set the proxy
server’s host name and port number.
Figure 3. The Registration Tool and
Online Activation tab
12
USERS’ GUIDE
Version 4.0
O-line activation
In the event that the machines on which you want to license the adapter do not have Internet connectivity,
you can claim a license by launching the registration tool, then selecting the
Oine License Activation tab
(Figure 4a).
Click the
Request License button and follow the instructions in the displayed page, or copy the displayed
registration key into an email and mail the license request to [email protected], or visit www.
jnbridge.com/swreg and follow the instructions there, supplying the registration key when requested.
In response, you will be emailed a license le that you should deploy to the adapter root installation
directory, e.g. C:\Program Files\JNBridge\JMSAdapters\BTS2006.
License managers
Certain types of licenses, including oating licenses, as well as licenses that will run on terminal
servers and virtual machines, require the use of a license manager. If you have purchased these licenses,
JNBridge will provide an optional license manager, which you should install and congure.
To use a license served up by a license manager, you will need to congure the adapter to point to point
the license manager. See Licensing and application conguration les, above, for a discussion of how to
do this.
The registration tool provides some assistance in doing this. When the
Use License Manager tab is
selected (Figure 4b), the user has the option of entering the hostname and port of the license manager
(that is, the hostname of the machine on which the license manager resides, and the port on which it is
listening). Once those values are entered, clicking on the Load License button will test whether these
values are correctly congured, and, if they are, clicking on the Export Cong File button will cause a
fragment of XML containing the conguration information to be output to a le. The contents of the le
can be incorporated into the application conguration le.
Please note the following:
● Clicking the
Load License button does not obtain a license for the application being licensed. It is still
necessary to add information to the application conguration le that points to the license manager.
● If you have clicked on the
Load License button, we recommend that you exit the registration tool
before running your application.
● Use of the functionality in the
Use License Manager tab is completely optional and is provided as a
convenience. It is entirely possible to congure the application manually, without the assistance of
this tool.
13
USERS’ GUIDE
Version 4.0
Figure 4a. Using o-line activation
64-bit vs. 32-bit platforms
The JNBridge JMS Adapter for BizTalk Server supports both 32 and 64-bit platforms.
32-bit platforms
On a 32-bit platform, the adapter supports only x86.
Required JRE
The x86 version of the adapter requires a 32-bit JRE. Do not install a 64-bit JRE on a 32-bit
machine.
64-bit platforms
On a 64-bit platform, the adapter supports both x86 and x64 depending on the BTS host instance.
Required JRE
A 32-bit host instance requires a x86 JRE. A 64-bit host instance requires a x64 JRE.
BizTalk Conguration of the JMS Adapter
After the JNBridge JMS Adapter for BizTalk Server has been installed, it must be added to BizTalk and
congured using the BizTalk Server Administration Console, shown in Figure 5.
14
USERS’ GUIDE
Version 4.0
Figure 5. Adding the JNBridge JMS Adapter to BizTalk
Adding the JMS Adapter to BizTalk Server
In the BizTalk Server Administration Console nd the Adapters folder under the Platform Settings folder
and right-click to bring up the context menu. Choose the
NewAdapter… menu choice to bring up the
Adapter Properties dialog box shown in Figure 5. Using the Adapter Properties dialog box, click on
the drop-down control Adapter: and choose JMS. The user may also enter a more meaningful name
and description for the adapter. Click on OK. The JNBridge JMS Adapter will now reside in the list of
adapters in the
Adapters pane of the BizTalk Administration Console.
Figure 4b. Pointing to a license manager
15
USERS’ GUIDE
Version 4.0
Conguring Send and Receive Adapter Handler Properties
In the BizTalk Administration Console, double click the JMS Adapter in the Adapters pane to open up
the
Send and Receive properties, shown in Figure 6. Double click either Send or Receive to open the
Adapter Handler Properties dialog box. Click on the Properties button to open the Transport Properties
grid, also shown in Figure 6. This grid contains handler transport properties global to all send or receive
ports congured to use the JNBridge JMS Adapter. In other words, all JMS Adapter send or receive ports
will inherit these transport properties. You must congure send handler transport properties in order to
produce messages to queues and topics. Likewise, you must congure receive handler transport properties
in order to consume messages from queues and topics. In most cases, the values of the properties will be
identical between the send and receive handlers; however, depending on the JMS server implementation,
they may be dierent.
JMS Properties Category
In the Adapter Transport Properties dialog, Figure 6, the JMS Properties category are properties used to
properly connect to a JMS server. In most cases, you should be able to obtain the correct property values
from the administrator of your JMS server.
JMS Acknowledge Mode
The Acknowledge Mode is a drop-down list containing the JMS specication that determines
how a JMS client and server institute a reliable messaging protocol. The choices are
AUTO_
ACKNOWLEDGE, CLIENT_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE. Regardless
of the choice, the JNBridge JMS Adapter will correctly implement the protocol. For most
JMS implementations, AUTO_ACKNOWLEDGE is the default conguration.
Initial Context Factory
This is a text-editable eld containing the name of the initial context factory. The initial
context factory is a Java class that provides instances of JNDI contexts required for a
complete JMS client. While the JNBridge JMS Adapter encapsulates the implementation
details of a JMS client providing a simple abstraction of the message service, it is still
necessary to choose among the various initial context factories congured for a particular
JMS implementation. The initial context factory shown in the
Transport Properties grid in
Figure 6 is the default initial context factory for ActiveMQ.
! Factory names are case sensitive—be sure the name (including the complete
namespace, if necessary) is typed correctly.
JMS Scheme
This is a text-editable eld. The JMS Scheme, or protocol, is particular to each vendor’s JMS
implementation and the types of connections supported. Each vendor may support several
schemes such as http, https or rmi (remote method invocation). The scheme name does not
have to reect a protocol—the scheme for Tibco EMS is tibjmsnaming, for example.
16
USERS’ GUIDE
Version 4.0
JMS Version
This property tells the adapter which JMS implementation to expect when it loads the
vendor’s client stack—the JAR les in the
Class Path property. The drop-down list contains
two choices, ‘JMS 1.1’ and ‘JMS 2.0’.
JMS Security Mode
The JMS Security Mode is a drop-down list that species the type of security required by the
JMS server implementation. The choices are
none and simple. If the choice is simple, then
the server expects a user name and password.
!If the JMS server implements simple security, it is not necessary to congure this
property. Enter a user name and password—the JNBridge JMS Adapter will
automatically switch to the simple security mode.
Queue Factory
This is a text-editable eld. The queue factory produces instances of classes used to connect
to queues hosted on the JMS server. Each JMS vendor may have several queue factories
implementing dierent properties.
Figure 6. Accessing the Handler Transport Properties dialog
17
USERS’ GUIDE
Version 4.0
Topic Factory
This is a text-editable eld. The topic factory produces instances of classes used to connect
to topics hosted on the JMS server. Each JMS vendor may have several topic factories
implementing dierent properties.
JNBridge Properties Category
The JNBridge Properties Category correctly congure the .NET-to-Java interoperability core components.
Class Path
The Java class path is a set of semicolon-separated paths to the
JAR or class les required
for a JMS client installation. The class path is used by the JNBridge Java and .NET
interoperability components to locate the JMS and JNDI client Java classes so they can be
instanced in the Java Virtual Machine.
To edit the class path, click in the eld to enable the browse button . Click on the button
to launch the
Edit Class Path dialog, Figure 7. The class path can be rearranged by selecting
a class path element and clicking on the
Move Up or Move Down buttons, or by selecting an
element and clicking on the
Delete button. The les and folders in the system CLASSPATH
environment variable can be added to the
class path list by clicking on the Add system
CLASSPATH button. Note that only checked
elements will be added to the Java class path
when the dialog is dismissed.
To add a folder or JAR le to the class path,
click on the
Add… button. This causes a New
Classpath Element dialog, shown in Figure 8, to
be displayed. In this dialog, the user can navigate
to the desired folders or jar les, or can enter a
le path directly.
The
New Classpath Element dialog supports
multiple selection—multiple folders and/or JAR
les may be selected by ctrl-clicking, while a
range of folders and/or JAR les may be selected
by shift-clicking. Clicking on the
OK button will
cause the indicated folders or les to be added to
the
Edit Classpath dialog.
Figure 7. The ClassPath editor
18
USERS’ GUIDE
Version 4.0
JVM Arguments
This property is used to send arguments to the
Java Virtual Machine. The most common JVM
arguments are the heap size, .e.g.
-Xms1024m
-Xmx1024m. Other arguments can be used to set
system properties, etc.
JVM Path
The JVM Path property is the absolute path to the
Java Virtual Machine implementation, jvm.dll.
To edit the JVM Path property, click in the eld to
enable the browse button.
Click on the button to launch the standard
File
Open
dialog. Navigate to jvm.dll and
click OK.
Security Properties Category
This category provides security credentials necessary to connect to a JMS server, if the JMS
implementation supports security mode
simple. If the JMS implementation supports security mode none,
then security credentials are not required.
Password
Click in this eld to drop-down the password edit eld. Type in the password.
User Name
This is a text editable eld. Enter the user name necessary to connect to the JMS server.
Batch Properties Category
This category allows you to optimize the number of messages in a batch. This allows the JNBridge JMS
Adapter to process messages in groups rather than one at a time. Setting a batch value will diminish
overhead associated with processing messages.
Batch size
This is a text-editable eld. Enter the size of a batch.
Figure 8. The New Classpath Element
dialog
19
USERS’ GUIDE
Version 4.0
Debugging Properties
This category provides means to log errors to a user selected le.
Error Log File
Choose a error log le. Use the browse button to open the
Open File dialog. Within the
dialog, use the context menu to create and rename les.
Log Errors
Toggle this from
False to True to disable and enable error logging to the congured le.
Removing or Nullifying Property Values
It may be necessary to remove or nullify property vales that
have been set in the Transport Properties grid. If you try and
highlight the value and strike the Delete or Backspace key,
the error message shown in Figure 9 will appear.
In order to correctly null a value, you must place the cursor
over the property name, e.g. Initial Context Factory, and
right-click to obtain a context menu that allows you to null the
property eld, shown in Figure 10.
Figure 9. An annoying error message
Figure 10. Using the context menu to
null property values
20
USERS’ GUIDE
Version 4.0
Conguring Send Ports and Receive Locations
Figure 11 shows a simple BizTalk orchestration that receives messages from a queue and forwards them
on to a topic. Once this orchestration is deployed into BizTalk Server, it is necessary to bind the logical
ports ReceiveQueue and PublishTopic to actual send and receive ports created and congured using the
BizTalk Server Administration Console. The JNBridge JMS Adapter for BizTalk supports static send and
receive ports, request/response receive ports, solicit/response send ports and dynamic send ports.
Figure 11. A simple orchestration
Creating and Conguring Send Ports
Figure 12 shows the creation of a Static
One-way Send Port by right-clicking
in the Send Ports pane of a deployed
application and choosing New. This will
bring up the Send Port Properties dialog
shown in Figure 13 on the next page. For
information on using dynamic send ports,
see the section Using Dynamic Send Ports.
Solicit/Response port properties use the
same properties shown in Figure13, next
page. For more information on Solicit/
Response send ports, see the section
Messaging Patterns.
Figure 12. Creating a Static One-way Send Port
21
USERS’ GUIDE
Version 4.0
In the Send Port Properties dialog, click the drop-down control Type: and choose the JNBridge JMS
Adapter. Click the Congure button to bring up the Transport Properties dialog, Figure 13, above. This
property grid contains the location properties that determines JMS server location, message type and
whether to transmit to queues or topics.
Adapter Behavior Category
The Adapter Behavior category, shown in Figure 13, contains two properties.
Ignore Server Exceptions
If a subscribed message is available for a send port, the adapter will rst check to see if the
JMS server has sent any asynchronous exceptions. If the property
Ignore Server Exceptions
is
True, then any asynchronous exceptions sent by the JMS server will be ignored. If False,
then the send port will disconnect if any asynchronous exception is sent by the JMS server.
Figure 13. Send Port Properties and the Send Transport Properties dialogs
22
USERS’ GUIDE
Version 4.0
The send location will then post an error event and suspend the message. When the next
subscribed message is available for the send port, the adapter will attempt to reconnect to the
JMS server. If the server is still unavailable, the adapter will post an error event and suspend
the message. The send port will not disable if the server is unavailable, but will continue to
attempt a re-connection with each subscribed message. If the adapter is able to reconnect to
the server, an event is posted and the message is transmitted. All suspended messages can
then be transmitted.
The JMS specication does not dene an exception class for server shutdown, it only
species that the server must send an asynchronous exception upon shutdown. This is why
any asynchronous exception is considered a server shutdown if
Ignore Server Exceptions is
False.
Response time-out
This property is used only for Solicit/Response send ports. It is the period of time a
solicitation will wait for a response. If a time-out occurs, an exception will be thrown and the
solicitation message will be suspended.
Connection Properties Category
Figure 13, preceding page, shows the category Connection Properties. These properties determine where
the JMS server resides and the port number where it is listening for connections.
Host Name
This a text-editable eld. Enter the name or IP address of the machine hosting the JMS server.
Port Number
This is a text-editable eld. Enter the port number on which the JMS server is accepting
connections.
Proprietary Connection String
This is a text-editable eld. This property is only used if the JMS implementation uses
complex URLs containing query expressions, or some proprietary connection string. For
example, ActiveMQ, supports a simple URL connection string,
tcp://medtner:61616, that can
be constructed from the
Host Name and Port Number properties. However, if connection and
protocol properties must be set, ActiveMQ supports URLs with query expressions:
failover:( tcp://scriabin:61616?wireFormat.maxInactivityDuration=30000,
tcp://elgar:61616?wireFormat.maxInactivityDuration=30000,
tcp://cage:61616?wireFormat.maxInactivityDuration=30000
)?randomize=false
If this property contains a value, then the Host Name and Port Number properties will be
ignored.
23
USERS’ GUIDE
Version 4.0
JMS Operation Properties Category
These properties determine what operation the send port will enable.
JMS Object Name
This is a text-editable eld. Enter the JNDI name bound to the JMS queue or topic.
Depending on the requirements of the JMS implementation, it may be necessary to supply a
complete path, e.g.
java:comp/resource/jms/myQueue.
JMS Object Type
This is a drop-down list containing two values:
Queue or Topic.
Message Type
This is a drop-down list containing several values:
Text, Text UTF, Text ISO-8859-15 or
Bytes. If any of the Text types are chosen, then the JNBridge JMS Adapter will send a JMS
Text Message converting the binary encoding correctly. If Bytes is chosen, then the JNBridge
JMS Adapter will send a JMS Bytes Message.
Transactions
Enable or disable local JMS transactions. When transactions are enabled, any resulting error
during transmission will result in the message being removed from the JMS queue or topic.
The send port will throw an exception and the message will be retransmitted dependent on
retry properties set by the user.
Override Transmit Handler Properties Category
Sometimes it may be necessary to override the factory class values entered in the
Send Transport Handler
properties discussed in the section JMS Properties. If the values are not overridden, then the Send Port
will use the initial context, queue connection and topic connection factories congured in the send handler
properties.
24
USERS’ GUIDE
Version 4.0
Figure 14. Creating and conguring a Receive Port and Location
Creating and Conguring Receive Ports and Locations
Creating a Receive Port is similar to creating a Send Port. Simply right-click in an application’s Receive
Ports pane and choose NewOne-way Receive Port or NewRequest Response Receive Port. This will
bring up the
Receive Port Properties dialog, Figure 14, following page.
For more information on Request/Response receive ports, see the section Messaging Patterns. Choose
Receive Locations in the left-hand pane and select New to bring up the Receive Location Properties
dialog box. Click on the drop-down list
Type: and select the JNBridge JMS Adapter. Click the button
Congure to bring up the Transport Properties dialog, shown in Figure 14, to congure JMS message
consumers.
25
USERS’ GUIDE
Version 4.0
Adapter Behavior Category
Asynchronous Batch Submit
If
True, then each batch will submitted to the BizTalk Message Box asynchronously. In other
words, the submittal of each group of messages could overlap if the polling period is short
and the batch size is large.
If
False, each batch is submitted synchronously and the adapter will wait until each batch
is successful before submitting the next batch. Set this property to False if ordered message
reception is required.
! The Asynchronous Batch Submit setting is ignored if the receive port is congured for
transactions or is a receive/response port. In other words, transactions and receive/
response require synchronous behavior.
Ignore Server Exceptions
If this property is
True, then any asynchronous exceptions sent by the JMS server will be
ignored. If False, then the receive location will disconnect if any asynchronous exception is
sent by the JMS server.
Server Reconnect
If this property is
False, then upon receiving an asynchronous exception from the JMS
server, the adapter will post an error event, close the connection and auto-disable the receive
location. If True, then the receive location will post an event, close the connection, but will
remain enabled and periodically attempt a re-connection. If the property Ignore Server
Exceptions is True, then this property is ignored.
Reconnect Period (minutes)
If the property
Server Reconnect is True, then the receive location will remain enabled and
attempt to continually reconnect with a period equal to the entered value. If Server Reconnect
is False, this value is ignored. If the property Ignore Server Exceptions is True, this property
is also ignored. If the reconnect attempts fail, the failures are posted to the error log, only.
If the reconnect attempt succeeds, an event is posted and the location begins to consume
messages.
Response time-out
The time-out, in seconds, for a response to arrive for a request. This value is ignored if the
receive port is one-way.
26
USERS’ GUIDE
Version 4.0
Connection Properties Category
Figure 14 shows the category
Connection Properties. These properties determine where the JMS server
resides and the port number where it is listening for connections.
Host Name
This a text-editable eld. Enter the name or IP address of the machine hosting the JMS server.
Port Number
This is a text-editable eld. Enter the port number on which the JMS server is accepting
connections.
Proprietary Connection String
This is a text-editable eld. This property is only used if the JMS implementation uses
complex URLs containing query expressions, or some proprietary connection string. For
example, ActiveMQ, supports a simple URL connection string,
tcp://medtner:61616, that can
be constructed from the Host Name and Port Number properties. However, if connection and
protocol properties must be set, ActiveMQ supports URLs with query expressions:
failover:( tcp://scriabin:61616?wireFormat.maxInactivityDuration=30000,
tcp://elgar:61616?wireFormat.maxInactivityDuration=30000,
tcp://cage:61616?wireFormat.maxInactivityDuration=30000
)?randomize=false
If this property contains a value, then the Host Name and Port Number properties will be
ignored.
User Handle
This is a text-editable eld. The string is used to dierentiate the BizTalk URL that represents
a receive location. Because the BizTalk send and receive location namespace is at, the user-
dened string allows multiple receive locations to consume messages from the same queue or
topic. This provides a mechanism to support concurrent message consumption using message
selectors.
JMS Operation Properties Category
These properties determine what operation type of operation the send port will enable.
JMS Object Name
This is a text-editable eld. Enter the JNDI name bound to the JMS queue or topic.
Depending on the requirements of the JMS implementation, it may be necessary to supply a
complete path, e.g.
java:comp/resource/jms/myQueue.
27
USERS’ GUIDE
Version 4.0
JMS Object Type
This is a drop-down list containing three values:
Queue, Topic and Shared Topic. Shared
Topics are only supported by JMS 2.0.
Message Type
This is a drop-down list containing four values:
Text, Text UTF-8, Text UTF-16, Text ISO-
8859-15, Bytes or Map. If a text type is chosen, then the JNBridge JMS Adapter expects to
receive a JMS Text Message. If Bytes is chosen, then the JNBridge JMS Adapter expects
to receive a JMS Bytes Message. If Map is chosen, the JNBridge JMS Adapter expects to
receive a JMS Map Message.
The
Text, Text UTF-8, Text UTF-16 and Text ISO-8859-15 values instruct the adapter to
encode the incoming XML document into the correct binary representation complete with a
Byte Order Marker for publication to the Biztalk Message Box. This is done because a JMS
Text message is, by denition, always encoded as UTF-16 BE (big-endian).
The value
Text will be interpreted as UTF-8 and encoded as single byte representation and
prefaced with the BOM 0xEFBBBF.
Text UTF-8 will be encoded as multi-byte, if necessary,
and prefaced with the BOM 0xEFBBBF. Text UTF-16 will be encoded as LE (little-endian)
double byte representation and prefaced with the BOM 0xFFFE.
Text ISO-8859-15 will be
encoded to its single-byte representation, but will not be preceded with a BOM. Choosing the
wrong encoding could result in a corrupted message.
Client ID
This is a string that uniquely identies the connection maintained by the receive port to the
JMS server. This is only used for topic and shared topic durable subscriptions.
Durable Subscription Name
Durable subscriptions are particular to topics and shared topics only. A durable subscription
for a topic allows consumers to register a name with the JMS server such that whenever a
receive port is active, all messages in the topic will be received. In this way, a receive port
does not have to be continually connected to receive messages from a topic. A receive port
that does not use durable subscriptions must be active and connected in order to subscribe to
a topic—any messages published by the topic while a nondurable receive port is not active
will not be available to that receive port when it becomes active. This is a text-editable eld.
Enter the durable subscription name.
Message Selector Filter
Message selectors are used by receive ports to lter or select messages from topics and
queues based on JMS and custom message header properties.
This is a text-editable eld. Enter in a selector expression. The expression is derived from a
subset of the SQL92 standard.
28
USERS’ GUIDE
Version 4.0
Transactions
Enable or disable local JMS transactions. When transactions are enabled, any resulting error
during reception and submission to the BizTalk Message Box will result in the message being
unconsumed and still present on the JMS queue or topic. The cause of the problem and the
message id is logged to the Application event log.
! Enabling receive transactions will slow down performance as the eective batch size
is 1.
! The Transactions property is ignored if the receive port is request/response.
Override Transmit Handler Properties Category
Sometimes it may be necessary to override the factory class values entered in the
Receive Transport
Handler
properties discussed in the section JMS Properties. If the values are not overridden, then the
receive port will use the initial context, queue connection and topic connection factories congured in the
receive handler properties.
Receive Polling Properties
This category congures the frequency with which BizTalk Server checks for received messages. The
JNBridge JMS Adapter receives messages from queues and topics by implementing a background
message listener. As such, messages are received when they arrive and are placed in a cache by the
adapter. The Polling Properties determine when cached messages are processed and placed in the BizTalk
Message Box.
Polling Interval
This is a text-editable eld. Enter an integer value representing minutes, seconds or
milliseconds.
Polling Interval Unit
This is a drop-down list containing three choices:
minutes, seconds or milliseconds.
Received Messages Buer Size
This is the size of an internal buer which holds received messages which have not been
processed and submitted to the BizTalk Message Box. The JMS adapter consumes messages
on a separate thread and, depending on load and throttling parameters, can quickly consume
memory holding un-submitted messages. The buer size is an upper limit of 1,2, 4, 8,16, 32
and 64 MB. If the upper limit is reached, the consuming thread will sleep an amount of time
equal to the Polling Interval. If the choice
Throttle O is used, then the adapter will not slow
down message consumption. This is recommended only for 64-bit host instances.
Throttling is only valid when transactions are disabled.
29
USERS’ GUIDE
Version 4.0
Messaging Patterns
The JNBridge JMS Adapter for BizTalk Server supports Request/Response and Solicit/Response
messaging patterns using JMS as a transport.
Request Response receive ports
The received JMS message which constitutes the request message must have the following JMS header
properties set.
JMSReplyTo
This property must contain the JMS destination that the adapter uses to send the response
back to the requestor. The response destination can either be a queue or topic. If the
JMSReplyTo property is null, the adapter will throw an exception.
JMSCorrelationID
This property is set in the JMS request message header and is copied to the response’s JMS
header. The developer may choose to override the incoming correlation id by setting the
response message’s correlation id explicitly in a Pipeline or Orchestration. If the incoming
property is empty, and the response message does not have its correlation id explicitly set by
an Orchestration or Pipeline, then the response message’s JMSCorrelationID will be set to the
message id of the request message.
The JMS adapter supports requests from both queues and topics. If the request message is a JMS Text
message, the adapter will respond with a text message. If the request message is a JMS Bytes message,
the adapter will respond with a JMS Bytes message.
Solicit Response send ports
The JNBridge JMS Adapter for BizTalk Server creates a JMS message used to solicit a response. The
adapter automatically creates and manages a temporary queue and places that destination into the
solicitation message’s JMSReplyTo header property. The adapter then listens for the response message
on that queue. If the solicitation message is a JMS Text message, then the adapter expects a JMS Text
message in response. If the solicitation message is a JMS Bytes message, then the adapter expects a JMS
Bytes message in response.
! The adapter supports only queues for solicit response messaging patterns.
30
USERS’ GUIDE
Version 4.0
Using Message Properties and Map Messages
A JMS message header contains sets of properties. A property is a combination of a data type, name and
a value. The JMS specication denes a set of standard, extended and user-dened properties for a JMS
header. The JNBridge JMS Adapter for BizTalk Server provides access within an orchestration or pipeline
to the standard, extended and user-dened JMS header properties. Additionally, a set of conguration
properties are dened in order to support dynamic send ports. Access to the standard and conguration
properties is enabled by referencing the schema assembly [InstallDir]\JNBridge\JMSAdapters\
BTS2006\bin\JNBridgeBTS2006JMSProperties.dll
within a Visual Studio 2005/2008 BizTalk
project. This assembly is also installed in the Global Assembly Cache at adapter installation. User-dened
or the extended JMS properties are supported only if a custom
Property Schema is implemented and
deployed by the user.
Within an orchestration, properties are accessed from a
Message Assignment shape. Property values can
be used in expressions. Some properties can be set such that the outgoing JMS message will contain those
properties. Conguration properties can be set to dynamically route the message using dynamic send
ports.
Properties, XML Schema and .NET namespaces
The JMS adapter has dened three XML schema namespaces along with three corresponding .NET
(XLANG) namespaces for use with properties. The three namespaces encapsulate received properties,
conguration properties and send properties and are dened, along with reserved property schemes, in the
schema assembly JNBridgeBTS2006JMSProperties.dll. User dened properties require a custom
BizTalk Property Schema and must use the received properties or send properties namespaces.
JMS Receive Properties
This schema uses the XML name space
http://schemas.jnbridge.com/JMSAdapter/BizTalk/
JMSRecvProperties and the .NET/XLANG namespace JMSRecvProperty. All properties that are
contained in a received JMS message header are placed in this namespace when they are written or
promoted to the internal BizTalk message context.
Standard and Extended Properties
The received properties namespace denes the following properties that correspond to the supported
standard JMS header properties, Table 1, following page. All standard JMS properties are
promoted to the
BTS message context. Promoted properties can be used for routing.
As shown in Table 1, along with the .NET type of the property (germane if accessed in a pipeline) is a
syntactic XLANG expression used in a Rule shape within an orchestration. Receive properties can only
be accessed, they cannot be assigned.
31
USERS’ GUIDE
Version 4.0
Name .NET Type XLANG Expression Usage
JMSCorrelationID String Message_2(JMSRecvProperty.JMSCorrelationID) == ”xyz”;
JMSDeliveryMode Int32 Message_2(JMSRecvProperty.JMSDeliveryMode) > 3;
JMSExpiration String* Message_2(JMSRecvProperty.JMSExpiration) == ”12467...”;
JMSMessageID String Message_2(JMSRecvProperty.JMSMessageID) == ”9C873...”;
JMSPriority Int32 Message_2(JMSRecvProperty.JMSPriority) < 2;
JMSRedelivered Boolean Message_2(JMSRecvProperty.JMSRedelivered) == true;
JMSTimestamp String* Message_2(JMSRecvProperty.JMSTimestamp) == “12693...”;
JMSType String Message_2(JMSRecvProperty.JMSType) == “Text”;
JMSDestination String* Message_2(JMSRecvProperty.JMSDestination) == “holst”;
The properties
JMSExpiration and JMSTimestamp are dened in the JMS 1.1 specication as type java.
lang.Long. While this would correspond to .NET type System.Long, 64-bit integers are not supported
as promoted properties with BizTalk. As all standard JMS header properties are promoted, the string
representation of the 64-bit integer is used instead. The property JMSDestination is a string.
! The JNBridge JMS Adapter for BizTalk does not support the JMS standard header
JMSReplyTo as a property that can be accessed using an XLANG expression. The
property is used for Request/Response messaging.
User-dened properties
All user-dened properties found in a JMS message header are
written to the BTS message context
in the receive XML schema namespace. Table 2 shows the supported Java property types and their
corresponding BizTalk (.NET) data type.
Java Type .NET Type Comment
java.lang.Float Single
java.lang.Long Int64 64-bit properties cannot be promoted, only written
java.lang.Short Int16
java.lang.JavaString String
java.lang.Byte Byte A Java byte is signed. A .NET byte is unsigned.
java.lang.Boolean Boolean
java.lang.Integer Int32
java.lang.Double Double
! The Java type java.lang.Object is not supported as a property. Properties of type
Object will be ignored.
Table 1. Standard JMS properties dened in receive schema namespace.
Table 2. Supported JMS header types and their .NET equivalent
32
USERS’ GUIDE
Version 4.0
All user-dened properties in a JMS message header that begin with the tag “PROPRM_” will be
promoted to the BTS message context. All other user-dened properties are written. If a user-dened
property is promoted, the user must supply a BizTalk Property Schema for that property. This schema
must be deployed to the BizTalk application. If the property schema is not found at run-time, the BTS
message persistence will fail and the message will be dropped and an error event will be posted. Figure 15
shows a user-dened BizTalk Property Schema that denes a single property.
Notice that the target namespace is the dened receive namespace,
http://schemas.jnbridge.com/
JMSAdapter/BizTalk/JMSRecvProperties
. All properties found in an incoming JMS header are written or
promoted to the BTS message context in this namespace. As such, a user-dened property that has been
promoted can be accessed in a Rule form using the XLANG expression:
Message_2(MyRecvProperties.PROPRM_myProp) > 4
Additionally, promoted properties can be used for routing. Extended JMS header properties, those that
begin with “
JMSX”, are always written to the BTS message context, they are never promoted.
JMS Send Properties
This schema uses the XML name space
http://schemas.jnbridge.com/JMSAdapter/BizTalk/
JMSSendProperties
and the .NET/XLANG namespace JMSSendProperty. All properties in this
namespace, regardless whether written or promoted, are placed in the JMS message header during a
transmission from a send port. This namespace schema predenes three standard JMS header properties
<?xml version=”1.0” encoding=”utf-16” ?>
<xs:schema xmlns:b=”http://schemas.microsoft.com/BizTalk/2003”
xmlns=”http://schemas.jnbridge.com/JMSAdapter/BizTalk/JMSRecvProperties”
targetNamespace=”http://schemas.jnbridge.com/JMSAdapter/BizTalk/JMSRecvProperties”
xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
<xs:annotation>
<xs:appinfo>
<b:schemaInfo schema_type=”property”
xmlns:b=”http://schemas.microsoft.com/BizTalk/2003” />
</xs:appinfo>
</xs:annotation>
<xs:element name=”PROPRM_myProp” type=”xs:int”>
<xs:annotation>
<xs:appinfo>
<b:eldInfopropertyGuid=”6bda887d-b81a-4660-91dc-4f146e6c1df6”
propSchFieldBase=”MessageContextPropertyBase” />
</xs:appinfo>
</xs:annotation>
</xs:element>
</xs:schema>
Figure 15. A user dened property schema generated in Visual Studio
33
USERS’ GUIDE
Version 4.0
and one DateTime property used to enable delivery delays supported by JMS 2.0, Table 3 on the
following page, in the assembly JNBridgeBTS2006JMSProperties.dll. All properties in the send
namespace can be set in a Message Assignment shape within an orchestration.
User properties that will be transmitted in the outgoing JMS message header must be dened in a user
supplied BizTalk Property Schema, Figure 16.
Name .NET Type Comment
JMSCorrelationID String
JMSType String
JMSPriority Int32 May be overwritten by JMS provider
DeliveryDelay DateTime Used to delay the consumption of the
transmitted message. This is a JMS 2.0
feature.
Table 3. Send Properties
Note that the same property with the auto-promote tag, PROPRM_myProp, that was dened in the receive
namespace for incoming JMS messages on page 25, is dened again here. As long as the .NET/XLANG
namespace is dierent for each separate xsd le (one for the receive XML namespace and one for the
send XML namespace), XLANG expressions that “get” receive properties are separate from expressions
that “set” the same properties. Even if the send namespace contains several properties, only those set in
Figure 16. Send BizTalk Property Schema
34
USERS’ GUIDE
Version 4.0
a Message Assignment shape will be written to the outward bound JMS message. Figure 17, following
page, displays a BizTalk Expression Editor setting the outgoing JMSCorrelationID as well as incrementing
the user-dened property,
PROPRM_myProp. Because received messages are immutable, the initial
expression copies
Message_1, the received inbound message, to Message_2, the outbound message.
JMS Congure Properties
This schema uses the XML name space
http://schemas.jnbridge.com/JMSAdapter/BizTalk/
JMSConfProperties and the .NET/XLANG namespace JMSConfProperty. This namespace schema
predenes six properties that can be set by the user in a
Message Assignment shape. If the orchestration
uses a dynamic send port, the congure properties can be used to dynamically route messages.
Table 4, on the next page, lists the congure properties. The properties are dened in the assembly,
JNBridgeBTS2006JMSProperties.dll.
Name .NET Type Comment
DS_Hostname String
DS_Port Int32
DS_DestType String Must be “Topic” or “Queue”. Case-sensitive.
DS_Destination String The JNDI location of the topic or queue.
DS_JMSType String Must be “Text” or “Binary”. Case-sensitive.
DS_DeliveryDelay DateTime Used to delay the consumption of the
transmitted message. This is a JMS 2.0
feature.
Table 4. Dynamic send port conguration properties.
Figure 17. XLANG Expressions setting outbound properties
35
USERS’ GUIDE
Version 4.0
Figure 18. Conguring a dynamic send port in an orchestration
Using Dynamic Send Ports
The JMS conguration namespace can be used with dynamic send ports. Dynamic send ports are
congured as dynamic within an orchestration, hence when the orchestration is deployed to BizTalk
Server, there is no bound logical port. The binding of a transport and an address to the dynamic port
is done within the orchestration. Figure 18, below, shows a portion of an orchestration conguring a
dynamic send port.
The expressions in the
Message Assignment form sets the ve congure properties. The Expression form
binds the JNBridge JMS transport to the dynamic send port by using the expression:
Port_2(Microsoft.XLANGs.BaseTypes.Address) = “jms://”;
By using the registered transport URL, jms://, for the JNBridge JMS Adapter, BizTalk Server knows to
bind the adapter to the dynamic send port.
36
USERS’ GUIDE
Version 4.0
Using Map Messages
The adapter will receive JMS Map Messages. A JMS Map Message is a message whose body contains a
set of custom properties. When a JMS Map Message is received, the adapter will convert the map into a
very simple XML document, see Figure 19.
<?xml version=”1.0” encoding=”utf-16”?>
<Map>
<shortValue type=”Short”>32767</shortValue>
<minFloatValue type=”Float”>-3.402823E+38</minFloatValue>
<longValue type=”Long”>9223372036854775807</longValue>
<maxDoubleValue type=”Double”>1.79769313486232E+308</maxDoubleValue>
<stringValue type=”String”>The quick brown fox...</stringValue>
<byteValue type=”Byte”>36</byteValue>
<byteArrayValue type=”Bytes”>VABoAGUAIABxAHUA=</byteArrayValue>
<minDoubleValue type=”Double”>-1.79769313486232E+308</minDoubleValue>
<maxFloatValue type=”Float”>3.402823E+38</maxFloatValue>
<booleanValue type=”Boolean”>true</booleanValue>
<charValue type=”Char”>12</charValue>
<intValue type=”Int”>2147483647</intValue>
</Map>
Figure 19. A Map Message converted to XML
It will be up to the user to provide the necessary schema for the particular properties contained in a Map
Message.
37
USERS’ GUIDE
Version 4.0
Trouble Shooting
Deploy JMS Header Schema to BizTalk Application
Where did my messages go? Receiving JMS messages from a JMS destination will cause this error if the
JMS properties schema has not been deployed to BizTalk. Even if you reference the schema assembly in a
BizTalk Visual Studio project, the schema assembly will not be deployed.
“Missing or malformed schema for a promoted property. Message cannot be re-submitted: unable
to persist message in BTS DB. Did you deploy [%INSTALL_DIR%]\JNBridge\JMSAdapters\
BTS2006\bin\JNBridgeBTS2006JMSProperties.dll to your BTS application?”
In order to properly handle JMS header properties within BizTalk, you must deploy the assembly,
JNBridgeBTS2006JMSProperties.dll, to your BizTalk application. This assembly contains the
XSD namespaces and schemas used by the JNBridge JMS Adapter to promote JMS header properties
within messages stored in the BizTalk Message Box.
! Deploying this assembly is mandatory.
To deploy the schema assembly
1 Open up the BizTalk Administrator and open your BizTalk application in the left-side tree view.
2 Right click on the application’s root node and choose
AddResources. This opens the Add
Resources dialog.
3 In the dialog, click on the
Add button and navigate to the schema DLL in the adapter install directory,
e.g. C:\Program Files\JNBridge\JMSAdapters\BTS2006\bin\
JNBridgeBTS2006JMSProperties.dll.
4 Click on
OK to close the Add Resources dialog.
5 Open the
Schemas folder in your application. You should see the three schemas:
JMSSendProperty.SendPropertySchema, JMSRecvProperty.
RecvPropertySchema
and JMSConfProperty.ConfPropertySchema.
6 Restart the host instance and application.