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.

Methods

E

endpoint

N

R

resource

Attributes

[R]	owning_interaction	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.
[R]	request	The Hoodoo::Services::Request instance giving details about the inbound request. Relevant information will depend upon the endpoint service implementation action being addressed.
[R]	response	The Hoodoo::Services::Response instance that a service implementation updates with results of its processing.
[R]	session	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.

Class Public methods

new( session, request, response, owning_interaction ) Link

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.

Source: show

# 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

Instance Public methods

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

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 = {} ) Link

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::Headers' HEADER_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.

Also aliased as: endpoint

Source: show

# 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

Class Hoodoo::Services::Context < Object