JBoss.orgCommunity Documentation
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.
The provided <BLACKTIE_BIN_DIR>/setenv.[sh|bat] should be executed to put the build tools in the environment.
Install Visual V++ 2008 Express Edition (only used to provide the compiler and linker on Windows)
The PATH environment variable will need the runtime DLLs in it
C:\Program Files\Microsoft Visual Studio
9.0\VC\redist\Debug_NonRedist\x86\Microsoft.VC90.DebugCRT
The PATH environment variable will also need the VC++ tools in it
C:\Program Files\Microsoft Visual Studio
9.0\VC\vcvarsall.bat
Each of the following configuration files must be present at runtime inorder for Blacktie servers or clients to operate correctly
btconfig.xml (this file although of the same structure, the content will be different for windows and for linux)
The schemas that these files must validate against are in <BLACKTIE_BIN_DIR>/schemas/xsd, you can read more about providing configuration here.
When building clients or servers using the provided ANT script you will need to make sure you have set the environment in the manner indicated in <BLACKTIE_BIN_DIR>/setenv.[sh|bat]
An example run configuration for the code generation tool would then look like:
<BLACKTIE_BIN_DIR>/bin/generate_server.<sh|bat> -Dserver.includes=BarService.c -Dservice.names=BAR
<BLACKTIE_BIN_DIR>/bin/generate_client.<sh|bat> -Dclient.includes=client.c
The following are the requirements to run the generated server and client:
The LD_LIBRARY_PATH or PATH must be set to include the <BLACKTIE_BIN_DIR>/lib folder (done by setenv.[sh|bat]
The commands must be executed from the directory relative to where the configuration files exist
Assuming the pre-requisites are adhered to all that must be done is to execute
server[.exe] -c [configuration_dir] -i [unique_id]
and then
client[.exe]
(if the client is not in the location of the
configuration files you
need to set the environment variable
BLACKTIE_CONFIGURATION_DIR
.
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:
Administrative
User defined
Each server exposes a single XATMI service that is built into the server executable and is exposed for the lifespan of the server. It is not intended to be accessed directly by the programmer although this is possible, instead however the results of the service are typically aggregated by a central Java domain-level XATMI administrative service.
The name of the service is not user defined although can be predicted:
<SERVER_NAME>_ADMIN_<SERVER_ID>
User defined services are not allowed to be configured with a name with _ADMIN in them
The name of the service again is not user defined although can be predicted from the domain name:
<DOMAIN_NAME>_ADMIN
All user defined service names must be declared within the constraints defined in the XATMI specification plus several constraints imposed by BlackTie:
Service names must be 128 characters or less
Servers may not contain overlapping service names, e.g. server 1 and server 2 cannot define service A
Service names may not use the reserved keyword _ADMIN_ in their name
The service must be defined in the btconfig.xml
The service may optionally be customized in the btconfig.xml
The same function for the same service is expected at each server
tpadvertise and tpunadvertise operate on the local service state, they are not used to (un)advertise the service at a domain wide level
If a service is not thread safe, it is important to set the SIZE for the SERVICE in the btconfig.xml file to 1
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:
Request/response services receive a single request and produce at most a single response to the request. The request is the application data sent from the client to the service. The service processes the request and returns application data to the client by means of at most one response;
Conversational services are invoked by means of a connection request from the client. Once the connection is established and the service invoked, the client and the service can exchange data in an application-specific manner until the service returns, whereupon the connection is logically terminated.
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:
the client must use the asynchronous request/response model, i.e. it must use tpacall.
the client must not expect a response, i.e. it must set the TPNOREPLY flag.
it must not have any outstanding transaction.
[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;
the SERVICE definition in btconfig.xml must set the "externally-managed-destination" attribute to true;
you must deploy a JMS queue named BTR_[service name] to the application server (the XML file containing this queue definition must end with the suffix -service.xml)
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"><?xml version="1.0" encoding="UTF-8"?></span><span class="xml_plain"></span><br /> <span class="xml_plain"></span><br /> <span class="xml_tag_symbols"><</span><span class="xml_tag_name">server</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">mbean</span><span class="xml_plain"> </span><span class="xml_attribute_name">code</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"org.jboss.jms.server.destination.QueueService"</span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"jboss.messaging.destination:service=Queue,name=BTR_TestOne"</span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_attribute_name">xmbean-dd</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"xmdesc/Queue-xmbean.xml"</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">depends</span><span class="xml_plain"> </span><span class="xml_attribute_name">optional-attribute-name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"ServerPeer"</span><span class="xml_tag_symbols">></span><span class="xml_plain">jboss.messaging:service=ServerPeer</span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">depends</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">depends</span><span class="xml_tag_symbols">></span><span class="xml_plain">jboss.messaging:service=PostOffice</span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">depends</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">mbean</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_tag_symbols"></</span><span class="xml_tag_name">server</span><span class="xml_tag_symbols">></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"><</span><span class="xml_tag_name">SERVICES</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">SERVICE</span><span class="xml_plain"> </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"> </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">/></span><span class="xml_plain"></span><br /> <span class="xml_tag_symbols"></</span><span class="xml_tag_name">SERVICES</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
clients do not need to configure the list of services in their btconfig.xml, they will need to try to connect to the queue first, then, the topic (unless they have the destination is configured in their btconfig.xml).
tpacalls to topics MUST have TPNOREPLY set. If the client tpacalls a topic without TPNOREPLY we should fail the call. It also means tpcalls should fail too.
And there is a intention that externally-managed-destination is set to true as there are multiple receivers.
You can get more information about these in examples/xatmi/topics.