Module: Webmachine::Resource::Callbacks

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

Overview

These

Instance Method Summary (collapse)

Instance Method Details

- (true, false) allow_missing_post?

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



51
52
53
# File 'lib/webmachine/resource/callbacks.rb', line 51

def allow_missing_post?
  false
end

- (Array<String>) allowed_methods

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



121
122
123
# File 'lib/webmachine/resource/callbacks.rb', line 121

def allowed_methods
  ['GET', 'HEAD']
end

- (String, ...) base_uri

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.



183
184
185
# File 'lib/webmachine/resource/callbacks.rb', line 183

def base_uri
  nil
end

- (nil, Array) charsets_provided

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.



229
230
231
# File 'lib/webmachine/resource/callbacks.rb', line 229

def charsets_provided
  nil
end

- (Object) content_types_accepted

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.



217
218
219
# File 'lib/webmachine/resource/callbacks.rb', line 217

def content_types_accepted
  []
end

- (Object) content_types_provided

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 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]].



206
207
208
# File 'lib/webmachine/resource/callbacks.rb', line 206

def content_types_provided
  [['text/html', :to_html]]
end

- (String, URI) create_path

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.



173
174
175
# File 'lib/webmachine/resource/callbacks.rb', line 173

def create_path
  nil
end

- (true, false) delete_completed?

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.



150
151
152
# File 'lib/webmachine/resource/callbacks.rb', line 150

def delete_completed?
  true
end

- (true, false) delete_resource

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



140
141
142
# File 'lib/webmachine/resource/callbacks.rb', line 140

def delete_resource
  false
end

- (Hash) encodings_provided

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.

See Also:



250
251
252
# File 'lib/webmachine/resource/callbacks.rb', line 250

def encodings_provided
  {"identity" => :encode_identity }
end

- (Time, ...) expires

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



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

def expires
  nil
end

- (Object) finish_request

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.



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

def finish_request; end

- (true, false) forbidden?

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



42
43
44
# File 'lib/webmachine/resource/callbacks.rb', line 42

def forbidden?
  false
end

- (String?) generate_etag

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.



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

def generate_etag
  nil
end

- (true, ...) is_authorized?(authorization_header = nil)

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.



33
34
35
# File 'lib/webmachine/resource/callbacks.rb', line 33

def is_authorized?(authorization_header = nil)
  true
end

- (true, false) is_conflict?

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



272
273
274
# File 'lib/webmachine/resource/callbacks.rb', line 272

def is_conflict?
  false
end

- (true, false) known_content_type?(content_type = nil)

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.



81
82
83
# File 'lib/webmachine/resource/callbacks.rb', line 81

def known_content_type?(content_type = nil)
  true
end

- (Array<String>) known_methods

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.



132
133
134
# File 'lib/webmachine/resource/callbacks.rb', line 132

def known_methods
  ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'TRACE', 'CONNECT', 'OPTIONS']
end

- (true, false) language_available?(accept_lang)

This should return true or false if the requested language(s) is available. Default is true.



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

def language_available?(accept_lang)
  true
end

- (Time, ...) last_modified

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.



321
322
323
# File 'lib/webmachine/resource/callbacks.rb', line 321

def last_modified
  nil
end

- (true, false) malformed_request?

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



59
60
61
# File 'lib/webmachine/resource/callbacks.rb', line 59

def malformed_request?
  false
end

- (String, ...) moved_permanently?

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.



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

def moved_permanently?
  false
end

- (String, ...) moved_temporarily?

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.



311
312
313
# File 'lib/webmachine/resource/callbacks.rb', line 311

def moved_temporarily?
  false
end

- (true, false) multiple_choices?

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.



283
284
285
# File 'lib/webmachine/resource/callbacks.rb', line 283

def multiple_choices?
  false
end

- (Hash) options

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 {}.



113
114
115
# File 'lib/webmachine/resource/callbacks.rb', line 113

def options
  {}
end

- (true, false) post_is_create?

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.



162
163
164
# File 'lib/webmachine/resource/callbacks.rb', line 162

def post_is_create?
  false
end

- (true, false) previously_existed?

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



291
292
293
# File 'lib/webmachine/resource/callbacks.rb', line 291

def previously_existed?
  false
end

- (true, ...) process_post

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



192
193
194
# File 'lib/webmachine/resource/callbacks.rb', line 192

def process_post
  false
end

- (true, false) resource_exists?

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



9
10
11
# File 'lib/webmachine/resource/callbacks.rb', line 9

def resource_exists?
  true
end

- (true, false) service_available?

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.



20
21
22
# File 'lib/webmachine/resource/callbacks.rb', line 20

def service_available?
  true
end

- (true, false) uri_too_long?(uri = nil)

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.



69
70
71
# File 'lib/webmachine/resource/callbacks.rb', line 69

def uri_too_long?(uri = nil)
  false
end

- (true, false) valid_content_headers?(content_headers = nil)

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



93
94
95
# File 'lib/webmachine/resource/callbacks.rb', line 93

def valid_content_headers?(content_headers = nil)
  true
end

- (true, false) valid_entity_length?(length = nil)

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.



104
105
106
# File 'lib/webmachine/resource/callbacks.rb', line 104

def valid_entity_length?(length = nil)
  true
end

- (true, ...) validate_content_checksum

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 false. Default is nil, which will invoke Webmachine's default validation.



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

def validate_content_checksum
  nil
end

- (Array<String>) variances

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 [].



263
264
265
# File 'lib/webmachine/resource/callbacks.rb', line 263

def variances
  []
end