A JMS provider can be used as the transport for one-way and request-response operations. A minimal one-way configuration is shown below:
| Code Block |
|---|
|
@Component
public class Client ... {
@JMS(value = @JMSConfiguration(destination = "ServiceQueue"))
protected Service service;
public String message(String message) {
service.onReceive(message);
}
}
@Component
@JMS(value = @JMSConfiguration(destination = "ServiceQueue"))
public class ServiceImpl implements Service {
public String onReceive(String message) {
// ...
}
}
public interface Service {
@OneWay
String onReceive(String message);
} |
In XML, JMS bindings are configured as follows:
| Code Block |
|---|
|
<component name="OneWayClientClient">
<implementation.java class="..."/>
<reference name="service">
<binding.jms>
<destination jndiName="serviceQueueServiceQueue"/>
</binding.jms>
</reference>
</component>
<component name="OneWayServiceService">
<implementation.java class="..."/>
<service>
<binding.jms>
<destination jndiName="serviceQueueServiceQueue"/>
</binding.jms>
</service>
</component>
|
The above configuration uses the "serviceQueueServiceQueue" queue to propagate messages. Depending on the JMS provider, it may also be necessary to specify a connection factory name (see below).
...
Configuring request-response operations involves specifying a separate response queue in addition to the forward queue:
| Code Block |
|---|
|
<component name="RequestResponseClient">
<implementation.java class="..."/>
<reference name="service">
<binding.jms>
<destination name="serviceQueue"/>
<response>
<destination jndiName="responseQueue"/>
</response>
</binding.jms>
</reference>
</component>
<component name="RequestResponseService">
<implementation.java class="..."/>
<service>
<binding.jms>
<destination name="serviceQueue"/>
<response>
<destination jndiName="responseQueue"/>
</response>
</binding.jms>
</service>
</component>
|
...
While JMS is an asynchronous model, it is important to note that the client component will block on request-response operations until a response is received. In some cases, this is the desired behavior. In other situations, such as long-running interactions, looser coupling is required where the client can continue processing without waiting for a response to be returned. Callbacks can be used to provide responses at some later point in time. Configuring callbacks involves specifying a callback queue:
| Code Block |
|---|
|
<component name="CallbackClient">
<implementation.java class="..."/>
<reference name="service">
<binding.jms>
<destination name="serviceQueue"/>
</binding.jms>
<callback>
<binding.jms>
<destination name="callbackQueue"/>
</binding.jms>
</callback>
</reference>
</component>
<component name="CallbackService">
<implementation.java class="..."/>
<service>
<binding.jms>
<destination name="serviceQueue"/>
</binding.jms>
<callback>
<binding.jms>
<destination name="callbackQueue"/>
</binding.jms>
</callback>
</service>
</component>
|
...
The previous examples assumed the JMS provider did not require the connection factory to be specified for simplicity. However, most JMS providers will require the connection factory to be specified using the conectionFactory element:
| Code Block |
|---|
|
<component name="CallbackClient">
<implementation.java class="..."/>
<reference name="service">
<binding.jms>
<connectionFactory jndiName="TheConnectionFactory"/>
<destination name="serviceQueue"/>
</binding.jms>
</reference>
</component>
|
...
Fabric3 supports XA transacted messaging. This is useful when a message must be reliably sent in conjunction with a database update. To enable transacted messaging, use the transactedOneWay intent on the JMS binding:
| Code Block |
|---|
|
<component name="TheComponent">
<implementation.java class="..."/>
<reference name="service">
<binding.jms requires="transactedOneWay">
<destination jndiName="TheQueue"/>
</binding.jms>
</reference>
</component>
|
The above will enqueue a message transactionally with the message provider. The component implementation is as follows:
| Code Block |
|---|
|
public class TheComponent implements ... {
@Reference
protected Service service;
public void operation() {
Message message = ...
service.invoke(message);
}
}
|
If the above implementation also needed to update a database using Hibernate in the same transaction as the message enque, it could be modified as follows to use the @ManagedTransaction annotation:
| Code Block |
|---|
|
@ManagedTransaction
public class TheComponent implements ... {
@PersisitenceContext(unitName = "employee")
Session session;
@Reference
protected Service service;
public void operation() {
Message message = ...
long id = message.getId();
Entity entity = session.find(Entity.class, id);
entity.update(message.getUpdate());
service.invoke(message);
}
}
|
Transacted Messaging and Request-Response
In a word: don't try it. Transacted messaging will not work with request reply. To see why, consider the following:
| Code Block |
|---|
|
@ManagedTransaction
public class TheComponent implements ... {
@Reference
protected Service service;
public void operation() {
Message message = ...
Response response = service.invoke(message);
}
}
|
...
If you need to receive a response and require transacted messaging, use a callback. The following shows how this is configured:
| Code Block |
|---|
|
<component name="TheComponent">
<implementation.java class="..."/>
<reference name="service">
<binding.jms requires="transactedOneWay">
<destination jndiName="TheQueue"/>
</binding.jms>
<callback>
<binding.jms requires="transactedOneWay">
<destination jndiName="TheCallbackQueue"/>
</binding.jms>
</callback>
</reference>
</component>
|
...
Starting with Fabric3 1.9.5, JMS listeners can be configured to pause (i.e. not receive messages) when the runtime is booted. The listeners can then be started using an HTTP POST operation via the REST Management API. To configure listeners to pause on startup, use the jms/@pause.on.start attribute in systemConfig.xml:
| Code Block |
|---|
|
<config>
<jms pause.on.start="true"/>
<!-- ... -->
</config>
|
The Fabric3 Admin CLI can then be used to start the listeners. Alternatively, a script can issue an HTTP POST operation. Note that if the POST is made against the zone cluster address, Fabric3 will replicate the management change to all runtimes in the zone (cluster). The following is an example CLI session that starts all listeners:
| Code Block |
|---|
//Goes ("follows" the link) to zone2 where the listeners are deployed. Substitute the appropriate zone name.
f zone2
// Puts the value "jms" to the zone/runtime/transports/resume resource.
// Since this is a zone address, the changes will be replicated throughout the cluster.
p zone/runtime/transports/resume jms
|
Alternatively, a script could POST the "jms" value serialized in the JSON format to http://<zone leader>/management/zone/runtime/transports/resume. Listeners on individual runtime instances can be started by using the direct runtime address as opposed to the zone address, e.g.:
| Code Block |
|---|
p runtime/transports/resume jms
|