Last week I installed JBoss Messaging 1.2.0.GA on our JBoss 4.0.5.GA instance. In this blog I will state the steps we performed to install the extension and configure it for our application. I am not sure this will be THE way to do it, but this is how it worked for us. Please note that JBoss Messaging will be standard in JBoss 5, but since we are working with JBoss 4.0.5 we have to install it ourselves.

  1. Well, as usual, the first step is to download the extension at this link. After obtaining the zip we extract it in some temporary directory.
  2. Second step is necessary if you don't have Ant 1.7 running at your machine already. This version of Ant is necessary for the installation. So if it is not at your machine you can download it here. Follow the instructions supplied with it to install it.
  3. Third step is also necessary if there hasn't been set a environment variable called 'JBOSS_HOME' pointing to your JBoss root directory. This environment variable is used by the Ant script to determine where to install the JBoss extension.

When this is all set you can browse to the directory '/jboss-messaging-1.2.0.GA/util' of the extracted jboss-messaging zip file and run Ant with the following command:
ant -f release-admin.xml

With this command the extension is installed and you will see in your JBoss instance a new server directory called 'messaging'. The next steps are the steps we performed to configure some queues and make them persisting themselves in a PostgreSQL 8 database.

To have JBoss persit its messages from the queue to Postgres it needs access to the Postgres JDBC driver. Therefor you need to copy the file 'postgresql-8.1-404.jdbc3.jar' (or your version) to the directory '$JBOSS_HOME$/server/messaging/lib'.

To tell JBoss how to access the Postgres database (define a datasource) we put a file called 'postgres-ds.xml' in the directory '$JBOSS_HOME$/server/bag/deploy/'. The file has the following content:

PLAIN TEXT
XML:
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <datasources>
  3.     <local-tx-datasource>
  4.         <jndi-name>JmsDS</jndi-name>
  5.     <connection-url>jdbc:postgresql://localhost/jms</connection-url>
  6.     <driver-class>org.postgresql.Driver</driver-class>
  7.     <user-name>jms</user-name>
  8.     <password>jms</password>
  9.     <new-connection-sql>select 1</new-connection-sql>
  10.     <check-valid-connection-sql>select 1</check-valid-connection-sql>
  11.     <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
  12.     <metadata>
  13.     <type-mapping>PostgreSQL 8.1</type-mapping>
  14.     </metadata>
  15.   </local-tx-datasource>
  16. </datasources>

As you can see in the file it tries to connect to a database called 'JMS' at the localhost. It uses username 'JMS' and password 'JMS'. You must make sure this database exists and the user JMS has the rights to create database objects in the database.

Now JBoss is ready and we have to define the queues in JBoss Messaging. Since we use the default ConnectionFactory we do not have to add one and we just add a MBean to the file 'destinations-service.xml' in the directory '$JBOSS_HOME/server/messaging/deploy/jboss-messaging.sar/':

PLAIN TEXT
XML:
  1. <mbean code="org.jboss.jms.server.destination.QueueService"
  2.       name="jboss.messaging.destination:service=Queue,name=BagQueue"
  3.       xmbean-dd="xmdesc/Queue-xmbean.xml">
  4.       <depends optional-attribute-name="ServerPeer"> jboss.messaging:service=ServerPeer</depends>
  5.       <depends>jboss.messaging:service=PostOffice</depends>
  6.    </mbean>

There is one more file that must be added to the directory '$JBOSS_HOME/server/bag/deploy/jboss-messaging.sar/': 'postgresql-persistence-service.xml'. The contents of this file:

PLAIN TEXT
XML:
  1. <?xml version="1.0" encoding="utf-8"?>
  2.  
  3. <!--
  4.      Postgresql non-clustered persistence deployment descriptor.
  6.      Tested with PostgresSQL 8.1.5
  8.      $Id: postgresql-persistence-service.xml 2449 2007-02-26 19:25:34Z timfox $
  9. -->
  10.  
  11. <server>
  12.  
  13.    <mbean code="org.jboss.messaging.core.plugin.JDBCPersistenceManagerService"
  14.          name="jboss.messaging:service=PgPersistenceManager"
  15.          xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">
  16.          <depends>jboss.jca:service=DataSourceBinding,name=JmsDS</depends>
  17.          <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
  18.          <attribute name="DataSource">java:/JmsDS</attribute>
  19.          <attribute name="CreateTablesOnStartup">true</attribute>
  20.          <attribute name="UsingBatchUpdates">true</attribute>
  21.        <attribute name="SqlProperties"><![CDATA[
  22.    CREATE_MESSAGE_REFERENCE=CREATE TABLE JBM_MSG_REF (CHANNEL_ID BIGINT, MESSAGE_ID BIGINT, TRANSACTION_ID BIGINT, STATE CHAR(1), ORD BIGINT, PAGE_ORD BIGINT, DELIVERY_COUNT INTEGER, SCHED_DELIVERY BIGINT, PRIMARY KEY(CHANNEL_ID, MESSAGE_ID))
  23.    CREATE_IDX_MESSAGE_REF_TX=CREATE INDEX JBM_MSG_REF_TX ON JBM_MSG_REF (TRANSACTION_ID)
  24.    CREATE_IDX_MESSAGE_REF_ORD=CREATE INDEX JBM_MSG_REF_ORD ON JBM_MSG_REF (ORD)
  25.    CREATE_IDX_MESSAGE_REF_PAGE_ORD=CREATE INDEX JBM_MSG_REF_PAGE_ORD ON JBM_MSG_REF (PAGE_ORD)
  26.    CREATE_IDX_MESSAGE_REF_MESSAGE_ID=CREATE INDEX JBM_MSG_REF_MESSAGE_ID ON JBM_MSG_REF (MESSAGE_ID)
  27.    CREATE_IDX_MESSAGE_REF_SCHED_DELIVERY=CREATE INDEX JBM_MSG_REF_SCHED_DELIVERY ON JBM_MSG_REF (SCHED_DELIVERY)
  28.    CREATE_MESSAGE=CREATE TABLE JBM_MSG (MESSAGE_ID BIGINT, RELIABLE CHAR(1), EXPIRATION BIGINT, TIMESTAMP BIGINT, PRIORITY SMALLINT, HEADERS BYTEA, PAYLOAD BYTEA, CHANNEL_COUNT INTEGER, TYPE SMALLINT, PRIMARY KEY (MESSAGE_ID))
  29.    CREATE_TRANSACTION=CREATE TABLE JBM_TX (TRANSACTION_ID BIGINT, BRANCH_QUAL BYTEA, FORMAT_ID INTEGER, GLOBAL_TXID BYTEA, PRIMARY KEY (TRANSACTION_ID))
  30.    CREATE_COUNTER=CREATE TABLE JBM_COUNTER (NAME VARCHAR(255), NEXT_ID BIGINT, PRIMARY KEY(NAME))
  31.    INSERT_MESSAGE_REF=INSERT INTO JBM_MSG_REF (CHANNEL_ID, MESSAGE_ID, TRANSACTION_ID, STATE, ORD, PAGE_ORD, DELIVERY_COUNT, SCHED_DELIVERY) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
  32.    DELETE_MESSAGE_REF=DELETE FROM JBM_MSG_REF WHERE MESSAGE_ID=? AND CHANNEL_ID=? AND STATE='C'
  33.    UPDATE_MESSAGE_REF=UPDATE JBM_MSG_REF SET TRANSACTION_ID=?, STATE='-' WHERE MESSAGE_ID=? AND CHANNEL_ID=? AND STATE='C'
  34.    UPDATE_PAGE_ORDER=UPDATE JBM_MSG_REF SET PAGE_ORD = ? WHERE MESSAGE_ID=? AND CHANNEL_ID=?
  35.    COMMIT_MESSAGE_REF1=UPDATE JBM_MSG_REF SET STATE='C', TRANSACTION_ID = NULL WHERE TRANSACTION_ID=? AND STATE='+'
  36.    COMMIT_MESSAGE_REF2=DELETE FROM JBM_MSG_REF WHERE TRANSACTION_ID=? AND STATE='-'
  37.    ROLLBACK_MESSAGE_REF1=DELETE FROM JBM_MSG_REF WHERE TRANSACTION_ID=? AND STATE='+'
  38.    ROLLBACK_MESSAGE_REF2=UPDATE JBM_MSG_REF SET STATE='C', TRANSACTION_ID = NULL WHERE TRANSACTION_ID=? AND STATE='-'
  39.    LOAD_PAGED_REFS=SELECT MESSAGE_ID, DELIVERY_COUNT, PAGE_ORD, SCHED_DELIVERY FROM JBM_MSG_REF WHERE CHANNEL_ID = ? AND PAGE_ORD BETWEEN ? AND ? ORDER BY PAGE_ORD
  40.    LOAD_UNPAGED_REFS=SELECT MESSAGE_ID, DELIVERY_COUNT, SCHED_DELIVERY FROM JBM_MSG_REF WHERE STATE = 'C' AND CHANNEL_ID = ? AND PAGE_ORD IS NULL ORDER BY ORD
  41.    LOAD_REFS=SELECT MESSAGE_ID, DELIVERY_COUNT, SCHED_DELIVERY FROM JBM_MSG_REF WHERE STATE = 'C' AND CHANNEL_ID = ? ORDER BY ORD
  42.    UPDATE_REFS_NOT_PAGED=UPDATE JBM_MSG_REF SET PAGE_ORD = NULL WHERE PAGE_ORD BETWEEN ? AND ? AND CHANNEL_ID=?
  43.    SELECT_MIN_MAX_PAGE_ORD=SELECT MIN(PAGE_ORD), MAX(PAGE_ORD) FROM JBM_MSG_REF WHERE CHANNEL_ID = ?
  44.    SELECT_EXISTS_REF=SELECT MESSAGE_ID FROM JBM_MSG_REF WHERE CHANNEL_ID = ? AND MESSAGE_ID = ?
  45.    SELECT_EXISTS_REF_MESSAGE_ID=SELECT MESSAGE_ID FROM JBM_MSG_REF WHERE MESSAGE_ID = ?
  46.    UPDATE_DELIVERY_COUNT=UPDATE JBM_MSG_REF SET DELIVERY_COUNT = ? WHERE CHANNEL_ID = ? AND MESSAGE_ID = ?
  47.    UPDATE_CHANNEL_ID=UPDATE JBM_MSG_REF SET CHANNEL_ID = ? WHERE CHANNEL_ID = ?
  48.    LOAD_MESSAGES=SELECT MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, HEADERS, PAYLOAD, TYPE FROM JBM_MSG
  49.    INSERT_MESSAGE=INSERT INTO JBM_MSG (MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, HEADERS, PAYLOAD, CHANNEL_COUNT, TYPE) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
  50.    INC_CHANNEL_COUNT=UPDATE JBM_MSG SET CHANNEL_COUNT = CHANNEL_COUNT + 1 WHERE MESSAGE_ID=?
  51.    DEC_CHANNEL_COUNT=UPDATE JBM_MSG SET CHANNEL_COUNT = CHANNEL_COUNT - 1 WHERE MESSAGE_ID=?
  52.    DELETE_MESSAGE=DELETE FROM JBM_MSG WHERE MESSAGE_ID=? AND CHANNEL_COUNT=0
  53.    MESSAGE_ID_COLUMN=MESSAGE_ID
  54.    MESSAGE_EXISTS=SELECT MESSAGE_ID FROM JBM_MSG WHERE MESSAGE_ID = ? FOR UPDATE
  55.    INSERT_TRANSACTION=INSERT INTO JBM_TX (TRANSACTION_ID, BRANCH_QUAL, FORMAT_ID, GLOBAL_TXID) VALUES(?, ?, ?, ?)
  56.    DELETE_TRANSACTION=DELETE FROM JBM_TX WHERE TRANSACTION_ID = ?
  57.    SELECT_PREPARED_TRANSACTIONS=SELECT TRANSACTION_ID, BRANCH_QUAL, FORMAT_ID, GLOBAL_TXID FROM JBM_TX
  58.    SELECT_MESSAGE_ID_FOR_REF=SELECT MESSAGE_ID, CHANNEL_ID FROM JBM_MSG_REF WHERE TRANSACTION_ID = ? AND STATE = '+' ORDER BY ORD
  59.    SELECT_MESSAGE_ID_FOR_ACK=SELECT MESSAGE_ID, CHANNEL_ID FROM JBM_MSG_REF WHERE TRANSACTION_ID = ? AND STATE = '-' ORDER BY ORD
  60.    UPDATE_COUNTER=UPDATE JBM_COUNTER SET NEXT_ID = ? WHERE NAME=?
  61.    SELECT_COUNTER=SELECT NEXT_ID FROM JBM_COUNTER WHERE NAME=? FOR UPDATE
  62.    INSERT_COUNTER=INSERT INTO JBM_COUNTER (NAME, NEXT_ID) VALUES (?, ?)
  63.    SELECT_ALL_CHANNELS=SELECT DISTINCT(CHANNEL_ID) FROM JBM_MSG_REF
  64.        ]]></attribute>
  65.  
  66.          <attribute name="MaxParams">500</attribute>
  67.    </mbean>
  68.  
  69.    <mbean code="org.jboss.messaging.core.plugin.DefaultPostOfficeService"
  70.       name="jboss.messaging:service=PostOffice"
  71.       xmbean-dd="xmdesc/DefaultPostOffice-xmbean.xml">
  72.       <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
  73.       <depends>jboss.jca:service=DataSourceBinding,name=JmsDS</depends>
  74.       <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
  75.       <attribute name="PostOfficeName">JMS</attribute>
  76.       <attribute name="DataSource">java:/JmsDS</attribute>
  77.       <attribute name="CreateTablesOnStartup">true</attribute>
  78.       <attribute name="SqlProperties"><![CDATA[
  79. CREATE_POSTOFFICE_TABLE=CREATE TABLE JBM_POSTOFFICE (POSTOFFICE_NAME VARCHAR(255), NODE_ID INTEGER, QUEUE_NAME VARCHAR(1023), COND VARCHAR(1023), SELECTOR VARCHAR(1023), CHANNEL_ID BIGINT, CLUSTERED CHAR(1))
  80. INSERT_BINDING=INSERT INTO JBM_POSTOFFICE (POSTOFFICE_NAME, NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED) VALUES (?, ?, ?, ?, ?, ?, ?)
  81. DELETE_BINDING=DELETE FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=? AND QUEUE_NAME=?
  82. LOAD_BINDINGS=SELECT NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME  = ?
  83.       ]]></attribute>
  84.    </mbean>
  85.  
  86.    <mbean code="org.jboss.jms.server.plugin.JDBCJMSUserManagerService"
  87.       name="jboss.messaging:service=JMSUserManager"
  88.       xmbean-dd="xmdesc/JMSUserManager-xmbean.xml">
  89.       <depends>jboss.jca:service=DataSourceBinding,name=JmsDS</depends>
  90.       <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
  91.       <attribute name="DataSource">java:/JmsDS</attribute>
  92.       <attribute name="CreateTablesOnStartup">true</attribute>
  93.       <attribute name="SqlProperties"><![CDATA[
  94. CREATE_USER_TABLE=CREATE TABLE JBM_USER (USER_ID VARCHAR(32) NOT NULL, PASSWD VARCHAR(32) NOT NULL, CLIENTID VARCHAR(128), PRIMARY KEY(USER_ID))
  95. CREATE_ROLE_TABLE=CREATE TABLE JBM_ROLE (ROLE_ID VARCHAR(32) NOT NULL, USER_ID VARCHAR(32) NOT NULL, PRIMARY KEY(USER_ID, ROLE_ID))
  96. SELECT_PRECONF_CLIENTID=SELECT CLIENTID FROM JBM_USER WHERE USER_ID=?
  97. POPULATE.TABLES.1=INSERT INTO JBM_USER (USER_ID,PASSWD,CLIENTID) VALUES ('dilbert','dogbert','dilbert-id')
  98.       ]]></attribute>
  99.    </mbean>
  100.  
  101. </server>

By default the file 'hsqldb-persistence-service.xml' is added to the directory to perform the persistence with HSQLDB. This file must now be removed to avoid clashes in JBoss configuration. So remove the file.

One more thing to do is to tell the JBoss Messaging to use our new persistence manager: PgPersistenceManager. To do this edit the file 'messaging-service.xml' in the directory '$JBOSS_HOME/server/bag/deploy/jboss-messaging.sar/' and replace the next line:

PLAIN TEXT
XML:
  1. <depends optional-attribute-name="PersistenceManager">jboss.messaging:service=PersistenceManager</depends>

with:

PLAIN TEXT
XML:
  1. <depends optional-attribute-name="PersistenceManager">jboss.messaging:service=PgPersistenceManager</depends>

That was the final step. You should now be able to access the JMS Queues with Spring for example as I have blogged here.