JBoss.orgCommunity Documentation

Chapter 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

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:

char * tpalloc(char *type, char *subtype, long size)

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

char* btalloc(msg_opts_t* ctrl, char* type, char* subtype, long size);

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 example showing this feature in action. Unpack the release and look at the REAME in the examples/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 examples/xatmi/topics.