# Adapters

`Zend_Queue` supports all queues implementing the interface `Zend_Queue_Adapter_AdapterInterface`. The following Message Queue services are supported:

- Apache ActiveMQ.

- A database driven queue via `Zend_Db`.

- A MemcacheQ queue driven via `Memcache`.

- Zend Platform's Job Queue.

- A local array. Useful for unit testing.

## Limitations

Message transaction handling is not supported.

## Specific Adapters - Configuration settings

If a default setting is indicated then the parameter is optional. If a default setting is not specified then the parameter is required.

### Apache ActiveMQ - Zend_Queue_Adapter_Activemq

Options listed here are known requirements. Not all messaging servers require username or password.

- $options['name'] = '/temp/queue1';

  This is the name of the queue that you wish to start using. (Required)

- $options['driverOptions']['host'] = 'host.domain.tld';

  $options['driverOptions']['host'] = '127.0.0.1';

  You may set host to an IP address or a hostname.

  Default setting for host is '127.0.0.1'.

- $options['driverOptions']['port'] = 61613;

  Default setting for port is 61613.

- $options['driverOptions']['username'] = 'username';

  Optional for some messaging servers. Read the manual for your messaging server.

- $options['driverOptions']['password'] = 'password';

  Optional for some messaging servers. Read the manual for your messaging server.

- $options['driverOptions']['timeout_sec'] = 2;

  $options['driverOptions']['timeout_usec'] = 0;

  This is the amount of time that `Zend_Queue_Adapter_Activemq` will wait for read activity on a socket before returning no messages.

### Db - Zend_Queue_Adapter_Db

Driver options are checked for a few required options such as type, host, username, password, and dbname. You may pass along additional parameters for `Zend_DB::factory()` as parameters in `$options['driverOptions']`. An example of an additional option not listed here, but could be passed would be port.

    $options = array(
        'driverOptions' => array(
            'host'      => 'db1.domain.tld',
            'username'  => 'my_username',
            'password'  => 'my_password',
            'dbname'    => 'messaging',
            'type'      => 'pdo_mysql',
            'port'      => 3306, // optional parameter.
        ),
        'options' => array(
            // use Zend_Db_Select for update, not all databases can support this
            // feature.
            Zend_Db_Select::FOR_UPDATE => true
        )
    );

    // Create a database queue.
    $queue = new Zend_Queue('Db', $options);

- $options['name'] = 'queue1';

  This is the name of the queue that you wish to start using. (Required)

- $options['driverOptions']['type'] = 'Pdo';

  type is the adapter you wish to have `Zend_Db::factory()` use. This is the first parameter for the `Zend_Db::factory()` class method call.

- $options['driverOptions']['host'] = 'host.domain.tld';

  $options['driverOptions']['host'] = '127.0.0.1';

  You may set host to an IP address or a hostname.

  Default setting for host is '127.0.0.1'.

- $options['driverOptions']['username'] = 'username';

- $options['driverOptions']['password'] = 'password';

- $options['driverOptions']['dbname'] = 'dbname';

  The database name that you have created the required tables for. See the notes section below.

### MemcacheQ - Zend_Queue_Adapter_Memcacheq

- $options['name'] = 'queue1';

  This is the name of the queue that you wish to start using. (Required)

- $options['driverOptions']['host'] = 'host.domain.tld';

  $options['driverOptions']['host'] = '127.0.0.1;'

  You may set host to an IP address or a hostname.

  Default setting for host is '127.0.0.1'.

- $options['driverOptions']['port'] = 22201;

  The default setting for port is 22201.

### Zend Platform Job Queue - Zend_Queue_Adapter_PlatformJobQueue

- $options['daemonOptions']['host'] = '127.0.0.1:10003';

  The hostname and port corresponding to the Zend Platform Job Queue daemon you will use. (Required)

- $options['daemonOptions']['password'] = '1234';

  The password required for accessing the Zend Platform Job Queue daemon. (Required)

### Array - Zend_Queue_Adapter_Array

- $options['name'] = 'queue1';

  This is the name of the queue that you wish to start using. (Required)

## Notes for Specific Adapters

The following adapters have notes:

### Apache ActiveMQ

Visibility duration for `Zend_Queue_Adapter_Activemq` is not available.

While Apache's ActiveMQ will support multiple subscriptions, the `Zend_Queue` does not. You must create a new `Zend_Queue` object for each individual subscription.

ActiveMQ queue/topic names must begin with one of:

- `/queue/`

- `/topic/`

- `/temp-queue/`

- `/temp-topic/`

For example: `/queue/testing`

The following functions are not supported:

- `create()` - create queue. Calling this function will throw an exception.

- `delete()` - delete queue. Calling this function will throw an exception.

- `getQueues()` - list queues. Calling this function will throw an exception.

### Zend_Db

The database CREATE TABLE ( ... ) SQL statement can be found in `Zend/Queue/Adapter/Db/mysql.sql`.

### MemcacheQ

Memcache can be downloaded from http://www.danga.com/memcached/.

MemcacheQ can be downloaded from http://memcachedb.org/memcacheq/.

- `deleteMessage()` - Messages are deleted upon reception from the queue. Calling this function would have no effect. Calling this function will throw an error.

- `count()` or `count($adapter)` - MemcacheQ does not support a method for counting the number of items in a queue. Calling this function will throw an error.

### Zend Platform Job Queue

Job Queue is a feature of Zend Platform's Enterprise Solution offering. It is not a traditional message queue, and instead allows you to queue a script to execute, along with the parameters you wish to pass to it. You can find out more about Job Queue on the zend.com website.

The following is a list of methods where this adapter's behavior diverges from the standard offerings:

- `create()` - Zend Platform does not have the concept of discrete queues; instead, it allows administrators to provide scripts for processing jobs. Since adding new scripts is restricted to the administration interface, this method simply throws an exception indicating the action is forbidden.

- `isExists()` - Just like `create()`, since Job Queue does not have a notion of named queues, this method throws an exception when invoked.

- `delete()` - similar to `create()`, deletion of JQ scripts is not possible except via the admin interface; this method raises an exception.

- `getQueues()` - Zend Platform does not allow introspection into the attached job handling scripts via the API. This method throws an exception.

- `count()` - returns the total number of jobs currently active in the Job Queue.

- `send()` - this method is perhaps the one method that diverges most from other adapters. The `$message` argument may be one of three possible types, and will operate differently based on the value passed:

  - string - the name of a script registered with Job Queue to invoke. If passed in this way, no arguments are provided to the script.

  - array - an array of values with which to configure a `ZendApi_Job` object. These may include the following:

    - `script` - the name of the Job Queue script to invoke. (Required)

    - `priority` - the job priority to use when registering with the queue.

    - `name` - a short string describing the job.

    - `predecessor` - the ID of a job on which this one depends, and which must be executed before this one may begin.

    - `preserved` - whether or not to retain the job within the Job Queue history. By default, off; pass a `TRUE` value to retain it.

    - `user_variables` - an associative array of all variables you wish to have in scope during job execution (similar to named arguments).

    - `interval` - how often, in seconds, the job should run. By default, this is set to 0, indicating it should run once, and once only.

    - `end_time` - an expiry time, past which the job should not run. If the job was set to run only once, and `end_time` has passed, then the job will not be executed. If the job was set to run on an interval, it will not execute again once `end_time` has passed.

    - `schedule_time` - a UNIX timestamp indicating when to run the job; by default, 0, indicating the job should run as soon as possible.

    - `application_id` - the application identifier of the job. By default, this is `NULL`, indicating that one will be automatically assigned by the queue, if the queue was assigned an application ID.

    As noted, only the `script` argument is required; all others are simply available to allow passing more fine-grained detail on how and when to run the job.

  - `ZendApi_Job` - finally, you may simply pass a `ZendApi_Job` instance, and it will be passed along to Platform's Job Queue.

  In all instances, `send()` returns a `Zend_Queue_Message_PlatformJob` object, which provides access to the `ZendApi_Job` object used to communicate with Job Queue.

- `receive()` - retrieves a list of active jobs from Job Queue. Each job in the returned set will be an instance of `Zend_Queue_Message_PlatformJob`.

- `deleteMessage()` - since this adapter only works with Job Queue, this method expects the provided `$message` to be a `Zend_Queue_Message_PlatformJob` instance, and will throw an exception otherwise.

### Array (local)

The Array queue is a PHP `array()` in local memory. The `Zend_Queue_Adapter_Array` is good for unit testing.