JBoss.orgCommunity Documentation

Chapter 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

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

  1. Section 7.4, “AtmiBrokerAdmin XATMI Service”

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

  1. Section 7.5, “Monitoring and management of blacktie servers by blacktie-rhq-plugin ”

Administration

Figure 7.1. Administration


7.1. BlackTie Administration Functions

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.

7.2. BlackTieAdminService XATMI Service

Defined in stompconnectservice:BlacktieAdminServiceXATMI

Contains the same functionality as the JMX bean

The XATMI service is accessed by:

7.3. BlacktieAdminService JMX Bean

Defined in the module: stompconnectservice:BlacktieAdminServiceMBean

The JMX bean is accessed by either:

7.4. AtmiBrokerAdmin XATMI Service

The BlackTie administration services marshal calls to this raw administration service deployed in each server

The service is bound with a well known name:

Each server exposes the administration service for the duration of its lifespan

Clients (typically the BlackTie administration services) are able to invoke a standard XATMI service with a structured command

Command structure is (note the trailing comma's):

<command>,[<arg1>,<arg2>,....]

7.5. Monitoring and management of blacktie servers by blacktie-rhq-plugin

  1. copy <BLACKTIE_BIN_DIR>/blacktie-admin-services/blacktie-rhq-plugin-<VERSION>.jar to <JBOSS_HOME>/server/all/deploy/admin-console.war/plugins

  2. restart jboss as

  3. open http://localhost:8080/admin-console, now you can find 'Blacktie Domains'

  1. start a server in <BLACKTIE_BIN_DIR>/example/xatmi/foo following with README

  2. navigate to "Blacktie Domains" -> "fooapp" -> "Servers" -> "default", you can click "Control"

  3. there is a operation named 'shutdown', and you can click the button. You should type in server id which used to start example server, e.g if you start example server with command 'server -c linux -i 1' , and you should type in '1'

  4. other operations such like 'listServiceStatus', 'getServiceCounter', 'advertise' and 'unadvertise'. you could type in a SERVICE NAME, e.g if you want to unadvertise service BAR in server 1, you should click operation 'unadvertise' and type '1' in id also type 'BAR' in service.

  1. If there is no server instance running, a red cross will be in front of the server name

  2. navigate to 'Metric' tab, you should see the number of running instances of server

7.6. BlackTie Command Line Administration

The following commands are supported by BlackTie:

Table 7.1. Commands

Command

Description

Section 7.6.2, “btadmin”

The btadmin command is used to administer the BlackTie serve process from the command line

Section 7.6.3, “generate_server”

The generate_server command is used to build a BlackTie server

Section 7.6.4, “generate_client”

The generate_client command is used to build a client application linked against the BlackTie libraries


The btadmin command is used to perform command line administration of the BlackTie server processes. In a well configured environment, the btadmin tool can be launched in either interactive mode (by ommitting a command) or in non-interactive mode by issues a command, for example: "btadmin startup". For the list of commands type: "help"

You must have called 

<BLACKTIE_HOME>/setenv.[sh|bat]

You must, either set BLACKTIE_CONFIGURATION_DIR to the directory containing a btconfig.xml for the domain that you wish to administer or ensure a valid btconfig.xml is in the working directory 

btadmin [<command>]

Table 7.2. btadmin commands

Command

Description

version

Print out the version of BlackTie that is linked against

startup [<serverName>]

Start the server, optionally constrained by the serverName

pauseDomain

Pause the domain

advertise <serverName> <serviceName>

Advertise the service indicated by the name at the server

help [command]

Get help on a command

getServersStatus

The status of the running servers

unadvertise <serverName> <serviceName>

Unadvertise the service at the specified server

resumeDomain

Resume the domain

listRunningServers

List all running servers in the domain

quit

Shutdown the btadmin tool, a no-op for a non-interactive btadmin shell

listRunningInstanceIds <serverName>

List the running instance ids of a specific server

listServiceStatus <serverName> <serviceName>

List the status of the service running on a particular server group

shutdown [<serverName> [<serverId>]]

Shutdown items in the domain, optionally constrained by a server name and (again, optionally) a serverId


The administration connection is assumed to be made within a secure network

The generate_server command is used to create a standalone BlackTie server application linking the user code against the BlackTie runtime libraries.

<BLACKTIE_HOME>/setenv.[sh|bat] must be executed prior to execution

generate_server <-Dservice.names=service[,service2,...]> <-Dserver.includes="source1[ source2 ..."]> <-Dx.inc.dir="directory"> <-Dx.inc.dir2="directory2">   <-Dx.lib.dir="directory" -Dx.libs="library[ library2]"> <-Dx.lib.dir2="directory2"> <-Dx.libs2="library[ library2]"> <-Dx.define="symbol1[,symbol2]">

Table 7.3. generate_server parameter

Parameter

Description

-Dservice.names=service[,service2,...]

This is the comma seperated list of services that should be advertised at boottime that were not coded in a DLL export compatible manner and as such cannot be registered for advertised in the btconfig.xml

-Dserver.includes="source1[ source2 ..."]

The list of files that should be compiled into this server

-Dx.inc.dir="directory"

A single additional directory for including

-Dx.lib.dir="directory"

A single additional directory for linking against

-Dx.libs="library[ library2]"

A space seperated list of libraries to link against in the lib dir

-Dx.inc.dir2="directory"

A second additional directory to include headers from

-Dx.lib.dir2="directory"

A second additional directory to include libraries from

-Dx.libs2="library[ library2]"

The list of libraries to include from the second library directory

-Dx.define="symbol1[,symbol2]"

The comma-seperated list of addtional pre-processor symbols to define


To link against the Oracle database

On Linux:

generate_server -Dservice.names=BAR -Dserver.includes="request.c ora.c DbService.c"
			-Dx.inc.dir="$ORACLE_HOME/rdbms/public"
			-Dx.lib.dir="$ORACLE_HOME/lib" -Dx.libs="occi clntsh"
			-Dx.define="ORACLE"

On Windows:

generate_server -Dservice.names=BAR -Dserver.includes="request.c ora.c DbService.c"
			-Dx.inc.dir="%ORACLE_HOME%\OCI\include"
			-Dx.lib.dir="%ORACLE_HOME%\OCI\lib\MSVC" -Dx.libs="oci"
			-Dx.define="ORACLE"

The generate_client command is used to create a standalone client application linking the user code against the BlackTie runtime libraries.

<BLACKTIE_HOME>/setenv.[sh|bat] must be executed prior to execution

generate_client <-Dclient.includes="source1[ source2 ..."]> <-Dx.inc.dir="directory" > <-Dx.inc.dir2="directory2">   <-Dx.lib.dir="directory" -Dx.libs="library[ library2]"> <-Dx.lib.dir2="directory2"> <-Dx.libs2="library[ library2]"> <-Dx.define="symbol1[,symbol2]">

Table 7.4. generate_client parameter

Parameter

Description

-Dclient.includes="source1[ source2 ..."]

The list of files that should be compiled into this client

-Dx.inc.dir="directory"

A single additional directory for including

-Dx.lib.dir="directory"

A single additional directory for linking against

-Dx.libs="library[ library2]"

A space seperated list of libraries to link against in the lib dir

-Dx.inc.dir2="directory"

A second additional directory to include headers from

-Dx.lib.dir2="directory"

A second additional directory to include libraries from

-Dx.libs2="library[ library2]"

The list of libraries to include from the second library directory

-Dx.define="symbol1[,symbol2]"

The comma-seperated list of addtional pre-processor symbols to define


To create a client which links against the Oracle database.

On Linux:

generate_client -Dclient.includes="client.c request.c ora.c cutil.c"
		-Dx.inc.dir="$ORACLE_HOME/rdbms/public"
		-Dx.lib.dir="$ORACLE_HOME/lib" -Dx.libs="occi clntsh"
		-Dx.define="ORACLE"

On Windows:

generate_client -Dclient.includes="client.c request.c ora.c cutil.c"
		-Dx.inc.dir="%ORACLE_HOME%\OCI\include"
		-Dx.lib.dir="%ORACLE_HOME%\OCI\lib\MSVC" -Dx.libs="oci"
		-Dx.define="ORACLE"