thekid/rfc — Issue #26: RFC 0026: JMS integration
Author: thekid
Created: 2011-10-09 14:15:47+00:00
State: open

Scope of Change
====
An API to access JMS (Java Messaging Service) will be created.

Rationale
====
There are many situations in which an existing, working implementation
(which JMS has proven to be) needs to be accessed.

Functionality
====
First: The PHP extension ext/java will not be used due to its instability
and memory-hungry implementation.

Analysis of the JMS API #1: Messaging domains
----

1) PTP (point-to-point)

Quote: "A point-to-point (PTP) product or application is built around
the concept of message queues, senders, and receivers. Each message is
addressed to a specific queue, and receiving clients extract messages
from the queue(s) established to hold their messages. Queues retain all
messages sent to them until the messages are consumed or until the
messages expire."

http://java.sun.com/products/jms/tutorial/1_3_1-fcs/doc/images/Fig2.2.gif

Java-Code:

```php

```

2) Publish / subscribe

Quote: "In a publish/subscribe (pub/sub) product or application, clients
address messages to a topic. Publishers and subscribers are generally
anonymous and may dynamically publish or subscribe to the content
hierarchy. The system takes care of distributing the messages
arriving from a topic's multiple publishers to its multiple subscribers.
Topics retain messages only as long as it takes to distribute them to
current subscribers."

http://java.sun.com/products/jms/tutorial/1_3_1-fcs/doc/images/Fig2.3.gif

Java-Code:

```php

```

Analysis of the JMS API #1: Messages
----
A JMS message has three parts:

* A header
* Properties (optional)
* A body (optional)

Headers:

```
Header Field Set By
----------------- -------------------------
JMSDestination send or publish method
JMSDeliveryMode send or publish method
JMSExpiration send or publish method
JMSPriority send or publish method
JMSMessageID send or publish method
JMSTimestamp send or publish method
JMSCorrelationID Client
JMSReplyTo Client
JMSType Client
JMSRedelivered JMS provider

```

Message types:

```
Message Type Body Contains
--------------- ------------------------------------------------------
TextMessage A java.lang.String object (for example, the contents
of an Extensible Markup Language file).

MapMessage A set of name/value pairs, with names as String objects
and values as primitive types in the Java programming
language. The entries can be accessed sequentially by
enumerator or randomly by name. The order of the
entries is undefined.

BytesMessage A stream of uninterpreted bytes. This message type is
for literally encoding a body to match an existing
message format.

StreamMessage A stream of primitive values in the Java programming
language, filled and read sequentially.

ObjectMessage A Serializable object in the Java programming language.

Message Nothing. Composed of header fields and properties only.
This message type is useful when a message body is not
required.

```

PHP API
----
The Java side contains a lot of boilerplate code which our target is to
simplify.

```php
producerFor('queue/testQueue');
with ($message= &$session->createTextMessage()); {
$message->setProperty('Example', 'Test');
$message->setText('Enterprise connectivity achieved');
}
$producer->send($message);

// 2) Publish a message to a topic
$producer= &$session->producerFor('topic/Orders');
with ($message= &$session->createTextMessage()); {
$message->setProperty('Example', 'Test');
$message->setText('Enterprise connectivity achieved');
}
$producer->send($message);

// 1) Receive a message
$consumer= &$session->consumerFor('queue/testQueue');
$message= &$consumer->receive();
$session->listen();

// 2) Either: Subscribe to a topic
$consumer= &$session->consumerFor('topic/Orders');
$message= &$consumer->receive(1000);
$session->listen();

// 2) Or: Create a listener
$consumer= &$session->consumerFor('topic/Orders');
$consumer->setMessageListener(new MyTopicListener());
$session->listen();
?>
```

Security considerations
====
n/a

Speed impact
====
n/a

Dependencies
====
n/a

Related documents
====
- Java Message Service Tutorial
http://java.sun.com/products/jms/tutorial/

- RMI
xp-framework/rfc #12

Comments
====
- friebe, Tue May 31 22:05:03 2005
Which package should this be contained in?