JBoss.orgCommunity Documentation
BlackTie supports all three of the buffer types defined in the XATMI specification.
Namely these are:
X_OCTET
X_COMMON
X_C_TYPE
BlackTie also supports the Nested Buffer Format described below.
The X_OCTET buffer type operates exactly as per is defined within Chapter 9 of the specification with the following points of interest:
A non-zero size MUST be provided to tpalloc and tprealloc calls
The entire buffer is initialized to \0 (NULL) prior to returning to the client
For our implementation of these buffer types we have required the user to configure the structure of the buffer in the btconfig.xml
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"><?xml version="1.0"?></span><span class="xml_plain"></span><br /> <span class="xml_tag_symbols"><</span><span class="xml_tag_name">xsd:schema</span><span class="xml_plain"> </span><span class="xml_attribute_name">xmlns:xsd</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"http://www.w3.org/2001/XMLSchema"</span><span class="xml_plain"> </span><span class="xml_attribute_name">xmlns</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"http://www.jboss.org/blacktie"</span><span class="xml_plain"> </span><span class="xml_attribute_name">targetNamespace</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"http://www.jboss.org/blacktie"</span><span class="xml_plain"> </span><span class="xml_attribute_name">elementFormDefault</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"qualified"</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">xsd:element</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"employee"</span><span class="xml_plain"> </span><span class="xml_attribute_name">type</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"employee_type"</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">xsd:complexType</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"employees_type"</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">xsd:sequence</span><span class="xml_plain"> </span><span class="xml_attribute_name">minOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"0"</span><span class="xml_plain"> </span><span class="xml_attribute_name">maxOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"unbounded"</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">xsd:element</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"employee"</span><span class="xml_plain"> </span><span class="xml_attribute_name">type</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"employee_type"</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">xsd:sequence</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">xsd:complexType</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">xsd:complexType</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"employee_type"</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">xsd:choice</span><span class="xml_plain"> </span><span class="xml_attribute_name">minOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"0"</span><span class="xml_plain"> </span><span class="xml_attribute_name">maxOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"unbounded"</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">xsd:element</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"name"</span><span class="xml_plain"> </span><span class="xml_attribute_name">minOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"0"</span><span class="xml_plain"> </span><span class="xml_attribute_name">maxOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"unbounded"</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">xsd:simpleType</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">xsd:restriction</span><span class="xml_plain"> </span><span class="xml_attribute_name">base</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"xsd:string"</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">xsd:maxLength</span><span class="xml_plain"> </span><span class="xml_attribute_name">value</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"8"</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">xsd:restriction</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">xsd:simpleType</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">xsd:element</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">xsd:element</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"id"</span><span class="xml_plain"> </span><span class="xml_attribute_name">minOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"0"</span><span class="xml_plain"> </span><span class="xml_attribute_name">maxOccurs</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"unbounded"</span><span class="xml_plain"> </span><span class="xml_attribute_name">type</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"xsd:long"</span><span class="xml_plain"> </span><span class="xml_attribute_name">default</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"0"</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">xsd:element</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">xsd:choice</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">xsd:complexType</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br /> <span class="xml_tag_symbols"></</span><span class="xml_tag_name">xsd:schema</span><span class="xml_tag_symbols">></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"> buffer </span><!-- <br/> --><span class="java_operator">=</span><!-- <br/> --><span class="java_plain"> tpalloc</span><!-- <br/> --><span class="java_separator">(</span><!-- <br/> --><span class="java_literal">"BT_NBF"</span><!-- <br/> --><span class="java_separator">,</span><!-- <br/> --><span class="java_plain"> </span><!-- <br/> --><span class="java_literal">"<buffer_name>"</span><!-- <br/> --><span class="java_separator">,</span><!-- <br/> --><span class="java_plain"> </span><!-- <br/> --><span class="java_literal">0</span><!-- <br/> --><span class="java_separator">);</span><!-- <br/> --><span class="java_plain"> </span><!-- <br/> --><span class="java_operator">//</span><!-- <br/> --><span class="java_plain"> in C</span><!-- <br/> --><span class="java_operator">++</span> <!-- --><br/><span class="java_plain">BT_NBF buffer </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_separator">(</span><span class="java_plain">BT_NBF</span><span class="java_separator">)</span><span class="java_plain"> connection</span><span class="java_separator">.</span><span class="java_plain">tpalloc</span><span class="java_separator">(</span><span class="java_literal">"BT_NBF"</span><span class="java_separator">,</span><span class="java_plain"> </span><span class="java_literal">"<buffer_name>"</span><span class="java_separator">,</span><span class="java_plain"> </span><span class="java_literal">0</span><span class="java_separator">);</span><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> in </span><span class="java_type">Java</span>
After that, the following options are available:
add a new attribute in buffer
int btaddattribute(char** buf, char* attributeId, char* attributeValue, int len); // in C++
retrieve a set attribute
int btgetattribute(char* buf, char* attributeId, int attributeIndex, char* attributeValue, int* len); // in C++
set an existing attribute
int btsetattribute(char** buf, char* attributeId, int attributeIndex, char* attributeValue, int len); // in C++
remove an existing attribute
int btdelattribute(char* buf, char* attributeId, int attributeIndex); // in C++
e.g.
<!-- C++ : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) --> <span class="cpp_comment">// add a attribute in buffer</span><br /> <span class="cpp_type">char</span><span class="cpp_plain"> 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"> </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"> len </span><span class="cpp_operator">=</span><span class="cpp_plain"> </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"> buf </span><span class="cpp_operator">=</span><span class="cpp_plain"> 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"> </span><span class="cpp_literal">"BT_NBF"</span><span class="cpp_separator">,</span><span class="cpp_plain"> </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"> </span><span class="cpp_literal">"employee"</span><span class="cpp_separator">,</span><span class="cpp_plain"> </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"> </span><span class="cpp_literal">"test"</span><span class="cpp_separator">);</span><span class="cpp_plain"></span><br /> <span class="cpp_plain"></span><br /> <span class="cpp_plain">rc </span><span class="cpp_operator">=</span><span class="cpp_plain"> btaddattribute</span><span class="cpp_separator">(</span><span class="cpp_operator">&</span><span class="cpp_plain">buf</span><span class="cpp_separator">,</span><span class="cpp_plain"> </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"> </span><span class="cpp_literal">"name"</span><span class="cpp_separator">,</span><span class="cpp_plain"> name</span><span class="cpp_separator">,</span><span class="cpp_plain"> 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 </span><span class="cpp_operator">=</span><span class="cpp_plain"> btgetattribute</span><span class="cpp_separator">(</span><span class="cpp_plain">buf</span><span class="cpp_separator">,</span><span class="cpp_plain"> </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"> </span><span class="cpp_literal">"name"</span><span class="cpp_separator">,</span><span class="cpp_plain"> </span><span class="cpp_literal">0</span><span class="cpp_separator">,</span><span class="cpp_plain"> </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"> </span><span class="cpp_keyword">value</span><span class="cpp_separator">,</span><span class="cpp_plain"> </span><span class="cpp_operator">&</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"> </span><span class="cpp_literal">"test"</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.