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