Java Utility Service for Broker Store Usage Monitoring 
____________________________________________
[ Placed in public domain 25 August 2011, courtesy of Corporate Express Australia (now part of Staples Inc.) ] 

This is an Integration Server Java service to monitoring broker store usage. (e.g., 'BrokerData.qs.stor' usage). 
The numbers returned by this service are meant to be monitored by an external monitoring service, so that 
operations/infrastructure teams are alerted when the broker store utilisation climbs too high.

To setup this utility, carry out the following steps on Integration Server:
	1. Create a Java service
	2. Add 'COM.activesw.api.client.*'to the service's 'Shared > Imports' section
	3. Copy the 'JAVA SERVICE COMMENTS' below in service comments
	4. Copy the 'JAVA SERVICE CODE' below as the Java service body
	5. Setup 1 input and 6 outputs (all string variables) as documented in service comments
	6. Setup Java service ACLs (as appropriate for calling by external monitoring service)
	7. Execute service by specifying hostName=<brokerHostname> 
	   Note, specifying the broker port like this: hostName=<brokerHostname:brokerPort>, seems to work fine.

If you use secure broker connections, you probably need to supply a BrokerConnectionDescriptor
argument in the BrokerServerClient() constructor call.
	    

--------------------JAVA SERVICE COMMENTS-----------------


INPUT
=======
hostName - hostname of the broker server

OUTPUT
=======
(All variables are of type 'string')

DUMP - Debug output. Usually contains textual representation of the raw BrokerEvent containing 
	broker storage information (see NOTES). It may also contain a 'BrokerException' message 
	(if a BrokerException is thrown).
CONFIG_current_kbytes_inuse - the number of KB of 'Configuration Data' store in use by broker
CONFIG_max_kbytes_available - total KB allocated to 'Configuration Data' store in broker
CONFIG_percentageUsed - calculated percentage of how much of the 'Configuration Data' store is in use by broker
DATA_current_kbytes_inuse - the number of KB of 'Run-time Data' store in use by broker
DATA_max_kbytes_available - total KB allocated to 'Run-time Data' store in broker
DATA_percentageUsed -  calculated percentage of how much of the 'Run-time Data' store is in use by broker

PROCESS
========
This service connects to a webMethods broker server and obtains utilisation data for the 'Configuration Data' 
and 'Run-time Data' broker server stores. 

The information returned is similar to that reported by this MWS function:
	Servers > Broker Server Details > (Utilization Tab) > ('Total' and 'Used' columns)
For instance, assume MWS reported usage of the broker 'Run-time Data' store (BrokerData.qs.stor) as:
	1040 KB used out of 4194304 KB allocated (0%)

The 'DATA_percentageUsed' output returned by this service was '0.024...'. 
(MWS reported '0%' as it seems to round broker usage percentages to integer values)

The numbers returned by this service are meant to be monitored by an external monitoring service, so 
that operations/infrastructure teams are alerted when the broker store utilisation climbs too high.

NOTES
=====
1. Parsing BrokerEvent containing storage statistics
This service uses the Broker Java API. The BrokerServerClient.getStorageStats() method is called to obtain 
broker storage statistics. This method returns the data in a 'BrokerEvent' object. 
This BrokerEvent object (its text representation is in the 'DUMP' output) is then queried
(using the BrokerEvent.getField() method) to obtain the store utilisation information. 

The following is assumed:
	a. The first 'sessions' object ('sessions[0]') reports on broker 'Configuration Data' store
	b. The second 'sessions' object ('sessions[1]') reports on broker 'Run-time Data' store
	c. The broker 'Configuration Data' and 'Run-time Data' stores use only one file each.
	   (detailed under 'sessions[0].stats[0]' and 'sessions[1].stats[0]' respectively)

If the structure of this object changes, or if broker is setup to use additional store files,
this service will need to be updated. 
--------------------END JAVA SERVICE COMMENTS-----------------



------------------JAVA SERVICE CODE-------------
// pipeline
IDataCursor pipelineCursor = pipeline.getCursor();
String hostName = IDataUtil.getString( pipelineCursor, "hostName" );

//Initialise intermediate variables
BrokerEvent evt = null;
BrokerServerClient serverClient = null;

//Initialise output variables
String DUMP = null;
Long 	DATA_current_kbytes_inuse = null, 	DATA_max_kbytes_available = null,
	CONFIG_current_kbytes_inuse = null, 	CONFIG_max_kbytes_available = null;
Float 	DATA_percentageUsed =null, 
	CONFIG_percentageUsed =null;

try {
	serverClient = new BrokerServerClient(hostName, null);

	//Get broker storage statistics as a broker event
	evt = serverClient.getStorageStats();

	//Get text representation of broker event for debugging purposes
	DUMP = evt.toString();

	//Obtain broker 'Configuration Data' store information and calculate the percentage used 
	//The if condition below checks that the broker event sub-field ('sessions[0]') queried is appropriate
	if ( evt.getField("sessions[0].session_usage").value.equals("CONFIG") ){
		//Note: The 'BrokerEvent.getField(...)' method returns a BrokerField object. 
		//	The 'BrokerField.value' field is a Java Object (actually a Long) 
		//	which is then cast to Long
		CONFIG_current_kbytes_inuse = (Long) evt.getField("sessions[0].stats[0].current_kbytes_inuse").value;
		CONFIG_max_kbytes_available = (Long) evt.getField("sessions[0].stats[0].max_kbytes_available").value;
		//Do floating point division to obtain percentage with decimal places
		CONFIG_percentageUsed = CONFIG_current_kbytes_inuse.floatValue() / CONFIG_max_kbytes_available.floatValue() * 100;
	}


	//Obtain broker 'Run-time Data' store information and calculate the percentage used
	//The if condition below checks that the broker event sub-field ('sessions[1]') queried is appropriate 
	if ( evt.getField("sessions[1].session_usage").value.equals("DATA") ){
		//Note: The 'BrokerEvent.getField(...)' method returns a BrokerField object. 
		//	The 'BrokerField.value' field is a Java Object (actually a Long) 
		//	which is then cast to Long
		DATA_current_kbytes_inuse = (Long) evt.getField("sessions[1].stats[0].current_kbytes_inuse").value;
		DATA_max_kbytes_available = (Long) evt.getField("sessions[1].stats[0].max_kbytes_available").value;
		//Do floating point division to obtain percentage with decimal places
		DATA_percentageUsed = DATA_current_kbytes_inuse.floatValue() / DATA_max_kbytes_available.floatValue() * 100;
	}


	//Call destroy method to disconnect the client from the broker host.
	serverClient.destroy();

} catch (BrokerException bee) {
	DUMP = "Broker Exception: " + bee.getMessage();
	Service.throwError(bee.getMessage());
}

pipelineCursor.destroy();

// pipeline
IDataCursor pipelineCursor_1 = pipeline.getCursor();
IDataUtil.put( pipelineCursor_1, "DUMP", DUMP);
IDataUtil.put( pipelineCursor_1, "CONFIG_current_kbytes_inuse", String.valueOf(CONFIG_current_kbytes_inuse));
IDataUtil.put( pipelineCursor_1, "CONFIG_max_kbytes_available", String.valueOf(CONFIG_max_kbytes_available));
IDataUtil.put( pipelineCursor_1, "CONFIG_percentageUsed", 	String.valueOf(CONFIG_percentageUsed) );
IDataUtil.put( pipelineCursor_1, "DATA_current_kbytes_inuse", 	String.valueOf(DATA_current_kbytes_inuse));
IDataUtil.put( pipelineCursor_1, "DATA_max_kbytes_available", 	String.valueOf(DATA_max_kbytes_available));
IDataUtil.put( pipelineCursor_1, "DATA_percentageUsed", 	String.valueOf(DATA_percentageUsed));

pipelineCursor_1.destroy();
------------------END JAVA SERVICE CODE-------------