Note : this documentation applies to the previous FFMQ version (2.x) and is deprecated.

FFMQ 2.x Documentation

Table of contents



FFMQ requires a JRE version 1.4 or above to run.

Default JVM parameters are set in the bin/ 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> archive from the Downloads page, and unpack it somewhere.
You will get the following directory tree :

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.


Server side

The main configuration file is conf/ 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.


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.


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"?>

Notes :


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"?>

Notes :

Command-line utility

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

Spring integration

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


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/"/>

Notes :

Client side

Client properties

The client-side API looks for a resource named 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/ in ffmq-core.jar to see available keys and their default values.
Here are the available options in the file :

# Time to wait for an anwser from the server (seconds)
# Time to wait for a connection attempt (seconds)
# SSL options
# Producer buffering (max number of messages to hold on the client side before flushing)

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">
            <prop key="java.naming.factory.initial">net.timewalker.ffmq.jndi.FFMQInitialContextFactory</prop>
            <prop key="java.naming.provider.url">tcp://localhost:10001</prop>

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">
      <prop key="java.naming.factory.initial">net.timewalker.ffmq.jndi.FFMQInitialContextFactory</prop>

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


Server side

Starting and stopping

- To start the server, use the ffmq-server.bat or shell script in the server bin/ directory.
- To stop the server, use the ffmq-shutdown.bat or 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 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 :

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 :

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.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();

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

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 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