view release on metacpan or  search on metacpan

lib/Catalyst/Plugin/AtomServer.pm  view on Meta::CPAN

=item * Simple XML Views

I<Catalyst::View::Atom::XML> provides a base view class that your application
can subclass can use to provide a simple view. Given an I<XML::Atom>-based
class in C<$c-E<lt>stash-E<gt>{xml_atom_object}>, it will automatically
serialize the object to XML and set the appropriate response headers.

=item * Request Extensions

I<Catalyst::Plugin::AtomServer> extends the I<Catalyst::Request> object to
add a couple of useful methods:

=over 4

=item * $req->is_atom

Once you know that a particular request is an Atom request, your Catalyst
handler should set I<is_atom> to C<1>, like so:

    $c->request->is_atom(1);

=item * $req->url_parameters

Atom servers often implement parametrized requests in the I<path_info>
portion of the request URI. These parameters will be automatically split up
into the I<url_parameters> hash reference. For example, the URI

    /base/foo=bar/baz=quux/

would be split into the hash reference

    {
        foo => 'bar',
        baz => 'quux',
    }

=item * $req->body_parsed

A parsed XML document containing the Atom portion of the request (the entire
request content in the case of a REST request, and only the Atom portion of
a SOAP request).

You can pass this in directly to initialize an I<XML::Atom>-based object.
For example:

    my $entry = XML::Atom::Entry->new( Doc => $req->body_parsed );

=back

=item * Authentication

I<Catalyst::Plugin::Authentication::Credential::Atom> provides support for
Basic and WSSE authentication using an Atom envelope. WSSE is supported
using either SOAP or REST, and Basic is supported in REST only.

=item * REST and SOAP interfaces

The Atom API supports either a REST interface or a SOAP interface using
a document-literal SOAP envelope. I<Catalyst::Plugin::AtomServer> supports
both interfaces, transparently for your application.

=item * Error Handling

I<Catalyst::Plugin::AtomServer> will automatically catch any exceptions
thrown by your application, and it will wrap the exception in the proper
response expected by an Atom client.

=back

=head1 EXAMPLE

Below is an example server that implements authentication, dispatching,
and views.

    package My::App;
    use strict;

    use Catalyst qw( AtomServer
                     Authentication
                     Authentication::Credential::Atom
                     Authentication::Store::Minimal
                   );
    use My::App::View::XML;
    use XML::Atom::Feed;

    __PACKAGE__->config(
        name => 'MyApp',
        authentication => { users => { foo => { password => 'bar' } } },
    );

    __PACKAGE__->setup;

    sub default : Private {
        my($self, $c) = @_;
        $c->request->is_atom(1);
        my $method = $c->request->method;
        if ($method eq 'GET') {
            $c->forward('get_entries');
        }
    }

    sub get_entries : Private {
        my($self, $c) = @_;

        ## Authenticate the user using WSSE or Basic auth.
        $c->login_atom or die "Unauthenticated";

        my $feed = XML::Atom::Feed->new;
        $feed->title('Blog');
        $c->stash->{xml_atom_object} = $feed;
    }

    sub end : Private {
        my($self, $c) = @_;
        $c->forward('My::App::View::XML');
    }

    package My::App::View::XML;
    use base qw( Catalyst::View::Atom::XML );