jenkins-plugin-runtime 0.1.18 → 0.1.20

data/lib/jenkins/model/build.rb

@@ -7,15 +7,14 @@ module Jenkins
     # all build steps, and can be used to configure, halt, message
     # the current running build.
     class Build
+      include Jenkins::Plugin::Wrapper
+
+      wrapper_for Java.hudson.model.AbstractBuild
 
       # Raised to indicate that a build wrapper halted a build.
       # Raising this does *not* set the build result to error.
       class Halt < Exception; end
 
-
-      # the Hudson::Model::AbstractBuild represented by this build
-      attr_reader :native
-
       # Hash of environment variables that will be added to each process
       # started as part of this build. E.g.
       #
@@ -30,7 +29,7 @@ module Jenkins
       attr_reader :env
 
       def initialize(native)
-        @native = native
+        super(native)
         @variables = {}
         @env = {}
         @native.buildEnvironments.add(EnvironmentVariables.new(@env))

data/lib/jenkins/model/describable.rb

@@ -29,17 +29,29 @@ module Jenkins
     # This class should generally not be needed by plugin authors since it is part of the
     # glue layer and not the public runtime API.
     module Describable
+      extend Plugin::Behavior
       DescribableError = Class.new(StandardError)
 
+      implemented do |cls|
+        Jenkins.plugin.register_describable cls if Jenkins.plugin
+      end
+
       module DescribeAs
+
         # Java class that represents the extension point, which gets eventually set to Descriptor.clazz
         # :with will use this java class as the type of descriptor.
         def describe_as cls, options = {}
           @describe_as_type = verify_java_class(cls).java_class
           @descriptor_is = verify_java_class(options[:with]).java_class if options[:with]
         end
-        attr_reader :describe_as_type
-        attr_reader :descriptor_is
+
+        def describe_as_type
+          @describe_as_type ? @describe_as_type : (superclass.describe_as_type if superclass.respond_to?(:describe_as_type))
+        end
+
+        def descriptor_is
+          @descriptor_is ? @descriptor_is : (superclass.descriptor_is if superclass.respond_to?(:descriptor_is))
+        end
 
         private
 
@@ -51,35 +63,9 @@ module Jenkins
         end
       end
 
-      # When a Describable class is subclassed, make it also Describable
-      module Inherited
-        def inherited(cls)
-          super(cls)
-          cls.extend Inherited
-          describe_as_type = @describe_as_type
-          descriptor_is = @descriptor_is
-          cls.class_eval do
-            @describe_as_type = describe_as_type
-            @descriptor_is = descriptor_is
-          end
-          if Jenkins::Plugin.instance
-            Jenkins::Plugin.instance.register_describable(cls, describe_as_type, descriptor_is)
-          end
-        end
-      end
-
-      module Included
-        def included(mod)
-          super
-          if mod.is_a? Class
-            mod.extend DescribeAs
-            mod.extend Inherited
-          else
-            warn "tried to include Describable into a Module. Are you sure?"
-          end
-        end
+      module ClassMethods
+        include DescribeAs
       end
-      self.extend Included
     end
   end
 end

data/lib/jenkins/model/root_action.rb

@@ -2,8 +2,8 @@ require 'jenkins/model/action'
 
 module Jenkins
   module Model
-    class RootAction < Action
-      include Model
+    class RootAction
+      include Action
     end
   end
 end

data/lib/jenkins/plugin.rb

@@ -28,6 +28,17 @@ module Jenkins
     # the instance of jenkins.ruby.RubyPlugin with which this Plugin is associated
     attr_reader :peer
 
+    # Add listeners for things that might happen to a plugin. E.g.
+    #
+    #     plugin.on.start do |plugin|
+    #       #do some setup
+    #     end
+    #     plugin.on.stop do |plugin|
+    #       #do some teardown
+    #     end
+    # @return [Lifecycle]
+    attr_reader :on
+
     # Initializes this plugin by reading the models.rb
     # file. This is a manual registration process
     # Where ruby objects register themselves with the plugin
@@ -40,6 +51,7 @@ module Jenkins
       @start = @stop = proc {}
       @descriptors = {}
       @proxies = Proxies.new(self)
+      @on = Lifecycle.new
     end
 
     # Initialize the singleton instance that will run for a
@@ -88,7 +100,7 @@ module Jenkins
     # @param [...] arguments to pass to
 
     def register_extension(class_or_instance, *args)
-      extension = class_or_instance.is_a?(Class) ? class_or_instance.new : class_or_instance
+      extension = class_or_instance.is_a?(Class) ? class_or_instance.new(*args) : class_or_instance
       @peer.addExtension(export(extension))
     end
 
@@ -98,15 +110,18 @@ module Jenkins
     # This method is invoked automatically as part of the auto-registration
     # process, and should not need to be invoked by plugin code.
     #
-    # @param [Class] ruby_class the class implementing the extension point
-    # @param [java.lang.Class] describable_class that Jenkins will see this extention point as
-    # @param [Class] descriptor_class that we use to instantiate Descriptor.
-    #                          nil to use the plain-vanilla Descriptor class for those extension points that don't define its own Descriptor type
-    def register_describable(ruby_class, describable_class, descriptor_class = nil)
-      descriptor_class ||= Jenkins::Model::Descriptor
-      descriptor = descriptor_class.new(ruby_class, self, describable_class)
-      @descriptors[ruby_class] = descriptor
-      register_extension(descriptor)
+    # Classes including `Describabble` will be autoregistered in this way.
+    #
+    # @param [Class] describable_class the class implementing the extension point
+    # @see [Model::Describable]
+    def register_describable(describable_class)
+      fail "#{describable_class} is not an instance of Describable" unless describable_class.is_a? Model::Describable
+      on.start do
+        descriptor_class = descriptor_class.descriptor_is || Jenkins::Model::Descriptor
+        descriptor = descriptor_class.new(ruby_class, self, describable_class.describe_as_type)
+        @descriptors[ruby_class] = descriptor
+        register_extension(descriptor)
+      end
     end
 
     # unique identifier for this plugin in the Jenkins server
@@ -118,14 +133,14 @@ module Jenkins
     # currently does nothing, but plugin startup hooks would
     # go here.
     def start
-      @start.call()
+      @on.fire(:start, self)
     end
 
     # Called one by Jenkins (via RubyPlugin) when this plugin
     # is shut down. Currently this does nothing, but plugin
     # shutdown hooks would go here.
     def stop
-      @stop.call()
+      @on.fire(:stop, self)
     end
 
     # Reflect an Java object coming from Jenkins into the context of this plugin
@@ -159,6 +174,12 @@ module Jenkins
       @proxies.linkout internal, external
     end
 
+    # Load all of the Ruby code associated with this plugin. For
+    # historical purposes this is called "models", but really
+    # it should be something like extensions ext/ or maybe it's
+    # just one file associated with the plugin itself. Who knows?
+    # The jury is definitely still out on the best way to discover
+    # and load extension points.
     def load_models
       path = @java.getModelsPath().getPath()
       # TODO: can we access to Jenkins console logger?
@@ -191,6 +212,34 @@ module Jenkins
         load_file_in_dir(dir)
       end
     end
+
+    class Lifecycle
+      def initialize
+        @start = []
+        @stop = []
+      end
+
+      def start(&block)
+        @start << block if block
+      end
+
+      def stop(&block)
+        @stop << block if block
+      end
+
+      def fire(event, *args)
+        if listeners = instance_variable_get("@#{event}")
+          listeners.each do |l|
+            callback(l, *args)
+          end
+        end
+      end
+      def callback(listener, *args)
+        listener.call(*args)
+      rescue Exception => e
+        $stderr.warn "#{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
+      end
+    end
   end
 
   # Make the singleton instance available from the top-level

data/lib/jenkins/plugin/behavior.rb

@@ -0,0 +1,96 @@
+require 'set'
+
+module Jenkins
+  class Plugin
+    # A Behavior will receive a callback any time that it is
+    # included into a class or when a class that has been included
+    # is extended. This is needed for a couple reasons.
+    #
+    # One case is to enable Transient marking behavior. Every
+    # time a concrete model class is implemented, it needs the
+    # ability to define which of its attributes are transient,
+    # so that they will not be persisted with the Jenkins serialization.
+    # which attributes are tracked on a per-class basis, so we
+    # need a callback for each class in the inheritance hierachy.
+    #
+    # class Foo
+    #  include Model
+    #  transient :foo do
+    #    @foo = 1 + 2
+    #  end
+    # end
+    # class Bar < Foo
+    #   transient :bar do # <- no need to include Model
+    #     @bar = create_bar
+    #   end
+    # end
+    #
+    # Another is the case of auto registration. We want to be able
+    # to find out when extension points are implemented, and register
+    # them with the Jenkins Runtime
+    #
+    # module Descriptor
+    #   implemented do |cls|
+    #     Jenkins.plugin.on.start do |plugin|
+    #       plugin.register_extension new(Jenkins.plugin, cls.ruby_type, cls.java_type)
+    #     end
+    #   end
+    # end
+    # And of course, there is the case of proxies where we need to make sure that
+    # certain behaviors are always included into the proxy, and that if java classes
+    # need to be implemented, they are.
+    module Behavior
+      def included(mod)
+        if mod.is_a? Class
+          mod.extend Implementation unless mod.is_a? Implementation
+        else
+          mod.extend Behavior unless mod.is_a? Behavior
+        end
+        mod.behaves_as *@_behaviors
+        super(mod)
+      end
+
+      def implemented(cls = nil, &implemented_block)
+        if cls
+          @implemented_block.call cls if @implemented_block
+        else
+          @implemented_block = implemented_block
+        end
+      end
+
+      def self.extended(mod)
+        super(mod)
+        mod.instance_eval do
+          @_behaviors = Set.new([self])
+        end
+      end
+
+      module BehavesAs
+        def behaves_as(*behaviors)
+          @_behaviors ||= Set.new
+          behaviors.each do |b|
+            unless @_behaviors.include? b
+              b.implemented self if self.is_a? Class
+              self.extend b::ClassMethods if b.const_defined? :ClassMethods
+              self.send(:include, b::InstanceMethods) if b.const_defined? :InstanceMethods
+              @_behaviors << b
+            end
+          end
+          return @_behaviors
+        end
+      end
+      include BehavesAs
+
+      module Implementation
+        include BehavesAs
+
+        def inherited(cls)
+          super.tap do
+            cls.extend Implementation unless cls.is_a? Implementation
+            cls.behaves_as *@_behaviors
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jenkins/plugin/proxies.rb

@@ -175,3 +175,7 @@ require 'jenkins/model/describable'
 ["action", "build_wrapper", "builder", "publisher", "root_action"].each do |proxy|
   require "jenkins/plugin/proxies/#{proxy}"
 end
+
+["cli/command"].each do |proxy|
+  require "jenkins/#{proxy}_proxy"
+end

data/lib/jenkins/plugin/proxies/action.rb

@@ -4,11 +4,17 @@ require 'jenkins/plugin/proxies/describable'
 module Jenkins
   class Plugin
     class Proxies
-      class Action
-        include Java.hudson.model.Action
-        include Java.jenkins.ruby.Get
+      module Action
         include Jenkins::Plugin::Proxy
-        include Jenkins::Plugin::Proxies::Describable
+        implemented do |cls|
+          cls.class_eval do
+            include Java.hudson.model.Action
+          end
+        end
+
+        def getDisplayName
+          @object.display_name
+        end
 
         def getIconFileName
           @object.icon
@@ -18,8 +24,6 @@ module Jenkins
           @object.url_path
         end
       end
-
-      register Jenkins::Model::Action, Action
     end
   end
 end

data/lib/jenkins/plugin/proxies/build_step.rb

@@ -2,6 +2,7 @@ module Jenkins
   class Plugin
     class Proxies
       module BuildStep
+        include Describable
         def prebuild(build, listener)
           boolean_result(listener) do
             @object.prebuild(import(build), import(listener))

data/lib/jenkins/plugin/proxies/build_wrapper.rb

@@ -11,9 +11,8 @@ module Jenkins
       # Ruby API Jenkins::Tasks::BuildWrapper
 
       class BuildWrapper < Java.hudson.tasks.BuildWrapper
-        include Jenkins::Plugin::Proxies::Describable
-        include Java.jenkins.ruby.Get
-        include Jenkins::Plugin::Proxy
+        include Describable
+        proxy_for Jenkins::Tasks::BuildWrapper
 
         def setUp(build, launcher, listener)
           @object.setup(import(build), import(launcher), import(listener))
@@ -45,8 +44,6 @@ module Jenkins
           false
         end
       end
-
-      register Jenkins::Tasks::BuildWrapper, BuildWrapper
     end
   end
 end

data/lib/jenkins/plugin/proxies/builder.rb

@@ -5,13 +5,9 @@ module Jenkins
   class Plugin
     class Proxies
       class Builder < Java.hudson.tasks.Builder
-        include Jenkins::Plugin::Proxies::Describable
-        include Java.jenkins.ruby.Get
-        include Jenkins::Plugin::Proxy
         include BuildStep
+        proxy_for Jenkins::Tasks::Builder
       end
-
-      register Jenkins::Tasks::Builder, Builder
     end
   end
 end

data/lib/jenkins/plugin/proxies/describable.rb

@@ -4,6 +4,12 @@ module Jenkins
       # mix-in on top of the subtypes of the Describable Java class
       # to add standard behaviour as a proxy to Ruby object
       module Describable
+        include Jenkins::Plugin::Proxy
+        implemented do |cls|
+          cls.class_eval do
+            include Java.jenkins.ruby.Get
+          end
+        end
         def getDescriptor
           @plugin.descriptors[@object.class]
         end

data/lib/jenkins/plugin/proxies/publisher.rb

@@ -5,13 +5,9 @@ module Jenkins
   class Plugin
     class Proxies
       class Publisher < Java.hudson.tasks.Publisher
-        include Jenkins::Plugin::Proxies::Describable
-        include Java.jenkins.ruby.Get
-        include Jenkins::Plugin::Proxy
         include BuildStep
+        proxy_for Jenkins::Tasks::Publisher
       end
-
-      register Jenkins::Tasks::Publisher, Publisher
     end
   end
 end

data/lib/jenkins/plugin/proxies/root_action.rb

@@ -4,25 +4,10 @@ module Jenkins
   class Plugin
     class Proxies
       class RootAction
+        include Action
         include Java.hudson.model.RootAction
-        include Java.jenkins.ruby.Get
-        include Jenkins::Plugin::Proxy
-        include Jenkins::Plugin::Proxies::Describable
-
-        def getDisplayName
-          @object.display_name
-        end
-
-        def getIconFileName
-          @object.icon
-        end
-
-        def getUrlName
-          @object.url_path
-        end
+        proxy_for Jenkins::Model::RootAction
       end
-
-      register Jenkins::Model::RootAction, RootAction
     end
   end
 end