Class: Puppet::Indirector::Indirection
- Includes:
- Util::Docs, Util::MethodHelper
- Defined in:
- lib/puppet/indirector/indirection.rb
Overview
The class that connects functional classes with their different collection back-ends. Each indirection has a set of associated terminus classes, each of which is a subclass of Puppet::Indirector::Terminus.
Constant Summary collapse
- @@indirections =
[]
Constants included from Util::Docs
Instance Attribute Summary collapse
-
#cache_class ⇒ Object
Returns the value of attribute cache_class.
-
#model ⇒ Object
Returns the value of attribute model.
-
#name ⇒ Object
Returns the value of attribute name.
-
#termini ⇒ Object
readonly
Returns the value of attribute termini.
-
#terminus_setting ⇒ Object
This can be used to select the terminus class.
Attributes included from Util::Docs
Class Method Summary collapse
-
.instance(name) ⇒ Object
Find an indirection by name.
-
.instances ⇒ Object
Return a list of all known indirections.
-
.model(name) ⇒ Object
Find an indirected model by name.
Instance Method Summary collapse
- #allow_remote_requests? ⇒ Boolean
-
#cache ⇒ Object
Create and return our cache terminus.
-
#cache? ⇒ Boolean
Should we use a cache?.
-
#delete ⇒ Object
This is only used for testing.
-
#destroy(key, options = {}) ⇒ Object
Remove something via the terminus.
-
#doc ⇒ Object
Generate the full doc string.
-
#expiration ⇒ Object
Calculate the expiration date for a returned instance.
-
#expire(key, options = {}) ⇒ Object
Expire a cached object, if one is cached.
-
#find(key, options = {}) ⇒ Object
Search for an instance in the appropriate terminus, caching the results if caching is configured..
- #find_in_cache(request) ⇒ Object
-
#head(key, options = {}) ⇒ Object
Search for an instance in the appropriate terminus, and return a boolean indicating whether the instance was found.
-
#initialize(model, name, options = {}) ⇒ Indirection
constructor
A new instance of Indirection.
-
#request(*args) ⇒ Object
Set up our request object.
- #reset_terminus_class ⇒ Object
-
#save(instance, key = nil, options = {}) ⇒ Object
Save the instance in the appropriate terminus.
-
#search(key, options = {}) ⇒ Object
Search for more than one instance.
-
#terminus(terminus_name = nil) ⇒ Object
Return the singleton terminus for this indirection.
-
#terminus_class ⇒ Object
Determine the terminus class.
-
#terminus_class=(klass) ⇒ Object
Specify the terminus class to use.
-
#ttl ⇒ Object
Default to the runinterval for the ttl.
-
#ttl=(value) ⇒ Object
Set the time-to-live for instances created through this indirection.
-
#validate_terminus_class(terminus_class) ⇒ Object
This is used by terminus_class= and cache=.
Methods included from Util::Docs
#desc, #dochook, #doctable, #markdown_definitionlist, #markdown_header, #nodoc?, #pad, scrub
Methods included from Util::MethodHelper
#requiredopts, #set_options, #symbolize_options
Constructor Details
#initialize(model, name, options = {}) ⇒ Indirection
Returns a new instance of Indirection.
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 |
# File 'lib/puppet/indirector/indirection.rb', line 92 def initialize(model, name, = {}) @model = model @name = name @termini = {} @cache_class = nil @terminus_class = nil raise(ArgumentError, "Indirection #{@name} is already defined") if @@indirections.find { |i| i.name == @name } @@indirections << self @indirected_class = .delete(:indirected_class) if mod = [:extend] extend(mod) .delete(:extend) end # This is currently only used for cache_class and terminus_class. () end |
Instance Attribute Details
#cache_class ⇒ Object
Returns the value of attribute cache_class.
49 50 51 |
# File 'lib/puppet/indirector/indirection.rb', line 49 def cache_class @cache_class end |
#model ⇒ Object
Returns the value of attribute model.
14 15 16 |
# File 'lib/puppet/indirector/indirection.rb', line 14 def model @model end |
#name ⇒ Object
Returns the value of attribute name.
14 15 16 |
# File 'lib/puppet/indirector/indirection.rb', line 14 def name @name end |
#termini ⇒ Object (readonly)
Returns the value of attribute termini.
15 16 17 |
# File 'lib/puppet/indirector/indirection.rb', line 15 def termini @termini end |
#terminus_setting ⇒ Object
This can be used to select the terminus class.
127 128 129 |
# File 'lib/puppet/indirector/indirection.rb', line 127 def terminus_setting @terminus_setting end |
Class Method Details
.instance(name) ⇒ Object
Find an indirection by name. This is provided so that Terminus classes can specifically hook up with the indirections they are associated with.
21 22 23 |
# File 'lib/puppet/indirector/indirection.rb', line 21 def self.instance(name) @@indirections.find { |i| i.name == name } end |
.instances ⇒ Object
Return a list of all known indirections. Used to generate the reference.
27 28 29 |
# File 'lib/puppet/indirector/indirection.rb', line 27 def self.instances @@indirections.collect { |i| i.name } end |
.model(name) ⇒ Object
Find an indirected model by name. This is provided so that Terminus classes can specifically hook up with the indirections they are associated with.
33 34 35 36 |
# File 'lib/puppet/indirector/indirection.rb', line 33 def self.model(name) return nil unless match = @@indirections.find { |i| i.name == name } match.model end |
Instance Method Details
#allow_remote_requests? ⇒ Boolean
177 178 179 |
# File 'lib/puppet/indirector/indirection.rb', line 177 def allow_remote_requests? terminus.allow_remote_requests? end |
#cache ⇒ Object
Create and return our cache terminus.
39 40 41 42 |
# File 'lib/puppet/indirector/indirection.rb', line 39 def cache raise(Puppet::DevError, "Tried to cache when no cache class was set") unless cache_class terminus(cache_class) end |
#cache? ⇒ Boolean
Should we use a cache?
45 46 47 |
# File 'lib/puppet/indirector/indirection.rb', line 45 def cache? cache_class ? true : false end |
#delete ⇒ Object
This is only used for testing.
57 58 59 |
# File 'lib/puppet/indirector/indirection.rb', line 57 def delete @@indirections.delete(self) if @@indirections.include?(self) end |
#destroy(key, options = {}) ⇒ Object
Remove something via the terminus.
251 252 253 254 255 256 257 258 259 260 261 262 263 |
# File 'lib/puppet/indirector/indirection.rb', line 251 def destroy(key, ={}) request = request(:destroy, key, nil, ) terminus = prepare(request) result = terminus.destroy(request) if cache? and cache.find(request(:find, key, nil, )) # Reuse the existing request, since it's equivalent. cache.destroy(request) end result end |
#doc ⇒ Object
Generate the full doc string.
79 80 81 82 83 84 85 86 87 88 89 90 |
# File 'lib/puppet/indirector/indirection.rb', line 79 def doc text = "" text << scrub(@doc) << "\n\n" if @doc text << "* **Indirected Class**: `#{@indirected_class}`\n"; if terminus_setting text << "* **Terminus Setting**: #{terminus_setting}\n" end text end |
#expiration ⇒ Object
Calculate the expiration date for a returned instance.
74 75 76 |
# File 'lib/puppet/indirector/indirection.rb', line 74 def expiration Time.now + ttl end |
#expire(key, options = {}) ⇒ Object
Expire a cached object, if one is cached. Note that we don’t actually remove it, we expire it and write it back out to disk. This way people can still use the expired object if they want.
162 163 164 165 166 167 168 169 170 171 172 173 174 175 |
# File 'lib/puppet/indirector/indirection.rb', line 162 def expire(key, ={}) request = request(:expire, key, nil, ) return nil unless cache? return nil unless instance = cache.find(request(:find, key, nil, )) Puppet.info _("Expiring the %{cache} cache of %{instance}") % { cache: self.name, instance: instance.name } # Set an expiration date in the past instance.expiration = Time.now - 60 cache.save(request(:save, nil, instance, )) end |
#find(key, options = {}) ⇒ Object
Search for an instance in the appropriate terminus, caching the results if caching is configured..
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 |
# File 'lib/puppet/indirector/indirection.rb', line 183 def find(key, ={}) request = request(:find, key, nil, ) terminus = prepare(request) result = find_in_cache(request) if not result.nil? result elsif request.ignore_terminus? nil else # Otherwise, return the result from the terminus, caching if # appropriate. result = terminus.find(request) if not result.nil? result.expiration ||= self.expiration if result.respond_to?(:expiration) if cache? Puppet.info _("Caching %{indirection} for %{request}") % { indirection: self.name, request: request.key } begin cache.save request(:save, key, result, ) rescue => detail Puppet.log_exception(detail) raise detail end end filtered = result if terminus.respond_to?(:filter) Puppet::Util::Profiler.profile(_("Filtered result for %{indirection} %{request}") % { indirection: self.name, request: request.key }, [:indirector, :filter, self.name, request.key]) do begin filtered = terminus.filter(result) rescue Puppet::Error => detail Puppet.log_exception(detail) raise detail end end end filtered end end end |
#find_in_cache(request) ⇒ Object
235 236 237 238 239 240 241 242 243 244 245 246 247 248 |
# File 'lib/puppet/indirector/indirection.rb', line 235 def find_in_cache(request) # See if our instance is in the cache and up to date. return nil unless cache? and ! request.ignore_cache? and cached = cache.find(request) if cached.expired? Puppet.info _("Not using expired %{indirection} for %{request} from cache; expired at %{expiration}") % { indirection: self.name, request: request.key, expiration: cached.expiration } return nil end Puppet.debug "Using cached #{self.name} for #{request.key}" cached rescue => detail Puppet.log_exception(detail, _("Cached %{indirection} for %{request} failed: %{detail}") % { indirection: self.name, request: request.key, detail: detail }) nil end |
#head(key, options = {}) ⇒ Object
Search for an instance in the appropriate terminus, and return a boolean indicating whether the instance was found.
226 227 228 229 230 231 232 233 |
# File 'lib/puppet/indirector/indirection.rb', line 226 def head(key, ={}) request = request(:head, key, nil, ) terminus = prepare(request) # Look in the cache first, then in the terminus. Force the result # to be a boolean. !!(find_in_cache(request) || terminus.head(request)) end |
#request(*args) ⇒ Object
Set up our request object.
114 115 116 |
# File 'lib/puppet/indirector/indirection.rb', line 114 def request(*args) Puppet::Indirector::Request.new(self.name, *args) end |
#reset_terminus_class ⇒ Object
141 142 143 |
# File 'lib/puppet/indirector/indirection.rb', line 141 def reset_terminus_class @terminus_class = nil end |
#save(instance, key = nil, options = {}) ⇒ Object
Save the instance in the appropriate terminus. This method is normally an instance method on the indirected class.
282 283 284 285 286 287 288 289 290 291 292 |
# File 'lib/puppet/indirector/indirection.rb', line 282 def save(instance, key = nil, ={}) request = request(:save, key, instance, ) terminus = prepare(request) result = terminus.save(request) # If caching is enabled, save our document there cache.save(request) if cache? result end |
#search(key, options = {}) ⇒ Object
Search for more than one instance. Should always return an array.
266 267 268 269 270 271 272 273 274 275 276 277 278 |
# File 'lib/puppet/indirector/indirection.rb', line 266 def search(key, ={}) request = request(:search, key, nil, ) terminus = prepare(request) if result = terminus.search(request) raise Puppet::DevError, "Search results from terminus #{terminus.name} are not an array" unless result.is_a?(Array) result.each do |instance| next unless instance.respond_to? :expiration instance.expiration ||= self.expiration end return result end end |
#terminus(terminus_name = nil) ⇒ Object
Return the singleton terminus for this indirection.
119 120 121 122 123 124 |
# File 'lib/puppet/indirector/indirection.rb', line 119 def terminus(terminus_name = nil) # Get the name of the terminus. raise Puppet::DevError, "No terminus specified for #{self.name}; cannot redirect" unless terminus_name ||= terminus_class termini[terminus_name] ||= make_terminus(terminus_name) end |
#terminus_class ⇒ Object
Determine the terminus class.
130 131 132 133 134 135 136 137 138 139 |
# File 'lib/puppet/indirector/indirection.rb', line 130 def terminus_class unless @terminus_class if setting = self.terminus_setting self.terminus_class = Puppet.settings[setting] else raise Puppet::DevError, "No terminus class nor terminus setting was provided for indirection #{self.name}" end end @terminus_class end |
#terminus_class=(klass) ⇒ Object
Specify the terminus class to use.
146 147 148 149 |
# File 'lib/puppet/indirector/indirection.rb', line 146 def terminus_class=(klass) validate_terminus_class(klass) @terminus_class = klass end |
#ttl ⇒ Object
Default to the runinterval for the ttl.
69 70 71 |
# File 'lib/puppet/indirector/indirection.rb', line 69 def ttl @ttl ||= Puppet[:runinterval] end |
#ttl=(value) ⇒ Object
Set the time-to-live for instances created through this indirection.
62 63 64 65 66 |
# File 'lib/puppet/indirector/indirection.rb', line 62 def ttl=(value) #TRANSLATORS "TTL" stands for "time to live" and refers to a duration of time raise ArgumentError, _("Indirection TTL must be an integer") unless value.is_a?(Integer) @ttl = value end |
#validate_terminus_class(terminus_class) ⇒ Object
This is used by terminus_class= and cache=.
152 153 154 155 156 157 |
# File 'lib/puppet/indirector/indirection.rb', line 152 def validate_terminus_class(terminus_class) raise ArgumentError, "Invalid terminus name #{terminus_class.inspect}" unless terminus_class and terminus_class.to_s != "" unless Puppet::Indirector::Terminus.terminus_class(self.name, terminus_class) raise ArgumentError, "Could not find terminus #{terminus_class} for indirection #{self.name}" end end |