view release on metacpan or  search on metacpan

lib/Atompub/Client.pm  view on Meta::CPAN

sub new {
    my($class, $args) = @_;
    my $rc = $args->{resource} || $args->{rc} or return;
    bless {
	resource      => $rc,
	last_modified => $args->{last_modified},
	etag          => $args->{etag},
    }, $class;
}

1;
__END__

=head1 NAME

Atompub::Client - A client for the Atom Publishing Protocol


=head1 SYNOPSIS

    use Atompub::Client;

    my $client = Atompub::Client->new;
    $client->username('Melody');
    $client->password('Nelson');
    #$client->proxy( $proxy_uri );

    # Get a Service Document
    my $service = $client->getService($service_uri);

    my @workspaces = $service->workspaces;
    my @collections = $workspaces[0]->collections;

    # CRUD an Entry Resource; assuming that the 0-th collection supports
    # Entry Resources
    my $collection_uri = $collections[0]->href;

    my $name = 'New Post';

    my $entry = XML::Atom::Entry->new;
    $entry->title($name);
    $entry->content('Content of my post.');

    my $edit_uri = $client->createEntry($collection_uri, $entry, $name);

    my $feed = $client->getFeed($collection_uri);
    my @entries = $feed->entries;

    $entry = $client->getEntry($edit_uri);

    $client->updateEntry($edit_uri, $entry);

    $client->deleteEntry($edit_uri);

    # CRUD a Media Resource; assuming that the 1-st collection supports
    # Media Resources
    my $collection_uri = $collections[1]->href;

    my $name = 'My Photo';

    my $edit_uri = $client->createMedia($collection_uri, 'sample1.png',
                                        'image/png', $name);

    # Get a href attribute of an "edit-media" link
    my $edit_media_uri = $client->resource->edit_media_link;

    my $binary = $client->getMedia($edit_media_uri);

    $client->updateMedia($edit_media_uri, 'sample2.png', 'image/png');

    $client->deleteEntry($edit_media_uri);

    # Access to the requested HTTP::Request object
    my $request  = $client->request;

    # Access to the received HTTP::Response object
    my $response = $client->response;

    # Access to the received resource (XML::Atom object or binary data)
    my $resource = $client->resource;


=head1 DESCRIPTION

L<Atompub::Client> implements a client for the Atom Publishing Protocol
described at L<http://www.ietf.org/rfc/rfc5023.txt>.

The client supports the following features:

=over 4

=item * Authentication

L<Atompub::Client> supports the Basic and WSSE Authentication described in
L<http://www.intertwingly.net/wiki/pie/DifferentlyAbledClients>.

=item * Service Document

L<Atompub::Client> understands Service Documents,
in which information of collections are described,
such as URIs, acceptable media types, and allowable categories.

=item * Media Resource support

Media Resources (binary data) as well as Entry Resources are supported.
You can create and edit Media Resources such as image and video
by using L<Atompub::Client>.

=item * Media type check

L<Atompub::Client> checks media types of resources
before creating and editing them to the collection.
Acceptable media types are shown in I<app:accept> elements in the Service Document.

=item * Category check

L<Atompub::Client> checks categories in Entry Resources
before creating and editing them to the collection.
Allowable categories are shown in I<app:categories> elements in the Service Document.

=item * Cache controll and versioning

On-memory cache and versioning, which are controlled by I<ETag> and I<Last-Modified> header,
are implemented in L<Atompub::Client>.

=item * Naming resources by I<Slug> header

The client can specify I<Slug> header when creating a resource,
which may be used as part of the resource URI.

=back


=head1 METHODS

=head2 Atompub::Client->new([ %options ])

Creates a new Atompub client object.
The options are same as L<LWP::UserAgent>.


=head2 $client->getService($service_uri)

Retrieves a Service Document at URI $service_uri.

Returns an L<XML::Atom::Service> object on success, false otherwise.


=head2 $client->getCategories($category_uri)

Retrieves a Category Document at URI $category_uri.

Returns an L<XML::Atom::Categories> object on success, false otherwise.


=head2 $client->getFeed($collection_uri)

Retrieves a Feed Document from the collection at URI $collection_uri.

Returns an L<XML::Atom::Feed> object, false otherwise.


=head2 $client->createEntry($collection_uri, $entry, [ $slug ])

Creates a new entry in the collection at URI $collection_uri.

$entry must be an L<XML::Atom::Entry> object.

If $slug is provided, it is set in I<Slug> header and may be used
as part of the resource URI.

Returns a I<Location> header, which contains a URI of the newly created resource,
or false on error.


=head2 $client->createMedia($collection_uri, $media, $media_type, [ $slug ])

Creates a new Media Resource and a Media Link Entry in the collection
at URI $collection_uri.

If $media is a reference to a scalar, it is treated as the binary.
If a scalar, treated as a file containing the Media Resource.

$media_type is the media type of the Media Resource, such as 'image/png'.

$slug is set in the I<Slug> header, and may be used as part of
the resource URI.

Returns a I<Location> header, which contains a URI of the newly created resource,
or false on error.


=head2 $client->getEntry($edit_uri)

Retrieves an Entry Document with the given URI $edit_uri.

Returns an L<XML::Atom::Entry> object on success, false otherwise.
If the server returns 304 (Not Modified), returns a cache of the Media Resource.


=head2 $client->getMedia($edit_uri)

Retrieves a Media Resource with the given URI $edit_uri.

Returns binary data of the Media Resource on success, false otherwise.
If the server returns 304 (Not Modified), returns a cache of the Media Resource.


=head2 $client->updateEntry($edit_uri, $entry)

Updates the Entry Document at URI $edit_uri with the new Entry Document $entry,
which must be an L<XML::Atom::Entry> object.

Returns true on success, false otherwise.


=head2 $client->updateMedia($edit_uri, $media, $media_type)

Updates the Media Resource at URI $edit_uri with the $media.

If $media is a reference to a scalar, it is treated as the binary.
If a scalar, treated as a file containing the Media Resource.

$media_type is the media type of the Media Resource, such as 'image/png'.

Returns true on success, false otherwise.


=head2 $client->deleteEntry($edit_uri)

Deletes the Entry Document at URI $edit_uri.

Returns true on success, false otherwise.


=head2 $client->deleteMedia($edit_uri)

Deletes the Media Resource at URI $edit_uri and related Media Link Entry.

Returns true on success, false otherwise.


=head1 Accessors

=head2 $client->username([ $username ])

If called with an argument, sets the username for login to $username.

Returns the current username that will be used when logging in to the
Atompub server.


=head2 $client->password([ $password ])

If called with an argument, sets the password for login to $password.

Returns the current password that will be used when logging in to the 
Atompub server.


=head2 $client->proxy([ $proxy_uri ])

If called with an argument, sets URI of proxy server like 'http://proxy.example.com:8080'.

Returns the current URI of the proxy server.


=head2 $client->resource

=head2 $client->rc

An accessor for Entry or Media Resource, which was retrieved in the previous action.


=head2 $client->request

=head2 $client->req

An accessor for an L<HTTP::Request> object, which was used in the previous action.


=head2 $client->response

=head2 $client->res