Module: Webmachine::Resource::Callbacks

Included in:
Webmachine::Resource
Defined in:
lib/webmachine/resource/callbacks.rb

Overview

These methods are the primary way your Webmachine::Resource instance interacts with HTTP and the Decision::FSM. Implementing a callback can change the portions of the graph that are made available to your application.

Instance Method Summary collapse

Instance Method Details

#allow_missing_post? ⇒ true, false

If the resource accepts POST requests to nonexistent resources, then this should return true. Defaults to false.

Returns:

  • (true, false) —

    Whether to accept POST requests to missing resources.



57
58
59
 
# File 'lib/webmachine/resource/callbacks.rb', line 57

def allow_missing_post?
  false
end

#allowed_methods ⇒ Array<String>

HTTP methods that are allowed on this resource. This must return an Array of Strings in all capitals. Defaults to [‘GET’,‘HEAD’].

Returns:

  • (Array<String>) —

    allowed methods on this resource



127
128
129
 
# File 'lib/webmachine/resource/callbacks.rb', line 127

def allowed_methods
  [GET_METHOD, HEAD_METHOD]
end

#base_uri ⇒ String, ...

This will be called after #create_path but before setting the Location response header, and is used to determine the root URI of the new resource. Default is nil, which uses the URI of the request as the base.

Returns:

  • (String, URI, nil) 


189
190
191
 
# File 'lib/webmachine/resource/callbacks.rb', line 189

def base_uri
  nil
end

#charsets_provided ⇒ nil, Array

If this is anything other than nil, it must be an array of pairs where each pair is of the form Charset, Converter where Charset is a string naming a charset and Converter is an arity-1 method in the resource which will be called on the produced body in a GET and ensure that it is in Charset.

Returns:

  • (nil, Array) —

    The provided character sets and encoder methods, or nothing.



236
237
238
 
# File 'lib/webmachine/resource/callbacks.rb', line 236

def charsets_provided
  nil
end

#content_types_accepted ⇒ Array

Similarly to content_types_provided, this should return an array of mediatype/handler pairs, except that it is for incoming resource representations – for example, PUT requests. Handler functions usually want to use Webmachine::Request#body to access the incoming entity.

Returns:

  • (Array) —

    an array of mediatype/handler pairs



224
225
226
 
# File 'lib/webmachine/resource/callbacks.rb', line 224

def content_types_accepted
  []
end

#content_types_provided ⇒ Object

This should return an array of pairs where each pair is of the form [mediatype, :handler] where mediatype is a String of Content-Type format (or MediaType) and :handler is a Symbol naming the method which can provide a resource representation in that media type. For example, if a client request includes an ‘Accept’ header with a value that does not appear as a first element in any of the return pairs, then a ‘406 Not Acceptable’ will be sent. Default is [[‘text/html’, :to_html]].

Returns:

  • an array of mediatype/handler pairs



213
214
215
 
# File 'lib/webmachine/resource/callbacks.rb', line 213

def content_types_provided
  [[TEXT_HTML, :to_html]]
end

#create_path ⇒ String, URI

This will be called on a POST request if post_is_create? returns true. The path returned should be a valid URI part following the dispatcher prefix. That path will replace the previous one in the return value of Webmachine::Request#disp_path for all subsequent resource function calls in the course of this request.

Returns:

  • (String, URI) —

    the path to the new resource



179
180
181
 
# File 'lib/webmachine/resource/callbacks.rb', line 179

def create_path
  nil
end

#delete_completed? ⇒ true, false

This method is called after a successful call to #delete_resource and should return false if the deletion was accepted but cannot yet be guaranteed to have finished. Defaults to true.

Returns:

  • (true, false) —

    Whether the deletion completed



156
157
158
 
# File 'lib/webmachine/resource/callbacks.rb', line 156

def delete_completed?
  true
end

#delete_resource ⇒ true, false

This method is called when a DELETE request should be enacted, and should return true if the deletion succeeded. Defaults to false.

Returns:

  • (true, false) —

    Whether the deletion succeeded.



146
147
148
 
# File 'lib/webmachine/resource/callbacks.rb', line 146

def delete_resource
  false
end

#encodings_provided ⇒ Hash

This should return a hash of encodings mapped to encoding methods for Content-Encodings your resource wants to provide. The encoding will be applied to the response body automatically by Webmachine. A number of built-in encodings are provided in the Encodings module. Default includes only the ‘identity’ encoding.

Returns:

  • (Hash) —

    a hash of encodings and encoder methods/procs

See Also:



267
268
269
 
# File 'lib/webmachine/resource/callbacks.rb', line 267

def encodings_provided
  {IDENTITY => :encode_identity }
end

#expires ⇒ Time, ...

If the resource expires, this method should return the date/time it expires. Default is nil.

Returns:

  • (Time, DateTime, Date, nil) —

    the expiration time



346
347
348
 
# File 'lib/webmachine/resource/callbacks.rb', line 346

def expires
  nil
end

#finish_request ⇒ Object

This method is called just before the final response is constructed and sent. The return value is ignored, so any effect of this method must be by modifying the response.



363
 
# File 'lib/webmachine/resource/callbacks.rb', line 363

def finish_request; end

#forbidden? ⇒ true, false

Is the request or client forbidden? Returning a truthy value (true or non-nil) will result in a ‘403 Forbidden’ response. Defaults to false.

Returns:

  • (true, false) —

    Whether the client or request is forbidden.



48
49
50
 
# File 'lib/webmachine/resource/callbacks.rb', line 48

def forbidden?
  false
end

#generate_etag ⇒ String?

If this returns a value, it will be used as the value of the ETag header and for comparison in conditional requests. Default is nil.

Returns:

  • (String, nil) —

    the entity tag for this resource



355
356
357
 
# File 'lib/webmachine/resource/callbacks.rb', line 355

def generate_etag
  nil
end

#handle_exception(e) ⇒ void

This method returns an undefined value.

This method is called when an error is raised within a subclass of Webmachine::Resource.

Parameters:

  • e (StandardError) —

    The error.



376
377
378
379
 
# File 'lib/webmachine/resource/callbacks.rb', line 376

def handle_exception(e)
  response.error = [e.message, e.backtrace].flatten.join("\n    ")
  Webmachine.render_error(500, request, response)
end

#is_authorized?(authorization_header = nil) ⇒ true, ...

Is the client or request authorized? Returning anything other than true will result in a ‘401 Unauthorized’ response. Defaults to true. If a String is returned, it will be used as the value in the WWW-Authenticate header, which can also be set manually.

Parameters:

  • authorization_header (String) (defaults to: nil) —

    The contents of the ‘Authorization’ header sent by the client, if present.

Returns:

  • (true, false, String) —

    Whether the client is authorized, and if not, the WWW-Authenticate header when a String.



39
40
41
 
# File 'lib/webmachine/resource/callbacks.rb', line 39

def is_authorized?(authorization_header = nil)
  true
end

#is_conflict? ⇒ true, false

If this returns true, the client will receive a ‘409 Conflict’ response. This is only called for PUT requests. Default is false.

Returns:

  • (true, false) —

    whether the submitted entity is in conflict with the current state of the resource



289
290
291
 
# File 'lib/webmachine/resource/callbacks.rb', line 289

def is_conflict?
  false
end

#known_content_type?(content_type = nil) ⇒ true, false

If the Content-Type on PUT or POST is unknown, this should return false, which will result in a ‘415 Unsupported Media Type’ response. Defaults to true.

Parameters:

  • content_type (String) (defaults to: nil) —

    the ‘Content-Type’ header sent by the client

Returns:

  • (true, false) —

    Whether the passed media type is known or accepted



87
88
89
 
# File 'lib/webmachine/resource/callbacks.rb', line 87

def known_content_type?(content_type = nil)
  true
end

#known_methods ⇒ Array<String>

HTTP methods that are known to the resource. Like #allowed_methods, this must return an Array of Strings in all capitals. Default includes all standard HTTP methods. One could override this callback to allow additional methods, e.g. WebDAV.

Returns:

  • (Array<String>) —

    known methods



138
139
140
 
# File 'lib/webmachine/resource/callbacks.rb', line 138

def known_methods
  STANDARD_HTTP_METHODS
end

#language_chosen(lang) ⇒ Object

This should receive the chosen language and do something with it that is resource-specific. The default is to store the value in the @language instance variable.

Parameters:

  • lang (String) —

    the negotiated language



254
255
256
 
# File 'lib/webmachine/resource/callbacks.rb', line 254

def language_chosen(lang)
  @language = lang
end

#languages_provided ⇒ Array<String>

This should return a list of language tags provided by the resource. Default is the empty Array, in which the content is in no specific language.

Returns:

  • (Array<String>) —

    a list of provided languages



245
246
247
 
# File 'lib/webmachine/resource/callbacks.rb', line 245

def languages_provided
  []
end

#last_modified ⇒ Time, ...

This method should return the last modified date/time of the resource which will be added as the Last-Modified header in the response and used in negotiating conditional requests. Default is nil.

Returns:

  • (Time, DateTime, Date, nil) —

    the last modified time



338
339
340
 
# File 'lib/webmachine/resource/callbacks.rb', line 338

def last_modified
  nil
end

#malformed_request? ⇒ true, false

If the request is malformed, this should return true, which will result in a ‘400 Malformed Request’ response. Defaults to false.

Returns:

  • (true, false) —

    Whether the request is malformed.



65
66
67
 
# File 'lib/webmachine/resource/callbacks.rb', line 65

def malformed_request?
  false
end

#moved_permanently? ⇒ String, ...

If this resource has moved to a new location permanently, this method should return the new location as a String or URI. Default is to return false.

Returns:

  • (String, URI, false) —

    the new location of the resource, or false



318
319
320
 
# File 'lib/webmachine/resource/callbacks.rb', line 318

def moved_permanently?
  false
end

#moved_temporarily? ⇒ String, ...

If this resource has moved to a new location temporarily, this method should return the new location as a String or URI. Default is to return false.

Returns:

  • (String, URI, false) —

    the new location of the resource, or false



328
329
330
 
# File 'lib/webmachine/resource/callbacks.rb', line 328

def moved_temporarily?
  false
end

#multiple_choices? ⇒ true, false

If this returns true, then it is assumed that multiple representations of the response are possible and a single one cannot be automatically chosen, so a 300 Multiple Choices will be sent instead of a 200. Default is false.

Returns:

  • (true, false) —

    whether the multiple representations are possible



300
301
302
 
# File 'lib/webmachine/resource/callbacks.rb', line 300

def multiple_choices?
  false
end

#options ⇒ Hash

If the OPTIONS method is supported and is used, this method should return a Hash of headers that should appear in the response. Defaults to {}.

Returns:

  • (Hash) —

    headers to appear in the response



119
120
121
 
# File 'lib/webmachine/resource/callbacks.rb', line 119

def options
  {}
end

#post_is_create? ⇒ true, false

If POST requests should be treated as a request to put content into a (potentially new) resource as opposed to a generic submission for processing, then this method should return true. If it does return true, then #create_path will be called and the rest of the request will be treated much like a PUT to the path returned by that call. Default is false.

Returns:

  • (true, false) —

    Whether POST creates a new resource



168
169
170
 
# File 'lib/webmachine/resource/callbacks.rb', line 168

def post_is_create?
  false
end

#previously_existed? ⇒ true, false

If this resource is known to have existed previously, this method should return true. Default is false.

Returns:

  • (true, false) —

    whether the resource existed previously



308
309
310
 
# File 'lib/webmachine/resource/callbacks.rb', line 308

def previously_existed?
  false
end

#process_post ⇒ true, ...

If post_is_create? returns false, then this will be called to process any POST request. If it succeeds, it should return true.

Returns:

  • (true, false, Integer) —

    Whether the POST was successfully processed, or an alternate response code



198
199
200
 
# File 'lib/webmachine/resource/callbacks.rb', line 198

def process_post
  false
end

#resource_exists? ⇒ true, false

Does the resource exist? Returning a falsey value (false or nil) will result in a ‘404 Not Found’ response. Defaults to true.

Returns:

  • (true, false) —

    Whether the resource exists



15
16
17
 
# File 'lib/webmachine/resource/callbacks.rb', line 15

def resource_exists?
  true
end

#service_available? ⇒ true, false

Is the resource available? Returning a falsey value (false or nil) will result in a ‘503 Service Not Available’ response. Defaults to true. If the resource is only temporarily not available, add a ‘Retry-After’ response header in the body of the method.

Returns:

  • (true, false) 


26
27
28
 
# File 'lib/webmachine/resource/callbacks.rb', line 26

def service_available?
  true
end

#uri_too_long?(uri = nil) ⇒ true, false

If the URI is too long to be processed, this should return true, which will result in a ‘414 Request URI Too Long’ response. Defaults to false.

Parameters:

  • uri (URI) (defaults to: nil) —

    the request URI

Returns:

  • (true, false) —

    Whether the request URI is too long.



75
76
77
 
# File 'lib/webmachine/resource/callbacks.rb', line 75

def uri_too_long?(uri = nil)
  false
end

#valid_content_headers?(content_headers = nil) ⇒ true, false

If the request includes any invalid Content-* headers, this should return false, which will result in a ‘501 Not Implemented’ response. Defaults to true.

Parameters:

  • content_headers (Hash) (defaults to: nil) —

    Request headers that begin with ‘Content-’

Returns:

  • (true, false) —

    Whether the Content-* headers are invalid or unsupported



99
100
101
 
# File 'lib/webmachine/resource/callbacks.rb', line 99

def valid_content_headers?(content_headers = nil)
  true
end

#valid_entity_length?(length = nil) ⇒ true, false

If the entity length on PUT or POST is invalid, this should return false, which will result in a ‘413 Request Entity Too Large’ response. Defaults to true.

Parameters:

  • length (Integer) (defaults to: nil) —

    the size of the request body (entity)

Returns:

  • (true, false) —

    Whether the body is a valid length (not too large)



110
111
112
 
# File 'lib/webmachine/resource/callbacks.rb', line 110

def valid_entity_length?(length = nil)
  true
end

#validate_content_checksum ⇒ true, ...

This method is called when verifying the Content-MD5 header against the request body. To do your own validation, implement it in this callback, returning true or false. To bypass header validation, simply return true. Default is nil, which will invoke Webmachine’s default validation.

Returns:

  • (true, false, nil) —

    Whether the Content-MD5 header validates against the request body



389
390
391
 
# File 'lib/webmachine/resource/callbacks.rb', line 389

def validate_content_checksum
  nil
end

#variances ⇒ Array<String>

If this method is implemented, it should return a list of strings with header names that should be included in a given response’s Vary header. The standard conneg headers (Accept, Accept-Encoding, Accept-Charset, Accept-Language) do not need to be specified here as Webmachine will add the correct elements of those automatically depending on resource behavior. Default is [].

Returns:

  • (Array<String>) —

    a list of variance headers



280
281
282
 
# File 'lib/webmachine/resource/callbacks.rb', line 280

def variances
  []
end