lib/Catalyst/Action/Serialize.pm

   1 #
   2 # Catlyst::Action::Serialize.pm
   3 # Created by: Adam Jacob, Marchex, <adam@hjksolutions.com>
   4 #
   5 # $Id$
   6
   7 package Catalyst::Action::Serialize;
   8
   9 use strict;
  10 use warnings;
  11
  12 use base 'Catalyst::Action::SerializeBase';
  13 use Module::Pluggable::Object;
  14 use MRO::Compat;
  15
  16 sub execute {
  17     my $self = shift;
  18     my ( $controller, $c ) = @_;
  19
  20     $self->maybe::next::method(@_);
  21
  22     return 1 if $c->req->method eq 'HEAD';
  23     return 1 if length( $c->response->body );
  24     return 1 if scalar @{ $c->error };
  25     return 1 if $c->response->status =~ /^(?:204|3\d\d)$/;
  26
  27     my ( $sclass, $sarg, $content_type ) =
  28       $self->_load_content_plugins( "Catalyst::Action::Serialize",
  29         $controller, $c );
  30     unless ( defined($sclass) ) {
  31         if ( defined($content_type) ) {
  32             $c->log->info("Could not find a serializer for $content_type");
  33         } else {
  34             $c->log->info(
  35                 "Could not find a serializer for an empty content-type");
  36         }
  37         return 1;
  38     }
  39     $c->log->debug(
  40         "Serializing with $sclass" . ( $sarg ? " [$sarg]" : '' ) ) if $c->debug;
  41
  42     my $rc;
  43     if ( defined($sarg) ) {
  44         $rc = $sclass->execute( $controller, $c, $sarg );
  45     } else {
  46         $rc = $sclass->execute( $controller, $c );
  47     }
  48     if ( $rc eq 0 ) {
  49         return $self->_unsupported_media_type( $c, $content_type );
  50     } elsif ( $rc ne 1 ) {
  51         return $self->_serialize_bad_request( $c, $content_type, $rc );
  52     }
  53
  54     return 1;
  55 }
  56
  57 1;
  58
  59 =head1 NAME
  60
  61 Catalyst::Action::Serialize - Serialize Data in a Response
  62
  63 =head1 SYNOPSIS
  64
  65     package Foo::Controller::Bar;
  66
  67     __PACKAGE__->config(
  68         'default'   => 'text/x-yaml',
  69         'stash_key' => 'rest',
  70         'map'       => {
  71             'text/html'          => [ 'View', 'TT', ],
  72             'text/x-yaml'        => 'YAML',
  73             'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
  74         }
  75     );
  76
  77     sub end :ActionClass('Serialize') {}
  78
  79 =head1 DESCRIPTION
  80
  81 This action will serialize the body of an HTTP Response.  The serializer is
  82 selected by introspecting the HTTP Requests content-type header.
  83
  84 It requires that your Catalyst controller is properly configured to set up the
  85 mapping between Content Type's and Serialization classes.
  86
  87 The specifics of serializing each content-type is implemented as a plugin to
  88 L<Catalyst::Action::Serialize>.
  89
  90 Typically, you would use this ActionClass on your C<end> method.  However,
  91 nothing is stopping you from choosing specific methods to Serialize:
  92
  93   sub foo :Local :ActionClass('Serialize') {
  94      .. populate stash with data ..
  95   }
  96
  97 When you use this module, the request class will be changed to
  98 L<Catalyst::Request::REST>.
  99
 100 =head1 CONFIGURATION
 101
 102 =head2 map
 103
 104 Takes a hashref, mapping Content-Types to a given serializer plugin.
 105
 106 =head2 default
 107
 108 This is the 'fall-back' Content-Type if none of the requested or acceptable
 109 types is found in the L</map>. It must be an entry in the L</map>.
 110
 111 =head2 stash_key
 112
 113 Specifies the key of the stash entry holding the data that is to be serialized.
 114 So if the value is "rest", we will serialize the data under:
 115
 116   $c->stash->{'rest'}
 117
 118 =head2 content_type_stash_key
 119
 120 Specifies the key of the stash entry that optionally holds an overriding
 121 Content-Type. If set, and if the specified stash entry has a valid value,
 122 then it takes priority over the requested content types.
 123
 124 This can be useful if you want to dynamically force a particular content type,
 125 perhaps for debugging.
 126
 127 =head1 HELPFUL PEOPLE
 128
 129 Daisuke Maki pointed out that early versions of this Action did not play
 130 well with others, or generally behave in a way that was very consistent
 131 with the rest of Catalyst.
 132
 133 =head1 SEE ALSO
 134
 135 You likely want to look at L<Catalyst::Controller::REST>, which implements
 136 a sensible set of defaults for doing a REST controller.
 137
 138 L<Catalyst::Action::Deserialize>, L<Catalyst::Action::REST>
 139
 140 =head1 AUTHORS
 141
 142 See L<Catalyst::Action::REST> for authors.
 143
 144 =head1 LICENSE
 145
 146 You may distribute this code under the same terms as Perl itself.
 147
 148 =cut