Class: Jenkins::Plugin

Inherits:
Object
  • Object
show all
Defined in:
lib/jenkins/plugin.rb,
lib/jenkins/plugin/proxy.rb,
lib/jenkins/plugin/proxies.rb,
lib/jenkins/plugin/wrapper.rb,
lib/jenkins/plugin/behavior.rb,
lib/jenkins/plugin/specification.rb,
lib/jenkins/plugin/runtime/version.rb

Overview

Acts as the primary gateway between Ruby and Jenkins There is one instance of this object for the entire plugin

On the Java side, it contains a reference to an instance of RubyPlugin. These two objects talk to each other to get things done.

Each running ruby plugin has exactly one instance of ‘Jenkins::Plugin`

Defined Under Namespace

Modules: Behavior, Proxy, Runtime, Wrapper Classes: Lifecycle, OpaqueJavaObject, Proxies, Specification

Constant Summary collapse

ExportError = 
Class.new(StandardError)
ImportError = 
Class.new(StandardError)
SpecificationError = 
Class.new(StandardError)
SpecificationNotFound = 
Class.new(SpecificationError)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(java) ⇒ Plugin

Initializes this plugin by reading the models.rb file. This is a manual registration process Where ruby objects register themselves with the plugin In the future, this process will be automatic, but I haven’t decided the best way to do this yet.

Parameters:

  • java (org.jenkinsci.ruby.RubyPlugin) —

    a native java RubyPlugin



49
50
51
52
53
54
55
 
# File 'lib/jenkins/plugin.rb', line 49

def initialize(java)
  @java = @peer = java
  @start = @stop = proc {}
  @descriptors = {}
  @proxies = Proxies.new(self)
  @on = Lifecycle.new
end

Instance Attribute Details

#descriptors ⇒ Object (readonly)

A list of all the hudson.model.Descriptor objects of which this plugin is aware *indexed by Wrapper class*

This is used so that wrappers can always have a single place to go when they are asked for a descriptor. That way, wrapper instances can always return the descriptor associated with their class.

This may go away.



26
27
28
 
# File 'lib/jenkins/plugin.rb', line 26

def descriptors
  @descriptors
end

#on ⇒ Lifecycle (readonly)

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

Returns:



40
41
42
 
# File 'lib/jenkins/plugin.rb', line 40

def on
  @on
end

#peer ⇒ Object (readonly)

the instance of jenkins.ruby.RubyPlugin with which this Plugin is associated



29
30
31
 
# File 'lib/jenkins/plugin.rb', line 29

def peer
  @peer
end

Class Method Details

.initialize(java) ⇒ Jenkins::Plugin

Initialize the singleton instance that will run for a ruby plugin. This method is designed to be called by the Java side when setting up the ruby plugin

Returns:



61
62
63
64
65
66
 
# File 'lib/jenkins/plugin.rb', line 61

def self.initialize(java)
  #TODO: check for double initialization?!?
  @instance = new(java)
  @instance.load_models
  return @instance
end

.instance ⇒ Jenkins::Plugin

Get the singleton instance associated with this plugin

This is useful when code in the plugin needs to get a reference to the plugin in which it is running e.g.

Jenkins::Plugin.instance #=> the running plugin

Returns:



76
77
78
 
# File 'lib/jenkins/plugin.rb', line 76

def self.instance
  @instance
end

Instance Method Details

#export(object) ⇒ Object

Reflect a native Ruby object into its External Java form.

Delegates to ‘Proxies` for the heavy lifting.

Parameters:

  • object (Object) —

    the object



175
176
177
 
# File 'lib/jenkins/plugin.rb', line 175

def export(object)
  @proxies.export object
end

#import(object) ⇒ Object

Reflect an Java object coming from Jenkins into the context of this plugin If the object is originally from the ruby plugin, and it was previously exported, then it will unwrap it. Otherwise, it will just use the object as a normal Java object.

Parameters:

  • object (Object) —

    the object to bring in from the outside

Returns:

  • the best representation of that object for this plugin



165
166
167
 
# File 'lib/jenkins/plugin.rb', line 165

def import(object)
  @proxies.import object
end

#linkout(internal, external) ⇒ Object

Link a plugin-local Ruby object to an external Java object.

see ‘Proxies#link`

Parameters:

  • internal (Object) —

    the object on the Ruby side of the link

  • external (java.lang.Object) —

    the object on the Java side of the link



185
186
187
 
# File 'lib/jenkins/plugin.rb', line 185

def linkout(internal, external)
  @proxies.linkout internal, external
end

#load_models ⇒ Object

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.



195
196
197
198
199
200
 
# File 'lib/jenkins/plugin.rb', line 195

def load_models
  path = @java.getModelsPath().getPath()
  # TODO: can we access to Jenkins console logger?
  puts "Trying to load models from #{path}"
  load_file_in_dir(path)
end

#name ⇒ Object

unique identifier for this plugin in the Jenkins server



140
141
142
 
# File 'lib/jenkins/plugin.rb', line 140

def name
  @peer.getWrapper().getShortName()
end

#register_describable(describable_class) ⇒ Object

Register a ruby class as a Jenkins extension point of a particular java type

This method is invoked automatically as part of the auto-registration process, and should not need to be invoked by plugin code.

Classes including ‘Describabble` will be autoregistered in this way.

Parameters:

  • describable_class (Class) —

    the class implementing the extension point

See Also:

  • Jenkins::Plugin.[Model[Model::Describable]


129
130
131
132
133
134
135
136
137
 
# File 'lib/jenkins/plugin.rb', line 129

def register_describable(describable_class)
  on.start do
    fail "#{describable_class} is not an instance of Describable" unless describable_class < Model::Describable
    descriptor_class = describable_class.descriptor_is
    descriptor = descriptor_class.new(describable_class, self, describable_class.describe_as_type.java_class)
    @descriptors[describable_class] = descriptor
    register_extension(descriptor)
  end
end

#register_extension(class_or_instance, *args) ⇒ Object

Registers a singleton extension point directly with Jenkins. Extensions registered via this method are different than those registered via ‘register_describable` in that there are only one instance of them, and so things like configuration construction, and validation do not apply.

This method accepts either an instance of the extension point or a class implementing the extension point. If a class is provided, it will attempt to construct an instance with the arguments provided. e.g.

# construct an instance
plugin.register_extension SomeRootAction, "gears.png"
# pass in a preconfigured instance
ext = MyGreatExtension.build do |c|
  c.name "fantastic"
  c.fizzle :foo
end
plugin.register_extension ext

Parameters:

  • extension (Class|Object) —

    the extension to register

  • arguments (...) —

    to pass to



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/jenkins/plugin.rb', line 102

def register_extension(class_or_instance, *args)
  extension = class_or_instance.is_a?(Class) ? class_or_instance.new(*args) : class_or_instance

  # look everywhere for possible ordinal value.
  # extension can be a Java object, or a Proxy to a Ruby object
  ordinal = 0
  if extension.class.respond_to? :order
    ordinal = extension.class.order
  else
    t = import(extension)
    if t.class.respond_to? :order
      ordinal = t.class.order
    end
  end
  @peer.addExtension(export(extension), ordinal)
end

#start ⇒ Object

Called once when Jenkins first initializes this plugin currently does nothing, but plugin startup hooks would go here.



147
148
149
 
# File 'lib/jenkins/plugin.rb', line 147

def start
  @on.fire(:start, self)
end

#stop ⇒ Object

Called one by Jenkins (via RubyPlugin) when this plugin is shut down. Currently this does nothing, but plugin shutdown hooks would go here.



154
155
156
 
# File 'lib/jenkins/plugin.rb', line 154

def stop
  @on.fire(:stop, self)
end