//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

==== JMS

The Apache Karaf MOM (Messaging Oriented Middleware/JMS) is an optional enterprise feature.

You have to install the `jms` feature first:

----
karaf@root()> feature:install jms
----

The `jms` feature doesn't install a JMS broker: it just installs the OSGi service, commands, and MBean to interact with
a JMS broker (not the broker itself).

It means that you have to install a JMS broker itself.

This JMS broker can be available:

* outside of Apache Karaf, as a standalone broker. In that case, Apache Karaf JMS will remotely connect to the JMS broker.
 For instance, you can use this topology with Apache ActiveMQ or IBM WebsphereMQ.
* embedded in Apache Karaf. With this topology, Apache Karaf itself provides a JMS broker service. Apache ActiveMQ provides
 a native support in Apache Karaf.

For instance, you can install Apache ActiveMQ directly in Apache Karaf:

----
karaf@root()> feature:repo-add activemq
Adding feature url mvn:org.apache.activemq/activemq-karaf/LATEST/xml/features
karaf@root()> feature:install activemq-broker
----

The `activemq-broker` feature installs:

* a Apache ActiveMQ broker directly in Apache Karaf, bind to the `61616` port number by default.
* the Apache ActiveMQ WebConsole bound to `http://0.0.0.0:8181/activemqweb` by default.

The Apache Karaf `jms` feature provides an OSGi service to create/delete JMS connection factories in the container
and perform JMS operations (send or consume messages, get information about a JMS broker, list the destinations, ...).

This JMS OSGi service can be manipulated programmatically (see the developer guide for details), using the `jms:*` commands, or using the JMS MBean.

===== Commands

====== `jms:create`

The `jms:create` command creates a JMS connection factory in the Apache Karaf container. It automatically creates a
blueprint XML file in the `deploy` folder containing the JMS connection factory definition corresponding
to the type that you mentioned.

The `jms:create` command accepts different arguments and options:

----
karaf@root()> jms:create --help
DESCRIPTION
        jms:create

        Create a JMS connection factory.

SYNTAX
        jms:create [options] name

ARGUMENTS
        name
                The JMS connection factory name
                (required)

OPTIONS
        -t, --type
                The JMS connection factory type (ActiveMQ, Artemis or WebsphereMQ)
                (defaults to activemq)
        --pool
                The pool mechanism to use for this connection factory
                (defaults to pooledjms)
        --help
                Display this help message
        --url
                URL of the JMS broker. For WebsphereMQ type, the URL is hostname/port/queuemanager/channel
                (defaults to tcp://localhost:61616)
        -p, --password
                Password to connect to the JMS broker
                (defaults to karaf)
        -u, --username
                Username to connect to the JMS broker
                (defaults to karaf)


----

* the `name` argument is required. It's the name of the JMS connection factory. The name is used to identify the connection factory, and to create the connection factory definition file (`deploy/connectionfactory-[name].xml`).
* the `-t` (`--type`) option is required. It's the type of the JMS connection factory. Currently on `activemq` and `webspheremq` type are supported. If you want to use another type of JMS connection factory, you can create the `deploy/connectionfactory-[name].xml` file by hand (using one as template).
* the `--url` option is required. It's the URL used by the JMS connection factory to connect to the broker. If the type is `activemq`, the URL looks like `tcp://localhost:61616`. If the type is `webspheremq`, the URL looks like `host/port/queuemanager/channel`.
* the `-u` (`--username`) option is optional (karaf by default). In the case of the broker requires authentication, it's the username used.
* the `-p` (`--password`) option is optional (karaf by default). In the case of the broker requires authentication, it's the password used.
* the `--pool` option is optional (`pooledjms` by default). It allows you to define the pooling framework you want to use: pooledjms, narayana, transx.


For instance, to create a JMS connection factory for a Apache ActiveMQ broker, you can do:

----
karaf@root()> feature:install pax-jms-activemq
karaf@root()> jms:create -t activemq --url tcp://localhost:61616 test
----

[NOTE]
====
When you use ActiveMQ, Karaf uses `transx` as connection factory pooling framework.
====

[NOTE]
====
The `jms:create` command doesn't install any feature or bundle providing the JMS connection factory classes (and dependencies).
You have to install the required features (for instance `activemq-broker` feature for Apache ActiveMQ), or bundles (for IBM WebsphereMQ) providing the JMS connection factory packages and classes.
====

In the previous example, we assume that you previously installed the `activemq-broker` feature.

We can see the created JMS connection factory:

----
karaf@root()> la
...
151 | Active   |  80 | 0.0.0                 | connectionfactory-test.xml
----

The `connectionfactory-test.xml` file has been created in the `deploy` folder.

By default, the `jms:create` command constructs a JNDI name for the connection factory: `/jms/[name]`.

It means that the connection factory name to use for the other `jms:*` commands is `/jms/[name]`.

====== `jms:delete`

The `jms:delete` command deletes a JMS connection factory. The `name` argument is the name that you used at creation time:

----
karaf@root()> jms:delete test
----

====== `jms:connectionfactories`

The `jms:connectionfactories` command lists the JMS connection factories:

----
karaf@root()> jms:connectionfactories 
JMS Connection Factory
----------------------
/jms/test     
----

====== `jms:info`

The `jms:info` command provides details about the JMS connection factory:

----
karaf@root()> jms:info /jms/test
Property | Value
-------------------
product  | ActiveMQ
version  | 5.9.0
----

You can see the JMS broker product and version.

If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.

====== `jms:queues`

The `jms:queues` command lists the JMS queues available on a JMS broker. For instance:

----
karaf@root()> jms:queues /jms/test
JMS Queues
----------
MyQueue
----

where `/jms/test` is the name of the JMS connection factory.

If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.

[NOTE]
====
Depending of the JMS connection factory type, this command may not work.
For now, the command works only with Apache ActiveMQ.
====

====== `jms:topics`

The `jms:topics` command lists the JMS topics available on a JMS broker. For instance:

----
karaf@root()> jms:topics /jms/test
JMS Topics
----------
MyTopic
----

where `/jms/test` is the name of the JMS connection factory.

If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.

[NOTE]
====
Depending of the JMS connection factory type, this command may not work.
For now, the command works only with Apache ActiveMQ.
====

====== `jms:send`

The `jms:send` command sends a message to a given JMS queue.

For instance, to send a message containing `Hello World` in the `MyQueue` queue, you can do:

----
karaf@root()> jms:send /jms/test MyQueue "Hello World"
----

If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.

====== `jms:consume`

The `jms:consume` command consumes messages from a JMS queue.

For instance, to consume all messages from `MyQueue`, you can do:

----
karaf@root()> jms:consume /jms/test MyQueue
2 message(s) consumed
----

If you want to consume only some messages, you can define a selector using the `-s` (`--selector`) option.

If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.

[NOTE]
====
The `jms:consume` command just consumes (so removes) messages from a JMS queue. It doesn't display the messages.
If you want to see the details of messages, you can use the `jms:browse` command.
====

====== `jms:count`

The `jms:count` command counts the number of pending messages into a JMS queue.

For instance, if you want to know the number of messages on `MyQueue`, you can do:

----
karaf@root()> jms:count /jms/test MyQueue
Messages Count
--------------
8
----

If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.

====== `jms:browse`

The `jms:browse` command browses a JMS queue and display details about messages.

For instance, to browse the `MyQueue` queue:

----
karaf@root()> jms:browse /jms/test MyQueue
Message ID                              | Content        | Charset | Type | Correlation ID | Delivery Mode | Destination     | Expiration | Priority | Redelivered | ReplyTo | Timestamp
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
ID:vostro-59602-1387462183019-3:1:1:1:1 | Hello World    | UTF-8   |      |                | Persistent    | queue://MyQueue | Never      | 4        | false       |         | Thu Dec 19 15:10:12 CET 2013
ID:vostro-59602-1387462183019-3:2:1:1:1 | Hello ActiveMQ | UTF-8   |      |                | Persistent    | queue://MyQueue | Never      | 4        | false       |         | Thu Dec 19 15:10:16 CET 2013
ID:vostro-59602-1387462183019-3:3:1:1:1 | Hello Karaf    | UTF-8   |      |                | Persistent    | queue://MyQueue | Never      | 4        | false       |         | Thu Dec 19 15:10:19 CET 2013
----

By default, the messages properties are not displayed. You can use the `-v` (`--verbose`) option to display the properties:

----
karaf@root()> jms:browse -v /jms/test MyQueue
Message ID                              | Content        | Charset | Type | Correlation ID | Delivery Mode | Destination     | Expiration | Priority | Redelivered | ReplyTo | Timestamp                    | Properties
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
ID:vostro-59602-1387462183019-3:1:1:1:1 | Hello World    | UTF-8   |      |                | Persistent    | queue://MyQueue | Never      | 4        | false       |         | Thu Dec 19 15:10:12 CET 2013 |
ID:vostro-59602-1387462183019-3:2:1:1:1 | Hello ActiveMQ | UTF-8   |      |                | Persistent    | queue://MyQueue | Never      | 4        | false       |         | Thu Dec 19 15:10:16 CET 2013 |
ID:vostro-59602-1387462183019-3:3:1:1:1 | Hello Karaf    | UTF-8   |      |                | Persistent    | queue://MyQueue | Never      | 4        | false       |         | Thu Dec 19 15:10:19 CET 2013 |
----

If you want to browse only some messages, you can define a selector using the `-s` (`--selector`) option.

If the JMS broker requires an authentication, you can use the `-u` (`--username`) and `-p` (`--password`) options.

====== `jms:move`

The `jms:move` command consumes all messages from a JMS queue and send it to another one.

For instance, to move all messages from `MyQueue` queue to `AnotherQueue` queue, you can do:

----
karaf@root()> jms:move /jms/test MyQueue AnotherQueue
3 message(s) moved
----

===== JMX JMS MBean

The JMX JMS MBean provides the attributes and operations to manipulate the JMS connection factories and JMS messages.

The object name to use is `org.apache.karaf:type=jms,name=*`.

====== Attributes

The `Connectionfactories` attribute provides the list of all JMS connection factories names.

====== Operations

* `create(name, type, url)` creates a JMS connection factory.
* `delete(name)` deletes a JMS connection factory.
* `Map<String, String> info(connectionFactory, username, password)` gets details about a JMS connection factory and broker.
* `int count(connectionFactory, queue, username, password)` counts the number of pending messages on a JMS queue.
* `List<String> queues(connectionFactory, username, password)` lists the JMS queues available on the JMS broker.
* `List<String> topics(connectionFactory, username, password)` lists the JMS topics available on the JMS broker.
* `TabularData browse(connectionFactory, queue, selector, username, password)` browses a JMS queue and provides a table of JMS messages.
* `send(connectionFactory, queue, content, replyTo, username, password)` sends a JMS message to a target queue.
* `int consume(connectionFactory, queue, selector, username, password)` consumes JMS messages from a JMS queue.
* `int move(connectionFactory, source, destination, selector, username, password)` moves messages from a JMS queue to another.