Table of contents

• I. Installing
  
  • I.1. Prerequisites
  • I.2. Server side
    
    • I.2.1. Unpacking the distribution
    • I.2.2. What's inside ?
  • I.3. Client side
• II. Configuring
  
  • II.1. Server side
    
    • II.1.1. Destination auto-creation
    • II.1.2. Security
    • II.1.3. Templates
    • II.1.4. Descriptors
    • II.1.5. Command-line utility
    • II.1.6. Spring integration
  • II.2. Client side
    
    • II.2.1. Client properties
    • II.2.2. Spring integration
• III. Running
  
  • III.1. Server side
    
    • III.1.1. Starting and stopping
    • III.1.2. Diskspace usage
  • III.2. Client side
    
    • III.2.1. JNDI integration
    • III.2.2. Command-line administration

---

Installing

Prerequisites

FFMQ requires a JRE version 1.4 or above to run.

Default JVM parameters are set in the bin/setenv.sh script, which is read on startup.
If you want to change things like the default FFMQ heap size this is the file to edit.

Server side

Unpacking the distribution

Download the latest ffmq-distribution-<version>-dist.zip archive from the Downloads page, and unpack it somewhere.
You will get the following directory tree :

• bin/
• bridges/
• conf/
• conf/templates/
• data/
• destinations/
• lib/

What's inside ?

The bin/ directory contains shell scripts to start, stop and manage the FFMQ server.
The bridges/ directory holds JMS bridges descriptors loaded by the server on startup.
The conf/ directory contains various configuration files used by the server (see Configuring below).
The conf/templates/ directory contains default templates used to create new destinations (queues or topics).
The data/ directory (empty upon installation) is the default data folder where queues mapping/data files will be stored.
The destinations/ directory (empty upon installation) is the default descriptor folder where queues and topics descriptors will be stored.
The lib/ directory contains all the jar files used by the server.

Client side

On the client-side, you need the ffmq-core.jar in your classpath. (plus commons-logging and log4j if you don't already have them)
You will find those jars in the lib/ directory of the server package.

Configuring

Server side

The main configuration file is conf/ffmq-server.properties. This is a standard java properties file with key/pair values.
See inside the distributed file for details, the various configuration settings are described in comments.

Destination auto-creation

FFMQ supports destination auto-creation based on templates.
When enabled, on first usage of a non-existing queue (or topic), a matching template will be looked up in the templates.mapping file and used to generate a valid queue (or topic) descriptor. This operation is transparent to clients and is useful to create auto-deploying queuers.

Security

If the default XML-based security module is enabled in the main configuration file, users and permissions must be described in the security.xml file.
See syntax inside the distributed file. Please note that security is disabled by default.

Templates

When a queue (or topic) is auto-created, the FFMQ engine looks up a template descriptor and copy the template values into a real descriptor (in the destinations/ folder)
Here is a sample queue template descriptor :

<?xml version="1.0" encoding="UTF-8"?>
<queueTemplate>
  <name>ADMIN_QUEUE_TEMPLATE</name>
  <blockCount>100</blockCount>
  <blockSize>1024</blockSize>
  <dataFolder>../data</dataFolder>
  <maxMessageSize>1024</maxMessageSize>
  <maxNonPersistentMessages>100</maxNonPersistentMessages>
  <syncOnWrite>true</syncOnWrite>
  <useNIOMap>true</useNIOMap>
</queueTemplate>

• name : the template name (also referenced in the templates.mapping file)
• blockCount : the number of blocks in the associated persistent block-file (0 disables persistent storage for this destination)
• blockSize : the size of a block (in bytes)
• dataFolder : the folder where to look for/create persistent storage files (may be relative to the server working directory, i.e. bin/)
• maxMessageSize : the maximum allowed size for a message (in bytes)
• maxNonPersistentMessages : maximum number of non-persistent messages allowed in this queue (0 disables non-persistent storage for this destination)
• syncOnWrite : (true/false) if set to false it disables synchronous I/O, making persistent storage way faster but less reliable
• useNIOMap : (true/false) if set to true it enables NIO memory-mapping of data files making persistent storage way faster. Note that memory-mapping space is limited and you may want to disable this on some queues to save the memory space for others.

Notes :

• The syntax is the same for a topic (except for the root node which is <topicTemplate>)
• For a topic, the various parameters will be applied to the temporary queues holding messages for the topic subscribers.
• There will be one temporary queue for each subscriber, so you need to take this into account when sizing your topic.
• A queue template filename must start with queueTemplate- to be taken into account.
• A topic template filename must start with topicTemplate- to be taken into account.

Descriptors

A destination descriptor is much like a template descriptor but it represents an actual existing destination.
Descriptors are automatically created from a template or created on demand from the administration utility (see below).
Here is a sample queue descriptor :

<?xml version="1.0" encoding="UTF-8"?>
<queueDefinition>
  <name>adm_in</name>
  <temporary>false</temporary>
  <blockCount>1200</blockCount>
  <blockSize>4096</blockSize>
  <dataFolder>E:\_workspaceFFMQ_\ffmq\server\runtime\bin\..\data</dataFolder>
  <maxMessageSize>4096</maxMessageSize>
  <maxNonPersistentMessages>1200</maxNonPersistentMessages>
  <syncOnWrite>true</syncOnWrite>
  <useNIOMap>true</useNIOMap>
</queueDefinition>

• name : the queue name
• temporary : (true/false) if set to true the queue is temporary and will be deleted on release
• blockCount : the number of blocks in the associated persistent block-file (0 disables persistent storage for this destination)
• blockSize : the size of a block (in bytes)
• dataFolder : the folder where the persistent storage files are located (may be relative to the server working directory, i.e. bin/)
• maxMessageSize : the maximum allowed size for a message (in bytes)
• maxNonPersistentMessages : maximum number of non-persistent messages allowed in this queue (0 disables non-persistent storage for this destination)
• syncOnWrite : (true/false) if set to false it disables synchronous I/O, making persistent storage way faster but less reliable
• useNIOMap : (true/false) if set to true it enables NIO memory-mapping of data files making persistent storage way faster. Note that memory-mapping space is limited and you may want to disable this on some queues to save the memory space for others.

Notes :

• The syntax is the same for a topic (except for the root node which is <topicDefinition>)
• A queue definition filename must start with queue-
• A topic definition filename must start with topic-

Command-line utility

There is a command-line utility to administrate the server. The utility must be configured in the conf/ffmq-admin-client.properties properties file.

Spring integration

You can start one (or more) engine instance in a given ApplicationContext, using a provided helper bean :

net.timewalker.ffmq.spring.FFMQServerBean

Here is a typical XML spring definition for this :

<bean id="FFMQServer" class="net.timewalker.ffmq.spring.FFMQServerBean" init-method="start" destroy-method="stop">
  <property name="engineName" value="myEngine"/>
  <property name="configLocation" value="../conf/ffmq-server.properties"/>
</bean>

Notes :

• The engineName property value must be unique in a given VM
• The configLocation property supports the classpath: notation and must point to an existing properties file
• This spring definition automatically calls the server start() and stop() methods on context init and close

Client side

Client properties

The client-side API looks for a resource named ffmq.properties in the classpath.
If you need to override some settings, you can create this file and add it to your classpath. You can refer to net/timewalker/ffmq/ffmq.properties in ffmq-core.jar to see available keys and their default values.
Here are the available options in the ffmq.properties file :

# Time to wait for an anwser from the server (seconds)
transport.timeout=120
# Time to wait for a connection attempt (seconds)
transport.tcp.connectTimeout=30
# SSL options
transport.tcp.ssl.protocol=SSLv3
transport.tcp.ssl.ignoreCertificates=false
# Producer buffering (max number of messages to hold on the client side before flushing)
producer.buffering.size=2

Note that in most cases you won't have to change anything in these default settings.

Spring integration

The FFMQ provider can be integrated in spring like any other JMS client implementation.

Here is how you would define a JMS connection factory :

<bean id="JMSConnectionFactory" class="org.springframework.jndi.JndiObjectFactoryBean">
  <property name="jndiName" value="factory/ConnectionFactory"/>
  <property name="jndiEnvironment">
        <props>
            <prop key="java.naming.factory.initial">net.timewalker.ffmq.jndi.FFMQInitialContextFactory</prop>
            <prop key="java.naming.provider.url">tcp://localhost:10001</prop>
        </props>
    </property>
</bean>

And here is how to obtain a a JMS destination bean from JNDI :

<bean id="myJMSQueue" class="org.springframework.jndi.JndiObjectFactoryBean">
  <property name="jndiName" value="queue/myJMSQueue"/>
  <property name="jndiEnvironment">
    <props>
      <prop key="java.naming.factory.initial">net.timewalker.ffmq.jndi.FFMQInitialContextFactory</prop>
    </props>
  </property>
</bean>

Then, you can declare spring JMS templates and listeners.
See the spring documentation for details.

Running

Server side

Starting and stopping

- To start the server, use the ffmq-server.bat or ffmq-server.sh shell script in the server bin/ directory.
- To stop the server, use the ffmq-shutdown.bat or ffmq-shutdown.sh shell script in the server bin/ directory.
(If you want to remotely stop the server, you need to enable the administrative queues in the server configuration and use the ffmq-remote-shutdown.bat or ffmq-remote-shutdown.sh shell script)
It is not recommended to kill the server process as it will cause a recovery of all the active persistent storages on next restart.

Diskspace usage

The persistent storage for a given destination is made of two files :

• A data file (blockCount*blockSize bytes large), containing the messages
• A map file (~ blockCount*14 bytes large) acting as an allocation table

The required disk space for a queue is close to blockCount*(blockSize+14)
Note that messages are splitted over complete blocks, which means you can store between
blockCount / (maxMessageSize modulo blockSize) (worst case) and blockCount (best case) in a given message store.

Client side

JNDI integration

The client implementation can be accessed through JNDI like any other standard JMS implementation.
Here is the JNDI configuration to use :

• Naming Context Factory : net.timewalker.ffmq.jndi.FFMQInitialContextFactory
• Connection Factory JNDI Name : factory/ConnectionFactory
• Provider URL : tcp://<hostname>:10001

Here is a sample source code if you need to do it yourself :

// Create and initialize a JNDI context
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, FFMQConstants.JNDI_CONTEXT_FACTORY);
env.put(Context.PROVIDER_URL, "tcp://localhost:10001");
Context context = new InitialContext(env);

// Lookup a connection factory in the context
ConnectionFactory connFactory = (ConnectionFactory)context.lookup(FFMQConstants.JNDI_CONNECTION_FACTORY_NAME);

// Obtain a JMS connection from the factory
Connection conn = connFactory.createConnection();
conn.start();
...

Note that to provide JMS 1.0.2 compliance, the following connection factories are also declared in the JNDI context :

• factory/QueueConnectionFactory
• factory/TopicConnectionFactory

Command-line administration

The FFMQ server can be (remotely) administered through a command-line utility.
To execute this utility, use the ffmq-admin-client.bat or ffmq-admin-client.sh shell script in the server bin/ directory.
Executing the utility without command-line parameters will display usage information :

Command-line parameters
-------------------------
-command : the command to execute (createQueue,createTopic,deleteQueue,deleteTopic,shutdown)
-destinationName : the queue/topic name
-conf : path to a properties file (optional)

Additional options for createQueue and createTopic commands
-blockCount : the block count
-blockSize : the block size (in bytes)
-maxMessageSize : the max. size allowed for messages (in bytes)
-maxNonPersistentMessages : max. number of non-persistent messages allowed
-syncOnWrite : force syncing to disk on write
-useNIOMap : use NIO Memory Mapping of data files

Examples :

# Ask the server to create queue test1 (a template must exist and be mapped to that name in the templates.mapping file)
ffmq-admin-client -command createQueue -destinationName test1

# Ask the server to create queue test2, giving all necessary parameters
ffmq-admin-client -command createQueue -destinationName test2 -blockCount 1000 -blockSize 1024
-maxMessageSize 32768 -maxNonPersistentMessages 0 -temporary false -syncOnWrite true -useNIOMap true

# Ask the server to shutdown
ffmq-admin-client -command shutdown