Merge pull request #74 from drnic/item_listener

Adding ItemListener wrapper

ruby-runtime/lib/jenkins/listeners.rb

@@ -1,4 +1,6 @@
 module Jenkins::Listeners
+  require 'jenkins/listeners/item_listener'
+  require 'jenkins/listeners/item_listener_proxy'
   require 'jenkins/listeners/run_listener'
   require 'jenkins/listeners/run_listener_proxy'
 end

ruby-runtime/lib/jenkins/listeners/item_listener.rb

@@ -0,0 +1,82 @@
+module Jenkins::Listeners
+  # Receives notifications about CRUD operations of Item.
+  #
+  # Include this module in your class in order to receive callbacks
+  # when items are created, copied, updated, deleted, etc...
+  #
+  # To receive a callback, override the method with the same name as
+  # the event. E.g.
+  #
+  #     class MyRunListener
+  #       include Jenkins::Listeners::ItemListener
+  #
+  #       def updated(item)
+  #         puts "#{item.native.inspect} updated!"
+  #       end
+  #     end
+  #
+  # Note: currently the +item+ objects being passed in are OpaqueJavaObject proxies
+  # around Java objects. You must invoke `.native` on them to access the underlying
+  # Java object that you want to interact with.
+  module ItemListener
+    extend Jenkins::Plugin::Behavior
+    include Jenkins::Extension
+
+    implemented do |cls|
+      Jenkins.plugin.register_extension ItemListenerProxy.new(Jenkins.plugin, cls.new)
+    end
+
+    # Called after a new job is created and added to jenkins.model.Jenkins,
+    # before the initial configuration page is provided.
+    # 
+    # This is useful for changing the default initial configuration of newly created jobs.
+    # For example, you can enable/add builders, etc.
+    def created(item)
+    end
+
+    # Called after a new job is created by copying from an existing job.
+    #
+    # For backward compatibility, the default implementation of this method calls onCreated.
+    # If you choose to handle this method, think about whether you want to call super.onCopied or not.
+    #
+    # @param src_item
+    #      The source item that the new one was copied from. Never null.
+    # @param  item
+    #      The newly created item. Never null.
+    def copied(src_item, item)
+    end
+
+    # Called after all the jobs are loaded from disk into jenkins.model.Jenkins
+    # object.
+    def loaded()
+    end
+
+    # Called right before a job is going to be deleted.
+    #
+    # At this point the data files of the job is already gone.
+    def deleted(item)
+    end
+
+    # Called after a job is renamed.
+    #
+    # @param item
+    #      The job being renamed.
+    # @param oldName
+    #      The old name of the job.
+    # @param newName
+    #      The new name of the job. Same as Item#getName().
+    def renamed(item, oldName, newName)
+    end
+
+    # Called after a job has its configuration updated.
+    #
+    # @since 1.460
+    def updated(item)
+    end
+
+    # Called at the begenning of the orderly shutdown sequence to
+    # allow plugins to clean up stuff
+    def before_shutdown()
+    end
+  end
+end

ruby-runtime/lib/jenkins/listeners/item_listener_proxy.rb

@@ -0,0 +1,70 @@
+module Jenkins::Listeners
+  class ItemListenerProxy < Java.hudson.model.listeners.ItemListener
+    include Jenkins::Plugin::Proxy
+
+    def initialize(plugin, object)
+      super(plugin, object)
+    end
+
+    # Called after a new job is created and added to jenkins.model.Jenkins,
+    # before the initial configuration page is provided.
+    # 
+    # This is useful for changing the default initial configuration of newly created jobs.
+    # For example, you can enable/add builders, etc.
+    def onCreated(item)
+      @object.created(import(item))
+    end
+
+    # Called after a new job is created by copying from an existing job.
+    #
+    # For backward compatibility, the default implementation of this method calls onCreated.
+    # If you choose to handle this method, think about whether you want to call super.onCopied or not.
+    #
+    # @param src_item
+    #      The source item that the new one was copied from. Never null.
+    # @param  item
+    #      The newly created item. Never null.
+    def onCopied(src_item, item)
+      @object.copied(import(src_item), import(item));
+    end
+
+    # Called after all the jobs are loaded from disk into jenkins.model.Jenkins
+    # object.
+    def onLoaded()
+      @object.loaded
+    end
+
+    # Called right before a job is going to be deleted.
+    #
+    # At this point the data files of the job is already gone.
+    def onDeleted(item)
+      @object.deleted(import(item))
+    end
+
+    # Called after a job is renamed.
+    #
+    # @param item
+    #      The job being renamed.
+    # @param oldName
+    #      The old name of the job.
+    # @param newName
+    #      The new name of the job. Same as Item#getName().
+    def onRenamed(item, oldName, newName)
+      @object.renamed(import(item), import(oldName), import(newName))
+    end
+
+    # Called after a job has its configuration updated.
+    #
+    # @since 1.460
+    def onUpdated(item)
+      @object.updated(import(item))
+    end
+
+    # Called at the begenning of the orderly shutdown sequence to
+    # allow plugins to clean up stuff
+    def onBeforeShutdown()
+      @object.before_shutdown
+    end
+
+  end
+end

ruby-runtime/spec/jenkins/listeners/item_listener_proxy_spec.rb

@@ -0,0 +1,82 @@
+require 'spec_helper'
+require 'rspec-spies'
+
+describe Jenkins::Listeners::ItemListenerProxy do
+  include ProxyHelper
+  before do
+    @proxy = Jenkins::Listeners::ItemListenerProxy.new(@plugin, @listener)
+    @item = mock
+    @src_item = mock
+  end
+
+  describe "when created" do
+    before do
+      @listener.stub(:created)
+      @proxy.onCreated(@item)
+    end
+    it 'invokes the created callback' do
+      @listener.should have_received(:created).with(@item)
+    end
+  end
+
+
+  describe "when copied" do
+    before do
+      @listener.stub(:copied)
+      @proxy.onCopied(@src_item, @item)
+    end
+    it 'invokes the copied callback' do
+      @listener.should have_received(:copied).with(@src_item, @item)
+    end
+  end
+
+  describe "when loaded" do
+    before do
+      @listener.stub(:loaded)
+      @proxy.onLoaded()
+    end
+    it 'invokes the loaded callback' do
+      @listener.should have_received(:loaded)
+    end
+  end
+
+  describe "when deleted" do
+    before do
+      @listener.stub(:deleted)
+      @proxy.onDeleted(@item)
+    end
+    it 'invokes the deleted callback' do
+      @listener.should have_received(:deleted).with(@item)
+    end
+  end
+
+  describe "when renamed" do
+    before do
+      @listener.stub(:renamed)
+      @proxy.onRenamed(@item, "oldname", "newname")
+    end
+    it 'invokes the renamed callback' do
+      @listener.should have_received(:renamed).with(@item, "oldname", "newname")
+    end
+  end
+
+  describe "when updated" do
+    before do
+      @listener.stub(:updated)
+      @proxy.onUpdated(@item)
+    end
+    it 'invokes the updated callback' do
+      @listener.should have_received(:updated).with(@item)
+    end
+  end
+
+  describe "when before_shutdown" do
+    before do
+      @listener.stub(:before_shutdown)
+      @proxy.onBeforeShutdown()
+    end
+    it 'invokes the before_shutdown callback' do
+      @listener.should have_received(:before_shutdown)
+    end
+  end
+end

ruby-tools/jpi/lib/jenkins/plugin/cli/generate.rb

@@ -49,6 +49,12 @@ def run_listener(name)
           template('templates/run_listener.tt', "models/#{name.downcase}_listener.rb")
         end
 
+        desc "item_listener", "item_listener NAME", :desc => "receive notification of job change events"
+        def item_listener(name)
+          @name = name
+          template('templates/item_listener.tt', "models/#{name.downcase}_listener.rb")
+        end
+
         desc "computer_listener", "computer_listener NAME", :desc => "receive notification of computers events"
         def computer_listener(name)
           @name = name

ruby-tools/jpi/lib/jenkins/plugin/cli/templates/item_listener.tt

@@ -0,0 +1,71 @@
+# Receives notifications about CRUD operations of Items.
+#
+# This class will receive callbacks
+# when items are created, copied, updated, deleted, etc...
+#
+# To receive a callback, override the method with the same name as
+# the event. E.g.
+#
+#     class MyRunListener
+#       include Jenkins::Listeners::ItemListener
+#
+#       def updated(item)
+#         puts "#{item.native.inspect} updated!"
+#       end
+#     end
+#
+# Note: currently the +item+ objects being passed in are OpaqueJavaObject proxies
+# around Java objects. You must invoke `.native` on them to access the underlying
+# Java object that you want to interact with.
+class <%= name.capitalize %>Listener
+  include Jenkins::Listeners::ItemListener
+
+  # Called after a new job is created and added to jenkins.model.Jenkins,
+  # before the initial configuration page is provided.
+  # 
+  # This is useful for changing the default initial configuration of newly created jobs.
+  # For example, you can enable/add builders, etc.
+  def created(item)
+  end
+
+  # Called after a new job is created by copying from an existing job.
+  #
+  # For backward compatibility, the default implementation of this method calls onCreated.
+  # If you choose to handle this method, think about whether you want to call super.onCopied or not.
+  #
+  # @param [Jenkins::Model::Item] The source item that the new one was copied from. Never null.
+  # @param [Jenkins::Model::Item] The newly created item. Never null.
+  def copied(src_item, item)
+  end
+
+  # Called after all the jobs are loaded from disk into jenkins.model.Jenkins
+  # object.
+  def loaded()
+  end
+
+  # Called right before a job is going to be deleted.
+  #
+  # At this point the data files of the job is already gone.
+  # @param [Jenkins::Model::Item] The item being deleted.
+  def deleted(item)
+  end
+
+  # Called after a job is renamed.
+  #
+  # @param [Jenkins::Model::Item] The item being renamed
+  # @param The old name of the job.
+  # @param The new name of the job. Same as Item#getName().
+  def renamed(item, oldName, newName)
+  end
+
+  # Called after a job has its configuration updated.
+  #
+  # @param [Jenkins::Model::Item] The item being updated
+  def updated(item)
+  end
+
+  # Called at the begenning of the orderly shutdown sequence to
+  # allow plugins to clean up stuff
+  def before_shutdown()
+  end
+end