| Configuration Guide
DropboxMQ can run in many different environments. This guide lists all public configuration settings. Standalone or JNDI Configuration JCA Configuration Resource Adapter Configuration Properties Endpoint Configuration Properties Class-Loaded Properties ## Standalone or JNDI Configuration Whether running in a standalone application or as part of an application server, the simplest way to interact with DropboxMQ is through JNDI lookups to JMS administered objects. The following properties can be passed to the InitialConext to configure DropboxMQ:
Name: | `java.naming.factory.initial`
Type: | `java.lang.String`
Default: | No default, required
Example: | `net.sf.dropboxmq.jndi.InitialContextFactoryImpl`
Specifies the JNDI factory to use. This property must be set to `net.sf.dropboxmq.jndi.InitialContextFactoryImpl` to lookup DropboxMQ objects.
Name: | `net.sf.dropboxmq.root`
Type: | `java.lang.String`
Default: | No default, required
Example (UNIX): | `/var/dropboxmq/root`
Example (Windows): | `C:\\DropboxMQ\\root`
Specifies the file path to the root directory that contains dropboxes. More information about the dropbox root can be found here.
Name: | `net.sf.dropboxmq.clientId`
Type: | `java.lang.String`
Default: | No default
Example: | `MyJMSApp`
Specifies the JMS client id of any connections. Client ids must be unique for all clients connected at a given time. If no client id is specified, a unique id is generated for each connection.
Name: | `net.sf.dropboxmq.redeliveryAttempts`
Type: | `java.lang.Integer`
Default: | `0`
Limits the number of times a message will be moved back to the `target` directory as the result of the message being recovered. If a message is being recovered and the number of redelivery attempts has been exceeded, the message will be moved to the `error` directory. Otherwise recovering a message causes it to be moved back to the `target` directory. Message recovery typically happens as the result of an application error while consuming a message. A message that has been moved to the `error` directory can always be manually moved to the `target` directory to attempt additional redeliveries.
Name: | `net.sf.dropboxmq.deleteProcessedMessages`
Type: | `java.lang.Boolean`
Default: | `false`
If true, successfully consumed messages, successfully committed transactions and successfully rolled-back transactions will be deleted. The default behaviour is to move successfully consumed messages to the `processed` directory, successfully committed transactions to the `committed` directory and successfully rolled-back transactions to the `rolled-back` directory.
Name: | `net.sf.dropboxmq.deleteExpiredMessages`
Type: | `java.lang.Boolean`
Default: | `false`
If true, expired messages will be deleted. The default behaviour is to move expired messages to the `expired` directory.
Name: | `net.sf.dropboxmq.deleteCompleteTransactions`
Type: | `java.lang.Boolean`
Default: | `true`
If true, committed and rolled-back transactions will be deleted. The default behaviour is to move committed transactions to the `committed` directory and rolled-back transactions to the `rolled-back` directory.
Name: | `net.sf.dropboxmq.preserveDeletedDropboxes`
Type: | `java.lang.Boolean`
Default: | `true`
If true, dropboxes being deleted by a call to `TemporaryQueue.delete()`, `TemporaryTopic.delete()` or `DirectoryStructure.deleteDropbox()` will not actually delete the dropbox but instead rename it to `{name}.deleted-{timestamp}`. If false, the dropbox and any messages contained within it will be deleted.
Name: | `net.sf.dropboxmq.connectionFactories`
Type: | `java.lang.String`
Default: | `ConnectionFactory`
Example (UNIX): | `cf:cf2`
Example (Windows): | `cf;cf2`
A path separator (`':'` on UNIX, `';'` on Windows) separated list of `ConnectionFactory`s that will be created and accessible from JNDI.
Name: | `net.sf.dropboxmq.consumeExpiredMessages`
Type: | `java.lang.Boolean`
Default: | `false`
If true, expiration checks not performed and messages are consumed regardless of whether they are expired or not.
Name: | `net.sf.dropboxmq.queueConnectionFactories`
Type: | `java.lang.String`
Default: | `QueueConnectionFactory`
Example (UNIX): | `qcf:qcf2`
Example (Windows): | `qcf;qcf2`
A path separator (`':'` on UNIX, `';'` on Windows) separated list of `QueueConnectionFactory`s that will be created and accessible from JNDI.
Name: | `net.sf.dropboxmq.topicConnectionFactories`
Type: | `java.lang.String`
Default: | `TopicConnectionFactory`
Example (UNIX): | `tcf:tcf2`
Example (Windows): | `tcf;tcf2`
A path separator (`':'` on UNIX, `';'` on Windows) separated list of `TopicConnectionFactory`s that will be created and accessible from JNDI.
Name: | `net.sf.dropboxmq.xaConnectionFactories`
Type: | `java.lang.String`
Default: | `XAConnectionFactory`
Example (UNIX): | `xacf:xacf2`
Example (Windows): | `xacf;xacf2`
A path separator (`':'` on UNIX, `';'` on Windows) separated list of `XAConnectionFactory`s that will be created and accessible from JNDI.
Name: | `net.sf.dropboxmq.xaQueueConnectionFactories`
Type: | `java.lang.String`
Default: | `XAQueueConnectionFactory`
Example (UNIX): | `xaqcf:xaqcf2`
Example (Windows): | `xaqcf;xaqcf2`
A path separator (`':'` on UNIX, `';'` on Windows) separated list of `XAQueueConnectionFactory`s that will be created and accessible from JNDI.
Name: | `net.sf.dropboxmq.xaTopicConnectionFactories`
Type: | `java.lang.String`
Default: | `XATopicConnectionFactory`
Example (UNIX): | `xatcf:xatcf2`
Example (Windows): | `xatcf;xatcf2`
A path separator (`':'` on UNIX, `';'` on Windows) separated list of `XATopicConnectionFactory`s that will be created and accessible from JNDI.
Name: | `net.sf.dropboxmq.pollingInterval`
Type: | `java.lang.Long`
Default: | `300` (milliseconds)
Specifies in milliseconds the amount of time a message consumer will wait between scans of the `target` directory when waiting for an extended amount of time for a message. Note that if this property is too small, DropboxMQ will spend a noticeable amount of CPU even when idle. If this property is too large, there may be some delay before messages are consumed.
Name: | `net.sf.dropboxmq.targetScanTimeout`
Type: | `java.lang.Long`
Default: | `30000` (30 seconds)
Specifies in milliseconds the amount of time DropboxMQ will use a directory listing of the `target` directory before the listing is considered stale, causing DropboxMQ to rescan the directory. Note that if this property is too small and a dropbox has a large backlog (hundreds of messages), DropboxMQ will spend much time sorting incoming messages. If this property is too large, low priority messages may be consumed before late arriving high priority messages.
Name: | `net.sf.dropboxmq.messageTranscoderFactory`
Type: | `java.lang.String`
Default: | `net.sf.dropboxmq.messagetranscoders.DefaultMessageTranscoderFactory`
Example: | `com.example.MyMessageTranscoderFactory`
Specifies the implementation of `net.sf.dropboxmq.messagetranscoders.MessageTranscoderFactory` that will be used. This factory will be used to create message comparators and transcoders. The comparators are used for sorting messages. The transcoders implement `net.sf.dropboxmq.messagetranscoders.MessageTranscoder` and are used for encoding and decoding message metadata (priority, message id, properties, etc.). Custom factories can be used to read and write metadata for messages that were produced by or will be consumed by clients that do not use DropboxMQ.
## JCA Configuration When running in a Java Connector Architecture (JCA) compliant application server, applications can opt to use DropboxMQ through its resource adapter. ### Resource Adapter Configuration Properties
Name: | `root`
See above.
Name: | `redeliveryAttempts`
See above.
Name: | `deleteProcessedMessages`
See above.
Name: | `deleteExpirededMessages`
See above.
Name: | `deleteCompleteTransactions`
See above.
Name: | `preserveDeletedDropboxes`
See above.
Name: | `consumeExpiredMessages`
See above.
Name: | `pollingInterval`
See above.
Name: | `targetScanTimeout`
See above.
Name: | `messageTranscoderFactory`
See above.
Name: | `classLoadedProperties`
Type: | `java.lang.String`
Default: | No name defined, class loaded properties will not be used.
Example: | `resources/dropboxmq.properties`
Specifies the name of a property file that is accessible to the class loader. The DropboxMQ resource adapter will load this file and use the values it contains to configure DropboxMQ. See below.
### Endpoint Configuration Properties For each endpoint consumer (i.e.: Message Driven Bean), the application container will prepare and configure the consumer with the properties defined in the `activation-config` element of the deployment descriptor. Resource adapter properties may also be defined for a endpoint consumer, but if undefined, values are inherited from th resource adapter. See above for the complete list of resource adapter properties.
Name: | `destination`
Type: | `java.lang.String`
Default: | No default, required though may be specified through a class-loaded property.
Example: | `jms/MyQueue`
The destination from which messages will be consumed.
Name: | `destinationType`
Type: | `java.lang.String`
Default: | No default, destination type not specified.
Example: | `javax.jms.Queue`
Not actually used. Provided only for compatibility with xdoclet. Must be not specified, `javax.jms.Queue` or `javax.jms.Topic`.
Name: | `acknowledgeMode`
Type: | `java.lang.String`
Default: | `Auto-acknowledge`
The acknowledge mode (see `Session.getAcknowledgeMode()`) in which messages will be consumed. Valid values are `Auto-acknowledge`, `Dups-ok-acknowledge`, `Client-acknowledge`, and `Session-transacted` (only value per endpoint). In `Auto-acknowledge` mode, messages are acknowledged (fully consumed) immediately as the endpoint begins processing. `Dups-ok-acknowledge` is not implemented and therefore behaves exactly as `Auto-acknowledge` mode does. `Client-acknowledge` mode causes the DropboxMQ resource adapter to acknowledge messages immediately after the message has been successfully processed ( `MessageListener.onMessage()` returns without throwing an exception). If `Session-transacted` mode is used, a transaction is opened before the message is sent and closed after the message is consumed. If `MessageListener.onMessage()` completes without exception, the transaction is committed. Otherwise, the transaction is rolled back.
Name: | `clientId`
Type: | `java.lang.String`
Default: | No default, no client id defined.
Example: | `MyApp`
The client id (see `Connection.setClientID()`) of the consumer.
Name: | `maxPoolSize`
Type: | `java.lang.Integer`
Default: | `1`
The maximum number of endpoint consumers that will be processing messages at any given time.
Name: | `subscriptionDurability`
Type: | `java.lang.String`
Default: | `Not-durable`
If set to exactly `Durable`, `subscriptionName` is set to a valid subscription name and `destination` references a topic destination, a durable subscription will be established if one does not already exist and the endpoint consumer will consume messages from this subscription. See `Session.createDurableSubscriber()` .
Name: | `subscriptionName`
Type: | `java.lang.String`
Default: | No default, subscription name not specified.
Example: | `MySubscription`
The durable subscription name that will be established when consuming from topics. See `Session.createDurableSubscriber()` .
Name: | `messageSelector`
Type: | `java.lang.String`
Default: | No default, no message selector specified, all messages selected.
Example: | `JMSPriority > 4000`
A message selector expression that will be used to selectively process messages. Only messages where the expression evaluates to `true` will be processed.
Name: | `maxMessages`
Type: | `java.lang.Integer`
Default: | `1`
The number of messages that will be allocated per endpoint before the endpoint starts processing messages. This value may be set to a number larger than one to reduce context switching in situations where the time to process each message is very short (less than one second). When volume is low, an endpoint may start processing with fewer than `maxMessages` but there will be a small delay.
Name: | `classLoadedPropertiesName`
Type: | `java.lang.String`
Default: | No default, no name specified and `classLoadedProperties` will not be used for this endpoint.
Example: | `MyMDB`
The name of the endpoint in the class-loaded properties file. All property values (except for `classLoadedPropertiesName`) can be specfied in the class-loaded property file in the format `<classLoadedPropertiesName>.<property name>.` See below.
## Class-Loaded Properties Class-loaded properties allow DropboxMQ to be configured by a property file loaded by the ClassLoader and thereby, in most cases, loaded from a file not in a binary archive (`.ear`, `.jar`, etc.). This allows such binary archives to have static content while the configuration properties are dynamic for the given runtime environment. Values specified in the class-loaded properties file take precedence over values specified through JCA. To use class-loaded properties, first configure the classpath of the Java container to reference a directory that will contain the property file. See your container's documentation to learn how to modify the classpath. Next, specify the file name of the class-loaded property file in the JCA configuration with the `classLoadedProperties` property. Finally, create the property file. It can contain top level properties such as `root` or endpoint specific properties such as `MyMDB.maxPoolSize`.
    root=/var/dropboxmq/root
    MyMDB.maxPoolSize=5