Catalyst::Controller::Atompub::Collection - A Catalyst controller for the Atom Collection Resources
# Use the Catalyst helper $ perl script/myatom_create.pl controller MyCollection Atompub::Collection # And edit lib/MyAtom/Controller/MyCollection.pm package MyAtom::Controller::MyCollection; use base 'Catalyst::Controller::Atompub::Collection'; # List resources in a Feed Document, which must be implemented in # the mehtod with "Atompub(list)" attribute sub get_feed :Atompub(list) { my($self, $c) = @_; # Skeleton of the Feed (XML::Atom::Feed) was prepared by # C::C::Atompub my $feed = $self->collection_resource->body; # Retrieve Entries sorted in descending order my $rs = $c->model('DBIC::Entries')->search({}, { order_by => 'edited desc', }); # Add Entries to the Feed while (my $entry_resource = $rs->next) { my $entry = XML::Atom::Entry->new(\$entry_resource->xml); $feed->add_entry($entry); } # Return true on success 1; } # Create new Entry in the method with "Atompub(create)" attribute sub create_entry :Atompub(create) { my($self, $c) = @_; # URI of the new Entry, which was determined by C::C::Atompub my $uri = $self->entry_resource->uri; # app:edited element, which was assigned by C::C::Atompub, # is coverted into ISO 8601 format like '2007-01-01 00:00:00' my $edited = $self->edited->iso; # POSTed Entry (XML::Atom::Entry) my $entry = $self->entry_resource->body; # Create new Entry $c->model('DBIC::Entries')->create({ uri => $uri, edited => $edited, xml => $entry->as_xml, }); # Return true on success 1; } # Search the requested Entry in the method with "Atompub(read)" # attribute sub get_entry :Atompub(read) { my($self, $c) = @_; my $uri = $c->entry_resource->uri; # Retrieve the Entry my $rs = $c->model('DBIC::Entries')->find({ uri => $uri }); # Set the Entry my $entry = XML::Atom::Entry->new(\$rs->xml); $self->entry_resource->body($entry); # Return true on success 1; } # Update the requested Entry in the method with "Atompub(update)" # attribute sub update_entry :Atompub(update) { my($self, $c) = @_; my $uri = $c->entry_resource->uri; # app:edited element, which was assigned by C::C::Atompub, # is coverted into ISO 8601 format like '2007-01-01 00:00:00' my $edited = $self->edited->iso; # PUTted Entry (XML::Atom::Entry) my $entry = $self->entry_resource->body; # Update the Entry $c->model('DBIC::Entries')->find({ uri => $uri })->update({ uri => $uri, edited => $edited, xml => $entry->as_xml, }); # Return true on success 1; } # Delete the requested Entry in the method with "Atompub(delete)" # attribute sub delete_entry :Atompub(delete) { my($self, $c) = @_; my $uri = $c->entry_resource->uri; # Delete the Entry $c->model('DBIC::Entries')->find({ uri => $uri })->delete; # Return true on success 1; } # Access to http://localhost:3000/mycollection and get Feed Document
Catalyst::Controller::Atompub::Collection provides the following features:
Pre-processing requests
Catalyst::Controller::Atompub::Collection pre-processes the HTTP requests. All you have to do is just writing CRUD operations in the subroutines with Atompub attribute.
Media Resource support
Media Resources (binary data) as well as Entry Resources are supported. A Media Link Entry, which has an atom:link element to the newly created Media Resource, is given by Catalyst::Controller::Atompub::Collection.
Media type check
Catalyst::Controller::Atompub::Collection checks a media type of the POSTed/PUTted resource based on collection configuration.
Category check
Catalyst::Controller::Atompub::Collection checks atom:category elements in the POSTed/PUTted Entry Document based on collection configuration.
Cache controll and versioning
Cache controll and versioning are enabled just by overriding find_version method, which returns ETag and/or Last-Modified header.
find_version
Naming resources by Slug header
Resource URIs are determined based on Slug header if exists. If the Slug header is "Entry 1", the resource URI will be like:
http://localhost:3000/mycollection/entry_1.atom
The default naming rules can be changed by overriding make_edit_uri method.
make_edit_uri
One or more subclasses are required in your Atompub server implementation. In the subclasses, methods with the following attributes must be defined.
Lists resources in a Feed Document.
This method is expected to add Entries and other elements to a skeleton of the Feed. The following accessors can be used.
URI of Collection
Skeleton of Feed (XML::Atom::Feed)
Returns true on success, false otherwise.
Creates new resource.
In Collections with Entry Resources
The implementation is expected to insert the new Entry to your model, such as DBIx::Class. The following accessors can be used.
URI of New Entry
app:edited element of New Entry
New Entry (XML::Atom::Entry)
In Collections with Media Resources
The implementation is expected to insert new Media Link Entry as well as new Media Resource to your model, such as DBIx::Class.
The following accessors can be used for the Media Resource.
URI of New Media Resource
app:edited element of New Media Resource
Media type of New Media Resource
New Media Resource (a byte string)
The following accessors can be used for Media Link Entry.
URI of New Media Link Entry
app:edited element of New Media Link Entry
New Media Link Entry (XML::Atom::Entry)
Searchs the requested resource.
The implementation is expected to search the Entry, which must be stored in body accessor described below. The following accessors can be used.
body
Entry (XML::Atom::Entry)
The implementation is expected to search Media Resource or Media Link Entry, which must be stored in body accessor described below. The following accessors can be used for the Media Resource.
Media type of Media Resource
Media Resource (a byte string)
The following accessors can be used for the Media Link Entry.
Media Link Entry (XML::Atom::Entry)
Updates the requested resource.
The implementation is expected to update the Entry. The following accessors can be used.
URI of Entry
app:edited element of Entry
The implementation is expected to update the Media Resource or the Media Link Entry. The following accessors can be used for the Media Resource.
URI of Media Resource
app:edited element of Media Resource
URI of Media Link Entry
app:edited element of Media Link Entry
Deletes the requested resource.
The implementation is expected to delete the resource. If the collection contains Media Resources, corresponding Media Link Entry must be deleted at once.
The following methods can be overridden to change the default behaviors.
By overriding find_version method, cache control and versioning are enabled.
The implementation is expected to return ETag and/or Last-Modified value of the requested URI:
package MyAtom::Controller::MyCollection; sub find_version { my($self, $c, $uri) = @_; # Retrieve ETag and/or Last-Modified of $uri return (etag => $etag, last_modified => $last_modified); }
When a resource of the URI does not exist, the implementation must return an empty array.
The behavior of Atompub server will be changed in the following manner:
On GET request
Status code of 304 (Not Modified) will be returned, if the requested resource has not been changed.
On PUT request
Status code of 412 (Precondition Failed) will be returned, if the current version of the resource that a client is modifying is not the same as the version that the client is basing its modifications on.
By default, if the Slug header is "Entry 1", the resource URI will be like:
This default behavior can be changed by overriding find_version method:
package MyAtom::Controller::MyCollection; sub make_edit_uri { my($self, $c, @args) = @_; my @uris = $self->SUPER::make_edit_uri($c, @args); # Modify @uris as you like return @uris; }
Arguments @args are media types of POSTed resources.
This method returns an array of resource URIs; the first element is a URI of the Entry Resource (including Media Link Entry), and the second one is a URI of the Media Resource if exists.
The collection URI can be changed, by overriding default and edit_uri methods and modify the attributes.
default
edit_uri
In the following example, the collection URI is changed like /mycollection/<username> by overriding default and edit_uri methods. The new parameter <username> is obtained by $c->req->captures->[0] in the collection, or $c->user->username in the service document.
Override make_collection_uri method, if collection URI has to be changed.
make_collection_uri
See samples/OurBlogs in details.
package MyAtom::Controller::MyCollection; sub default :LocalRegex('^(\w+)$') { my($self, $c) = @_; $self->NEXT::default($c); } sub edit_uri :LocalRegex('^(\w+)/([.\w]+)$') { my($self, $c) = @_; $self->NEXT::edit_uri($c); } sub make_collection_uri { my($self, $c) = @_; my $class = ref $self || $self; $class->NEXT::make_collection_uri($c).'/' .(ref $c->controller eq $class ? $c->req->captures->[0] : $c->user->username); }
An accessor for a resource object except Media Link Entry.
An accessor for a Collection Resource object.
An accessor for an Entry Resource objecgt.
An accessor for a Media Resource object.
An accessor for a Media Link Entry object.
An accessor for a app:edited, which is applied for the POSTed/PUTted Entry Resource.
This module does not provide paging of Feed Documents. Paging mechanism should be implemented in a method with "Atompub(list)" attribute.
By default (no configuration), Collections accept Entry Documents (application/atom+xml) and any atom:category element.
Acceptable atom:category elements can be set like:
Controller::EntryCollection: collection: title: Diary categories: - fixed: yes scheme: http://example.com/cats/big3 category: - term: animal label: animal - term: vegetable label: vegetable - term: mineral scheme: http://example.com/dogs/big3 label: mineral
Acceptable media types is configured like:
Controller::MediaCollection: collection: title: Photo accept: - image/png - image/jpeg - image/gif
See ERROR HANDLING in Catalyst::Controller::Atompub::Base.
See SAMPLES in Catalyst::Controller::Atompub.
XML::Atom XML::Atom::Service Atompub Catalyst::Controller::Atompub
Takeru INOUE <takeru.inoue _ gmail.com>
<takeru.inoue _ gmail.com>
Copyright (c) 2007, Takeru INOUE <takeru.inoue _ gmail.com>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install Catalyst::Controller::Atompub, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Catalyst::Controller::Atompub
CPAN shell
perl -MCPAN -e shell install Catalyst::Controller::Atompub
For more information on module installation, please visit the detailed CPAN module installation guide.