/ 
Queue-DBI-2.3.0
River stage zero No dependents
/ Queue::DBI::Admin

NAME

Queue::DBI::Admin - Manage Queue::DBI queues.

VERSION

Version 2.3.0

SYNOPSIS

use Queue::DBI::Admin;

# Create the object which will allow managing the queues.
my $queues_admin = Queue::DBI::Admin->new(
	database_handle => $dbh,
);

# Check if the tables required by Queue::DBI exist.
if ( !$queues_admin->has_tables() )
{
	# Create the tables required by Queue::DBI to store the queues and data.
	$queues_admin->create_tables();
}

# Create a new queue.
my $queue = $queues_admin->create_queue( $queue_name );

# Test if a queue exists.
if ( $queues_admin->has_queue( $queue_name ) )
{
	...
}

# Retrieve a queue.
my $queue = $queues_admin->retrieve_queue( $queue_name );

# Delete a queue.
$queues_admin->delete_queue( $queue_name );

SUPPORTED DATABASES

This distribution currently supports:

  • SQLite

  • MySQL

Please contact me if you need support for another database type, I'm always glad to add extensions if you can help me with testing.

QUEUES ADMINISTRATION METHODS

new()

Create a new Queue::DBI::Admin object.

my $queues_admin = Queue::DBI::Admin->new(
	database_handle => $database_handle,
);

The 'database_handle' parameter is mandatory and must correspond to a DBI connection handle object.

Optional parameters:

  • queues_table_name

    By default, Queue::DBI uses a table named queues to store the queue definitions. This allows using your own name, if you want to support separate queuing systems or legacy systems.

  • queue_elements_table_name

    By default, Queue::DBI uses a table named queue_elements to store the queued data. This allows using your own name, if you want to support separate queuing systems or legacy systems.

my $queues_admin = Queue::DBI::Admin->new(
	database_handle           => $database_handle,
	queues_table_name         => $custom_queues_table_name,
	queue_elements_table_name => $custom_queue_elements_table_name,
);

create_queue()

Create a new queue.

$queues_admin->create_queue( $queue_name );

has_queue()

Test if a queue exists.

if ( $queues_admin->has_queue( $queue_name ) )
{
	...
}

retrieve_queue()

Retrieve a queue.

my $queue = $queues_admin->retrieve_queue( $queue_name );

# See Queue::DBI->new() for all the available options.
my $queue = $queues_admin->retrieve_queue(
	$queue_name,
	'cleanup_timeout'   => 3600,
	'verbose'           => 1,
	'max_requeue_count' => 5,
);

delete_queue()

Delete a queue and all associated data, permanently. Use this function at your own risk!

$queues_admin->delete_queue( $queue_name );

DATABASE SETUP METHODS

has_tables()

Determine if the tables required for Queue::DBI to operate exist.

In scalar context, this method returns a boolean indicating whether all the necessary tables exist:

# Determine if the tables exist.
my $tables_exist = $queues_admin->has_tables();

In list context, this method returns a boolean indicating whether all the necessary tables exist, and an arrayref of the name of the missing table(s) if any:

# Determine if the tables exist, and the missing one(s).
my ( $tables_exist, $missing_tables ) = $queues_admin->has_tables();

create_tables()

Create the tables required by Queue::DBI to store the queues and data.

$queues_admin->create_tables(
	drop_if_exist => $boolean,
);

By default, it won't drop any table but you can force that by setting 'drop_if_exist' to 1. See drop_tables() for more information on how tables are dropped.

drop_tables()

Drop the tables used to store the queues and queue data.

Warning: there is no undo for this operation. Make sure you really want to drop the tables before using this method.

$queues_admin->drop_tables();

Note: due to foreign key constraints, the tables are dropped in the reverse order in which they are created.

INTERNAL METHODS

get_database_handle()

Return the database handle associated with the Queue::DBI::Admin object.

my $database_handle = $queue->get_database_handle();

get_queues_table_name()

Return the name of the table used to store queue definitions.

my $queues_table_name = $queues_admin->get_queues_table_name();

get_queue_elements_table_name()

Return the name of the table used to store queue elements.

my $queue_elements_table_name = $queues_admin->get_queue_elements_table_name();

get_quoted_queues_table_name()

Return the name of the table used to store queue definitions, quoted for inclusion in SQL statements.

my $quoted_queues_table_name = $queues_admin->get_quoted_queues_table_name();

get_quoted_queue_elements_table_name()

Return the name of the table used to store queue elements, quoted for inclusion in SQL statements.

my $quoted_queue_elements_table_name = $queues_admin->get_quoted_queue_elements_table_name();

assert_database_type_supported()

Assert (i.e., die on failure) whether the database type specified by the database handle passed to new() is supported or not.

my $database_type = $queues_admin->assert_database_type_supported();

Note: the type of the database handle associated with the current object is returned when it is supported.

get_database_type()

Return the database type corresponding to the database handle associated with the Queue::DBI::Admin object.

my $database_type = $queues_admin->get_database_type();

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

BUGS

Please report any bugs or feature requests to bug-queue-dbi at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Queue-DBI. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Queue::DBI::Admin

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to Sergey Bond for suggesting this administration module to extend and complete the features offered by Queue::DBI.

COPYRIGHT & LICENSE

Copyright 2009-2012 Guillaume Aubert.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/