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.



55
56
57
 
# File 'lib/webmachine/resource/callbacks.rb', line 55

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



125
126
127
 
# File 'lib/webmachine/resource/callbacks.rb', line 125

def allowed_methods
  ['GET', 'HEAD']
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) 


187
188
189
 
# File 'lib/webmachine/resource/callbacks.rb', line 187

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.



234
235
236
 
# File 'lib/webmachine/resource/callbacks.rb', line 234

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



222
223
224
 
# File 'lib/webmachine/resource/callbacks.rb', line 222

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



211
212
213
 
# File 'lib/webmachine/resource/callbacks.rb', line 211

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



177
178
179
 
# File 'lib/webmachine/resource/callbacks.rb', line 177

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



154
155
156
 
# File 'lib/webmachine/resource/callbacks.rb', line 154

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.



144
145
146
 
# File 'lib/webmachine/resource/callbacks.rb', line 144

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:



265
266
267
 
# File 'lib/webmachine/resource/callbacks.rb', line 265

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



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

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.



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

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.



46
47
48
 
# File 'lib/webmachine/resource/callbacks.rb', line 46

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



353
354
355
 
# File 'lib/webmachine/resource/callbacks.rb', line 353

def generate_etag
  nil
end

#handle_exception(e) ⇒ void

This method returns an undefined value.

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

Parameters:

  • e (Exception) —

    The exception.



374
375
376
377
 
# File 'lib/webmachine/resource/callbacks.rb', line 374

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.



37
38
39
 
# File 'lib/webmachine/resource/callbacks.rb', line 37

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



287
288
289
 
# File 'lib/webmachine/resource/callbacks.rb', line 287

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



85
86
87
 
# File 'lib/webmachine/resource/callbacks.rb', line 85

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



136
137
138
 
# File 'lib/webmachine/resource/callbacks.rb', line 136

def known_methods
  ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'TRACE', 'CONNECT', 'OPTIONS']
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



252
253
254
 
# File 'lib/webmachine/resource/callbacks.rb', line 252

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



243
244
245
 
# File 'lib/webmachine/resource/callbacks.rb', line 243

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



336
337
338
 
# File 'lib/webmachine/resource/callbacks.rb', line 336

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.



63
64
65
 
# File 'lib/webmachine/resource/callbacks.rb', line 63

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



316
317
318
 
# File 'lib/webmachine/resource/callbacks.rb', line 316

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



326
327
328
 
# File 'lib/webmachine/resource/callbacks.rb', line 326

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



298
299
300
 
# File 'lib/webmachine/resource/callbacks.rb', line 298

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



117
118
119
 
# File 'lib/webmachine/resource/callbacks.rb', line 117

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



166
167
168
 
# File 'lib/webmachine/resource/callbacks.rb', line 166

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



306
307
308
 
# File 'lib/webmachine/resource/callbacks.rb', line 306

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, Fixnum) —

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



196
197
198
 
# File 'lib/webmachine/resource/callbacks.rb', line 196

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



13
14
15
 
# File 'lib/webmachine/resource/callbacks.rb', line 13

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) 


24
25
26
 
# File 'lib/webmachine/resource/callbacks.rb', line 24

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.



73
74
75
 
# File 'lib/webmachine/resource/callbacks.rb', line 73

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



97
98
99
 
# File 'lib/webmachine/resource/callbacks.rb', line 97

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 (Fixnum) (defaults to: nil) —

    the size of the request body (entity)

Returns:

  • (true, false) —

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



108
109
110
 
# File 'lib/webmachine/resource/callbacks.rb', line 108

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



387
388
389
 
# File 'lib/webmachine/resource/callbacks.rb', line 387

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



278
279
280
 
# File 'lib/webmachine/resource/callbacks.rb', line 278

def variances
  []
end