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
-
#allow_missing_post? ⇒ true, false
If the resource accepts POST requests to nonexistent resources, then this should return true.
-
#allowed_methods ⇒ Array<String>
HTTP methods that are allowed on this resource.
-
#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.
-
#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.
-
#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.
-
#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.
-
#create_path ⇒ String, URI
This will be called on a POST request if post_is_create? returns true.
-
#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.
-
#delete_resource ⇒ true, false
This method is called when a DELETE request should be enacted, and should return true if the deletion succeeded.
-
#encodings_provided ⇒ Hash
This should return a hash of encodings mapped to encoding methods for Content-Encodings your resource wants to provide.
-
#expires ⇒ Time, ...
If the resource expires, this method should return the date/time it expires.
-
#finish_request ⇒ Object
This method is called just before the final response is constructed and sent.
-
#forbidden? ⇒ true, false
Is the request or client forbidden? Returning a truthy value (true or non-nil) will result in a ‘403 Forbidden’ response.
-
#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.
-
#handle_exception(e) ⇒ void
This method is called when an error is raised within a subclass of Webmachine::Resource.
-
#is_authorized?(authorization_header = nil) ⇒ true, ...
Is the client or request authorized? Returning anything other than true will result in a ‘401 Unauthorized’ response.
-
#is_conflict? ⇒ true, false
If this returns true, the client will receive a ‘409 Conflict’ response.
-
#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.
-
#known_methods ⇒ Array<String>
HTTP methods that are known to the resource.
-
#language_chosen(lang) ⇒ Object
This should receive the chosen language and do something with it that is resource-specific.
-
#languages_provided ⇒ Array<String>
This should return a list of language tags provided by the resource.
-
#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.
-
#malformed_request? ⇒ true, false
If the request is malformed, this should return true, which will result in a ‘400 Malformed Request’ response.
-
#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.
-
#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.
-
#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.
-
#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.
-
#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.
-
#previously_existed? ⇒ true, false
If this resource is known to have existed previously, this method should return true.
-
#process_post ⇒ true, ...
If post_is_create? returns false, then this will be called to process any POST request.
-
#resource_exists? ⇒ true, false
Does the resource exist? Returning a falsey value (false or nil) will result in a ‘404 Not Found’ response.
-
#service_available? ⇒ true, false
Is the resource available? Returning a falsey value (false or nil) will result in a ‘503 Service Not Available’ response.
-
#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.
-
#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.
-
#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.
-
#validate_content_checksum ⇒ true, ...
This method is called when verifying the Content-MD5 header against the request body.
-
#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.
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.
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’].
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.
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.
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.
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]].
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.
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.
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.
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.
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.
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.
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.
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.
376 377 378 379 |
# File 'lib/webmachine/resource/callbacks.rb', line 376 def handle_exception(e) response.error = [e., 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.
39 40 41 |
# File 'lib/webmachine/resource/callbacks.rb', line 39 def ( = 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 {}.
119 120 121 |
# File 'lib/webmachine/resource/callbacks.rb', line 119 def {} 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.
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.
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.
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.
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.
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.
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.
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.
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.
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 [].
280 281 282 |
# File 'lib/webmachine/resource/callbacks.rb', line 280 def variances [] end |