lib/Catalyst/Action/REST.pm

   1 #
   2 # REST.pm
   3 # Created by: Adam Jacob, Marchex, <adam@marchex.com>
   4 # Created on: 10/12/2006 03:00:32 PM PDT
   5 #
   6 # $Id$
   7
   8 package Catalyst::Action::REST;
   9
  10 use strict;
  11 use warnings;
  12
  13 use base 'Catalyst::Action';
  14 use Class::Inspector;
  15 use Catalyst::Request::REST;
  16 use 5.8.1;
  17
  18 our
  19    $VERSION = '0.60';
  20
  21 # This is wrong in several ways. First, there's no guarantee that
  22 # Catalyst.pm has not been subclassed. Two, there's no guarantee that
  23 # the user isn't already using their request subclass.
  24 Catalyst->request_class('Catalyst::Request::REST')
  25   unless Catalyst->request_class->isa('Catalyst::Request::REST');
  26
  27 =head1 NAME
  28
  29 Catalyst::Action::REST - Automated REST Method Dispatching
  30
  31 =head1 SYNOPSIS
  32
  33     sub foo :Local :ActionClass('REST') {
  34       ... do setup for HTTP method specific handlers ...
  35     }
  36
  37     sub foo_GET {
  38       ... do something for GET requests ...
  39     }
  40
  41     sub foo_PUT {
  42       ... do somethign for PUT requests ...
  43     }
  44
  45 =head1 DESCRIPTION
  46
  47 This Action handles doing automatic method dispatching for REST requests.  It
  48 takes a normal Catalyst action, and changes the dispatch to append an
  49 underscore and method name.
  50
  51 For example, in the synopsis above, calling GET on "/foo" would result in
  52 the foo_GET method being dispatched.
  53
  54 If a method is requested that is not implemented, this action will
  55 return a status 405 (Method Not Found).  It will populate the "Allow" header
  56 with the list of implemented request methods.  You can override this behavior
  57 by implementing a custom 405 handler like so:
  58
  59    sub foo_not_implemented {
  60       ... handle not implemented methods ...
  61    }
  62
  63 If you do not provide an _OPTIONS subroutine, we will automatically respond
  64 with a 200 OK.  The "Allow" header will be populated with the list of
  65 implemented request methods.
  66
  67 It is likely that you really want to look at L<Catalyst::Controller::REST>,
  68 which brings this class together with automatic Serialization of requests
  69 and responses.
  70
  71 When you use this module, the request class will be changed to
  72 L<Catalyst::Request::REST>.
  73
  74 =head1 METHODS
  75
  76 =over 4
  77
  78 =item dispatch
  79
  80 This method overrides the default dispatch mechanism to the re-dispatching
  81 mechanism described above.
  82
  83 =cut
  84
  85 sub dispatch {
  86     my $self = shift;
  87     my $c    = shift;
  88
  89     my $controller = $c->component( $self->class );
  90     my $method     = $self->name . "_" . uc( $c->request->method );
  91     if ( $controller->can($method) ) {
  92         $c->execute( $self->class, $self, @{ $c->req->args } );
  93         return $controller->$method( $c, @{ $c->req->args } );
  94     } else {
  95         if ( $c->request->method eq "OPTIONS" ) {
  96             return $self->_return_options($c);
  97         } else {
  98             my $handle_ni = $self->name . "_not_implemented";
  99             if ( $controller->can($handle_ni) ) {
 100                 return $controller->$handle_ni( $c, @{ $c->req->args } );
 101             } else {
 102                 return $self->_return_not_implemented($c);
 103             }
 104         }
 105     }
 106 }
 107
 108 sub _return_options {
 109     my ( $self, $c ) = @_;
 110
 111     my @allowed = $self->_get_allowed_methods($c);
 112     $c->response->content_type('text/plain');
 113     $c->response->status(200);
 114     $c->response->header( 'Allow' => \@allowed );
 115 }
 116
 117 sub _get_allowed_methods {
 118     my ( $self, $c ) = @_;
 119
 120     my $controller = $self->class;
 121     my $methods    = Class::Inspector->methods($controller);
 122     my @allowed;
 123     foreach my $method ( @{$methods} ) {
 124         my $name = $self->name;
 125         if ( $method =~ /^$name\_(.+)$/ ) {
 126             push( @allowed, $1 );
 127         }
 128     }
 129     return @allowed;
 130 }
 131
 132 sub _return_not_implemented {
 133     my ( $self, $c ) = @_;
 134
 135     my @allowed = $self->_get_allowed_methods($c);
 136     $c->response->content_type('text/plain');
 137     $c->response->status(405);
 138     $c->response->header( 'Allow' => \@allowed );
 139     $c->response->body( "Method "
 140           . $c->request->method
 141           . " not implemented for "
 142           . $c->uri_for( $self->reverse ) );
 143 }
 144
 145 1;
 146
 147 =back
 148
 149 =head1 SEE ALSO
 150
 151 You likely want to look at L<Catalyst::Controller::REST>, which implements
 152 a sensible set of defaults for a controller doing REST.
 153
 154 L<Catalyst::Action::Serialize>, L<Catalyst::Action::Deserialize>
 155
 156 =head1 AUTHOR
 157
 158 Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
 159
 160 Marchex, Inc. paid me while I developed this module.  (http://www.marchex.com)
 161
 162 =head1 CONTRIBUTERS
 163
 164 Daisuke Maki <daisuke@endeworks.jp>
 165
 166 =head1 LICENSE
 167
 168 You may distribute this code under the same terms as Perl itself.
 169
 170 =cut
 171