lib/Catalyst/Action/Serialize.pm

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