Chapter 5. Installation
Prev |  | Next

## Chapter 5. Installation

By default, a JBoss AS 4.0.x instance ships with JBossMQ as default JMS provider. In order to use the JBoss AS instance with JBoss Messaging, you need to perform the installation procedure described below.

### Warning

A JBossMQ and a JBoss Messaging instance cannot coexist, at least not unless special precautions are taken. Do not simply attempt to copy the Messaging release artifact `jboss-messaging-scoped.sar` over to the JBoss instance `deploy` directory. Follow one of the alternate installation procedures outlined below instead.

## 5.1. Installing JBoss Messaging with JBoss AS 4.x

### 5.1.1. Installation procedure

Set up the `JBOSS_HOME` environment variable to point to the JBoss 4.x installation you want to use JBoss Messaging with. Run the installation script, available in the `util` directory of the release bundle. Note that you need Apache Ant 1.6.x or newer installed and accessible from your current directory.

        cd util
        ant -f release-admin.xml

The installation script will create a `$JBOSS_HOME/server/messaging` configuration.

### Note

If you want to create a JBoss Messaging configuration with a different name, modify the `messaging.config.name` system property declared at the beginning of the installation script accordingly.

## 5.2. Starting the Server

To run the server, execute the `run.bat` or `run.sh` script as appropriate for your operating system, in the `$JBOSS_HOME/bin` directory.

         cd $JBOSS_HOME/bin
         ./run.sh -c messaging

A successful JBoss Messaging deployment generates logging output similar to:

    ....
    14:23:56,174 WARN  [JDBCPersistenceManager]

    JBoss Messaging Warning: DataSource connection transaction isolation should be READ_COMMITTED, but it is currently NONE.
                             Using an isolation level less strict than READ_COMMITTED may lead to data consistency problems.
                             Using an isolation level more strict than READ_COMMITTED may lead to deadlock.

    14:23:57,276 INFO  [ServerPeer] JBoss Messaging 1.0.1.CR3 server [server.0] started
    14:23:57,937 INFO  [ConnectionFactory] Connector has leasing enabled, lease period 20000 milliseconds
    14:23:57,937 INFO  [ConnectionFactory] [/ConnectionFactory, /XAConnectionFactory, java:/ConnectionFactory, java:/XAConnectionFactory] deployed
    14:23:57,987 INFO  [Queue] Queue[/queue/DLQ] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:57,997 INFO  [Topic] Topic[/topic/testTopic] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,017 INFO  [Topic] Topic[/topic/securedTopic] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,017 INFO  [Topic] Topic[/topic/testDurableTopic] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,027 INFO  [Queue] Queue[/queue/testQueue] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,027 INFO  [Queue] Queue[/queue/A] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,037 INFO  [Queue] Queue[/queue/B] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,057 INFO  [Queue] Queue[/queue/C] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,067 INFO  [Queue] Queue[/queue/D] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,077 INFO  [Queue] Queue[/queue/ex] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,077 INFO  [Topic] Topic[/topic/openTopic] started, fullSize=75000, pageSize=2000, downCacheSize=2000
    14:23:58,117 INFO  [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=ConnectionFactoryBinding,name=JmsXA' to JNDI name 'java:JmsXA'
    ....

### Note

The warning message `DataSource connection transaction isolation should be READ_COMMITTED, but it is currently NONE` is there to remind you that by default JBossAS ships with Hypersonic, an in-memory Java-based database engine, which is apropriate for demo purposes, but not for heavy load production environments. The Critique of Hypersonic wiki page outlines some of the well-known issues occuring when using this database.

### Warning

Before using Messaging in production, you must configure the Messaging instance to use an enterprise-class database backend such as MySQL or Oracle, otherwise you risk losing your data. See Section 6.2.1, “Changing the Database” for details about replacing Hypersonic.

## 5.3. Installation Validation

The release bundle contains a series of examples that should run "out of the box" and could be used to validate a new installation. Such an example sends a persistent JMS message to a queue called `queue/testQueue`.

To run the example and validate the installation, open an new command line window and set the `JBOSS_HOME` environment variable to point to the JBoss AS 4.x installation you've just installed Messaging on. Navigate to the folder where you extracted the release bundle and drill down to `/examples/queue`. Apache Ant must pe present in your path in order to be able to run the example.

        setenv JBOSS_HOME=<your_JBoss_installation>
        cd .../examples/queue
        $ant

A successfull execution log output looks similar to:

    Buildfile: build.xml
    identify:
      [echo] Running the queue example
      [echo] The queue: testQueue
    sanity-check:
    init:
    compile:
    run:
      [java] Queue /queue/testQueue exists
      [java] The message was successfully sent to the testQueue queue
      [java] Received message: Hello!
      [java] The example connected to JBoss Messaging version 1.0.0 (1.0)
      [java] #####################
      [java] ###    SUCCESS!   ###
      [java] #####################

It is recommended to run `all` validation examples available in the `example` directory (`queue`, `topic`, `mdb`, `stateless`, etc.). In Chapter 4, Running the Examples, we will have a look at each of those examples.

Prev | Up | Next
Chapter 4. Running the Examples | Home | Chapter 6. Configuration