NAME

WebService::GData::Base - core read/write methods for google data API v2.

SYNOPSIS

    use WebService::GData::Base;

    #read only
        
    my $base = new WebService::GData::Base();

    my $ret  = $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated');
    my $feed = $ret->{feed};

    #give write access
        
    $base->auth($auth);

    #now you can
    #get hidden/private contents
        
    my $ret = $base->get('http://gdata.youtube.com/feeds/api/users/default/playlists');

    #new entry with application/x-www-form-urlencoded content-type
        
    my $ret = $base->post('http://gdata.youtube.com/feeds/api/users/default/playlists',$content);

    my $ret = $base->delete('http://gdata.youtube.com/feeds/api/users/playlist/'.$someid);

    #content is decorated with the xml entry basic tags
    #the content type is application/atom+xml; charset=UTF-8
        
    my $ret = $base->insert($uri,$content,$callback);

    #does a PUT. The content is decorated with the xml entry basic tags
    #the content type is application/atom+xml; charset=UTF-8
        
    my $ret = $base->update($uri,$content,$callback);

    #modify the query string query string: ?alt=jsonc&v=2&prettyprint=false&strict=true
        
    $base->query->alt('jsonc')->prettyprint('false');

    #overwrite WebService::GData::Query with youtube query parameters
        
    $base->query(new WebService::GData::YouTube::Query);

    #now the query will have the following query string: 
    #?alt=json&v=2&prettyprint=false&strict=true&safeSearch=none
        
    $base->query->safe_search('none');

DESCRIPTION

inherits from WebService::GData

This package grants you access to the main read/write methods available for the google data APIs by wrapping LWP methods. You gain access to: get,post,insert,update,delete. These methods calls the authentification objects to add extra headers. This package should be inherited by services (youtube,analytics,calendar) to offer higher level of abstraction.

Every _request (get,post,insert,update,delete) will throw a WebService::GData::Error in case of failure. It is therefore recommanded to enclose your code in eval blocks to catch and handle the error as you see fit.

The google data based APIs offer different format for the core protocol: atom based, rss based,json based, jsonc based. In order to offer good parsing performance, we use the json based response as a default to WebService::GData::Base::get() the feeds. Unfortunately, if we can set to read the feeds in json,the write methods require atom based data. The server also sends back an atom response too. We have therefore a hugly mixed of atom/json logic for now.

but...

The JSONC format which is now being incorporated in google data based services will offer the same level of interaction as the atom based protocol.

CONSTRUCTOR

new

Create an instance.

Parameters

auth:AuthObject (optional) - You can set an authorization object like WebService::GData::ClientLogin

Returns

WebService::GData::Base

Example:

    use WebService::GData::Base;
        
    my $base   = new WebService::GData::Base(auth=>$auth);

SETTER/GETTER METHODS

auth

Set/get an auth object that handles acess to protected contents. The auth object will be used by post/insert/update/delete methods by calling two methods:

set_authorization_headers(base:WebService::GData::Base,req:HTTP::Request)

- Headers required by the authentication protocol.
set_service_headers(base:WebService::GData::Base,req:HTTP::Request)

- Extra headers required by a particular service.
source()

- The name of the application. Will be used for the user agent string.

These methods will receive the instance calling them and the _request instance. They shall add any extra headers required to implement their own authentication protocol (ie,ClientLogin,OAuth,SubAuth). If the object can not handle the above methods it will not be set.

Example:

    use WebService::GData::Base;
        
    #should be in a eval {... }; block to catch an error...
        
    my $auth = new WebService::GData::ClientLogin(email=>...);

    my $base = new WebService::GData::Base(auth=>$auth);
        
    #or
        
    my $base   = new WebService::GData::Base(); 
       $base  -> auth($auth);

query

Set/get a query object that handles the creation of the query string. The query object will be used to add extra query parameters when calling WebService::GData::Base::get().

The query object should only implement the following methods (do not need to inherit from WebService::GData::Query):

get('value-name') - Gives access to a parameter value
to_query_string() - return the query string.
get('v') - should return a version number >=WebService::GData::Constants::GDATA_MINIMUM_VERSION

Parameters

none - use as a getter
query:Object - use as a setter: a query object defining the necessary methods.

Returns

void in a setter context.
query:Object in a getter context.

The WebService::GData::Query returns by default:

    '?alt=json&prettyprint=false&strict=true&v=2'

when to_query_string() is called.

When you call WebService::GData::Base::get(), you should only set an url with no query string:

Example:

    use WebService::GData::Constants qw(:all);
    use WebService::GData::Base;
        
    #should be in a eval { ... }; block...
    my $auth   = new WebService::GData::ClientLogin(email=>...);

    my $base   = new WebService::GData::Base(auth=>$auth);

    $base->query->alt(JSONC);
    
    $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated');
    #is in fact calling:
    #http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=jsonc&prettyprint=false&strict=true&v=2

    #or set a new query object:
    $base->query(new WebService::GData::YouTube::Query());

override_method

Set/get the override method.

Depending on your server configurations, you might not be able to set the method to PUT/DELETE/PATCH. This will forbid you to do any updates or deletes. In such a case, you should set override_method to TRUE so that it uses the POST method but override it by the proper value (ie,PUT/DELETE/PATCH) using X-HTTP-Method-Override.

Parameters

none - use as a getter
true_or_false:Scalar - use as a setter: WebService::GData::Constants::TRUE or WebService::GData::Constants::FALSE (default)

Returns

void in a setter context.
override_state:Scalar in a getter context, either WebService::GData::Constants::TRUE or WebService::GData::Constants::FALSE.

Example:

    use WebService::GData::Constants qw(:all);
    use WebService::GData::Base;
        
        
        #using override_method makes sense only if you are logged in
        #and want to do some write methods.

    my $auth = new WebService::GData::ClientLogin(email=>...);

    my $base = new WebService::GData::Base(auth=>$auth);

        $base->override_method(TRUE);
        
        $base->update($url,$content);

READ METHODS

get

Get the content of a feed in any format. If the format is json or jsonc, it will send back a perl object. If an auth object is specified, it will call the required methods to set the authentication headers. It will also set the 'GData-Version' header by calling $this->query->get('v'); You should put the code in a eval { ... }; block to catch any error.

Parameters

url:Scalar - an url to fetch that do not contain any query string.: Query string will be removed before sending the _request.

Returns

response:Object|Scalar - a perl object if it is a json or jsonc _request else the raw content.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    my $base   = new WebService::GData::Base();
    
    $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated');
        
    #is in fact calling:
    #http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=json&prettyprint=false&strict=true&v=2

    #the query string will be erased...
        
    $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=atom');
        
    #is in fact calling:
    #http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?alt=json&prettyprint=false&strict=true&v=2

WRITE METHODS

post

Post data to an url with application/x-www-form-urlencoded content type. An auth object must be specified. it will call the required methods to set the authentication headers. It will also set the 'GData-Version' header by calling $this->query->get('v'); You should put the code in a eval { ... }; block to catch any error.

Parameters

url:Scalar - the url to query
content:Scalar|Binary - the content to post

Returns

response:Scalar - the response to the query in case of success.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    #you must be authorized to do any write actions.
    my $base   = new WebService::GData::Base(auth=>...);
    
    #create a new entry with application/x-www-form-urlencoded content-type
    my $ret = $base->post($url,$content);

insert

Insert data to an url with application/atom+xml; charset=UTF-8 content type (POST). An auth object must be specified. it will call the required methods to set the authentication headers. It will also set the 'GData-Version' header by calling $this->query->get('v'); You should put the code in a eval { ... }; block to catch any error.

Parameters

url:Scalar - the url to query

content:Scalar - the content to post in xml format will be decorated with:

    <?xml version="1.0" encoding="UTF-8"?><entry $xmlns>$content</entry>

where $xmlns is the result of get_namespace.

Returns

response:Scalar - the response to the query in case of success.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    #you must be authorized to do any write actions.
    my $base   = new WebService::GData::Base(auth=>...);
    
    #create a new entry with application/atom+xml; charset=UTF-8 content-type
    my $ret = $base->insert($url,$content);

update

Update data to an url with application/atom+xml; charset=UTF-8 content type (PUT). An auth object must be specified. it will call the required methods to set the authentication headers. It will also set the 'GData-Version' header by calling $this->query->get('v'); You should put the code in a eval { ... }; block to catch any error.

Parameters

url:Scalar - the url to query

content:Scalar - the content to put in xml format will be decorated with:

    <?xml version="1.0" encoding="UTF-8"?><entry $xmlns>$content</entry>

where $xmlns is the result of get_namespace.

Returns

response:Scalar - the response to the query in case of success.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    #you must be authorized to do any write actions.
    my $base   = new WebService::GData::Base(auth=>...);
    
    #create a new entry with application/atom+xml; charset=UTF-8 content-type
    my $ret = $base->upate($url,$content);

delete

Delete data from an url with application/atom+xml; charset=UTF-8 content type (DELETE). An auth object must be specified. it will call the required methods to set the authentication headers. It will also set the 'GData-Version' header by calling $this->query->get('v'); You should put the code in a eval { ... }; block to catch any error.

Parameters

url:Scalar - the url to query

Returns

response:Scalar - the response to the query in case of success.

Throws

WebService::GData::Error if it fails to reach the contents.

Example:

    use WebService::GData::Base;
        
    #you must be authorized to do any write actions.
    my $base   = new WebService::GData::Base(auth=>...);
    
    #create a new entry with application/atom+xml; charset=UTF-8 content-type
    my $ret = $base->delete($url);

add_namespace

When inserting/updating contents, you will use an atom entry tag. This entry tag may contain tags that are not in the atom original namespace schema. You will need therefore to specify the extra namespaces used so that it gets parsed properly. Note that the atom namespace is already set by default and that WebService::GData::Constants already contains some predefined namespaces that you might want to use, less typing and if an update is necessary, it will be in this package, not in your source code.

Parameters

namespace:Scalar - the xml representation of a namespace,ie xmlns:media='http://search.yahoo.com/mrss/'

Returns

void

Example:

    use WebService::GData::Base qw(:namespace);
    use WebService::GData::Base;

        
    #you must be authorized to do any write actions.
    my $base   = new WebService::GData::Base(auth=>...);
    
    $base->add_namespace(MEDIA_NAMESPACE);
    $base->add_namespace(GDATA_NAMESPACE);
        
    #the content will be decorated with the above namespaces...
    my $ret = $base->insert($url,$content);

get_namespace

This method returns as a string separated by a space the namespaces set so far.

Parameters

none

Returns

namespaces:Scalar - all the namespaces set separated by a space. (Default to WebService::GData::Constants::ATOM_NAMESPACE)

Example:

    use WebService::GData::Constants qw(:namespace);
    use WebService::GData::Base;
                
    my $base   = new WebService::GData::Base();
    
    $base->add_namespace(MEDIA_NAMESPACE);
    $base->add_namespace(GDATA_NAMESPACE);
        
    #the content will be decorated with the above namespaces...
        
    my $namespaces = $base->get_namespace();

    #$namespaces = xmlns="http://www.w3.org/2005/Atom" xmlns:media='http://search.yahoo.com/mrss/' xmlns:gd="http://schemas.google.com/g/2005"

clean_namespace

This method resets all the namespaces set so far, including the default WebService::GData::Constants::ATOM_NAMESPACE.

Parameters

none

Returns

void

Example:

    use WebService::GData::Constants qw(:namespace);
    use WebService::GData::Base;
                
    my $base   = new WebService::GData::Base();
    
    $base->add_namespace(MEDIA_NAMESPACE);
    $base->add_namespace(GDATA_NAMESPACE);
        
    #the content will be decorated with the above namespaces...
        
    my $namespaces = $base->get_namespace();

    #$namespaces = xmlns="http://www.w3.org/2005/Atom" xmlns:media='http://search.yahoo.com/mrss/' xmlns:gd="http://schemas.google.com/g/2005"
        
    $base->clean_namespace();
    my $namespaces = $base->get_namespace();#""

HANDLING ERRORS

Google data APIs relies on querying remote urls on particular services.

Some of these services limits the number of _request with quotas and may return an error code in such a case.

All queries that fail will throw (die) a WebService::GData::Error object.

You should enclose all code that requires connecting to a service within eval blocks in order to handle it.

Example:

    use WebService::GData::Base;
        
    my $base   = new WebService::GData::Base();
        
    #the server is dead or the url is not available anymore or you've reach your quota of the day.
    #boom the application dies and your program fails...
    $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated');

    #with error handling...

    #enclose your code in a eval block...
    eval {
        $base->get('http://gdata.youtube.com/feeds/api/standardfeeds/top_rated');
    }; 

    #if something went wrong, you will get a WebService::GData::Error object back:
    if(my $error = $@){

        #do whatever you think is necessary to recover (or not)
        #print/log: $error->content,$error->code
    }

DEPENDENCIES

JSON

LWP

BUGS AND LIMITATIONS

If you do me the favor to _use_ this module and find a bug, please email me i will try to do my best to fix it (patches welcome)!

AUTHOR

shiriru <shirirulestheworld[arobas]gmail.com>

LICENSE AND COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install WebService::GData, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WebService::GData

CPAN shell

perl -MCPAN -e shell
install WebService::GData

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

new

SETTER/GETTER METHODS

auth

query

override_method

READ METHODS

get

WRITE METHODS

post

insert

update

delete

add_namespace

get_namespace

clean_namespace

HANDLING ERRORS

DEPENDENCIES

BUGS AND LIMITATIONS

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions