class Hoodoo::Services::Context

A collection of objects which describe the context in which a service is being called. The service reads session and request information and returns results of its processing via the associated response object.

Attributes

owning_interaction[R]

The Hoodoo::Services::Middleware::Interaction instance for which this context exists (the ‘owning’ instance). Generally speaking this is only needed internally as part of the inter-resource call mechanism.

request[R]

The Hoodoo::Services::Request instance giving details about the inbound request. Relevant information will depend upon the endpoint service implementation action being addressed.

response[R]

The Hoodoo::Services::Response instance that a service implementation updates with results of its processing.

session[R]

The Hoodoo::Services::Session instance describing the authorised call context. If a resource implementation is handling a public action this may be nil, else it will be a valid instance.

Public Class Methods

new( session, request, response, owning_interaction ) click to toggle source

Create a new instance. There is almost certainly never any need to call this unless you’re the Hoodoo::Services::Middleware::Interaction constructor! If you want to build a context for (say) test purposes, it’s probably best to construct an interaction instance and use the context instance this provides.

session

See session.

request

See request.

response

See response.

owning_interaction

See interaction.

# File lib/hoodoo/services/services/context.rb, line 55
def initialize( session, request, response, owning_interaction )
  @session            = session
  @request            = request
  @response           = response
  @owning_interaction = owning_interaction
end

Public Instance Methods

endpoint( resource, version = 1, options = {} )

Alias of resource, as syntax sugar for those who prefer to think of the return value as an endpoint that is used to contact a resource, rather than a remote abstraction of the resource as an entity.

Alias for: resource
resource( resource, version = 1, options = {} ) click to toggle source

Request (and lazy-initialize) a new resource endpoint instance for talking to a resource’s interface. See Hoodoo::Client::Endpoint.

You can request an endpoint for any resource name, whether or not an implementation actually exists for it. Until you try and talk to the interface through the endpoint instance, you won’t know if it is there. All endpoint methods return instances of classes that mix in Hoodoo::Client::AugmentedBase; these mixin methods provide error handling options to detect a “not found” error (equivanent to HTTP status code 404) returned when a resource implementation turns out to not actually be present.

The idiomatic call sequence is something like the following, where you get hold of an endpoint, make a call and handle the response:

clock = context.resource( :Clock, 2 ) # v2 of 'Clock' resource
time  = clock.show( 'now' )

return if time.adds_errors_to?( context.response.errors )

…or alternatively:

clock = context.resource( :Clock, 2 ) # v2 of 'Clock' resource
time  = clock.show( 'now' )

context.response.add_errors( time.platform_errors )
return if context.response.halt_processing?

The return value of calls made to the endpoint is an Array or Hash that mixes in Hoodoo::Client::AugmentedBase; see this class’s documentation for details of the two alternative error handling approaches shown above.

resource

Resource name for the endpoint, e.g. :Purchase. String or symbol.

version

Optional required implemented version for the endpoint, as an Integer - defaults to 1.

options

Optional options Hash (see below).

The options Hash key/values are as follows:

locale

Locale string for request/response, e.g. “en-gb”. Optional. If omitted, defaults to the locale set in this Client instance’s constructor.

Others

See Hoodoo::Client::HeadersHEADER_TO_PROPERTY. For any options in that map which describe themselves as being automatically transferred from one endpoint to another, you can prevent this by explicitly pasisng a nil value for the option; otherwise, OMIT the option for normal behaviour. Non-auto-transfer properties can be specified as nil or omitted with no change in behaviour.

# File lib/hoodoo/services/services/context.rb, line 117
def resource( resource, version = 1, options = {} )
  middleware = @owning_interaction.owning_middleware_instance
  endpoint   = middleware.inter_resource_endpoint_for(
    resource,
    version,
    @owning_interaction
  )

  endpoint.locale = options[ :locale ] unless options[ :locale ].nil?

  Hoodoo::Client::Headers::HEADER_TO_PROPERTY.each do | rack_header, description |
    property        = description[ :property        ]
    property_writer = description[ :property_writer ]
    auto_transfer   = description[ :auto_transfer   ]

    # For automatically transferred options there's no way to stop the
    # auto transfer unless explicitly stating 'nil' to overwrite any
    # existing value, so here, only write the value into the endpoint if
    # the property specifically exists in the inbound options hash.
    #
    # For other properties, 'nil' has no meaning and there's no need to
    # override anything, so use "unless nil?" in that case.

    value = options[ property ]

    if auto_transfer == true
      endpoint.send( property_writer, value ) if options.has_key?( property )
    else
      endpoint.send( property_writer, value ) unless value.nil?
    end
  end

  return endpoint
end
Also aliased as: endpoint