The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-Myspace-Data-0.17
++
/ WWW::Myspace::Data

NAME

WWW::Myspace::Data - WWW::Myspace database interaction

VERSION

Version 0.17

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 STARTUP

new()

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.

track_friend

Please note that this function requires an additional database table ("tracking") that has been added to the mysql.txt as of version 0.07. The method returns a Class::DBI object representing the row which has just been inserted.

 EXAMPLE
 
 my $tracking = $data->track_friend( friend_id => $friend_id );
 
 OR
 
 my $page = $myspace->get_profile( $friend_id );
 my $tracking = $data->track_friend( page => $page );
 
 print "views: " . $tracking->profile_views . "\n";
 
 print "friends: " . $tracking->friend_count . "\n";
 
 print "comments: " . $tracking->comment_count . "\n";

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(), } 
    );

  • format => 'dt'

    This option will cause the method to return the actual DateTime object rather than a string. Can be handy if you just need a DateTime object and want it initialized with the proper time zone.

is_band( $friend_id )

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( $friend_id )

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.

is_invalid( $friend_id )

Checks the database to see if the friend id is a valid (ie active) id. Returns 1 if true, 0 if false and undef if no data is on file.

is_private( $friend_id )

Checks the database to see if the friend id is set to "private". Returns 1 if true, 0 if false and undef if no data is on file.

get_age( $friend_id )

Checks the database to get the age of the friend, if it's cached there. Otherwise, returns null.

last_login( $friend_id )

Checks the database to get the last login time of the friend, if it's cached there. Otherwise, returns null.

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 accept all of the arguments that the WWW::Myspace 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',
    } );

approve_friend_requests

A wrapper around WWW::Myspace->approve_friend_requests(). Calls this method and then logs the friend requests which have been accepted. Returns the list of friend_ids which have been approved.

post_comment

A wrapper around WWW::Myspace->post_comment(). Calls this method and then logs the comment details. Returns the return value of WWW::Myspace->post_comment().

get_comments( friend_id => $friend_id )

A wrapper around WWW::Myspace->get_comments(). Calls this method and caches the results. This method is efficient and only retrieves comments not cached previously.

send_message( %options )

A wrapper around WWW::Myspace->send_message(). Calls this method and then logs the message details. Returns the return value of WWW::Myspace->send_message() This method accepts the %options hash -- not the positional parameters.

get_last_lookup_id ( )

Returns the friend id of the last id for which a WWW::Myspace.pm lookup was performed. This is used by WWW::Myspace::FriendAdder 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( $params_hashref )

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::Data. 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.

DEPENDENCIES

This module may have varying dependencies, depending on which database server you opt to use (MySQL, SQLite etc). For this reason, you may need to install modules in addition to those which were included with the default install.

For example, if you are using MySQL, you will need to install the following modules if they are not already on your system:

SQLite will require:

Postgres (untested) will require:

AUTHOR

Olaf Alders, <olaf at wundersolutions.com>

BUGS

The following Class::DBI issue has been reported:

Please report any bugs or feature requests to bug-www-myspace-data at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Myspace-Data. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

NOTES

This module has been stable for some time. Myspace, however, is not. The code does a lot of cool stuff, but the database schema is subject to change. Database changes will be tracked in the "mysql_changes.txt" file, which is included in the distribution. Please keep this in mind when upgrading.

TO DO

This module provides a wrapper around many, but by no means all of the WWW::Myspace functions. I've written it to suit my own needs. If it does not suit all of yours, patches are very welcome.

These scripts have been tested on Mac and Ubuntu platforms, running MySQL. I have no idea how these modules perform on other systems or with other databases, but I'm happy to work with you if you need to solve issues related to this.

HOW TO SUBMIT A PATCH

Please see the HOW TO SUBMIT A PATCH section of WWW::Myspace for a quick set of instructions on how to get your patch included in a coming distribution.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WWW::Myspace::Data

You can also look for information at:

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