# class Chef::Resource

### Constants

FORBIDDEN_IVARS
HIDDEN_IVARS
SmartOSPackage

  Backwards compatability @todo remove in Chef 12

### Attributes

allowed_actions[RW]
cookbook_name[RW]
elapsed_time[R]
enclosing_provider[RW]
not_if_args[R]
only_if_args[R]
params[RW]
provider[RW]
recipe_name[RW]
resource_name[R]
retries[RW]
retry_delay[RW]
run_context[RW]
source_line[RW]
updated[R]

### Public Class Methods

dsl_name() click to toggle source

    # File lib/chef/resource.rb, line 209
    def self.dsl_name
      convert_to_snake_case(name, 'Chef::Resource')
    end

find_subclass_by_name(class_name) click to toggle source

Look up a subclass by `class_name` which should be a string that matches `Subclass.name`

    # File lib/chef/resource.rb, line 163
    def self.find_subclass_by_name(class_name)
      resource_classes.first {|c| c.name == class_name }
    end

identity_attr(attr_name=nil) click to toggle source

Set or return the “identity attribute” for this resource class. This is generally going to be the “name attribute” for this resource. In other words, the resource type plus this attribute uniquely identify a given bit of state that chef manages. For a File resource, this would be the path, for a package resource, it will be the package name. This will show up in chef-client’s audit records as a searchable field.

    # File lib/chef/resource.rb, line 197
    def self.identity_attr(attr_name=nil)
      @identity_attr ||= nil
      @identity_attr = attr_name if attr_name

      # If this class doesn't have an identity attr, we'll defer to the superclass:
      if @identity_attr || !superclass.respond_to?(:identity_attr)
        @identity_attr
      else
        superclass.identity_attr
      end
    end

inherited(subclass) click to toggle source

Callback when subclass is defined. Adds subclass to list of subclasses.

    # File lib/chef/resource.rb, line 157
    def self.inherited(subclass)
      resource_classes << subclass
    end

json_create(o) click to toggle source

    # File lib/chef/resource.rb, line 722
    def self.json_create(o)
      resource = self.new(o["instance_vars"]["@name"])
      o["instance_vars"].each do |k,v|
        resource.instance_variable_set("@#{k}".to_sym, v)
      end
      resource
    end

new(name, run_context=nil) click to toggle source

Each notify entry is a resource/action pair, modeled as an Struct with a resource and action member

    # File lib/chef/resource.rb, line 235
    def initialize(name, run_context=nil)
      @name = name
      @run_context = run_context
      @noop = nil
      @before = nil
      @params = Hash.new
      @provider = nil
      @allowed_actions = [ :nothing ]
      @action = :nothing
      @updated = false
      @updated_by_last_action = false
      @supports = {}
      @ignore_failure = false
      @retries = 0
      @retry_delay = 2
      @not_if = []
      @only_if = []
      @source_line = nil
      @guard_interpreter = :default
      @elapsed_time = 0

      @node = run_context ? deprecated_ivar(run_context.node, :node, :warn) : nil
    end

platform_map() click to toggle source

    # File lib/chef/resource.rb, line 747
    def self.platform_map
      @@platform_map ||= PlatformMap.new
    end

provider_base(arg=nil) click to toggle source

Resources that want providers namespaced somewhere other than Chef::Provider can set the namespace with `provider_base` Ex:

    class MyResource < Chef::Resource
      provider_base Chef::Provider::Deploy
      # ...other stuff
    end

    # File lib/chef/resource.rb, line 742
    def self.provider_base(arg=nil)
      @provider_base ||= arg
      @provider_base ||= Chef::Provider
    end

provides(short_name, opts={}) click to toggle source

Maps a short_name (and optionally a platform and version) to a Chef::Resource. This allows finer grained per platform resource attributes and the end of overloaded resource definitions (I’m looking at you Chef::Resource::Package) Ex:

    class WindowsFile < Chef::Resource
      provides :file, :on_platforms => ["windows"]
      # ...other stuff
    end

TODO: 2011-11-02 schisamo - platform_version support

    # File lib/chef/resource.rb, line 762
    def self.provides(short_name, opts={})
      short_name_sym = short_name
      if short_name.kind_of?(String)
        short_name.downcase!
        short_name.gsub!(/\s/, "_")
        short_name_sym = short_name.to_sym
      end
      if opts.has_key?(:on_platforms)
        platforms = [opts[:on_platforms]].flatten
        platforms.each do |p|
          p = :default if :all == p.to_sym
          platform_map.set(
            :platform => p.to_sym,
            :short_name => short_name_sym,
            :resource => self
          )
        end
      else
        platform_map.set(
          :short_name => short_name_sym,
          :resource => self
        )
      end
    end

resource_classes() click to toggle source

Track all subclasses of Resource. This is used so names can be looked up when attempting to deserialize from JSON. (See: json_compat)

    # File lib/chef/resource.rb, line 149
    def self.resource_classes
      # Using a class variable here ensures we have one variable to track
      # subclasses shared by the entire class hierarchy; without this, each
      # subclass would have its own list of subclasses.
      @@resource_classes ||= []
    end

resource_for_node(short_name, node) click to toggle source

Returns a resource based on a short_name and a node’s platform and version.

#### Parameters¶ ↑

short_name<Symbol>

  short_name of the resource (ie :directory)

node<Chef::Node>

  Node object to look up platform and version in

### Returns¶ ↑

<Chef::Resource>

  returns the proper Chef::Resource class

    # File lib/chef/resource.rb, line 810
    def self.resource_for_node(short_name, node)
      begin
        platform, version = Chef::Platform.find_platform_and_version(node)
      rescue ArgumentError
      end
      resource = resource_for_platform(short_name, platform, version)
      resource
    end

resource_for_platform(short_name, platform=nil, version=nil) click to toggle source

Returns a resource based on a short_name anda platform and version.

#### Parameters¶ ↑

short_name<Symbol>

  short_name of the resource (ie :directory)

platform<Symbol,String>

  platform name

version<String>

  platform version

### Returns¶ ↑

<Chef::Resource>

  returns the proper Chef::Resource class

    # File lib/chef/resource.rb, line 797
    def self.resource_for_platform(short_name, platform=nil, version=nil)
      platform_map.get(short_name, platform, version)
    end

state_attrs(*attr_names) click to toggle source

Set or return the list of “state attributes” implemented by the Resource subclass. State attributes are attributes that describe the desired state of the system, such as file permissions or ownership. In general, state attributes are attributes that could be populated by examining the state of the system (e.g., File.stat can tell you the permissions on an existing file). Contrarily, attributes that are not “state attributes” usually modify the way Chef itself behaves, for example by providing additional options for a package manager to use when installing a package.

This list is used by the Chef client auditing system to extract information from resources to describe changes made to the system.

    # File lib/chef/resource.rb, line 179
    def self.state_attrs(*attr_names)
      @state_attrs ||= []
      @state_attrs = attr_names unless attr_names.empty?

      # Return *all* state_attrs that this class has, including inherited ones
      if superclass.respond_to?(:state_attrs)
        superclass.state_attrs + @state_attrs
      else
        @state_attrs
      end
    end

strict_const_defined?(const) click to toggle source

    # File lib/chef/resource.rb, line 138
    def self.strict_const_defined?(const)
      const_defined?(const)
    end

### Public Instance Methods

action(arg=nil) click to toggle source

    # File lib/chef/resource.rb, line 342
    def action(arg=nil)
      if arg
        action_list = arg.kind_of?(Array) ? arg : [ arg ]
        action_list = action_list.collect { |a| a.to_sym }
        action_list.each do |action|
          validate(
            {
              :action => action,
            },
            {
              :action => { :kind_of => Symbol, :equal_to => @allowed_actions },
            }
          )
        end
        @action = action_list
      else
        @action
      end
    end

after_created() click to toggle source

Hook to allow a resource to run specific code after creation

    # File lib/chef/resource.rb, line 731
    def after_created
      nil
    end

as_json(*a) click to toggle source

#as_json does most of the #to_json heavy lifted. It exists here in case activesupport is loaded. activesupport will call #as_json and skip over to_json. This ensure json is encoded as expected

    # File lib/chef/resource.rb, line 521
    def as_json(*a)
      safe_ivars = instance_variables.map { |ivar| ivar.to_sym } - FORBIDDEN_IVARS
      instance_vars = Hash.new
      safe_ivars.each do |iv|
        instance_vars[iv.to_s.sub(/^@/, '')] = instance_variable_get(iv)
      end
      {
        'json_class' => self.class.name,
        'instance_vars' => instance_vars
      }
    end

cookbook_version() click to toggle source

    # File lib/chef/resource.rb, line 606
    def cookbook_version
      if cookbook_name
        run_context.cookbook_collection[cookbook_name]
      end
    end

custom_exception_message(e) click to toggle source

    # File lib/chef/resource.rb, line 675
    def custom_exception_message(e)
      "#{self} (#{defined_at}) had an error: #{e.class.name}: #{e.message}"
    end

customize_exception(e) click to toggle source

    # File lib/chef/resource.rb, line 679
    def customize_exception(e)
      new_exception = e.exception(custom_exception_message(e))
      new_exception.set_backtrace(e.backtrace)
      new_exception
    end

defined_at() click to toggle source

    # File lib/chef/resource.rb, line 591
    def defined_at
      # The following regexp should match these two sourceline formats:
      #   /some/path/to/file.rb:80:in `wombat_tears'
      #   C:/some/path/to/file.rb:80 in 1`wombat_tears'
      # extracting the path to the source file and the line number.
      (file, line_no) = source_line.match(/(.*):(\d+):?.*$/).to_a[1,2] if source_line
      if cookbook_name && recipe_name && source_line
        "#{cookbook_name}::#{recipe_name} line #{line_no}"
      elsif source_line
        "#{file} line #{line_no}"
      else
        "dynamically defined"
      end
    end

delayed_notifications() click to toggle source

    # File lib/chef/resource.rb, line 457
    def delayed_notifications
      run_context.delayed_notifications(self)
    end

epic_fail(arg=nil) click to toggle source

    # File lib/chef/resource.rb, line 402
    def epic_fail(arg=nil)
      ignore_failure(arg)
    end

events() click to toggle source

    # File lib/chef/resource.rb, line 612
    def events
      run_context.events
    end

guard_interpreter(arg=nil) click to toggle source

    # File lib/chef/resource.rb, line 406
    def guard_interpreter(arg=nil)
      set_or_return(
        :guard_interpreter,
        arg,
        :kind_of => Symbol
      )
    end

identity() click to toggle source

Returns the value of the identity attribute, if declared. Falls back to name if no identity attribute is declared.

    # File lib/chef/resource.rb, line 270
    def identity
      if identity_attr = self.class.identity_attr
        send(identity_attr)
      else
        name
      end
    end

ignore_failure(arg=nil) click to toggle source

    # File lib/chef/resource.rb, line 378
    def ignore_failure(arg=nil)
      set_or_return(
        :ignore_failure,
        arg,
        :kind_of => [ TrueClass, FalseClass ]
      )
    end

immediate_notifications() click to toggle source

    # File lib/chef/resource.rb, line 453
    def immediate_notifications
      run_context.immediate_notifications(self)
    end

inspect() click to toggle source

    # File lib/chef/resource.rb, line 511
    def inspect
      ivars = instance_variables.map { |ivar| ivar.to_sym } - FORBIDDEN_IVARS
      ivars.inject("<#{to_s}") do |str, ivar|
        str << " #{ivar}: #{instance_variable_get(ivar).inspect}"
      end << ">"
    end

is(*args) click to toggle source

    # File lib/chef/resource.rb, line 483
    def is(*args)
      if args.size == 1
        args.first
      else
        return *args
      end
    end

load_prior_resource() click to toggle source

    # File lib/chef/resource.rb, line 302
    def load_prior_resource
      begin
        prior_resource = run_context.resource_collection.lookup(self.to_s)
        # if we get here, there is a prior resource (otherwise we'd have jumped
        # to the rescue clause).
        Chef::Log.warn("Cloning resource attributes for #{self.to_s} from prior resource (CHEF-3694)")
        Chef::Log.warn("Previous #{prior_resource}: #{prior_resource.source_line}") if prior_resource.source_line
        Chef::Log.warn("Current  #{self}: #{self.source_line}") if self.source_line
        prior_resource.instance_variables.each do |iv|
          unless iv.to_sym == :@source_line || iv.to_sym == :@action || iv.to_sym == :@not_if || iv.to_sym == :@only_if
            self.instance_variable_set(iv, prior_resource.instance_variable_get(iv))
          end
        end
        true
      rescue Chef::Exceptions::ResourceNotFound
        true
      end
    end

method_missing(method_symbol, *args, &block) click to toggle source

If an unknown method is invoked, determine whether the enclosing Provider’s lexical scope can fulfill the request. E.g. This happens when the Resource’s block invokes new_resource.

    # File lib/chef/resource.rb, line 294
    def method_missing(method_symbol, *args, &block)
      if enclosing_provider && enclosing_provider.respond_to?(method_symbol)
        enclosing_provider.send(method_symbol, *args, &block)
      else
        raise NoMethodError, "undefined method `#{method_symbol.to_s}' for #{self.class.to_s}"
      end
    end

name(name=nil) click to toggle source

    # File lib/chef/resource.rb, line 362
    def name(name=nil)
      if !name.nil?
        raise ArgumentError, "name must be a string!" unless name.kind_of?(String)
        @name = name
      end
      @name
    end

node() click to toggle source

    # File lib/chef/resource.rb, line 287
    def node
      run_context && run_context.node
    end

noop(tf=nil) click to toggle source

    # File lib/chef/resource.rb, line 370
    def noop(tf=nil)
      if !tf.nil?
        raise ArgumentError, "noop must be true or false!" unless tf == true || tf == false
        @noop = tf
      end
      @noop
    end

not_if(command=nil, opts={}, &block) click to toggle source

If command is a block, returns false if the block returns true, true if it returns false. (“Do not run this resource if the block is true”)

If the command is not a block, executes the command. If it returns a 0 exitstatus, returns false. (“Do not run this resource if the command returns 0”)

### Parameters¶ ↑

command<String>

  A a string to execute.

opts<Hash>

  Options control the execution of the command

block<Proc>

  A ruby block to run. Ignored if a command is given.

### Evaluation¶ ↑

- evaluates to true if the block is false, or if the command returns a non-zero exit status.

- evaluates to false if the block is true, or if the command returns a 0 exit status.

    # File lib/chef/resource.rb, line 584
    def not_if(command=nil, opts={}, &block)
      if command || block_given?
        @not_if << Conditional.not_if(self, command, opts, &block)
      end
      @not_if
    end

notifies(action, resource_spec, timing=:delayed) click to toggle source

Sets up a notification from this resource to the resource specified by `resource_spec`.

    # File lib/chef/resource.rb, line 415
    def notifies(action, resource_spec, timing=:delayed)
      # when using old-style resources(:template => "/foo.txt") style, you
      # could end up with multiple resources.
      resources = [ resource_spec ].flatten
      resources.each do |resource|

        validate_resource_spec!(resource_spec)

        case timing.to_s
        when 'delayed'
          notifies_delayed(action, resource)
        when 'immediate', 'immediately'
          notifies_immediately(action, resource)
        else
          raise ArgumentError,  "invalid timing: #{timing} for notifies(#{action}, #{resources.inspect}, #{timing}) resource #{self} "                                 "Valid timings are: :delayed, :immediate, :immediately"
        end
      end

      true
    end

notifies_delayed(action, resource_spec) click to toggle source

    # File lib/chef/resource.rb, line 449
    def notifies_delayed(action, resource_spec)
      run_context.notifies_delayed(Notification.new(resource_spec, action, self))
    end

notifies_immediately(action, resource_spec) click to toggle source

    # File lib/chef/resource.rb, line 445
    def notifies_immediately(action, resource_spec)
      run_context.notifies_immediately(Notification.new(resource_spec, action, self))
    end

only_if(command=nil, opts={}, &block) click to toggle source

If command is a block, returns true if the block returns true, false if it returns false. (“Only run this resource if the block is true”)

If the command is not a block, executes the command. If it returns any status other than 0, it returns false (clearly, a 0 status code is true)

### Parameters¶ ↑

command<String>

  A a string to execute.

opts<Hash>

  Options control the execution of the command

block<Proc>

  A ruby block to run. Ignored if a command is given.

### Evaluation¶ ↑

- evaluates to true if the block is true, or if the command returns 0

- evaluates to false if the block is false, or if the command returns a non-zero exit code.

    # File lib/chef/resource.rb, line 563
    def only_if(command=nil, opts={}, &block)
      if command || block_given?
        @only_if << Conditional.only_if(self, command, opts, &block)
      end
      @only_if
    end

provider_for_action(action) click to toggle source

    # File lib/chef/resource.rb, line 662
    def provider_for_action(action)
      # leverage new platform => short_name => resource
      # which requires explicitly setting provider in
      # resource class
      if self.provider
        provider = self.provider.new(self, self.run_context)
        provider.action = action
        provider
      else # fall back to old provider resolution
        Chef::Platform.provider_for_resource(self, action)
      end
    end

resolve_notification_references() click to toggle source

Iterates over all immediate and delayed notifications, calling resolve_resource_reference on each in turn, causing them to resolve lazy/forward references.

    # File lib/chef/resource.rb, line 440
    def resolve_notification_references
      run_context.immediate_notifications(self).each { |n| n.resolve_resource_reference(run_context.resource_collection) }
      run_context.delayed_notifications(self).each {|n| n.resolve_resource_reference(run_context.resource_collection) }
    end

resources(*args) click to toggle source

    # File lib/chef/resource.rb, line 461
    def resources(*args)
      run_context.resource_collection.find(*args)
    end

run_action(action, notification_type=nil, notifying_resource=nil) click to toggle source

    # File lib/chef/resource.rb, line 616
    def run_action(action, notification_type=nil, notifying_resource=nil)
      # reset state in case of multiple actions on the same resource.
      @elapsed_time = 0
      start_time = Time.now
      events.resource_action_start(self, action, notification_type, notifying_resource)
      # Try to resolve lazy/forward references in notifications again to handle
      # the case where the resource was defined lazily (ie. in a ruby_block)
      resolve_notification_references
      validate_action(action)

      if Chef::Config[:verbose_logging] || Chef::Log.level == :debug
        # This can be noisy
        Chef::Log.info("Processing #{self} action #{action} (#{defined_at})")
      end

      # ensure that we don't leave @updated_by_last_action set to true
      # on accident
      updated_by_last_action(false)

      begin
        return if should_skip?(action)
        provider_for_action(action).run_action
      rescue Exception => e
        if ignore_failure
          Chef::Log.error("#{custom_exception_message(e)}; ignore_failure is set, continuing")
          events.resource_failed(self, action, e)
        elsif retries > 0
          events.resource_failed_retriable(self, action, retries, e)
          @retries -= 1
          Chef::Log.info("Retrying execution of #{self}, #{retries} attempt(s) left")
          sleep retry_delay
          retry
        else
          events.resource_failed(self, action, e)
          raise customize_exception(e)
        end
      ensure
        @elapsed_time = Time.now - start_time
        events.resource_completed(self)
      end
    end

should_skip?(action) click to toggle source

Evaluates #not_if and #only_if conditionals. Returns a falsey value if any of the conditionals indicate that this resource should be skipped, i.e., if an #only_if evaluates to false or a #not_if evaluates to true.

If this resource should be skipped, returns the first conditional that “fails” its check. Subsequent conditionals are not evaluated, so in general it’s not a good idea to rely on side effects from #not_if or #only_if commands/blocks being evaluated.

Also skips conditional checking when the action is :nothing

    # File lib/chef/resource.rb, line 694
    def should_skip?(action)
      conditional_action = ConditionalActionNotNothing.new(action)

      conditionals = [ conditional_action ] + only_if + not_if
      conditionals.find do |conditional|
        if conditional.continue?
          false
        else
          events.resource_skipped(self, action, conditional)
          Chef::Log.debug("Skipping #{self} due to #{conditional.description}")
          true
        end
      end
    end

state() click to toggle source

Returns a Hash of attribute => value for the state attributes declared in the resource’s class definition.

    # File lib/chef/resource.rb, line 261
    def state
      self.class.state_attrs.inject({}) do |state_attrs, attr_name|
        state_attrs[attr_name] = send(attr_name)
        state_attrs
      end
    end

subscribes(action, resources, timing=:delayed) click to toggle source

    # File lib/chef/resource.rb, line 465
    def subscribes(action, resources, timing=:delayed)
      resources = [resources].flatten
      resources.each do |resource|
        if resource.is_a?(String)
          resource = Chef::Resource.new(resource, run_context)
        end
        if resource.run_context.nil?
          resource.run_context = run_context
        end
        resource.notifies(action, self, timing)
      end
      true
    end

supports(args={}) click to toggle source

    # File lib/chef/resource.rb, line 321
    def supports(args={})
      if args.any?
        @supports = args
      else
        @supports
      end
    end

to_hash() click to toggle source

    # File lib/chef/resource.rb, line 539
    def to_hash
      safe_ivars = instance_variables.map { |ivar| ivar.to_sym } - FORBIDDEN_IVARS
      instance_vars = Hash.new
      safe_ivars.each do |iv|
        key = iv.to_s.sub(/^@/,'').to_sym
        instance_vars[key] = instance_variable_get(iv)
      end
      instance_vars
    end

to_json(*a) click to toggle source

Serialize this object as a hash

    # File lib/chef/resource.rb, line 534
    def to_json(*a)
      results = as_json
      results.to_json(*a)
    end

to_s() click to toggle source

    # File lib/chef/resource.rb, line 491
    def to_s
      "#{@resource_name}[#{@name}]"
    end

to_text() click to toggle source

    # File lib/chef/resource.rb, line 495
    def to_text
      ivars = instance_variables.map { |ivar| ivar.to_sym } - HIDDEN_IVARS
      text = "# Declared in #{@source_line}\n\n"
      text << self.class.dsl_name + "(\"#{name}\") do\n"
      ivars.each do |ivar|
        if (value = instance_variable_get(ivar)) && !(value.respond_to?(:empty?) && value.empty?)
          value_string = value.respond_to?(:to_text) ? value.to_text : value.inspect
          text << "  #{ivar.to_s.sub(/^@/,'')} #{value_string}\n"
        end
      end
      [@not_if, @only_if].flatten.each do |conditional|
        text << "  #{conditional.to_text}\n"
      end
      text << "end\n"
    end

updated=(true_or_false) click to toggle source

    # File lib/chef/resource.rb, line 279
    def updated=(true_or_false)
      Chef::Log.warn("Chef::Resource#updated=(true|false) is deprecated. Please call #updated_by_last_action(true|false) instead.")
      Chef::Log.warn("Called from:")
      caller[0..3].each {|line| Chef::Log.warn(line)}
      updated_by_last_action(true_or_false)
      @updated = true_or_false
    end

updated?() click to toggle source

    # File lib/chef/resource.rb, line 718
    def updated?
      updated
    end

updated_by_last_action(true_or_false) click to toggle source

    # File lib/chef/resource.rb, line 709
    def updated_by_last_action(true_or_false)
      @updated ||= true_or_false
      @updated_by_last_action = true_or_false
    end

updated_by_last_action?() click to toggle source

    # File lib/chef/resource.rb, line 714
    def updated_by_last_action?
      @updated_by_last_action
    end

validate_action(action) click to toggle source

    # File lib/chef/resource.rb, line 658
    def validate_action(action)
      raise ArgumentError, "nil is not a valid action for resource #{self}" if action.nil?
    end

validate_resource_spec!(resource_spec) click to toggle source

    # File lib/chef/resource.rb, line 479
    def validate_resource_spec!(resource_spec)
      run_context.resource_collection.validate_lookup_spec!(resource_spec)
    end