JBoss.orgCommunity Documentation

User Guide

Using BlackTie

by Tom Jenkinson, Michael Musgrove, and Amos Feng

Abstract

User guide for BlackTie


Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. We Need Feedback!
1. About This Guide
1.1. Audience
1.2. Prerequisites
2. Standards
2.1. X/Open
3. Using Buffers with BlackTie
3.1. X_OCTET
3.2. X_COMMON/X_C_TYPE
3.3. How to use Nested Buffers in BlackTie
3.3.1. Defining a schema
4. Services
4.1. Building XATMI services and clients
4.1.1. Pre-requisites
4.1.2. Configuring the server, services and clients
4.1.3. Running the code generation tool
4.1.4. Running a generated server and client
4.2. XATMI Services and BlackTie
4.2.1. Administrative Services
4.2.2. C XATMI Per Server Service
4.2.3. Java XATMI Domain-wide Service
4.2.4. User Defined Services
4.3. Decoupling XATMI services and clients using a queuing pattern
4.3.1. Introduction
4.4. How to use topics
5. BlackTie Configuration
5.1. Environment variables
5.2. Configuration Files
5.3. btconfig.xml
5.4. SERVICES
5.5. ENV_VARIABLES
5.6. BUFFERS
5.7. log4cxx.properties
6. Advanced run instructions for BlackTie
6.1. Running the TAO implementation repository with BlackTie
6.1.1. Introduction
6.1.2. To start the ImR:
6.1.3. Adding a new server
6.1.4. Is the ImR a single point of failure?
6.2. Running BlackTie with a different host IP address
6.3. Using ESB contented based routing in Blacktie
6.3.1. Install JBossESB
6.3.2. Running CBR Quickstart
6.3.3. Content Routing Rulers
7. BlackTie Administration
7.1. BlackTie Administration Functions
7.1.1. The following operations all perform functionality at the domain level
7.1.2. The following operations perform functionality at the server level
7.1.3. Viewing Transaction Statistics
7.2. BlackTieAdminService XATMI Service
7.3. BlacktieAdminService JMX Bean
7.4. AtmiBrokerAdmin XATMI Service
7.5. Monitoring and management of blacktie servers by blacktie-rhq-plugin
7.5.1. Install blacktie-rhq-plugin
7.5.2. How to manage a blacktie server
7.5.3. How to monitor a blacktie server
7.6. BlackTie Command Line Administration
7.6.1. Introduction
7.6.2. btadmin
7.6.3. generate_server
7.6.4. generate_client
A. Revision History

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:

The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.

Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:

The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

BlackTie supports all three of the buffer types defined in the XATMI specification.

Namely these are:

  1. X_OCTET

  2. X_COMMON

  3. X_C_TYPE

BlackTie also supports the Nested Buffer Format described below.

Nested Buffer Format is defined in a xsd schema file, such as employee.xsd:

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_processing_instruction">&lt;?xml&nbsp;version=&quot;1.0&quot;?&gt;</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:schema</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">xmlns:xsd</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;http://www.w3.org/2001/XMLSchema&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">xmlns</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;http://www.jboss.org/blacktie&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">targetNamespace</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;http://www.jboss.org/blacktie&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">elementFormDefault</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;qualified&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:element</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;employee&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">type</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;employee_type&quot;</span><span class="xml_tag_symbols">/&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:complexType</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;employees_type&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:sequence</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">minOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;0&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">maxOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;unbounded&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:element</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;employee&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">type</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;employee_type&quot;</span><span class="xml_tag_symbols">/&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">xsd:sequence</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">xsd:complexType</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:complexType</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;employee_type&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:choice</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">minOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;0&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">maxOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;unbounded&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:element</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;name&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">minOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;0&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">maxOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;unbounded&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:simpleType</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:restriction</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">base</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;xsd:string&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:maxLength</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">value</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;8&quot;</span><span class="xml_tag_symbols">/&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">xsd:restriction</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">xsd:simpleType</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">xsd:element</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">xsd:element</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;id&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">minOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;0&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">maxOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;unbounded&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">type</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;xsd:long&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">default</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;0&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">xsd:element</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">xsd:choice</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">xsd:complexType</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">xsd:schema</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />

All xsd schema files should been placed in buffers directory.

Get a nested buffer in blacktie, you should use

<!-- <br/> --><span class="java_type">char</span><!-- <br/> --><span class="java_operator">*</span><!-- <br/> --><span class="java_plain">&nbsp;buffer&nbsp;</span><!-- <br/> --><span class="java_operator">=</span><!-- <br/> --><span class="java_plain">&nbsp;tpalloc</span><!-- <br/> --><span class="java_separator">(</span><!-- <br/> --><span class="java_literal">&quot;BT_NBF&quot;</span><!-- <br/> --><span class="java_separator">,</span><!-- <br/> --><span class="java_plain">&nbsp;</span><!-- <br/> --><span class="java_literal">&quot;&lt;buffer_name&gt;&quot;</span><!-- <br/> --><span class="java_separator">,</span><!-- <br/> --><span class="java_plain">&nbsp;</span><!-- <br/> --><span class="java_literal">0</span><!-- <br/> --><span class="java_separator">);</span><!-- <br/> --><span class="java_plain">&nbsp;&nbsp;</span><!-- <br/> --><span class="java_operator">//</span><!-- <br/> --><span class="java_plain">&nbsp;in&nbsp;C</span><!-- <br/> --><span class="java_operator">++</span>
<!--  --><br/><span class="java_plain">BT_NBF&nbsp;buffer&nbsp;</span><span class="java_operator">=</span><span class="java_plain">&nbsp;</span><span class="java_separator">(</span><span class="java_plain">BT_NBF</span><span class="java_separator">)</span><span class="java_plain">&nbsp;connection</span><span class="java_separator">.</span><span class="java_plain">tpalloc</span><span class="java_separator">(</span><span class="java_literal">&quot;BT_NBF&quot;</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_literal">&quot;&lt;buffer_name&gt;&quot;</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_literal">0</span><span class="java_separator">);</span><span class="java_plain">&nbsp;&nbsp;&nbsp;</span><span class="java_operator">//</span><span class="java_plain">&nbsp;in&nbsp;</span><span class="java_type">Java</span>

After that, the following options are available:

e.g.

<!-- C++ : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="cpp_comment">//&nbsp;add&nbsp;a&nbsp;attribute&nbsp;in&nbsp;buffer</span><br />
<span class="cpp_type">char</span><span class="cpp_plain">&nbsp;name</span><span class="cpp_separator">[</span><span class="cpp_literal">16</span><span class="cpp_separator">];</span><span class="cpp_plain"></span><br />
<span class="cpp_type">char</span><span class="cpp_plain">&nbsp;</span><span class="cpp_keyword">value</span><span class="cpp_separator">[</span><span class="cpp_literal">16</span><span class="cpp_separator">];</span><span class="cpp_plain"></span><br />
<span class="cpp_type">int</span><span class="cpp_plain">&nbsp;len&nbsp;</span><span class="cpp_operator">=</span><span class="cpp_plain">&nbsp;</span><span class="cpp_literal">16</span><span class="cpp_separator">;</span><span class="cpp_plain"></span><br />
<span class="cpp_plain"></span><br />
<span class="cpp_type">char</span><span class="cpp_operator">*</span><span class="cpp_plain">&nbsp;buf&nbsp;</span><span class="cpp_operator">=</span><span class="cpp_plain">&nbsp;tpalloc</span><span class="cpp_separator">((</span><span class="cpp_type">char</span><span class="cpp_operator">*</span><span class="cpp_separator">)</span><span class="cpp_plain">&nbsp;</span><span class="cpp_literal">&quot;BT_NBF&quot;</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_separator">(</span><span class="cpp_type">char</span><span class="cpp_operator">*</span><span class="cpp_separator">)</span><span class="cpp_plain">&nbsp;</span><span class="cpp_literal">&quot;employee&quot;</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_literal">0</span><span class="cpp_separator">);</span><span class="cpp_plain"></span><br />
<span class="cpp_plain">strcpy</span><span class="cpp_separator">(</span><span class="cpp_plain">name</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_literal">&quot;test&quot;</span><span class="cpp_separator">);</span><span class="cpp_plain"></span><br />
<span class="cpp_plain"></span><br />
<span class="cpp_plain">rc&nbsp;</span><span class="cpp_operator">=</span><span class="cpp_plain">&nbsp;btaddattribute</span><span class="cpp_separator">(</span><span class="cpp_operator">&amp;</span><span class="cpp_plain">buf</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_separator">(</span><span class="cpp_type">char</span><span class="cpp_operator">*</span><span class="cpp_separator">)</span><span class="cpp_plain">&nbsp;</span><span class="cpp_literal">&quot;name&quot;</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;name</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;strlen</span><span class="cpp_separator">(</span><span class="cpp_plain">name</span><span class="cpp_separator">));</span><span class="cpp_plain"></span><br />
<span class="cpp_plain">rc&nbsp;</span><span class="cpp_operator">=</span><span class="cpp_plain">&nbsp;btgetattribute</span><span class="cpp_separator">(</span><span class="cpp_plain">buf</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_separator">(</span><span class="cpp_type">char</span><span class="cpp_operator">*</span><span class="cpp_separator">)</span><span class="cpp_plain">&nbsp;</span><span class="cpp_literal">&quot;name&quot;</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_literal">0</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_separator">(</span><span class="cpp_type">char</span><span class="cpp_operator">*</span><span class="cpp_separator">)</span><span class="cpp_plain">&nbsp;</span><span class="cpp_keyword">value</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_operator">&amp;</span><span class="cpp_plain">len</span><span class="cpp_separator">);</span><span class="cpp_plain"></span><br />
<span class="cpp_plain"></span><br />
<span class="cpp_plain">strcmp</span><span class="cpp_separator">(</span><span class="cpp_keyword">value</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_literal">&quot;test&quot;</span><span class="cpp_separator">);</span><span class="cpp_plain"></span><br />

more quickstarts can be founded under <BLACKTIE_HOME>/quickstart/nbf, and this quickstart also runs as part of the run_all_quickstarts script.

This article should explain how to work with the Blacktie framework in order to develop your own XATMI services and clients. We will discuss how to run the code generation tool along with how to provide the configuration files that are required on the client and server side.

Here a service is defined as a unit of business logic that implements the tpservice(SVCINFO) method as defined in the XATMI specification section 3.3.

In BlackTie services are broadly categorised as either:

Starting from release blacktie-3_0_0 we have added two methods called btenqueue and btdequeue to simplify sending and receiving message. The M1 release supports transactional sends and the M2 release will support transactional receives.

This page will be updated soon to reflect the change.

XATMI (http://www.opengroup.org/pubs/catalog/c506.htm) is a standard which specifies how to connect clients to services. A client is a program that requests services to be performed. A service is a program that performs a specific application function on behalf of clients. In XATMI there are two types of service:

However this model breaks down if there is no service currently running that can handle the client request. The latest release of BlackTie includes an enhancement (to XATMI) that facilitates the queuing of client requests such that the request can be processed at a later time when an appropriate service becomes available.

In XATMI message payloads are obtained using the following call:

<!-- C++ : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="cpp_type">char</span><span class="cpp_plain">&nbsp;</span><span class="cpp_operator">*</span><span class="cpp_plain">&nbsp;tpalloc</span><span class="cpp_separator">(</span><span class="cpp_type">char</span><span class="cpp_plain">&nbsp;</span><span class="cpp_operator">*</span><span class="cpp_plain">type</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_type">char</span><span class="cpp_plain">&nbsp;</span><span class="cpp_operator">*</span><span class="cpp_plain">subtype</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_type">long</span><span class="cpp_plain">&nbsp;size</span><span class="cpp_separator">)</span><span class="cpp_plain"></span><br />

To take advantage of the new BlackTie feature you will need to pass an extra parameter to the XATMI buffer allocation routine:

<!-- C++ : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="cpp_type">char</span><span class="cpp_operator">*</span><span class="cpp_plain">&nbsp;btalloc</span><span class="cpp_separator">(</span><span class="cpp_plain">msg_opts_t</span><span class="cpp_operator">*</span><span class="cpp_plain">&nbsp;ctrl</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_type">char</span><span class="cpp_operator">*</span><span class="cpp_plain">&nbsp;type</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_type">char</span><span class="cpp_operator">*</span><span class="cpp_plain">&nbsp;subtype</span><span class="cpp_separator">,</span><span class="cpp_plain">&nbsp;</span><span class="cpp_type">long</span><span class="cpp_plain">&nbsp;size</span><span class="cpp_separator">);</span><span class="cpp_plain"></span><br />

The resulting buffer can be used to make service requests with the following restrictions:

[Currently we are using the extra parameter to control the priority of message delivery though we could, in the future, add other features to give the client more control over the mechanism].

And that's it, now when the requested service is brought on-line the queued requests will be made available to its' service routine. The latest BlackTie release (http://www.jboss.org/blacktie/downloads.html) includes an quickstart showing this feature in action. Unpack the release and look at the REAME in the quickstarts/xatmi/queues directory.

There are two BlackTie specific config requirements to ensure that requests are queued even when the target server is unavailable;

Internally BlackTie uses JMS queues to connect services with clients. Normally when a server calls tpadvertise a queue is created and clients may then connect with the server via that queue. However, no such server is running in the scenario we are discussing and this is the reason the queue needs to be deployed before running the client.

So, for example, if the service name is TestOne then deploy a queue called BTR_TestOne to the JBoss deploy directory using an XML file containing the following:

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_processing_instruction">&lt;?xml&nbsp;version=&quot;1.0&quot;&nbsp;encoding=&quot;UTF-8&quot;?&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">server</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">mbean</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">code</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;org.jboss.jms.server.destination.QueueService&quot;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;jboss.messaging.destination:service=Queue,name=BTR_TestOne&quot;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">xmbean-dd</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;xmdesc/Queue-xmbean.xml&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">depends</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">optional-attribute-name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;ServerPeer&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain">jboss.messaging:service=ServerPeer</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">depends</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">depends</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain">jboss.messaging:service=PostOffice</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">depends</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">mbean</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">server</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />

Basically, topics are used to burst out messages to multiple XATMI services that do not necessarily expect a reponse.

If it helps, you might consider using topics for things like stock ticker updates where the receiver is not required to notify the sender that they have received the ticker.

To config a SERVIECE use topics, you could set type to 'topic', for example:

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">SERVICES</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">SERVICE</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">'foo'</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">type</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">'topic'</span><span class="xml_tag_symbols">/&gt;</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">SERVICES</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />

You can get more information about these in quickstarts/xatmi/topics.

The btconfig.xml is the most significant runtime configuration file for BlackTie. The content of its structure is defined and validated against the btconfig.xsd file which ships with each version of BlackTie.

The configuration includes:

The wiki contains the latest instructions for running BlackTie, the relevant article can be found here: http://community.jboss.org/wiki/DeployingBlacktie

The ImR can start servers on demand - if a client has an IOR that embeds the ImR location then the ImR knows how to start the required server. You can add servers using the tao_imr executable by specifying the comand line to start server. (Note that there is also an option to start servers whenever the ImR is started).

For example, to start our quickstarts:

tao_imr -ORBInitRef ImplRepoService=file://locator.ior add ATMI_RM_202 -c "./server -c linux" -w "/home/mmusgrov/blacktie/trunk/atmibroker-xatmi/src/quickstart/txfooapp" -e LD_LIBRARY_PATH="/home/mmusgrov/blacktie/releases/blacktie-1.0-MR6-SNAPSHOT/lib:.:/usr/local/product/11.1.0/db_1/lib:/home/mmusgrov/blacktie/trunk/atmibroker-tx/target/cxx/test/lib:/home/mmusgrov/blacktie/util/ACE+TAO-5.7.1/ACE_wrappers/lib" -e BLACKTIE_SCHEMA_DIR="/home/mmusgrov/blacktie/releases/blacktie-1.0-MR6-SNAPSHOT/schemas/xsd"

(where ATMI_RM_202 is a unique name for the server) or we could supply shell or batch files to simplify the command.

The unique name for the server must correspond to the name of a POA running in the server (this is a limitation of the TAO orb).

I use a single POA for recovery (created in XAResourceManagerFactory::create_poa ) and use the environment variable BLACKTIE_SERVER_NAME for the name of this poa. We must use the same name when starting servers via the ImR.

The BLACKTIE_SERVER_NAME environment variable is defined by concatenating domain, server and serverid (see AtmiBrokerServer::serverinit ).

To manually start this server use tao_imr command providing it with the name of the server we just added:

tao_imr -ORBInitRef ImplRepoService=file://locator.ior start ATMI_RM_202

The server needs to know that is should use an ImR. To do this we need to update the btconfig.xml file and add:

-ORBUseImR 1 to the ORBOPT environment variable. For example:

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">ENV_VARIABLE</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">NAME</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain">ORBOPT</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">NAME</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">VALUE</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain">-ORBUseImR&nbsp;1&nbsp;-ORBInitRef</span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NameService=corbaloc::localhost:3528/NameService</span><span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">VALUE</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">ENV_VARIABLE</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />

The Section 7.1, “BlackTie Administration Functions” are exposed through a both a JMX MBean and a Java XATMI service deployed into JBoss AS, configured the same btconfig.xml of the domain it is administering

Each BlackTie server exposes the same administration service, registered during AtmiBrokerServer startup

Queue administration for the AtmiBrokerAdmin service is performed through a separate Java XATMI service

  1. stompconnectservice: BlacktieStompAdministrationService

Administration is facilitated graphically from a JBoss AS RHQ administration console plugin


In a typical BlackTie installation the transaction service will be running in the JBoss Application server where you installed the stomp connect service. In such a setup basic transaction management information is exposed by the native transaction service running in the AS. For example to enable statistics open the JBossTS property file located at:

and set the enableStatistics property to YES:

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">property</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;com.arjuna.ats.arjuna.coordinator.enableStatistics&quot;</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">value</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;YES&quot;</span><span class="xml_tag_symbols">/&gt;</span><span class="xml_plain"></span><br />

The statistics are then available via any standard JMX browser or programatically via JMX. The object name of the MBean that maintains the stats is:

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_plain">jboss.management.local:J2EEServer=Local,j2eeType=JTAResource,name=TransactionManager</span><br />

If you are using the web based JBossAS jmx console then look for the name

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_plain">J2EEServer=Local,j2eeType=JTAResource,name=TransactionManager</span><br />

in the section called jboss.management.local

In the jmx console some extra transaction information is also exposed as a service with the following name:

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_plain">service=TransactionManager</span><br />

The statistics are global to the application server. We would like to provide similar information on a per BlackTie domain and per BlackTie server basis in a future release.

Revision History
Revision 1Fri May 13 2011Tom Jenkinson
Initial conversion of wiki into Docbook