Using the micro broker JMS client

The following is a brief example of how to instantiate and use the micro broker’s JMS client in an Expeditor environment.

Setting project dependencies

You will need the following plug-in dependencies specified in your MANIFEST.MF:

• com.ibm.mqttclient.jms
• com.ibm.micro.utils
• com.ibm.pvc.jms

Creating your JMS Connection Factory programmatically

The micro broker provides a factory (a “factory factory”!) for creating JMS Connection Factory instances. This factory is accessed as follows:

JmsFactoryFactory jmsFactory = JmsFactoryFactory.getInstance(MQTTConstants.PROVIDER_NAME);

// Obtain a connection factory
ConnectionFactory cf = jmsFactory.createConnectionFactory();
// We need to set the target endpoint on the connection factory
// Connecting to localhost over TCP
((JmsConnectionFactory) cf).setStringProperty(MQTTConstants.MQTT_CONNECTION_URL,MQTTConstants.MQTT_TCP_SCHEMA + "127.0.0.1:1883");

Note that we set some specific properties for MQTT, such as the connection URL. A client ID is mandatory for the micro broker JMS client too. Connection Factories can be created declaratively using an Expeditor Extension Point. Details of how to do this can be found in the Expeditor Info Center on this page.

Creating a JMS Connection

The main point to note here is that the micro broker requires a client ID to be specified.

// Now obtain a connection from the factory
Connection conn = cf.createConnection();
// A client ID is required
conn.setClientID("Pinger");
// Connection is ready for use.

A sample JMS application

// Connection Factory
JmsFactoryFactory jmsFactory = JmsFactoryFactory.getInstance(MQTTConstants.PROVIDER_NAME);
// Obtain a connection factory
ConnectionFactory cf = jmsFactory.createConnectionFactory();
// We need to set the target endpoint on the connection factory
// Connecting to localhost over TCP
((JmsConnectionFactory) cf).setStringProperty(MQTTConstants.MQTT_CONNECTION_URL, MQTTConstants.MQTT_TCP_SCHEMA + "127.0.0.1:1883");
...
// Now obtain a connection from the factory
Connection conn = cf.createConnection();
// A client ID is required
conn.setClientID("Pinger");
// Finally start the connection up
conn.start();
...
Session session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
MessageProducer producer = session.createProducer(session.createTopic(MICROBROKER_TOPIC_NAME_OUTBOUND));
MessageConsumer consumer = session.createConsumer(session.createTopic(MICROBROKER_TOPIC_NAME_INBOUND));
...
TextMessage requestMsg = session.createTextMessage("{ \"telephone\" : \"04962 915000\" }");
requestMsg.setStringProperty("TargetFunctionName", "checkDSL");
producer.send(requestMsg);
...
Message responseMsg = (Message) consumer.receive(JMS_REQUEST_TIMEOUT);
...
session.close();
conn.stop();
conn.close();

Installing features without the Expeditor GUI

In cases where we have either a “headless” Expeditor installation or when we otherwise need to update the platform with new features and plug-ins via a non-Expeditor GUI route (e.g. via a separate install package), there are a couple of options that can be used.

Use an install manifest file

Expeditor has the concept of an install manifest file that essentially provides a script for installing (or removing) features from the platform. An example follows:

<?xml version="1.0" encoding="UTF-8"?>
<ibm-portal-composite>
	<domain-object name="com.ibm.rcp.installmanifest">
		<object-data>
			<install>
				<installfeature id="Acme.PoC" required="true" mergeaction="add">
					<requirements>
						<feature id="com.ibm.issw.acme.poc.feature"
							version="1.0.0"
							match="compatible"
							action="install"
							url="file:/C:\installers\acme\updatesite"
							shared="false" />
					</requirements>
				</installfeature>
			</install>
		</object-data>
	</domain-object>
</ibm-portal-composite>

In the above example, we are installing version 1.0.0 of the feature com.ibm.issw.acme.poc.feature from an update site at the URL file:/C:\installers\acme\updatesite. Naturally we could have added more features from other sites. The shared=false setting tells Expeditor we want to install the updates in the user area (workspace) rather than the base installation location for Expeditor. This is a handy separation of application code from base Expeditor.

Having created this manifest for the features and update sites we require, we process it without Expeditor running using the following command line within the Expeditor installation location (e.g. C:\Program Files\IBM\Lotus\Expeditor):

rcp\rcplauncher.exe -application com.ibm.rcp.provisioning.application.ProvisioningApplication -provisioningOperation provision c:\installers\acme\install.update.xml -provisioningStatusLog mylog.txt -console -data ".\workspace"

where the location of the XML provisioning manifest follows the provision keyword (in the above example the manifest was stored in c:\installers\acme\install.update.xml for example).

Note that the -data option may not be required if the rcp.data property in your rcplauncher.properties is set. This property tells Expeditor where the user workspace data is to be stored.

Use the provisioning capabilities from the OSGi console

If running in headless mode or console mode, you can achieve the same net effect as the above using an OSGi command using the Provisioning capabilities built into Expeditor. Expeditor provides the prov command to which you simply provide the name of the feature, the version required and the URL of the update site, for example:

prov i com.ibm.issw.acme.poc.feature 1.0.0 file:/c:\installers\acme\updatesite

The i switch tells Expeditor this is an installation request. Typing ? on the OSGi command line will yield a full description of the prov options.