Class: Needle::Interceptor

### Home Classes Methods

### In Files

- lib/needle/interceptor.rb

### Parent

Object

### Namespace

- CLASS Needle::Interceptor::DynamicInterceptor

### Methods

- ::new
- #[]
- #[]=
- #action
- #doing
- #with
- #with!
- #with_options

### Files

- README

### Class/Module Index

Quicksearch

- Needle
- Needle::Bug
- Needle::Container
- Needle::DefinitionContext
- Needle::IncludeExclude
- Needle::Interceptor
- Needle::Interceptor::DynamicInterceptor
- Needle::InterceptorChainBuilder
- Needle::InterceptorChainBuilder::InterceptedServiceProxy
- Needle::InterceptorChainBuilder::InterceptorChainElement
- Needle::InterceptorChainBuilder::ProxyObjectChainElement
- Needle::InterceptorConfigurationError
- Needle::Lifecycle
- Needle::Lifecycle::Deferred
- Needle::Lifecycle::Initialize
- Needle::Lifecycle::Multiton
- Needle::Lifecycle::Proxy
- Needle::Lifecycle::Singleton
- Needle::Lifecycle::Threaded
- Needle::LogFactory
- Needle::Logger
- Needle::LoggingInterceptor
- Needle::NeedleError
- Needle::Pipeline
- Needle::Pipeline::Collection
- Needle::Pipeline::Collection::BlockElement
- Needle::Pipeline::Element
- Needle::Pipeline::InterceptorElement
- Needle::QueryableMutex
- Needle::Registry
- Needle::ServiceNotFound
- Needle::ServicePoint
- Needle::Version

No matching classes.

# Needle::Interceptor

This represents the definition of an interceptor as it is attached to a service point. Instances of Interceptor are also used for configuring themselves programmatically.

You will almost never instantiate an Interceptor object directly. Instead, use the Container#intercept method. You can then configure the new interceptor by chaining methods of the new object together, quite readably:

    container.intercept( :foo ).with! { some_interceptor }.
      with_options( :arg => :value )

You can also create new interceptors on the fly via the Interceptor#doing method.

### Attributes

options[R]

The set of options that were given to this interceptor via the with_options method.

### Public Class Methods

new() click to toggle source

Create a new Interceptor definition. By default, it has no implementation and a priority of 0.

    # File lib/needle/interceptor.rb, line 81
    def initialize
      @options = { :priority => 0 }
      @doing = @with = nil
    end

### Public Instance Methods

[]( name ) click to toggle source

A convenience method for querying the options on an interceptor definition.

    # File lib/needle/interceptor.rb, line 177
    def []( name )
      @options[ name ]
    end

[]=( name, value ) click to toggle source

A convenience method for setting the options on an interceptor definition.

    # File lib/needle/interceptor.rb, line 183
    def []=( name, value )
      @options[ name ] = value
    end

action() click to toggle source

Returns the action that was specified for this interceptor as a proc instance. This will either be the block passed to with, or a proc that wraps the instantiation of a DynamicInterceptor (when doing was used).

If neither with nor doing were specified, an InterceptorConfigurationError is raised.

    # File lib/needle/interceptor.rb, line 93
    def action
      return @with if @with
      raise InterceptorConfigurationError,
        "You must specify either 'with' or 'doing'" unless @doing

      return proc { |c| DynamicInterceptor.new( @doing ) }
    end

doing( &block ) click to toggle source

This allows new interceptors to be defined "on-the-fly". The associated block must accept two parameters--an object representing the chain of interceptors, and the context of the current method invocation. The block should then invoke process_next on the chain (passing the context as the lone parameter) when the next element of the chain should be invoked.

You should only call doing once per interceptor, and never after invoking with on the same interceptor.

    # File lib/needle/interceptor.rb, line 149
    def doing( &block )
      if @doing
        raise InterceptorConfigurationError,
          "you cannot redefine 'doing' behavior"
      end

      if @with
        raise InterceptorConfigurationError,
          "cannot specify 'doing' after specifying 'with'"
      end

      if block.nil?
        raise InterceptorConfigurationError,
          "you must specify a block to 'doing'"
      end

      @doing = block
      self
    end

with( &block ) click to toggle source

Sets the action for this interceptor to be that defined by the interceptor returned when the block is executed. You can only invoke with once, and never after previously invoking doing on the same interceptor instance.

Usage:

    container.intercept( :foo ).
      with { |c| c.logging_interceptor }

    # File lib/needle/interceptor.rb, line 110
    def with( &block )
      if @with
        raise InterceptorConfigurationError,
          "you cannot redefine 'with' behavior"
      end

      if @doing
        raise InterceptorConfigurationError,
          "cannot specify 'with' after specifying 'doing'"
      end

      if block.nil?
        raise InterceptorConfigurationError,
          "you must specify a block to 'with'"
      end

      @with = block
      self
    end

with!( &block ) click to toggle source

This is identical to with, but it wraps the block in another proc that calls `instance_eval` on the container, with the block.

Usage:

    container.intercept( :foo ).
      with! { logging_interceptor }

    # File lib/needle/interceptor.rb, line 137
    def with!( &block )
      with { |c| c.instance_eval( &block ) }
    end

with_options( opts={} ) click to toggle source

Merge the given `opts` hash into the interceptors options hash.

    # File lib/needle/interceptor.rb, line 170
    def with_options( opts={} )
      @options.update opts
      self
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.