← Back to branch summary

~nvalcarcel/ubuntu/lucid/puppet/fix-546677

« back to all changes in this revision

Viewing changes to lib/puppet/util/queue.rb

  • Committer: Bazaar Package Importer
  • Author(s): Chuck Short
  • Date: 2009-12-23 00:48:10 UTC
  • mfrom: (1.1.10 upstream) (3.1.7 squeeze)
  • Revision ID: james.westby@ubuntu.com-20091223004810-3i4oryds922g5n59
Tags: 0.25.1-3ubuntu1
* Merge from debian testing.  Remaining changes:
  - debian/rules:
    + Don't start puppet when first installing puppet.
  - debian/puppet.conf, lib/puppet/defaults.rb:
    + Move templates to /etc/puppet
  - lib/puppet/defaults.rb:
    + Fix /var/lib/puppet/state ownership.
  - man/man8/puppet.conf.8: 
    + Fix broken URL in manpage.
  - debian/control:
    + Update maintainer accordint to spec.
    + Puppetmaster Recommends -> Suggests
    + Created puppet-testsuite as a seperate. Allow the users to run puppet's 
      testsuite.
  - tests/Rakefile: Fix rakefile so that the testsuite can acutally be ran.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/puppet/util/queue.rb
 
1
 
 
2
require 'puppet/indirector'
 
3
require 'puppet/util/instance_loader'
 
4
 
 
5
# Implements a message queue client type plugin registry for use by the indirector facility.
 
6
# Client modules for speaking a particular protocol (e.g. Stomp::Client for Stomp message
 
7
# brokers, Memcached for Starling and Sparrow, etc.) register themselves with this module.
 
8
#
 
9
# Client classes are expected to live under the Puppet::Util::Queue namespace and corresponding
 
10
# directory; the attempted use of a client via its typename (see below) will cause Puppet::Util::Queue
 
11
# to attempt to load the corresponding plugin if it is not yet loaded.  The client class registers itself
 
12
# with Puppet::Util::Queue and should use the same type name as the autloader expects for the plugin file.
 
13
#   class Puppet::Util::Queue::SpecialMagicalClient < Messaging::SpecialMagic
 
14
#       ...
 
15
#       Puppet::Util::Queue.register_queue_type_class(self)
 
16
#   end
 
17
#
 
18
# This module reduces the rightmost segment of the class name into a pretty symbol that will
 
19
# serve as the queuing client's name.  Which means that the "SpecialMagicalClient" above will
 
20
# be named <em>:special_magical_client</em> within the registry.
 
21
#
 
22
# Another class/module may mix-in this module, and may then make use of the registered clients.
 
23
#   class Queue::Fue
 
24
#       # mix it in at the class object level rather than instance level
 
25
#       extend ::Puppet::Util::Queue
 
26
#   end
 
27
#
 
28
# Queue::Fue instances can get a message queue client through the registry through the mixed-in method
 
29
# +client+, which will return a class-wide singleton client instance, determined by +client_class+.
 
30
#
 
31
# The client plugins are expected to implement an interface similar to that of Stomp::Client:
 
32
# * <tt>new()</tt> should return a connected, ready-to-go client instance.  Note that no arguments are passed in.
 
33
# * <tt>send_message(queue, message)</tt> should send the _message_ to the specified _queue_.
 
34
# * <tt>subscribe(queue)</tt> _block_ subscribes to _queue_ and executes _block_ upon receiving a message.
 
35
# * _queue_ names are simple names independent of the message broker or client library.  No "/queue/" prefixes like in Stomp::Client.
 
36
module Puppet::Util::Queue
 
37
    extend Puppet::Util::InstanceLoader
 
38
    instance_load :queue_clients, 'puppet/util/queue'
 
39
 
 
40
    # Adds a new class/queue-type pair to the registry.  The _type_ argument is optional; if not provided,
 
41
    # _type_ defaults to a lowercased, underscored symbol programmatically derived from the rightmost
 
42
    # namespace of <em>klass.name</em>.
 
43
    #
 
44
    #   # register with default name +:you+
 
45
    #   register_queue_type(Foo::You)
 
46
    #
 
47
    #   # register with explicit queue type name +:myself+
 
48
    #   register_queue_type(Foo::Me, :myself)
 
49
    #
 
50
    # If the type is already registered, an exception is thrown.  No checking is performed of _klass_,
 
51
    # however; a given class could be registered any number of times, as long as the _type_ differs with
 
52
    # each registration.
 
53
    def self.register_queue_type(klass, type = nil)
 
54
        type ||= queue_type_from_class(klass)
 
55
        raise Puppet::Error, "Queue type %s is already registered" % type.to_s if instance_hash(:queue_clients).include?(type)
 
56
        instance_hash(:queue_clients)[type] = klass
 
57
    end
 
58
 
 
59
    # Given a queue type symbol, returns the associated +Class+ object.  If the queue type is unknown
 
60
    # (meaning it hasn't been registered with this module), an exception is thrown.
 
61
    def self.queue_type_to_class(type)
 
62
        c = loaded_instance :queue_clients, type
 
63
        raise Puppet::Error, "Queue type %s is unknown." % type unless c
 
64
        c
 
65
    end
 
66
 
 
67
    # Given a class object _klass_, returns the programmatic default queue type name symbol for _klass_.
 
68
    # The algorithm is as shown in earlier examples; the last namespace segment of _klass.name_ is taken
 
69
    # and converted from mixed case to underscore-separated lowercase, and interned.
 
70
    #   queue_type_from_class(Foo) -> :foo
 
71
    #   queue_type_from_class(Foo::Too) -> :too
 
72
    #   queue_type_from_class(Foo::ForYouTwo) -> :for_you_too
 
73
    #
 
74
    # The implicit assumption here, consistent with Puppet's approach to plugins in general,
 
75
    # is that all your client modules live in the same namespace, such that reduction to
 
76
    # a flat namespace of symbols is reasonably safe.
 
77
    def self.queue_type_from_class(klass)
 
78
        # convert last segment of classname from studly caps to lower case with underscores, and symbolize
 
79
        klass.name.split('::').pop.sub(/^[A-Z]/) {|c| c.downcase}.gsub(/[A-Z]/) {|c| '_' + c.downcase }.intern
 
80
    end
 
81
 
 
82
    # The class object for the client to be used, determined by queue configuration
 
83
    # settings.
 
84
    # Looks to the <tt>:queue_type</tt> configuration entry in the running application for
 
85
    # the default queue type to use.
 
86
    def client_class
 
87
        Puppet::Util::Queue.queue_type_to_class(Puppet[:queue_type])
 
88
    end
 
89
 
 
90
    # Returns (instantiating as necessary) the singleton queue client instance, according to the
 
91
    # client_class.  No arguments go to the client class constructor, meaning its up to the client class
 
92
    # to know how to determine its queue message source (presumably through Puppet configuration data).
 
93
    def client
 
94
        @client ||= client_class.new
 
95
    end
 
96
end