/ 
Amazon-SQS-Client-2.0.7
/ Amazon::SQS::Config

NAME

Amazon::SQS::Config - configuration file class for Amazon::SQS::QueueHandler

SYNOPSIS

my $config = Amazon::SQS::Config->new( file => 'amazon-sqs.ini' );

my $config = Amazon::SQS::Config->new( file => \*DATA );

NOTE: you won't typically create your own configuration objects as this is done as part of the QueueDaemon.pl startup procedure.

DESCRIPTION

Config::IniFiles based class to retrieve configuration information for AWS SQS services from a .ini style file.

SECTIONS

The configuration file should contain multiple sections describe below.

handler

The handler section describes your queue handler and other attributes that control how messages are processed.

[handler]
class = MyHandler
message_type = application/json
max_children = 1
class

Name of the class that implements your handler. If you do not provide a class the default class Amazon::SQS::QueueHandler is used. That class will dump and delete each message it reads.

message_type

The message mime type. Can be one of 'text/plain', 'application/json', or 'application/x-www-form-urlencoded'.

If the message type is 'application/json' it will be decoded using the JSON class. If the message type is 'application/x-www-form-urlencoded' the message will be decode using CGI::Simple and returned as a hash reference.

default: text/plain

NOTE: The message sent to your handler is the decoded message. The raw message is available using the get_raw_message method. The decoded messsage is also available using the getter get_message.

max_children

The maximum number of children that can be instantiated by the QueuDaemon.pl script. Currently the maximum is 1. Future versions may support forking.

pidfile

Path of the pid file.

default: /var/run/QueueDaemon.pl.pid

error

The exit section describes what to do with messages when they are handled successfully or when an error occurs. Your handler should return a true value indicating it successfully handled the message and a false value otherwise. Options here then describe what actions to take based on the result of calling your handler.

There are three outcomes possible when processing the message:

1. Your handler returned a true value
2. Your handler returned a false value
3. Your handler or decoding the message resulted in an exception

Two configuration values (exit, delete) control what to do next.

[error]
exit = error
delete = true
exit

  • error

    Exit whenever an exception occurs.

  • never

    Never exit.

  • always

    Exit after processing any message, regardless of state.

  • false

    Exit if your handler returns a false value.

delete

  • always

    Always delete messages (when an error occurs or regardless of your handler's return value).

  • true

    Only delete messages if your handler returns a true value. This is the default value if the QueueDaemon.pl script is not provided a setting for the delete option.

  • false

    Only delete messages if your handler returns a false value.

  • error

    Delete messages only when an error occurs.

queue

This section decribes the queue.

[queue]
interval = 2 
max_wait = 20 
max_messages = 1
visibility_timeout = 60
max_error_retry = 3
name = <your-queue-name>
url = https://sqs.us-east-1.amazonaws.com/<your-account-number>/<your-queue-name>
create_queue

Set to 'yes' if you want the QueueDaemon.pl script to create the queue if it does not exist. Set the name option to just the name of the queue (not the URL).

interval

Number of seconds to wait after no message is received. The script will sleep for this amount of time before attempting to receive another message. If after waking there are still no messages, the sleep time is incremented by this amount up to the max_wait value.

max_error_retry

Number of retries for invoking any AWS API.

default: 3

max_messages

Maximum number of messages to return from the receive message API. Current maximum value is 1. This may change in future versions.

max_wait

The maxium amount of time in seconds to sleep.

default: 60s

name

The name (not the URL) of the queue.

url

The queue URL.

visibility_timeout

From the AWS documentation:

You can provide the VisibilityTimeout parameter in your request. The parameter is applied to the messages that Amazon SQS returns in the response. If you don't include the parameter, the overall visibility timeout for the queue is used for the returned messages. The default visibility timeout for a queue is 30 seconds.

default: 30

wait_time

The number of seconds to wait for a message (long polling). The maximum value is 20 seconds.

The advantage of using long polling is that your messages will be received almost as soon as they are available on the queue. The disadvantage is that you may incur more costs if you are making a lot of calls to receive messages on a queue that is infrequently used. In that case you may want to consider short polling with an interval value. This will result in far fewer calls to receive messages but may delay receipt of messages up to the max wait time.

NOTE: Using long polling instead of short polling will result in your daemon blocking until the ReceiveMessage API returns. Signals received during this period not be may not be immediately acting upon.

aws

This section describes the SQS endpoint and your API credentials. By default, the QueueDaemon.pl script will use the Amazon::Credentials class to find your credentials so you do not need to configure them here.

[aws]
access_key_id = <Your Access Key ID>
secret_access_key = <Your Secret Access Key>
endpoint_url = https://sqs.amazonaws.com
access_key_id

Your AWS Access key value.

secrete_access_key

Your AWS Secret Access key value.

endpoint_url

The AWS SQS endpoint.

default: https://queue.amazonaws.com

log

The log section describe how the QueueDaemon.pl script will log messages. The script instantiates a Log::Log4perl logger automatically for you that will log to the parent's STDERR. See note below regarding how the daemonization process closes STDOUT, STDERR.

[log]
level = debug
file = /tmp/amazon_sqs.log

When you daemonize the script, if either stdout or stderr is set the parent's STDOUT or STDERR will be closed and then reopened using those settings. If these are not set, then they will not be closed. The closing STDERR will stop the Log::Log4perl logger.

level

Log::Log4perl logging level ('trace', 'debug', 'info', 'warn', 'error').

file

Name of a log file for Log::Log4perl messages. You can also use the values of 'stdout' or 'stderr' to log to STDOUT and STDERR.

WARNING: You should probably make sure that the .ini file is properly protected with restrictive permissions if you place credentials in this file.

METHODS AND SUBROUTINES

new

new( file => filename | handle )

You can pass either the name of a file or a file handle to the new method. See Config::IniFiles.

file

The name of a .ini style file that contains the AWS SQS configuration information or handle to an open .ini style file.

SEE ALSO

Config::IniFiles

AUTHOR

Rob Lauer - <bigfoot@cpan.org>