X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Action-REST.git;a=blobdiff_plain;f=lib%2FCatalyst%2FController%2FREST.pm;h=b77eb61431ee4f1fd6eacc0886728be10c93deba;hp=5d267b39df720f737476c9b27c3c021843c6f56b;hb=5cb5f6bb8bd7e95865e8e3eb238b482aa161aa0d;hpb=d4611771994693e9145e19c00c4b2d5bc7b485eb

diff --git a/lib/Catalyst/Controller/REST.pm b/lib/Catalyst/Controller/REST.pm
index 5d267b3..b77eb61 100644
--- a/lib/Catalyst/Controller/REST.pm
+++ b/lib/Catalyst/Controller/REST.pm
@@ -1,25 +1,32 @@
 package Catalyst::Controller::REST;
+use strict;
+use warnings;
+
+our $VERSION = '0.78';
+$VERSION = eval $VERSION;
 
 =head1 NAME
 
-Catalyst::Controller::REST - A RESTful controller 
+Catalyst::Controller::REST - A RESTful controller
 
 =head1 SYNOPSIS
 
     package Foo::Controller::Bar;
-
-    use base 'Catalyst::Controller::REST';
+    use Moose;
+    use namespace::autoclean;
+    
+    BEGIN { extends 'Catalyst::Controller::REST' }
 
     sub thing : Local : ActionClass('REST') { }
 
     # Answer GET requests to "thing"
     sub thing_GET {
        my ( $self, $c ) = @_;
-     
+
        # Return a 200 OK, with the data in entity
-       # serialized in the body 
+       # serialized in the body
        $self->status_ok(
-            $c, 
+            $c,
             entity => {
                 some => 'data',
                 foo  => 'is real bar-y',
@@ -28,31 +35,31 @@ Catalyst::Controller::REST - A RESTful controller
     }
 
     # Answer PUT requests to "thing"
-    sub thing_PUT { 
-      .. some action ..
+    sub thing_PUT {
+      ... some action ...
     }
 
 =head1 DESCRIPTION
 
 Catalyst::Controller::REST implements a mechanism for building
 RESTful services in Catalyst.  It does this by extending the
-normal Catalyst dispatch mechanism to allow for different 
-subroutines to be called based on the HTTP Method requested, 
+normal Catalyst dispatch mechanism to allow for different
+subroutines to be called based on the HTTP Method requested,
 while also transparently handling all the serialization/deserialization for
 you.
 
 This is probably best served by an example.  In the above
 controller, we have declared a Local Catalyst action on
-"sub thing", and have used the ActionClass('REST').  
+"sub thing", and have used the ActionClass('REST').
 
 Below, we have declared "thing_GET" and "thing_PUT".  Any
-GET requests to thing will be dispatched to "thing_GET", 
-while any PUT requests will be dispatched to "thing_PUT".  
+GET requests to thing will be dispatched to "thing_GET",
+while any PUT requests will be dispatched to "thing_PUT".
 
 Any unimplemented HTTP methods will be met with a "405 Method Not Allowed"
 response, automatically containing the proper list of available methods.  You
 can override this behavior through implementing a custom
-C<thing_not_implemented> method.  
+C<thing_not_implemented> method.
 
 If you do not provide an OPTIONS handler, we will respond to any OPTIONS
 requests with a "200 OK", populating the Allowed header automatically.
@@ -67,20 +74,25 @@ contents of $c->request->body based on the requests content-type header.
 A list of understood serialization formats is below.
 
 If we do not have (or cannot run) a serializer for a given content-type, a 415
-"Unsupported Media Type" error is generated. 
+"Unsupported Media Type" error is generated.
 
 To make your Controller RESTful, simply have it
 
-  use base 'Catalyst::Controller::REST'; 
+  BEGIN { extends 'Catalyst::Controller::REST' }
+
+=head1 CONFIGURATION
+
+See L<Catalyst::Action::Serialize/CONFIGURATION>. Note that the C<serialize>
+key has been deprecated.
 
 =head1 SERIALIZATION
 
 Catalyst::Controller::REST will automatically serialize your
 responses, and deserialize any POST, PUT or OPTIONS requests. It evaluates
 which serializer to use by mapping a content-type to a Serialization module.
-We select the content-type based on: 
+We select the content-type based on:
 
-=over 2
+=over
 
 =item B<The Content-Type Header>
 
@@ -93,7 +105,7 @@ If this is a GET request, you can supply a content-type query parameter.
 =item B<Evaluating the Accept Header>
 
 Finally, if the client provided an Accept header, we will evaluate
-it and use the best-ranked choice.  
+it and use the best-ranked choice.
 
 =back
 
@@ -101,56 +113,58 @@ it and use the best-ranked choice.
 
 A given serialization mechanism is only available if you have the underlying
 modules installed.  For example, you can't use XML::Simple if it's not already
-installed.  
+installed.
 
-In addition, each serializer has it's quirks in terms of what sorts of data
+In addition, each serializer has its quirks in terms of what sorts of data
 structures it will properly handle.  L<Catalyst::Controller::REST> makes
-no attempt to svae you from yourself in this regard. :) 
+no attempt to save you from yourself in this regard. :)
 
 =over 2
 
-=item C<text/x-yaml> => C<YAML::Syck>
+=item * C<text/x-yaml> => C<YAML::Syck>
 
 Returns YAML generated by L<YAML::Syck>.
 
-=item C<text/html> => C<YAML::HTML>
+=item * C<text/html> => C<YAML::HTML>
 
 This uses L<YAML::Syck> and L<URI::Find> to generate YAML with all URLs turned
 to hyperlinks.  Only useable for Serialization.
 
-=item C<text/x-json> => C<JSON::Syck>
+=item * C<application/json> => C<JSON>
 
-Uses L<JSON::Syck> to generate JSON output
+Uses L<JSON> to generate JSON output.  It is strongly advised to also have
+L<JSON::XS> installed.  The C<text/x-json> content type is supported but is
+deprecated and you will receive warnings in your log.
 
-=item C<text/x-data-dumper> => C<Data::Serializer>
+=item * C<text/x-data-dumper> => C<Data::Serializer>
 
 Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
 
-=item C<text/x-data-denter> => C<Data::Serializer>
+=item * C<text/x-data-denter> => C<Data::Serializer>
 
 Uses the L<Data::Serializer> module to generate L<Data::Denter> output.
 
-=item C<text/x-data-taxi> => C<Data::Serializer>
+=item * C<text/x-data-taxi> => C<Data::Serializer>
 
 Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
 
-=item C<application/x-storable> => C<Data::Serializer>
+=item * C<application/x-storable> => C<Data::Serializer>
 
 Uses the L<Data::Serializer> module to generate L<Storable> output.
 
-=item C<application/x-freezethaw> => C<Data::Serializer>
+=item * C<application/x-freezethaw> => C<Data::Serializer>
 
 Uses the L<Data::Serializer> module to generate L<FreezeThaw> output.
 
-=item C<text/x-config-general> => C<Data::Serializer>
+=item * C<text/x-config-general> => C<Data::Serializer>
 
 Uses the L<Data::Serializer> module to generate L<Config::General> output.
 
-=item C<text/x-php-serialization> => C<Data::Serializer>
+=item * C<text/x-php-serialization> => C<Data::Serializer>
 
 Uses the L<Data::Serializer> module to generate L<PHP::Serialization> output.
 
-=item C<text/xml> => C<XML::Simple>
+=item * C<text/xml> => C<XML::Simple>
 
 Uses L<XML::Simple> to generate XML output.  This is probably not suitable
 for any real heavy XML work. Due to L<XML::Simple>s requirement that the data
@@ -158,37 +172,63 @@ you serialize be a HASHREF, we transform outgoing data to be in the form of:
 
   { data => $yourdata }
 
-=item L<View>
+=item * L<View>
 
-Uses a regular Catalyst view.  For example, if you wanted to have your 
-C<text/html> and C<text/xml> views rendered by TT:
+Uses a regular Catalyst view.  For example, if you wanted to have your
+C<text/html> and C<text/xml> views rendered by TT, set:
 
-	'text/html' => [ 'View', 'TT' ],
-	'text/xml'  => [ 'View', 'XML' ],
-	
-Will do the trick nicely. 
+  __PACKAGE__->config(
+      map => {
+          'text/html' => [ 'View', 'TT' ],
+          'text/xml'  => [ 'View', 'XML' ],
+      }
+  );
 
-=back
+Your views should have a C<process> method like this:
 
-By default, L<Catalyst::Controller::REST> will return a C<415 Unsupported Media Type>
-response if an attempt to use an unsupported content-type is made.  You
-can ensure that something is always returned by setting the C<default>
-config option:
+  sub process {
+      my ( $self, $c, $stash_key ) = @_;
 
-   __PACKAGE__->config->{'default'} = 'text/x-yaml';
+      my $output;
+      eval {
+          $output = $self->serialize( $c->stash->{$stash_key} );
+      };
+      return $@ if $@;
 
-Would make it always fall back to the serializer plugin defined for text/x-yaml.
+      $c->response->body( $output );
+      return 1;  # important
+  }
+  
+  sub serialize {
+      my ( $self, $data ) = @_;
 
-Implementing new Serialization formats is easy!  Contributions
-are most welcome!  See L<Catalyst::Action::Serialize> and
-L<Catalyst::Action::Deserialize> for more information.
+      my $serialized = ... process $data here ...
+
+      return $serialized;
+  }
+
+=back
+
+By default, L<Catalyst::Controller::REST> will return a 
+C<415 Unsupported Media Type> response if an attempt to use an unsupported
+content-type is made.  You can ensure that something is always returned by
+setting the C<default> config option:
+
+  __PACKAGE__->config(default => 'text/x-yaml');
+
+would make it always fall back to the serializer plugin defined for
+C<text/x-yaml>.
 
 =head1 CUSTOM SERIALIZERS
 
-If you would like to implement a custom serializer, you should create two new
-modules in the L<Catalyst::Action::Serialize> and
-L<Catalyst::Action::Deserialize> namespace.  Then assign your new class
-to the content-type's you want, and you're done.
+Implementing new Serialization formats is easy!  Contributions
+are most welcome!  If you would like to implement a custom serializer, 
+you should create two new modules in the L<Catalyst::Action::Serialize>
+and L<Catalyst::Action::Deserialize> namespace.  Then assign your new
+class to the content-type's you want, and you're done.
+
+See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize> 
+for more information.
 
 =head1 STATUS HELPERS
 
@@ -197,43 +237,40 @@ Using them will ensure that you are responding with the proper codes,
 headers, and entities.
 
 These helpers try and conform to the HTTP 1.1 Specification.  You can
-refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.  
+refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
 These routines are all implemented as regular subroutines, and as
 such require you pass the current context ($c) as the first argument.
 
-=over 4
+=over
 
 =cut
 
-use strict;
-use warnings;
 use base 'Catalyst::Controller';
 use Params::Validate qw(SCALAR OBJECT);
 
 __PACKAGE__->mk_accessors(qw(serialize));
 
 __PACKAGE__->config(
-        'stash_key' => 'rest',
-        'map'       => {
-            'text/html'          => 'YAML::HTML',
-            'text/xml'           => 'XML::Simple',
-            'text/x-yaml'        => 'YAML',
-            'text/x-json'        => 'JSON',
-            'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
-            'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
-            'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
-            'application/x-storable'    => [ 'Data::Serializer', 'Storable'     ],
-            'application/x-freezethaw'  => [ 'Data::Serializer', 'FreezeThaw'   ],
-            'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
-            'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
-        },
+    'stash_key' => 'rest',
+    'map'       => {
+        'text/html'          => 'YAML::HTML',
+        'text/xml'           => 'XML::Simple',
+        'text/x-yaml'        => 'YAML',
+        'application/json'   => 'JSON',
+        'text/x-json'        => 'JSON',
+        'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
+        'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
+        'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
+        'application/x-storable'   => [ 'Data::Serializer', 'Storable' ],
+        'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
+        'text/x-config-general'    => [ 'Data::Serializer', 'Config::General' ],
+        'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
+    },
 );
 
-sub begin : ActionClass('Deserialize') {
-}
+sub begin : ActionClass('Deserialize') { }
 
-sub end : ActionClass('Serialize') {
-}
+sub end : ActionClass('Serialize') { }
 
 =item status_ok
 
@@ -242,7 +279,7 @@ Returns a "200 OK" response.  Takes an "entity" to serialize.
 Example:
 
   $self->status_ok(
-    $c, 
+    $c,
     entity => {
         radiohead => "Is a good band!",
     }
@@ -268,7 +305,7 @@ and a "location" where the created object can be found.
 Example:
 
   $self->status_created(
-    $c, 
+    $c,
     location => $c->req->uri->as_string,
     entity => {
         radiohead => "Is a good band!",
@@ -310,7 +347,7 @@ Returns a "202 ACCEPTED" response.  Takes an "entity" to serialize.
 Example:
 
   $self->status_accepted(
-    $c, 
+    $c,
     entity => {
         status => "queued",
     }
@@ -328,6 +365,20 @@ sub status_accepted {
     return 1;
 }
 
+=item status_no_content
+
+Returns a "204 NO CONTENT" response.
+
+=cut
+
+sub status_no_content {
+    my $self = shift;
+    my $c    = shift;
+    $c->response->status(204);
+    $self->_set_entity( $c, undef );
+    return 1.;
+}
+
 =item status_bad_request
 
 Returns a "400 BAD REQUEST" response.  Takes a "message" argument
@@ -337,7 +388,7 @@ response.
 Example:
 
   $self->status_bad_request(
-    $c, 
+    $c,
     message => "Cannot do what you have asked!",
   );
 
@@ -363,7 +414,7 @@ response.
 Example:
 
   $self->status_not_found(
-    $c, 
+    $c,
     message => "Cannot find what you were looking for!",
   );
 
@@ -380,6 +431,31 @@ sub status_not_found {
     return 1;
 }
 
+=item gone
+
+Returns a "41O GONE" response.  Takes a "message" argument as a scalar,
+which will become the value of "error" in the serialized response.
+
+Example:
+
+  $self->status_gone(
+    $c,
+    message => "The document have been deleted by foo",
+  );
+
+=cut
+
+sub status_gone {
+    my $self = shift;
+    my $c    = shift;
+    my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
+
+    $c->response->status(410);
+    $c->log->debug( "Status Gone " . $p{'message'} ) if $c->debug;
+    $self->_set_entity( $c, { error => $p{'message'} } );
+    return 1;
+}
+
 sub _set_entity {
     my $self   = shift;
     my $c      = shift;
@@ -409,25 +485,21 @@ L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>.  It should
 This class provides a default configuration for Serialization.  It is currently:
 
   __PACKAGE__->config(
-      serialize => {
-         'stash_key' => 'rest',
-         'map'       => {
-            'text/html'          => 'YAML::HTML',
-            'text/xml'           => 'XML::Simple',
-            'text/x-yaml'        => 'YAML',
-            'text/x-json'        => 'JSON',
-            'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
-            'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
-            'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
-            'application/x-storable'    => [ 'Data::Serializer', 'Storable'     
-],
-            'application/x-freezethaw'  => [ 'Data::Serializer', 'FreezeThaw'   
-],
-            'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ]
-,
-            'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
-          },
-      }
+      'stash_key' => 'rest',
+      'map'       => {
+         'text/html'          => 'YAML::HTML',
+         'text/xml'           => 'XML::Simple',
+         'text/x-yaml'        => 'YAML',
+         'application/json'   => 'JSON',
+         'text/x-json'        => 'JSON',
+         'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
+         'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
+         'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
+         'application/x-storable'   => [ 'Data::Serializer', 'Storable' ],
+         'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
+         'text/x-config-general'    => [ 'Data::Serializer', 'Config::General' ],
+         'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
+      },
   );
 
 You can read the full set of options for this configuration block in
@@ -438,7 +510,7 @@ L<Catalyst::Action::Serialize>.
 The C<begin> method uses L<Catalyst::Action::Deserialize>.  The C<end>
 method uses L<Catalyst::Action::Serialize>.  If you want to override
 either behavior, simply implement your own C<begin> and C<end> actions
-and use NEXT:
+and use MRO::Compat:
 
   my Foo::Controller::Monkey;
   use base qw(Catalyst::Controller::REST);
@@ -446,17 +518,19 @@ and use NEXT:
   sub begin :Private {
     my ($self, $c) = @_;
     ... do things before Deserializing ...
-    $self->NEXT::begin($c); 
+    $self->maybe::next::method($c);
     ... do things after Deserializing ...
-  } 
+  }
 
   sub end :Private {
     my ($self, $c) = @_;
     ... do things before Serializing ...
-    $self->NEXT::end($c); 
+    $self->maybe::next::method($c);
     ... do things after Serializing ...
   }
 
+=back
+
 =head1 A MILD WARNING
 
 I have code in production using L<Catalyst::Controller::REST>.  That said,
@@ -476,11 +550,9 @@ Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
 
 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
 
-=head1 AUTHOR
-
-Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
+=head1 AUTHORS
 
-Marchex, Inc. paid me while I developed this module.  (http://www.marchex.com)
+See L<Catalyst::Action::REST> for authors.
 
 =head1 LICENSE