Getting started
Create a ConnectionFactory
The core Object where all JMS actions orginate is the ConnectionFactory. A ConnectionFactory is Threadsafe and heavy weight, so normally there is just one in you application, of course you can have as much as you want if needed (e.g. special buissiness case or different JMS providers to use in parrallel).
There are two ways these can get into your system and thus Pax JMS:
Create manually and register as Service
You can create a specific ConnectionFactory and set it up as needed, then register it with the OSGi Service factory so it can be picked up by other bundles. This might alo be used if you already has one configured inside Spring DM or Blueprint, then just export this instance as a service!
Use the Configuration-driven Pax JMS Component
Pax JMS provides a configuration based aproach of setting up a ConnectionFactory. For this create a (factory-)configuration for the pid 'org.ops4j.pax.jms.ConfigurationBasedConnectionFactoryProvider' with the following properties:
org.ops4j.pax.jms.factoryclass - (required) the name of the JMS providers factory class e.g. org.apache.activemq.ActiveMQConnectionFactory
org.ops4j.pax.jms.property.<Java Bean Property> - (optional) the name of any java bean property to configure
You can of course provide other properties they will just be ignored but present in the service registered.
Create a Connection
As a source for sessions, a connection is also needed to interoperate with JMS. As with the ConnectionFactory there is normally only one in the whole system per ConnectionFactory. Again there might be reasons where more than one is managed, e.g. different credentials. And again there are two ways to get a Connection into the system:
Create manually and register as Service
You can always fetch the ConnectionFactory as a service, create a Connection and register that as a service. Again you can even register any existing Object you fetched from any other location.
In fact, in most cases it would even be enough to only register a Connection as a service without any ConnectionFactory at all. For flexibillity this is just not recommend.
You should always register an ExceptionListener with the Connection and unregister it if a serious problem occurs. Pax JMS will assume that whenever a Connection gets broken and must be recreated the corresponding service goes away! The Configuration driven Pax JMS Component will do this automatically. You are also responsible for start/stop/close the Connection!
Use the Configuration-driven Pax JMS Component
Pax JMS provides a configuration based aproach of setting up a Connection. For this create a (factory-)configuration for the pid 'org.ops4j.pax.jms.JMSConnectionProvider' this will create a Connection service for one (the highest ranked) ConnectionFactory service. The following properties are supported:
org.ops4j.pax.jms.username - the username to use in ConnectionFactory#createConnection
org.ops4j.pax.jms.password - the password to use in ConnectionFactory#createConnection
To use a specific one (e.g. if there are more than one in the system) you can provide a filter that determines which service to use with the property 'Connection.target' it must be a valid OSGi filter string and should match one service. You can for example use the org.ops4j.pax.jms.factoryclass or any custom property to distinguish between service instances.