jenkins-plugin-runtime 0.1.0

data/lib/jenkins/plugin/cli.rb

@@ -0,0 +1,20 @@
+
+require 'thor'
+
+module Jenkins
+  module Plugins
+    class CLI < Thor
+
+
+      desc "init", "Create a new Jenkins plugin"
+      def init
+
+      end
+
+      desc "gen", "generate extension boilerplate"
+      def gen
+
+      end
+    end
+  end
+end

data/lib/jenkins/plugin/proxies.rb

@@ -0,0 +1,131 @@
+
+
+module Jenkins
+  class Plugin
+
+    ExportError = Class.new(StandardError)
+    ImportError = Class.new(StandardError)
+
+    # Maps JRuby objects part of the idomatic Ruby API
+    # to a plain Java object representation and vice-versa.
+    #
+    # One of the pillars of Jenkins Ruby plugins is that writing
+    # plugins must "feel" like native Ruby, and not merely like
+    # scripting Java with Ruby. To this end, jenkins-plugins provides
+    # a idiomatic Ruby API that sits on top of the native Jenkins
+    # Java API with which plugin developers can interact.
+    #
+    # This has two consequences. Native Ruby objects authored as part
+    # of the plugin must have a foreign (Java) representation with which
+    # they can wander about the Jenkins universe and possibly interact
+    # with other foreign objects and APIs. Also, Foreign objects
+    # coming in from Jenkins at large should be wrapped, where possible
+    # to present an idomatic interface..
+    #
+    # Finally, Native plugin that had been wrapped and are comping home
+    # must be unwrapped from their external form.
+    #
+    # For all cases, we want to maintain referential integrety so that
+    # the same object always uses the same external form, etc... so
+    # there is one instance of the `Proxies` class per plugin which will
+    # reuse mappings where possible.
+    class Proxies
+
+      def initialize(plugin)
+        @plugin = plugin
+        @int2ext = java.util.WeakHashMap.new
+        @ext2int = java.util.WeakHashMap.new
+      end
+
+      # Reflect a foreign Java object into the context of this plugin.
+      #
+      # If the object is a native plugin object that had been previously
+      # exported, then it will unwrapped.
+      #
+      # Otherwise, we try to choose the best idiomatic API object for
+      # this foreign object
+      #
+      # @param [Object] object the object to bring in from the outside
+      # @return the best representation of that object for this plugin
+      def import(object)
+        if ref = @ext2int[object]
+          return ref.get() if ref.get()
+        end
+        cls = object.class
+        while cls do
+          if internal_class = @@extcls2intcls[cls]
+            internal = internal_class.new(object)
+            link(internal, object)
+            return internal
+          end
+          cls = cls.superclass
+        end
+        raise ImportError, "unable to find suitable representation for #{object.inspect}"
+      end
+
+      # Reflect a native Ruby object into its External Java form.
+      #
+      # Try to find a suitable form for this object and if one is found then decorate it.
+      # @param [Object] object the ruby object that is being exported to Java
+      # @return [java.lang.Object] the Java wrapper that provides an interface to `object`
+      # @throw [ExportError] if no suitable Java representation can be found
+      def export(object)
+        if ref = @int2ext[object]
+          return ref.get() if ref.get()
+        end
+
+        cls = object.class
+        while cls do
+          if proxy_class = @@intcls2extcls[cls]
+            proxy = proxy_class.new(@plugin, object)
+            link(object, proxy)
+            return proxy
+          end
+          cls = cls.superclass
+        end
+        raise ExportError, "unable to find suitable Java Proxy for #{object.inspect}"
+      end
+
+      ##
+      # Link a plugin-local Ruby object to an external Java object such that they will
+      # be subsituted for one another when passing values back and forth between Jenkins
+      # and this plugin. An example of this is associating the Ruby Jenkins::Launcher object
+      # with an equivalent
+      #
+      # @param [Object] internal the object on the Ruby side of the link
+      # @param [java.lang.Object] external the object on the Java side of the link
+      def link(internal, external)
+        @int2ext.put(internal, java.lang.ref.WeakReference.new(external))
+        @ext2int.put(external, java.lang.ref.WeakReference.new(internal))
+      end
+
+      ##
+      # Associated the the Ruby class `internal_class` with the Java class `external_class`.
+      #
+      # Whenever a plugin is importing or exporting an object to the other side, it will first
+      # see if there is an instance already linked. If not, it will try to create the other side
+      # of the link by constructing it via reflection. `register` links two classes together so
+      # that links can be built automatically.
+      #
+      # @param [Class] internal_class the Ruby class
+      # @param [java.lang.Class] external_class the Java class on the othe side of this link.
+      def self.register(internal_class, external_class)
+        @@intcls2extcls[internal_class] = external_class
+        @@extcls2intcls[external_class] = internal_class
+      end
+
+      ##
+      # Remove all class linkages. This is mainly for testing purposes.
+      def self.clear
+        @@intcls2extcls = {}
+        @@extcls2intcls = {}
+      end
+      clear
+    end
+  end
+end
+
+require 'jenkins/model/describable'
+["build_wrapper", "builder"].each do |proxy|
+  require "jenkins/plugin/proxies/#{proxy}"
+end

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

@@ -0,0 +1,50 @@
+
+require 'jenkins/tasks/build_wrapper'
+
+module Jenkins
+  class Plugin
+    class Proxies
+
+      ##
+      # Binds the Java hudson.tasks.BuildWrapper API to the idomatic
+      # Ruby API Jenkins::Tasks::BuildWrapper
+
+      class BuildWrapper < Java.hudson.tasks.BuildWrapper
+        include Java.jenkins.ruby.Get
+        include Jenkins::Plugin::Proxy
+
+        def setUp(build, launcher, listener)
+          env = {}
+          @object.setup(import(build), import(launcher), import(listener), env)
+          EnvironmentWrapper.new(self, @plugin, @object, env)
+        end
+
+        def getDescriptor
+          @plugin.descriptors[@object.class]
+        end
+
+        def get(name)
+          @object.respond_to?(name) ? @object.send(name) : nil
+        end
+
+      end
+
+
+      class EnvironmentWrapper < Java.hudson.tasks.BuildWrapper::Environment
+
+        def initialize(build_wrapper, plugin, impl, env)
+          super(build_wrapper)
+          @plugin = plugin
+          @impl = impl
+          @env = env
+        end
+
+        def tearDown(build, listener)
+          @impl.teardown(@plugin.import(build), @plugin.import(listener), @env)
+        end
+      end
+
+      register Jenkins::Tasks::BuildWrapper, BuildWrapper
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+
+require 'jenkins/tasks/builder'
+
+module Jenkins
+  class Plugin
+    class Proxies
+      class Builder < Java.hudson.tasks.Builder
+        include Jenkins::Plugin::Proxy
+
+        def prebuild(build, launcher, listener)
+          @object.prebuild(import(build), import(launcher), import(listener)) ? true : false
+        end
+
+        def perform(build, launcher, listener)
+          @object.perform(import(build), import(launcher), import(listener)) ? true : false
+        end
+
+      end
+      register Jenkins::Tasks::Builder, Builder
+    end
+  end
+end

data/lib/jenkins/plugin/proxy.rb

@@ -0,0 +1,76 @@
+
+module Jenkins
+  class Plugin
+
+    ##
+    # The Jenkins Ruby API uses "proxies" which are Java subclasses of the native Jenkins
+    # Java API. These proxies provide the mapping between the Java API and the idomatic
+    # Ruby API. Sometimes these mappings can appear convoluted, but it is only so in order to make
+    # the Ruby side as simple and clean as possible.
+    #
+    # This module provides common functionality for all proxies.
+    module Proxy
+      def self.included(mod)
+        super
+        mod.extend(Marshal)
+        mod.send(:include, Unmarshal)
+        mod.send(:include, Customs)
+      end
+
+      # Every Proxy object has a reference to the plugin to which it belongs, as well as the
+      # native Ruby object which it represents.
+      #
+      # @param [Jenkins::Plugin] plugin the plugin from whence this proxy object came
+      # @param [Object] object the implementation to which this proxy will delegate.
+      def initialize(plugin, object)
+        super() if defined? super
+        @plugin, @object = plugin, object
+        @pluginid = @plugin.name
+      end
+
+      # Make sure that proxy classes do not try to persist the plugin parameter.
+      # when serializing this proxy to XStream. It will be reconstructed with
+      # [Unmarshal#read_completed]
+      module Marshal
+
+        # Tell XStream that we never want to persist the @plugin field
+        # @param [String] field name of the field which xstream is enquiring about
+        # @return [Boolean] true if this is the plugin field, otherwise delegate
+        def transient?(field)
+          field.to_s == "plugin" or (super if defined? super)
+        end
+      end
+
+      # Reanimates Proxy objects after their values have been unserialized from XStream
+      module Unmarshal
+
+        # Once the proxy has been unmarshalled from XStream, re-find the plugin
+        # that it is associated with, and use it to populate the @plugin field.
+        # Also, make sure to associate this proxy with the object it represents
+        # so that they remain referentially equivalent.
+        def read_completed
+          @plugin = Java.jenkins.model.Jenkins.getInstance().getPlugin(@pluginid).getNativeRubyPlugin()
+          @plugin.link @object, self
+        end
+
+      end
+
+      ##
+      # Convenience methods for converting from Ruby API to Java API objects and back
+      module Customs
+
+        ##
+        # convert an external Java object into a Ruby friendly object
+        def import(object)
+          @plugin.import(object)
+        end
+
+        ##
+        # convert an internal Ruby object into a Java proxy that is free to roam about Jenkins-land
+        def export(object)
+          @plugin.export(object)
+        end
+      end
+    end
+  end
+end

data/lib/jenkins/plugin/runtime.rb

@@ -0,0 +1,13 @@
+require 'jenkins/plugin'
+require 'jenkins/plugin/runtime/version'
+require 'jenkins/plugin/proxy'
+require 'jenkins/plugin/proxies'
+require 'jenkins/model'
+require 'jenkins/model/action'
+require 'jenkins/model/build'
+require 'jenkins/model/descriptor'
+require 'jenkins/model/listener'
+require 'jenkins/slaves/cloud'
+require 'jenkins/tasks/builder'
+require 'jenkins/tasks/build_wrapper'
+require 'jenkins/launcher'

data/lib/jenkins/plugin/runtime/version.rb

@@ -0,0 +1,7 @@
+module Jenkins
+  class Plugin
+    module Runtime
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/jenkins/slaves/cloud.rb

@@ -0,0 +1,9 @@
+
+module Jenkins
+  module Slaves
+    class Cloud
+      include Jenkins::Model
+
+    end
+  end
+end

data/lib/jenkins/tasks/build_wrapper.rb

@@ -0,0 +1,39 @@
+
+require 'jenkins/model'
+
+module Jenkins
+  module Tasks
+
+    # Decorate a build with pre and post hooks.
+    # {http://javadoc.jenkins-ci.org/hudson/tasks/BuildWrapper.html}
+    class BuildWrapper
+      include Jenkins::Model
+      include Jenkins::Model::Describable
+
+      describe_as Java.hudson.tasks.BuildWrapper
+
+      # Perform setup for a build
+      #
+      # invoked after checkout, but before any `Builder`s have been run
+      # @param [Jenkins::Model::Build] build the build about to run
+      # @param [Jenkins::Launcher] launcher a launcher for the orderly starting/stopping of processes.
+      # @param [Jenkins::Model::Listener] listener channel for interacting with build output console
+      # @param [Hash] env a place to store information needed by #teardown
+      def setup(build, launcher, listener, env)
+
+      end
+
+      # Optionally perform optional teardown for a build
+      #
+      # invoked after a build has run for better or for worse. It's ok if subclasses
+      # don't override this.
+      #
+      # @param [Jenkins::Model::Build] the build which has completed
+      # @param [Jenkins::Model::Listener] listener channel for interacting with build output console
+      # @param [Hash] env contains anything that #setup needs to tell #teardown about
+      def teardown(build, listener, env)
+
+      end
+    end
+  end
+end

data/lib/jenkins/tasks/builder.rb

@@ -0,0 +1,33 @@
+
+module Jenkins
+  module Tasks
+    ##
+    # A single step in the entire build process
+    class Builder
+
+      ##
+      # Runs before the build begins
+      #
+      # @param [Jenkins::Model::Build] build the build which will begin
+      # @param [Jenkins::Launcher] launcher the launcher that can run code on the node running this build
+      # @param [Jenkins::Model::Listener] listener the listener for this build.
+      # @return `true` if this build can continue or `false` if there was an error
+      # and the build needs to be aborted
+      def prebuild(build, launcher, listener)
+
+      end
+
+      ##
+      # Runs the step over the given build and reports the progress to the listener.
+      #
+      # @param [Jenkins::Model::Build] build on which to run this step
+      # @param [Jenkins::Launcher] launcher the launcher that can run code on the node running this build
+      # @param [Jenkins::Model::Listener] listener the listener for this build.
+      # return `true if this build can continue or `false` if there was an error
+      # and the build needs to be aborted
+      def perform(build, launcher, listener)
+
+      end
+    end
+  end
+end

data/spec/jenkins/launcher_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+
+describe Jenkins::Launcher do
+
+  it "can be instantiated" do
+    Jenkins::Launcher.new
+  end
+end

data/spec/jenkins/model/action_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+require 'jenkins/model/action'
+describe Jenkins::Model::Action do
+
+  it "has the same display_name semantics as Model" do
+    a = new_action do
+      display_name "CoolAction"
+    end
+    a.display_name.should eql "CoolAction"
+  end
+
+  describe "its icon_file" do
+    it "is nil by default" do
+      new_action.icon.should be_nil
+    end
+    it "can be configured" do
+      action = new_action do
+        icon "foo.png"
+      end
+      action.new.icon.should == "foo.png"
+    end
+  end
+
+  describe "url_name" do
+    it "can be configured"
+  end
+
+  private
+
+  def new_action(&body)
+    action = Class.new
+    action.send(:include, Jenkins::Model::Action)
+    action.class_eval(&body) if block_given?
+    return action
+  end
+end