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