{ "componentChunkName": "component---src-templates-blog-post-tsx", "path": "/blog/2012-01-16-implementing-a-jenkins-extension-point-with-native-api-in-ruby/", "result": {"data":{"blogPost":{"title":"Implementing a Jenkins Extension Point with the Native Java API inside a Ruby Plugin","slug":"/blog/2012-01-16-implementing-a-jenkins-extension-point-with-native-api-in-ruby/","authorNodes":[{"name":"Charles Lowell","slug":"/people/charles-lowell/"}],"markdown":{"html":"
\n

In which I elaborate why the idomatic Ruby API is sometimes not enough,\nand describe a method to harness the full power of the underlying\nJenkins API while still happily coding your extension in Ruby

\n
\n

The Ruby API

\n

One of the primary goals of the effort to bring Ruby to Jenkins\nis to enable developers to extend Jenkins in a way that looks and\nfeels like a normal Ruby environment. This means using rake, bundler\nERB, and plain old Ruby objects to roll your plugin.

\n

For example, the native BuildStep class is made available through\nthe Ruby BuildStep. They are similar to be sure, but the Ruby\nobject is much less complicated, and actually bears no relation to its\nJava equivalent inside the Java hiearchy of inheritance.

\n

Exposing this simplicity is a worthy goal, but to do so requires\ncareful consideration of each Jenkins Java API and how to provide its\nfunctionality in the Ruby way --no mean feat given the breadth of the\nJenkins.

\n

Sadly, it means that these Ruby-friendly APIs must necessarily lag\nbehind their Java counterparts.

\n

This can be a serious source of frustration for those looking to\ndive into Jenkins Ruby development right now. Initial excitement is\nquickly dulled when you find out that the extension point that you\nwanted to implement is unavailable from Ruby land. You might get\ndiscouraged and feel like you might as well be coding your plugin\nwith Java.

\n

Well don't lose heart! I'd like to share with you a super easy way to\nwrite your extension points in Ruby even when there isn't a friendly\nwrapper. We'll actually implement a very handy extension point called\nRunListener within a Ruby plugin even though it is not part of the\nofficial Ruby API. We'll do it by scripting the Java class directly\nwith JRuby's Java integration feature, and then register it directly\nwith the plugin runtime.

\n

The Extension Point

\n

We'll be working with the Jenkins RunListener interface. This is\na wonderful extension point that allows you to receive callbacks\nat each point during the actual running of a build. There's currently\nno nice ruby API for it, but we won't let that stop us.

\n

First, let's create a new plugin called my-listener. We'll do this\nwith the jpi new command.

\n
legolas:Jenkins cowboyd$ jpi new my-listener\n    create  my-listener/Gemfile\n    create  my-listener/my-listener.pluginspec
\n
\n

Fun fact: 'jpi' is an acronym for (J)enkins (P)lug-(I)n. You can\ninstall the tool with rubygems: gem install jpi

\n
\n

Next, we'll cd into our new plugin and create our listener class\ninside the models/ directory. Jenkins will automatically evaluate\neverything in this directory on plugin initialization.

\n
legolas:Jenkins cowboyd$ cd my-listener/\nlegolas:my-listener cowboyd$ mkdir models\nlegolas:my-listener cowboyd$ touch models/my_listener.rb
\n

Our ultimate goal here is to implement a RunListener, so let's\ngo ahead and start our class definition inside that file.

\n
class MyListener < Java.hudson.model.listeners.RunListener\n  def initialize()\n    super(Java.hudson.model.Run.java_class)\n  end\nend
\n

There's a couple key takeaways here. First, notice that we use\nJRuby integration to extend the class\nhudson.model.listeners.RunListener directly. Second, and this is\na gotcha anytime you extend a Java class: you must invoke one of\nthe Java super constructors if it does not have a default\nconstructor. I can't tell you how many times I've been bitten by this.

\n

In our case, the RunListener class filters which jobs\nit will provide callbacks for by class. By providing a more specific\nclass to the constructor, you limit the scope of jobs you'll receive\nto subclasses of that class. For our purposes, we cast a pretty wide\nnet by selecting all builds via the AbstractBuild Java class.

\n
\n

Pro Tip: when you're implementing a native Java API, it really\nhelps to have the javadoc open in one window so that you\ncan view the documentation and crib from the source

\n
\n

Now that we've got our class defined, let's implement some methods!\nWe'll add callbacks for when a build is started and when it's\ncompleted.

\n
class MyListener < Java.hudson.model.listeners.RunListener\n  def initialize()\n    super(Java.hudson.model.AbstractBuild.java_class)\n  end\n  def onStarted(run, listener)\n    listener.getLogger().println(\"onStarted(#{run})\")\n  end\n  def onCompleted(run, listener)\n    listener.getLogger().println(\"onCompleted(#{run})\")\n  end\nend\nJenkins.plugin.register_extension MyListener.new
\n

And finally, on the last line, we actually inform Jenkins about the\nexistence of our new Listener with the call to\nJenkins.plugin.register_extension

\n

And that's about it. We can start up our test server with our jpi\ntool to see our listener in action.

\n
legolas:my-listener cowboyd$ jpi server\nListening for transport dt_socket at address: 8000\nRunning from: /Users/cowboyd/.rvm/gems/jruby-1.6.5/gems/jenkins-war-1.446/lib/jenkins/jenkins.war\n...\nJan 16, 2012 12:46:15 AM ruby.RubyRuntimePlugin start\nINFO: Injecting JRuby into XStream\nLoading /Users/cowboyd/Projects/Jenkins/my-listener/models/my_listener.rb\nINFO: Prepared all plugins\n...\nINFO: Jenkins is fully up and running
\n

To view the output, create a freestyle build called HelloWorld that\ndoesn't have any build steps at all, build it and view the console\noutput. You should see something like this:

\n
Started by user anonymous\nonStarted(#<Java::HudsonModel::FreeStyleBuild:0x2870068a>)\nonCompleted(#<Java::HudsonModel::FreeStyleBuild:0x2870068a>)\nFinished: SUCCESS
\n

The Sweet Reality

\n

Even though we were dealing more directly with Java, we were\nstill able to use all of the simplicity that comes with developing\nplugins in Ruby. Furthermore, even though our extension point was just\nscripted Java, it doesn't mean that inside its methods it can't call\nas much pure Ruby code as its heart desires.

\n

I hope that if you're considering writing your next (or your first!)\nJenkins plugin in Ruby, you'll feel confident that you can always\nfall back to the native APIs at any point.

","frontmatter":{"date":"January 16, 2012","description":null,"tags":["jenkins","ruby","java"],"img":{"childImageSharp":{"fixed":{"src":"/static/bf4163a654c532fd8669027037560ed5/31987/2012-01-16-implementing-a-jenkins-extension-point-with-native-api-in-ruby-1.png"}}}}}}},"pageContext":{"id":"b1fc7ba8-ccaf-5de7-aa8a-b9f02cd0d71a"}}, "staticQueryHashes": ["1241260443"]}