Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WebService::GData::BasUser Contributed Perl DocumentWebService::GData::Base(3)

NAME
       WebService::GData::Base - core read/write methods over HTTP 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);

	   #the	content	type is	application/atom+xml; charset=UTF-8

	   my $ret = $base->insert($uri,$content,$callback);

	   #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 allows you to manipulate the data stored on	Google
       servers.	 It grants you access to the main read/write
       (get,post,insert,update,delete) methods available for the google	data
       APIs by wrapping	LWP methods.  Some actions require to be authenticated
       (ClientLogin,OAuth,SubAuth). If an authentication object	is set at
       construction time, it will be called to add any extra headers the
       authentication mechanism	requires.  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 get()	the feeds.  Unfortunately, if we can 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.

   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);

   PROXY METHODS
       Any call	to a method that is not	defined	in this	package	will be
       dispatched to the LWP::UserAgent	instance.  In getter context, they
       send back the WebService::GData::Base instance.

       Example:

	   use WebService::GData::Base;

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

	   #LWP::UserAgent timeout is set to 15
	   #and	will look after	environment variables for proxy	settings
	      $base->timeout(15)->env_proxy;

   SETTER/GETTER METHODS
       auth

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

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

	       - Headers required by the authentication	protocol.

	   o   "set_service_headers(base:WebService::GData::Base,req:HTTP::Request)"

	       - Extra headers required	by a particular	service.

	   o   "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.

	   Parameters

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

	   Returns

	   "auth:Object" in a setter/getter context.

	   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):

	   o   "get('value-name')" - Gives access to a parameter value

	   o   "to_query_string()" - return the	query string.

	   o   "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

	   "query:Object" in a setter/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);

       enable_compression

	   Set/get the compression mode.

	   Depending on	your perl configuration, you might be able to handle
	   data	compress using gzip.  By setting this method to	TRUE, the data
	   coming from Google servers will be gzipped and unzipped for you as
	   a convenience.  It may offer	a way to limit the number of bytes
	   exchanged over the network but requires more	calculation on your
	   side.  By default, compression mode is not enabled.

	   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.
	   "compression_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;
		   my $base = new WebService::GData::Base();
		  $base->enable_compression(TRUE);

	       my $ret = $base->get($url);#the data was	gzipped	and ungzipped if possible

       get_uri

	   Get the last	queried	uri.

	   Parameters

	   "none" - getter only

	   Returns

	   "uri:Scalar"	in a getter context, either undef if no	query has been
	   made	or the uri with	no query string	as a Scalar.

	   Example:

	       use WebService::GData::Base;

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

	       $base->get('http://www.example.com?v=2');

	       $base->get_uri();#'http://www.example.com'

       user_agent_name

	   Set or get the user agent name set.

	   Parameters

	   "none" - getter
	   "name:Scalar" - set the user	agent name

	   Returns

	   "user_agent_name:Scalar" the	full user agent	name when used in a
	   getter context

	   Example:

	       use WebService::GData::Base;

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

	       $base->get('http://www.example.com?v=2');

	       $base->user_agent_name();#WebService::GData::Base/2

	       $base->auth($auth);#where $auth->source eq 'MyApp-MyCompany-ID'

	       $base->user_agent_name();#MyApp-MyCompany-ID WebService::GData::Base/2

	       $base->user_agent_name("my app");#MyApp-MyCompany-ID my app WebService::GData::Base/2

   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	and change to query->to_query_string()

	       $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
       All the following methods will set the 'GData-Version' header by
       calling $this->query->get('v'); You should put the code in a eval { ...
       }; block	to catch any error these methods may throw.

       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.

	   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.

	   Parameters

	   "url:Scalar"	- the url to query
	   "content:Scalar" - 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/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.

	   Parameters

	   "url:Scalar"	- the url to query
	   "content:Scalar" - the content to put.

	   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).

	   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);

   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.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 425:
	   =back without =over

perl v5.24.1			  2011-04-30	    WebService::GData::Base(3)

NAME | SYNOPSIS | DESCRIPTION | DEPENDENCIES | BUGS AND LIMITATIONS | AUTHOR | LICENSE AND COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=WebService::GData::Base&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help