qpid_management 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 680e99b92e33b73931b81e0008846acc105eae5d
+  data.tar.gz: c39a443cc5b7205bd9a8a64f2c984f2024ed3e3e
+SHA512:
+  metadata.gz: ba56998378d73cbe90b5887c7b2587773520c9b8c9893ebbed34d1d0438fbf08294e57301ebaf63fb37fcdd53d3d434a1f55b4dd9ebf45036292f704447b4056
+  data.tar.gz: 0a65eb4d520421451bd1d27bebc6bcdbe8b065ce846a20b4dddd8aa8b7cb19f4692c9720787e27ac2f8d20aee93a333fb44f844237ba2c5bae46ed13a5046e65

data/.gitignore

@@ -0,0 +1,3 @@
+*.gem
+.bundle
+pkg/*

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,30 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in qpid_config.gemspec
+gemspec
+
+# development deps
+gem 'rspec'
+gem 'pry'
+gem 'pry-stack_explorer'
+gem 'pry-debugger'
+gem 'yard'

data/Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: .
+  specs:
+    qpid_management (1.0)
+      qpid_messaging
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    binding_of_caller (0.7.1)
+      debug_inspector (>= 0.0.1)
+    coderay (1.0.9)
+    columnize (0.3.6)
+    debug_inspector (0.0.2)
+    debugger (1.4.0)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.1.1)
+      debugger-ruby_core_source (~> 1.2.0)
+    debugger-linecache (1.1.2)
+      debugger-ruby_core_source (>= 1.1.1)
+    debugger-ruby_core_source (1.2.0)
+    diff-lcs (1.2.1)
+    method_source (0.8.1)
+    pry (0.9.12)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    pry-debugger (0.2.2)
+      debugger (~> 1.3)
+      pry (~> 0.9.10)
+    pry-stack_explorer (0.4.9)
+      binding_of_caller (>= 0.7)
+      pry (~> 0.9.11)
+    qpid_messaging (0.20.2)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.0)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.0)
+    slop (3.4.3)
+    yard (0.8.5.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  pry
+  pry-debugger
+  pry-stack_explorer
+  qpid_management!
+  rspec
+  yard

data/Rakefile

@@ -0,0 +1,27 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+require 'rake/clean'
+CLOBBER.include('pkg')
+
+RSpec::Core::RakeTask.new('spec')
+

data/lib/qpid_management/acl.rb

@@ -0,0 +1,38 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+module Qpid
+  module Management
+    # Representation of the access control list (ACL) for the broker. Properties
+    # include:
+    # - aclDenyCount
+    # - brokerRef
+    # - connectionDenyCount
+    # - enforcingAcl
+    # - lastAclLoad
+    # - maxConnectionsPerIp
+    # - maxConnectionsPerUser
+    # - maxQueuesPerUser
+    # - policyFile
+    # - queueQuotaDenyCount
+    # - transferAcl
+    class Acl < BrokerObject
+    end
+  end
+end

data/lib/qpid_management/binding.rb

@@ -0,0 +1,31 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+module Qpid
+  module Management
+    # Representation of a binding in the broker. Properties include:
+    # - arguments
+    # - bindingKey
+    # - exchangeRef
+    # - msgMatched
+    # - queueRef
+    class Binding < BrokerObject
+    end
+  end
+end

data/lib/qpid_management/bridge.rb

@@ -0,0 +1,39 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+module Qpid
+  module Management
+    # Representation of a bridge to another broker. Properties include:
+    # - channelId
+    # - dest
+    # - durable
+    # - dynamic
+    # - excludes
+    # - key
+    # - linkRef
+    # - name
+    # - src
+    # - srcIsLocal
+    # - srcIsQueue
+    # - sync
+    # - tag
+    class Bridge < BrokerObject
+    end
+  end
+end

data/lib/qpid_management/broker.rb

@@ -0,0 +1,278 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+module Qpid
+  module Management
+    # Representation of the broker. Properties include:
+    # - abandoned
+    # - abandonedViaAlt
+    # - acquires
+    # - byteDepth
+    # - byteFtdDepth
+    # - byteFtdDequeues
+    # - byteFtdEnqueues
+    # - bytePersistDequeues
+    # - bytePersistEnqueues
+    # - byteTotalDequeues
+    # - byteTotalEnqueues
+    # - byteTxnDequeues
+    # - byteTxnEnqueues
+    # - connBacklog
+    # - dataDir
+    # - discardsLvq
+    # - discardsNoRoute
+    # - discardsOverflow
+    # - discardsPurge
+    # - discardsRing
+    # - discardsSubscriber
+    # - discardsTtl
+    # - maxConns
+    # - mgmtPubInterval
+    # - mgmtPublish
+    # - msgDepth
+    # - msgFtdDepth
+    # - msgFtdDequeues
+    # - msgFtdEnqueues
+    # - msgPersistDequeues
+    # - msgPersistEnqueues
+    # - msgTotalDequeues
+    # - msgTotalEnqueues
+    # - msgTxnDequeues
+    # - msgTxnEnqueues
+    # - name
+    # - port
+    # - queueCount
+    # - releases
+    # - reroutes
+    # - stagingThreshold
+    # - systemRef
+    # - uptime
+    # - version
+    # - workerThreads
+    class Broker < BrokerObject
+      # Adds methods for the specified collections to be able to access all instances
+      # of a given collection, as well as a single instance by oid.
+      #
+      # == Example
+      # <tt>has_many :queues</tt> which will add:
+      # * <tt>#queues</tt> to retrieve all queues
+      # * <tt>#queue(oid)</tt> to retrieve a queue by oid (note, this is the short form of the object id, e.g. "myqueue" for a queue instead of "org.apache.qpid.broker:queue:myqueue"
+      #
+      # @param collections one or more symbols for the collections of objects a broker manages
+      def self.has_many(*collections)
+        [*collections].each do |collection|
+          singular_form = collection.to_s[0..-2]
+          capitalized_type = singular_form.gsub(/^\w/) { $&.upcase }
+
+          define_method(collection) do
+            @agent.find_all_by_class(Qpid::Management::const_get(capitalized_type))
+          end
+
+          define_method(singular_form) do |oid|
+            @agent.find_by_object_id(Qpid::Management::const_get(capitalized_type), "org.apache.qpid.broker:#{singular_form}:#{oid}")
+          end
+        end
+      end
+
+      # Adds method for the specified types to be able to access the singular
+      # instance of a given type.
+      #
+      # == Example
+      # <tt>has_one :acl</tt> which will add:
+      # * <tt>#acl</tt> to retrieve the Acl data for the Broker
+      #
+      # @param types one or more symbols for the singular objects a broker manages
+      def self.has_one(*types)
+        [*types].each do |type|
+          capitalized_type = type.to_s.gsub(/^\w/) { $&.upcase }
+
+          define_method("#{type}") do
+            @agent.find_first_by_class(Qpid::Management::const_get(capitalized_type))
+          end
+        end
+      end
+
+      has_many :connections, :sessions, :subscriptions, :exchanges, :queues, :bindings, :links, :bridges
+      has_one :acl, :memory
+
+      # Adds an exchange to the broker
+      # @param [String] type exchange type (fanout, direct, topic, headers, xml)
+      # @param [String] name exchange name
+      # @param [Hash] options exchange creation options
+      def add_exchange(type, name, options={})
+        create_broker_object('exchange', name, options.merge!({'exchange-type' => type}))
+      end
+
+      # Deletes an exchange from the broekr
+      # @param [String] name exchange name
+      def delete_exchange(name)
+        invoke_method('delete', {'type' => 'exchange', 'name' => name})
+      end
+
+      # Adds a queue to the broker
+      # @param [String] name queue name
+      # @param [Hash] options queue creation options
+      def add_queue(name, options={})
+        create_broker_object('queue', name, options)
+      end
+
+      # Deletes a queue from the broker
+      # @param [String] name queue name
+      def delete_queue(name)
+        invoke_method('delete', {'type' => 'queue', 'name' => name})
+      end
+
+      # Adds a binding from an exchange to a queue
+      # @param [String] exchange exchange name
+      # @param [String] queue queue name
+      # @param [String] key binding key
+      # @param [Hash] options binding creation options
+      def add_binding(exchange, queue, key="", options={})
+        create_broker_object('binding', "#{exchange}/#{queue}/#{key}", options)
+      end
+
+      # Deletes a binding from an exchange to a queue
+      # @param [String] exchange exchange name
+      # @param [String] queue queue name
+      # @param [String] key binding key
+      def delete_binding(exchange, queue, key="")
+        invoke_method('delete', {'type' => 'binding', 'name' => "#{exchange}/#{queue}/#{key}"})
+      end
+
+      # Adds a link to a remote broker
+      # @param [String] name link name
+      # @param [String] host remote broker host name or IP address
+      # @param [Fixnum] port remote broker port
+      # @param [String] transport transport mechanism used to connect to the remote broker
+      # @param [Boolean] durable should this link be persistent
+      # @param [String] auth_mechanism authentication mechanism to use
+      # @param [String] username user name to authenticate with the remote broker
+      # @param [String] password password for the user name
+      def add_link(name, host, port, transport='tcp', durable=false, auth_mechanism="", username="", password="")
+        options = {
+          'host' => host,
+          'port' => port,
+          'transport' => transport,
+          'durable' => durable,
+          'authMechanism' => auth_mechanism,
+          'username' => username,
+          'password' => password
+        }
+
+        create_broker_object('link', name, options)
+      end
+
+      # Deletes a link to a remote broker
+      # @param [String] name link name
+      def delete_link(name)
+        invoke_method('delete', {'type' => 'link', 'name' => name})
+      end
+
+      # Adds a queue route
+      # @param [String] name the name of the bridge to create
+      # @param [Hash] options options for the queue route
+      # @option options [String] :link the name of the link to use (required)
+      # @option options [String] :queue the name of the source queue from which messages are pulled (required)
+      # @option options [String] :exchange the name of the destination exchange to which messages are sent (required)
+      # @option options [Fixnum] :sync the number of messages to send before issuing an explicit session sync (required)
+      def add_queue_route(name, options={})
+        validate_options(options, [:link, :queue, :exchange, :sync])
+
+        properties = {
+          'link' => options[:link],
+          'src' => options[:queue],
+          'dest' => options[:exchange],
+          'srcIsQueue' => true,
+          'sync' => options[:sync]
+        }
+
+        create_broker_object('bridge', name, properties)
+      end
+
+      # Adds an exchange route
+      # @param [String] name the name of the bridge to create
+      # @param [Hash] options options for the exchange route
+      # @option options [String] :link the name of the link to use (required)
+      # @option options [String] :exchange the name of the exchange to use (required)
+      # @option options [String] :key routing key to federate (required)
+      # @option options [Fixnum] :sync the number of messages to send before issuing an explicit session sync (required)
+      # @option options [String] :bridge_queue name of the queue to use as a bridge queue (optional)
+      def add_exchange_route(name, options={})
+        validate_options(options, [:link, :exchange, :key, :sync])
+
+        properties = {
+          'link' => options[:link],
+          'src' => options[:exchange],
+          'dest' => options[:exchange],
+          'key' => options[:key],
+          'sync' => options[:sync]
+        }
+
+        properties['queue'] = options[:bridge_queue] if options.has_key?(:bridge_queue)
+
+        create_broker_object('bridge', name, properties)
+      end
+
+      # Adds a dynamic route
+      # @param [String] name the name of the bridge to create
+      # @param [Hash] options options for the dynamic route
+      # @option options [String] :link the name of the link to use (required)
+      # @option options [String] :exchange the name of the exchange to use (required)
+      # @option options [Fixnum] :sync the number of messages to send before issuing an explicit session sync (required)
+      # @option options [String] :bridge_queue name of the queue to use as a bridge queue (optional)
+      def add_dynamic_route(name, options={})
+        validate_options(options, [:link, :exchange, :sync])
+
+        properties = {
+          'link' => options[:link],
+          'src' => options[:exchange],
+          'dest' => options[:exchange],
+          'dynamic' => true,
+          'sync' => options[:sync]
+        }
+
+        properties['queue'] = options[:bridge_queue] if options.has_key?(:bridge_queue)
+
+        create_broker_object('bridge', name, properties)
+      end
+
+      # Deletes a bridge (route)
+      # @param [String] name bridge name
+      def delete_bridge(name)
+        invoke_method('delete', {'type' => 'bridge', 'name' => name})
+      end
+
+    private
+
+      def create_broker_object(type, name, options)
+        invoke_method('create', {'type' => type,
+                                 'name' => name,
+                                 'properties' => options,
+                                 'strict' => true})
+      end
+
+      def validate_options(options, required)
+        required.each do |req|
+          raise "Option :#{req.to_s} is required" unless options.has_key?(req)
+        end
+      end
+
+    end
+  end
+end

data/lib/qpid_management/broker_agent.rb

@@ -0,0 +1,173 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+# for simplistic UUID - may want to consider something better in the future
+require 'securerandom'
+
+# Ruby 1.8 doesn't include SecureRandom#uuid, so let's add it if it's missing
+unless SecureRandom.respond_to? :uuid
+  module SecureRandom
+    def self.uuid
+      ary = self.random_bytes(16).unpack("NnnnnN")
+      ary[2] = (ary[2] & 0x0fff) | 0x4000
+      ary[3] = (ary[3] & 0x3fff) | 0x8000
+      "%08x-%04x-%04x-%04x-%04x%08x" % ary
+    end
+  end
+end
+
+module Qpid
+  module Management
+    # This is the primary class that interacts with a Qpid messaging broker for
+    # querying information from the broker and for configuring it.
+    class BrokerAgent
+      # Creates a new BrokerAgent instance. A new Qpid::Messaging::Session,
+      # Qpid::Messaging::Receiver, and Qpid::Messaging::Sender will be created
+      # so this instance of the BrokerAgent may send requests to the broker
+      # and receive replies back.
+      # @param [Qpid::Messaging::Connection] connection a valid, opened connection
+      def initialize(connection)
+        @connection = connection
+        @session = @connection.create_session()
+        @reply_to = "qmf.default.topic/direct.#{SecureRandom.uuid}; {node: {type:topic}, link:{x-declare:{auto-delete:True,exclusive:True}}}"
+        @reply_rx = @session.create_receiver(@reply_to)
+        @reply_rx.capacity = 10
+        @tx = @session.create_sender("qmf.default.direct/broker")
+      end
+
+      # Closes the Qpid::Messaging::Session for this BrokerAgent.
+      def close()
+        @session.close()
+      end
+
+      # Queries the broker for the Broker QMF object.
+      # @return [Broker] the broker QMF object
+      def broker()
+        find_first_by_class(Broker)
+      end
+
+      # Queries the broker for the Cluster QMF object.
+      # @return [Cluster] the cluster QMF object
+      def cluster
+        find_first_by_class(Cluster)
+      end
+
+      # Queries the broker for the HaBroker QMF object.
+      # @return [HaBroker] the HA broker QMF object
+      def ha_broker
+        find_first_by_class(HaBroker)
+      end
+
+      # Invokes a method on a target object.
+      # @param [String] method the name of the method to invoke
+      # @param [Hash] args the arguments to pass to the method
+      # @param [String] addr the full id of the target object
+      # @param [Fixnum] timeout the amount of time to wait for the broker to respond to the method invocation
+      def invoke_method(method, args, addr="org.apache.qpid.broker:broker:amqp-broker", timeout=10)
+        content = {'_object_id' => {'_object_name' => addr},
+                   '_method_name' => method,
+                   '_arguments' => args}
+
+        message = Qpid::Messaging::Message.new()
+        message.content = content
+        message.reply_to = @reply_to
+        message['method'] = 'request'
+        message['qmf.opcode'] = '_method_request'
+        message['x-amqp-0-10.app-id'] = 'qmf2'
+        message.subject = 'broker'
+
+        @tx.send(message)
+
+        response = @reply_rx.fetch(Qpid::Messaging::Duration.new(timeout * 1000))
+        @session.acknowledge()
+
+        raise "Exception from Agent: #{response.content['_values']}" if response.properties['qmf.opcode'] == '_exception'
+        raise "Bad response: #{response.properties}" if response.properties['qmf.opcode'] != '_method_response'
+
+        return response.content['_arguments']
+      end
+
+      def send_query(query)
+        message = Qpid::Messaging::Message.new()
+        message.content = query
+        message.reply_to = @reply_to
+        message['method'] = 'request'
+        message['qmf.opcode'] = '_query_request'
+        message['x-amqp-0-10.app-id'] = 'qmf2'
+        message.subject = 'broker'
+
+        @tx.send(message)
+
+        response = @reply_rx.fetch(Qpid::Messaging::Duration.new(10*1000))
+        @session.acknowledge()
+
+        raise 'Bad response' if response.properties['qmf.opcode'] != '_query_response'
+
+        items = response.content
+
+        while response.properties.has_key?('partial')
+          response = @reply_rx.fetch(Qpid::Messaging::Duration.new(10*1000))
+          items += response.content
+          @session.acknowledge()
+        end
+
+        return items
+      end
+
+      def find_all_by_class(clazz)
+        query = {
+          '_what' => 'OBJECT',
+          '_schema_id' => {
+            '_class_name' => BrokerObject.qmf_class(clazz)
+          }
+        }
+
+        items = send_query(query)
+
+        [].tap do |objs|
+          for item in items
+            objs << clazz.new(self, item)
+          end
+        end
+      end
+
+      def find_first_by_class(clazz)
+        objects = find_all_by_class(clazz)
+        return objects[0] if objects.size > 0
+        return nil
+      end
+
+      def find_by_object_id(clazz, oid)
+        query = {
+          '_what' => 'OBJECT',
+          '_object_id' => {
+            '_object_name' => oid
+          }
+        }
+
+        results = send_query(query)
+
+        return clazz.new(self, results[0]) if results.count == 1 and not results[0].nil?
+
+        # return nil if not found
+        return nil
+      end
+    end
+  end
+end