Class: Pling::Gateway

Inherits:
Object
  • Object
show all
Includes:
Configurable
Defined in:
lib/pling/gateway.rb

Overview

This is the base class of all gateways. It defines the public interface of all gateways and provides helper methods to configure gateways and define the device types a gateway is able to handle.

Gateway implementations must set the types they're able to handle by calling the Gateway.handles macro.

Every gateway must implement a #deliver! method which does the actual delivering.

Examples:


class Pling::Example::Gateway < Pling::Gateway
  handles :example, :foo, :bar

  def deliver!(message, device)
    puts "Delivering #{message.body} to #{device.identifier} (#{device.type})"
  end
end

Direct Known Subclasses

APN::Gateway, C2DM::Gateway, Pling::GCM::Gateway

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Gateway) initialize(config = {})

Initializes a new Gateway instance.

Parameters:

  • config (Hash) (defaults to: {})

    Configuration for this gateway instance

Options Hash (config):

  • :middlewares (Array)

    List of middlewares to execute before delivering

  • :on_exception (#call(exception))

    Callback to execute when an exception is raised



64
65
66
67
68
69
# File 'lib/pling/gateway.rb', line 64

def initialize(config = {})
  setup_configuration(config)
  middlewares = configuration[:middlewares]
  configuration.merge!(:middlewares => Pling::DelayedInitializer.new)
  middlewares.each { |middleware| configuration[:middlewares] << middleware } if middlewares
end

Class Method Details

+ (Pling::Gateway) discover(device)

Finds a gateway that handles the given device

Parameters:

  • device (#to_pling_device)

Returns:

Raises:



32
33
34
35
36
37
38
# File 'lib/pling/gateway.rb', line 32

def discover(device)
  device = Pling._convert(device, :device)
  Pling.gateways.initialize!
  Pling.gateways.detect do |gateway|
    gateway.handles?(device)
  end or raise(Pling::NoGatewayFound, "Could not find a gateway for #{device.class} with type :#{device.type}")
end

+ (Array<#to_sym>) handled_types

Returns a list of device types that this gateway is able to handle

Returns:

  • (Array<#to_sym>)

    List of types



53
54
55
# File 'lib/pling/gateway.rb', line 53

def handled_types
  @handled_types ||= []
end

+ (Array<#to_sym>) handles(*types)

Defines the device types a gateway is able to handle

Parameters:

  • types (Array<#to_sym>)

    List of types

Returns:

  • (Array<#to_sym>)

    List of types



45
46
47
# File 'lib/pling/gateway.rb', line 45

def handles(*types)
  @handled_types = [types].flatten.map { |t| t.to_sym }
end

Instance Method Details

- (Object) deliver(message, device, stack = nil)

Delivers the given message to the given device using the given stack. If the :on_exception callback is configured it'll rescue all Pling::Errors and pass them to the given callback.

Parameters:

  • message (#to_pling_message)
  • device (#to_pling_device)
  • stack (Array) (defaults to: nil)

    The stack to use (Default: configuration)

Raises:

  • (Pling::DeliveryError)

    unless configuration callback is set



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
# File 'lib/pling/gateway.rb', line 99

def deliver(message, device, stack = nil)
  message = Pling._convert(message, :message)
  device  = Pling._convert(device,  :device)

  stack ||= [] + configuration[:middlewares].initialize!

  return deliver!(message, device) if stack.empty?

  stack.shift.deliver(message, device) do |m, d|
    deliver(m, d, stack)
  end
rescue Pling::Error => error
  callback = configuration[:on_exception]
  callback && callback.respond_to?(:call) ? callback.call(error) : raise
end

- (Object) deliver!(message, device)

Delivers the given message to the given device without using the middleware.

Parameters:

  • message (#to_pling_message)
  • device (#to_pling_device)

Raises:

  • (Pling::NotImplementedError)

    This method must be implemented in subclasses



121
122
123
# File 'lib/pling/gateway.rb', line 121

def deliver!(message, device)
  raise NotImplementedError, "Please implement #{self.class}#deliver!(message, device)"
end

- (Boolean) handles?(device)

Checks if this gateway is able to handle the given device

Parameters:

  • device (#to_pling_device)

Returns:

  • (Boolean)


85
86
87
88
# File 'lib/pling/gateway.rb', line 85

def handles?(device)
  device  = Pling._convert(device,  :device)
  self.class.handled_types.include?(device.type)
end

- (Object) setup!

Sets up this gateway



73
74
# File 'lib/pling/gateway.rb', line 73

def setup!
end

- (Object) teardown!

Tears down this gateway



78
79
# File 'lib/pling/gateway.rb', line 78

def teardown!
end