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.

Returns:

  • (true, false)

    Whether to accept POST requests to missing resources.



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

Returns:

  • (Array<String>)

    allowed methods on this resource



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.

Returns:

  • (String, URI, nil)


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.

Returns:

  • (nil, Array)

    The provided character sets and encoder methods, or nothing.



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.

Returns:

  • an array of mediatype/handler pairs



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

Returns:

  • an array of mediatype/handler pairs



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.

Returns:

  • (String, URI)

    the path to the new resource



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.

Returns:

  • (true, false)

    Whether the deletion completed



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.

Returns:

  • (true, false)

    Whether the deletion succeeded.



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.

Returns:

  • (Hash)

    a hash of encodings and encoder methods/procs

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.

Returns:

  • (Time, DateTime, Date, nil)

    the expiration time



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.

Returns:

  • (true, false)

    Whether the client or request is forbidden.



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.

Returns:

  • (String, nil)

    the entity tag for this resource



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.

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.



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.

Returns:

  • (true, false)

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



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.

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



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.

Returns:

  • (Array<String>)

    known methods



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.

Returns:

  • (true, false)

    whether the language is available



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.

Returns:

  • (Time, DateTime, Date, nil)

    the last modified time



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.

Returns:

  • (true, false)

    Whether the request is malformed.



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.

Returns:

  • (String, URI, false)

    the new location of the resource, or 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.

Returns:

  • (String, URI, false)

    the new location of the resource, or 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.

Returns:

  • (true, false)

    whether the multiple representations are possible



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

Returns:

  • (Hash)

    headers to appear in the response



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.

Returns:

  • (true, false)

    Whether POST creates a new resource



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.

Returns:

  • (true, false)

    whether the resource existed previously



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.

Returns:

  • (true, false, Fixnum)

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



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.

Returns:

  • (true, false)

    Whether the resource exists



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.

Returns:

  • (true, false)


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.

Parameters:

  • uri (URI) (defaults to: nil)

    the request URI

Returns:

  • (true, false)

    Whether the request URI is too long.



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.

Parameters:

  • content_headers (Hash) (defaults to: nil)

    Request headers that begin with 'Content-'

Returns:

  • (true, false)

    Whether the Content-* headers are invalid or unsupported



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.

Parameters:

  • length (Fixnum) (defaults to: nil)

    the size of the request body (entity)

Returns:

  • (true, false)

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



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.

Returns:

  • (true, false, nil)

    Whether the Content-MD5 header validates against the request body



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

Returns:

  • (Array<String>)

    a list of variance headers



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

def variances
  []
end