WWW::Myspace::Data(3) User Contributed Perl DocumentationWWW::Myspace::Data(3)NAMEWWW::Myspace::Data - WWW::Myspace database interaction
VERSION
Version 0.06
SYNOPSIS
This module is the database interface for the WWW::Myspace modules. It
imports methods into the caller's namespace which allow the caller to
bypass the loader object by calling the methods directly. This module
is intended to be used as a back end for the Myspace modules, but it
can also be called directly from a script if you need direct database
access.
my %db = (
dsn => 'dbi:mysql:database_name',
user => 'username',
password => 'password',
);
# create a new object
my $data = WWW::Myspace::Data->new( $myspace, { db => \%db } );
# set up a database connection
my $loader = $data->loader();
# initialize the database with Myspace login info
my $account_id = $data->set_account( $username, $password );
# now do something useful...
my $update = $data->update_friend( $friend_id );
CONSTRUCTOR AND STARTUPnew()new() creates a WWW::Myspace::Data object, based on parameters which
are passed to it. You can (optionally) pass a valid WWW::Myspace
object to new as the first argument. If you just want database access,
there is no need to pass the myspace object. However, most update
methods require a valid login, so it's not a bad idea to pass it if you
don't mind the login overhead.
my %db = (
dsn => 'dbi:mysql:database_name',
user => 'username',
password => 'password',
);
my $data = WWW::Myspace::Data->new( $myspace, { db => \%db } );
Required Parameters
All parameters must be passed in the form of a hash reference.
· "db => HASHREF"
The db HASHREF can made up of the following 3 parameters:
Required Parameters
· "dsn => $value"
The dsn is passed directly to Class::DBI::Loader, so whatever
qualifies as a valid dsn for Class::DBI is valid here.
# for a MySQL database
'dbi:mysql:database_name'
# Or
# if you are using SQLite
'dbi:SQLite:dbname=/path/to/dbfile'
Optional Parameters
· "user => $value"
This is your database username. If you're running the script
from the command line, it will default to the user you are
logged in as.
· "password => $value"
Your database password (if any). If you don't need a password
to access your database, just leave this blank.
· "time_zone => $value"
This is any valid DateTime time zone designation. eg:
time_zone => 'America/Toronto'
Optional Parameters
· "config_file => $value"
If you prefer to keep your startup parameters in a file, pass a
valid filename to new.
Your startup file may contain any of the parameters that can be
passed to new() (except the $myspace object). Your config file
will be used to set the default parameters for startup. Any other
parameters which you also pass to new() will override the
corresponding values in the config file. So, if you have a default
setting for exclude_my_friends in your config file but also pass
exclude_my_friends directly to new(), the config file value will be
overriden. The default behaviour is not to look for a config file.
Default file format is YAML.
my $adder = WWW::Myspace::FriendAdder->(
$myspace,
{ config_file => '/path/to/adder_config.cfg', },
);
· "config_file_format => [YAML|CFG]"
If you have chosen to use a configuration file, you may state
explicitly which format you are using. You may choose between YAML
and Config::General. If you choose not to pass this parameter, it
will default to YAML.
loader( )
Before you do anything, call the loader() method. This returns the
Class::DBI::Loader object. Handy if you want to access the database
directly. If a loader object does not already exist, loader() will try
to create one.
my $loader = $data->loader();
# get a list of all your friends
my @friend_objects = WWW::Myspace::Data::Friends->retrieve_all;
set_account ( $account, $password )
In order to use the database, you'll need to store your account login
information in the accounts table. This method attempts to log in to
Myspace first. If successful, your login information will be stored.
If your account already exists in the accounts table, your password
will be updated to the password supplied to the method.
In order to use this module, you'll have to call this function at least
once. Once your account has been added to the database, there's no
need to call set_account again, provided you always use the same
Myspace account and you don't change your password information.
This mutator will also allow you to switch accounts within the same
object. So, you can switch from user A to user B, without creating a
new object. In order to prevent you from shooting yourself in the foot,
set_account() will die if it is unable to log in to Myspace with the
username/password you provide.
To prevent any problems, be sure to check the return value. If
successful, it returns the id of the account. That is, the id which
has been assigned to this account in the accounts table. Returns 0 if
there was a problem creating or updating the account.
get_account( )
Returns the account id assigned by the database for the account under
which $myspace is currently logged in. Mostly useful for internal
stuff, but it's available if you need it.
cache_friend( $friend_id )
Add this friend id to the friends table. cache_friend will not create
a relationship between the friend_id and any account. It just logs the
friend information in order to speed up various other operations. It's
basically an internal method, but you could use it to cache information
about any friend_id that isn't tied to any specific account. ie if you
are spidering myspace and you just want to collect info on anyone, you
can call this method.
update_friend( $friend_id )
The "friends" table in your local database stores information about
myspace friends, shared among all accounts using your database. This
lets you store additional information about them, such as their first
name, and is also used by WWW::Myspace methods and modules to track
information related to friends.
Basically this method calls cache_friend() and then creates a friend to
account relationship.
update_friend takes a single friend id and makes sure it is represented
in the local "friends" table. Returns 1 if the entry was successfully
updated. (Returns Class::DBI return value for the update).
my $data = new WWW::Myspace::Data( \%config );
$data->update_friend( $friend_id );
Optional Parameters
Optionally, using a hash reference as your second parameter, you may
supply update_friend with "freshness" parameters, to ensure that
updates are only performed on friend ids which have not been updated
since some arbitrary time. You would define expired data in the
following way:
my %freshness = (
days => 7,
hours => 12, );
$data->update_friend( $friend_id, { freshness => \%freshness } );
This would only update friend_ids which were updated more than 7.5 days
ago. Available parameters are:
· "years => $value"
· "months => $value"
· "days => $value"
· "hours => $value"
· "seconds => $value"
Each value should be an integer. If you do not supply freshness
criteria the default behaviour will be to update the friend regardless
of last update time.
update_all_friends( )
update_all_friends is really just a wrapper around update_friend This
method fetches a complete list of your friends currently listed at
Myspace and makes sure that all myspace users that are friends of your
account are represented in the local "friends" table. It does not
delete friends which may have been removed from your Myspace account
since your last update.
Just like update_friend, this method also takes "freshness" arguments.
$data->update_all_friend( { freshness => \%freshness } )
For more info on freshness parameters, see update_friend()
date_stamp( )
A wrapper around DateTime which provides a date stamp to be used when
entries are updated. This is essentially an internal routine. When
called internally the time zone is supplied from the value passed to
new().
Optional Parameters
· "time_zone => $value"
Any valid DateTime time zone, like 'America/Toronto' or
'America/Chicago'. Defaults to GMT.
· "epoch => $value"
Any positive number representing seconds since the epoch. Defaults
to current system time
my $date_stamp = $data->date_stamp(
{ time_zone => 'America/Toronto', epoch => time(), }
);
is_band( )
Calls is_band_from_cache to see if the friend id is a band profile. If
it returns undef, the function will look up the info using Myspace.pm's
is_band function, cache the info and return the result.
is_band_from_cache( )
Checks the database to see if the friend id is a band profile. Returns
undef if the id could not be found or band info is not cached for this
id.
friends_from_profile( { friend_id => $friend_id } )
This is "sort of" a wrapper around WWW::Myspace->friends_from_profile
The method will first check the database to see if there are any
friends listed for $friend_id. If friends exist, they will be
returned. Otherwise, the method will call
WWW::Myspace->friends_from_profile. It will cache the results, perform
a database lookup and then return the results to the caller. Aside
from speeding up lookups, this allows you to do some fancier limiting
and sorting when requesting data. This method doesn't take all of the
arguments that the Myspace module takes, so please read the docs
carefully.
Required Parameters
· "friend_id => $friend_id"
A valid Myspace friend id.
Optional Parameters
· "refresh => [0|1]"
Skip the database access and force the method to do a new lookup on
the Myspace site. This is useful if you want to add any new friend
ids which may have been added since you last ran this method.
Because the data that Myspace.com returns can't be trusted, friends
missing from a previous list will *not* be deleted from the cache.
· "limit => $value"
Limit the number of friends returned to some positive integer. By
default, no LIMIT is applied to queries.
· "offset => $value"
Used for OFFSET argument in a query. Must be used in tandem with
the limit parameter. Offset will set the amount of entries which
should be skipped before returning values. For example:
# Only return 500 results, beginning after the first 10
my @friend_ids = $data->friends_from_profile( {
friend_id => $my_friend_id,
limit => 500,
offset => 10,
} );
· "order_column => [friend_id | friend_since]"
The column by which to order returned results. Defaults to
"friend_id".
· "order_direction => [ASC | DESC]"
The direction by which to sort results. ASC (ascending) or DESC
(descending). Defaults to ASC.
So, for example, if you're starting from scratch and you want to start
with a complete list of your own friends in the database, you can do
something like this:
$data->set_account ( $account, $password );
my @friend_ids = $data->friends_from_profile( {
friend_id => $my_friend_id
} );
This will cache all of your friends by their id numbers. Because of
speed concerns, it will not cache any other info about them. If you
want more info on each friend, just add the following call:
foreach my $friend_id ( @friend_ids ) {
$data->cache_friend( $friend_id );
}
Here's how you might call this method using all available parameters:
my @friends = $data->friends_from_profile( {
friend_id => $friend_id,
refresh => 0,
limit => 100,
offset => 50,
order_direction => 'DESC',
order_column => 'friend_id',
} );
get_last_lookup_id ( )
Returns the friend id of the last id for which a Myspace.pm lookup was
performed. This is used by FriendAdder.pm to determine whether to
sleep after skipping a profile. If the lookup did not extend beyond
the database, there's no reason to sleep. May be useful for
troubleshooting as well.
is_cached( $friend_id )
Returns 1 if this friend is in the database, 0 if not.
_loader( )
This is a private method, which creates a Class::DBI::Loader object,
based on configuration parameters passed to new() To access the loader
object directly, use loader()
_die_pretty( )
Internal method that deletes the Myspace object from $self and then
prints $self via Data::Dumper. The Myspace object is so big, that when
you get it out of the way it can be easier to debug set parameters.
$adder->_die_pretty;
_add_friend_to_account ( { friend_id => $friend_id, account_id =>
$account_id } )
Internal method. Maps a friend to an account id in the db.
_find_or_create_friend( $friend_id )
Internal method. Adds friend id to db, but does not associate friend
with any account.
_friends_from_profile( $friend_id )
Internal method. Checks db for cached friends.
_fresh_after ( { days => $value } )
Internal method. Returns a DateTime object for time/data comparisons.
See update_friend for arguments that _fresh_after takes.
_is_fresh( $last_update_time, $fresh_after_time )
Internal method. Returns true if data is still "fresh", meaning that
the cached information does not need an update.
_regex_city ( $content )
Internal method. Regex to find City/Region data.
_regex_date ( $content )
Internal method. Regex to return last login time.
DATABASE SCHEMA
You'll find the database schema in a file called mysql.txt in the top
directory after untarring WWW::Myspace. This is a dump of the MySQL db
from phpMyAdmin. It can easily be altered for other database formats
(like SQLite). You can import the schema directly from the command
line:
mysql -u username -p databasename < mysql.txt
You may also use a utility like phpMyAdmin to import this file as SQL.
Keep in mind that the schema hasn't been 100% finalized and is subject
to change.
AUTHOR
Olaf Alders, "<olaf at wundersolutions.com>"
BUGS
Please report any bugs or feature requests to "bug-www-myspace at
rt.cpan.org", or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Myspace
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Myspace>. I will be
notified, and then you'll automatically be notified of progress on your
bug as I make changes.
NOTES
This module is still in its infancy. It does a lot of cool stuff, but
the interface is still subject to change. Please keep this in mind
when upgrading
TO DO
This module is in developer mode. We still need to finalize a database
schema and integrate it fully with the other WWW::Myspace modules.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WWW::Myspace::Data
You can also look for information at:
· AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/WWW-Myspace <http://annocpan.org/dist/WWW-
Myspace>
· CPAN Ratings
http://cpanratings.perl.org/d/WWW-Myspace
<http://cpanratings.perl.org/d/WWW-Myspace>
· RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Myspace
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Myspace>
· Search CPAN
http://search.cpan.org/dist/WWW-Myspace
<http://search.cpan.org/dist/WWW-Myspace>
ACKNOWLEDGEMENTS
Many thanks to Grant Grueninger for giving birth to WWW::Myspace and
for his help and advice in the development of this module.
COPYRIGHT & LICENSE
Copyright 2006 Olaf Alders, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2006-08-04 WWW::Myspace::Data(3)
