Object::eBay - Object-oriented interface to the eBay API

Object-eBay documentation Contained in the Object-eBay distribution.

Index

Code Index:

NAME

Top

Object::eBay - Object-oriented interface to the eBay API

SYNOPSIS

Top

    use Object::eBay;
    my $ebay = # ... create a Net::eBay object ...
    Object::eBay->init($ebay);

    my $item = Object::eBay::Item->new({ item_id => 12345678 });
    my $title = $item->title();
    my $price = $item->selling_status->current_price();
    print "Item titled '$title' is going for $price\n"

DESCRIPTION

Top

Object::eBay provides an object-oriented interface to the eBay API. Objects are created to represent entities dealing with eBay such as items, users, etc. You won't want to create objects of the class Object::eBay but rather of its subclasses such as: Object::eBay::Item or Object::eBay::User. eBay API calls are processed using the Perl module Net::eBay (available from CPAN or from http://www.net-ebay.org).

Object::eBay follows some simple rules to make the names of eBay API objects more "Perlish." Namely, for packages, eBay's camelcase is retained. For example Object::eBay::ListingDetails. For attribute names, the camelcase is converted to underscore separated method names with roughly the following algorithm:

    Before each capital letter after the first one, place an underscore
    Make all letters lowercase

So, eBay's "FeedbackScore" becomes the method name "feedback_score". Generally, the transformation algorithm does what you'd expect. Attributes like "ItemID" become "item_id" as anticipated.

PUBLIC METHODS

Top

The following methods are intended for general use.

init

  Object::eBay->init($net_ebay_object);

Requires a single Net::eBay object as an argument. This class method must be called before creating any Object::eBay objects. The Net::eBay object provided to init should be initialized and ready to perform eBay API calls. All Object::eBay objects will use this Net::eBay object.

new

This documentation covers functionality that is common to the new method of all Object::eBay classes. For details for specific class, see the appropriate class documentation. The new constructor tries to be as lazy as possible and will not invoke an eBay API call until it's really necessary. Generally this happens when the first method is invoked on a new object. After that, cached values from the API call are returned. That means, each object should only cost use API call and that only if you call a method on the object.

The new method constructs a new object. It accepts a single hashref as an argument. Each subclass determines the values that are accepted or required. However, new always accepts a key named 'needs_methods' to indicate which expensive methods you plan to use. The value of this key should be an arrayref containing the names of the expensive methods you intend to call with the newly created object.

Some eBay API calls return a lot of data, for example, the description of an item can be quite large. To avoid a performance penalty for programs that don't use these expensive methods, Object::eBay avoids fetching the data unless you really need it. You indicate to Object::eBay that you plan to use an expensive method by specifying it with the 'needs_methods' argument. Here's an example where we intend to access an item's description:

    my $item = Object::eBay::Item->new({
        item_id       => 123456789,
        needs_methods => [qw( description )],
    });

Expensive methods indicate this in their documention so that you know in advance. Take a look at description in Object::eBay::Item for example.

PRIVATE METHODS

Top

The following methods are intended for internal use, but are documented here to make code maintenance and subclassing easier. Most users of Object::eBay will never use these methods. Instead, proceed to the documentation about the other Object::eBay classes: SEE ALSO.

api_inputs

    $res = Object::eBay->ask_ebay(
        $self->api_call(),
        $self->api_inputs(),
    );

This method returns a hash reference containing all the inputs required by the invocant's API call. This is used when retrieving the details about an object which does not yet have any details.

ask_ebay

    $res = Object::eBay->ask_ebay(
        GetItem => {
            ItemID => 12345678,
            DetailLevel => 'ItemReturnDescription',
        }
    )

A thin wrapper around submitRequest in Net::eBay which performs API calls using eBay's API and encapsulates error handling. If an error occurs during the API call, or eBay returns a result with an error, an exception is thrown.

complex_attributes

    __PACKAGE__->complex_attributes({
        Seller => {
            class => 'User',
        },
        Description => {
            DetailLevel => 'ItemReturnDescription',
        },
        WatchCount => {
            IncludeWatchCount => 'true',
        },
    });

This method is called by subclasses of eBay::Object to create methods that map to attributes of eBay API return values. The example above will create three methods: seller, description and watch_count. The return value of the seller method will be an Object::eBay::User object. The return value of the description and watch_count methods will be non-reference scalars.

The description method requires that 'DetailLevel' be 'ItemReturnDescription' or higher. In addition to 'DetailLevel', any API Input value can be specified (for example 'IncludeWatchCount' in the sample above). Object::eBay objects try to be lazy and request as little information from eBay as possible. This is done by correlating arguments to complex_attributes with the value of 'needs_methods' set when calling new.

The argument to complex_attributes should be a single hash reference. The keys of the hash should be eBay attribute names. The value of each key should likewise be a hash reference.

For simpler mapping of eBay attributes to method names, see simple_attributes.

ebay_name_to_method_name

    $method_name = Object::eBay->ebay_name_to_method_name('SellingStatus')
    # returns 'selling_status'

Converts an eBay name in camelcase to a method name in lowercase with words separated by underscores. This method implements the algorithm sketched in the DESCRIPTION section.

get_details

    $title = $item->get_details->{Title};

Returns a hash reference containing detailed information about the invocant object. This hash reference is a slightly modified version of the hashref returned by Net::eBay::submitRequest. Again, this method is intended to be private. If you want to access information about an Object::eBay object, please use an accessor method. If there is no accessor method for the information you want, see HELPING OUT for information on how to add the accessor method and then send me a patch.

method_name_to_ebay_name

    $ebay_name = Object::eBay->method_name_to_ebay_name('selling_status')
    # returns 'SellingStatus'

Converts a method name with underscores separating words into an ebay name in camelcase. This method implements the inverse of the algorithm sketched in the DESCRIPTION section.

simple_attributes

    __PACKAGE__->simple_attributes(qw{ Quantity Title });

This method is called by subclasses of eBay::Object to create methods that map easily to attributes of eBay API return values. The example above will create two methods: quantity and title which return the "Quantity" and "Title" attributes of the object in question. The return value of methods created with simple_attributes will be non-reference scalars. For more complex mapping of eBay attributes to method names, see complex_attributes.

DIAGNOSTICS

Top

init() requires a valid Net::eBay object

This exception is thrown when init is called without providing a Net::eBay object as the argument.

Error inflating '%s': %s

If calling the inflation subroutine defined by a Object::eBay subclass causes an exception, this exception will be thrown with the original exception message attached.

Can't find '%s' via %s

If the API response from eBay does not contain the raw information necessary to evaluate a method, this exception is thrown.

Can't inflate '%s' via %s

The result of inflating an attribute into an object was an undefined value.

CONFIGURATION AND ENVIRONMENT

Top

Object::eBay requires no configuration files or environment variables. However, Net::eBay can make use of configuration files and that is often easier than including set up information in every program that uses Object::eBay.

DEPENDENCIES

Top

* Class::Std
* Net::eBay

INCOMPATIBILITIES

Top

None known.

HELPING OUT

Top

The latest source code for Object-eBay is available with git from git://ndrix.com/Object-eBay. You may also browse the repository at http://git.ndrix.com/?p=Object-eBay;a=summary.

If you have any patches, please submit them through the RT bug tracking interface see BUGS AND LIMITATIONS. Right now, the most needed assistance is with filling out the objects and associated accessor methods. To create a new Object::eBay subclass to implement an additional class of objects on eBay, you'll need to implement the following methods. Take a look at Object::eBay::Item for examples.

api_call

Override this method so that it returns the name of the eBay API call which should be invoked to return details about a particular object. For example, the Object::eBay::Item class defines this method to return "GetItem"

response_field

Override this method so that it returns the hash key which accesses all the important details about a particular object. For example, the Object::eBay::Item class defines this method to return "Item".

BUGS AND LIMITATIONS

Top

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

SUPPORT

Top

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

    perldoc Object::eBay

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Object-eBay

* CPAN Ratings

http://cpanratings.perl.org/d/Object-eBay

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Object-eBay

* Search CPAN

http://search.cpan.org/dist/Object-eBay

http://www.ndrix.com

SEE ALSO

Top

* Object::eBay::Item
* Object::eBay::ListingDetails
* Object::eBay::SellingStatus
* Object::eBay::User

ACKNOWLEDGEMENTS

Top

JJ Games for sponsoring the original development http://www.jjgames.com.

Video Game Price Charts for sponsoring further development http://www.videogamepricecharts.com.

Igor Chudov for writing Net::eBay.

AUTHOR

Top

Michael Hendricks <michael@ndrix.com>

LICENSE AND COPYRIGHT

Top

Copyright (c) 2006-2007 Michael Hendricks (<michael@ndrix.com>). All rights reserved.

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

Object-eBay documentation Contained in the Object-eBay distribution. 
package Object::eBay;
our $VERSION = '0.4.0';

use Class::Std; {
    use warnings;
    use strict;
    use Carp;
    use Scalar::Util qw( blessed );

    my $net_ebay;           # holds a singleton object
    my %details_for :ATTR;
    my %inputs_for  :ATTR( :get<api_inputs> );  # inputs to the API call

    sub init {
        my ($pkg, $net_ebay_object) = @_;
        croak "init() requires a valid Net::eBay object"
            if !defined $net_ebay_object;
        $net_ebay = $net_ebay_object;
    }

    sub BUILD {
        my ($self, $ident, $args_ref) = @_;

        my $object_details = delete $args_ref->{object_details};
        my $needs_methods = delete $args_ref->{needs_methods} || [];
        $inputs_for{$ident} = $self->_convert_args($args_ref);

        for my $method_name (@$needs_methods) {
            $self->_add_inputs( $self->$method_name(':meta') );
        }

        $details_for{$ident} = $object_details if $object_details;
    }
    sub _convert_args {
        my ($self, $args) = @_;

        my %new_args;
        for my $method_name (keys %$args) {
            my $ebay_name = $self->method_name_to_ebay_name($method_name);
            $new_args{$ebay_name} = $args->{$method_name};
        }

        return \%new_args;
    }
    sub _add_inputs {
        my ($self, $meta) = @_;
        my $ident = ident $self;
        
        # handle each extra input
        for my $input ( grep { /\A[A-Z]/ } keys %$meta ) {
            my $new_value = $meta->{$input};

            # handle conflicts
            # TODO allow conflict resolution to be specified by subclasses
            if ( exists $inputs_for{$ident}{$input} ) {
                my $old_value = $inputs_for{$ident}{$input};
                croak "Conflicting $input: '$old_value' and '$new_value'"
                    if $input ne 'DetailLevel';
                $new_value = 'ReturnAll';
            }

            $inputs_for{$ident}{$input} = $new_value;
        }
    }
    sub _make_datetime {
        my ($self, $iso) = @_;
        require DateTime;
        my ($y, $m, $d, $h, $min, $s) = split /[-T:.]/, $iso;
        return DateTime->new(
            year      => $y,
            month     => $m,
            day       => $d,
            hour      => $h,
            minute    => $min,
            second    => $s,
            time_zone => 'UTC',
        );
    }

    ##########################################################################
    # Usage     : $method_name = Object::eBay->ebay_name_to_method_name($name)
    # Purpose   : Convert eBay names into method names
    # Returns   : a method name equivalent to the given eBay name
    # Arguments : $name - an eBay name such as (Title or SellingStatus)
    # Throws    : no exceptions
    # Comments  : none
    # See Also  : n/a
    sub ebay_name_to_method_name {
        my ($pkg, $ebay_name) = @_;
        return $ebay_name if !$ebay_name;
        $ebay_name =~ s{
                        ([[:lower:]])   # lower case letter
                        ([[:upper:]])   # followed by an upper case letter
                }{$1_\l$2}xmsg;
        return lc $ebay_name;
    }

    
    #########################################################################
    # Usage     : $ebay_name = Object::eBay->method_name_to_ebay_name($name)
    # Purpose   : Convert a method name into an eBay name
    # Returns   : an ebay name equivalent to the given method name
    # Arguments : $name - a method name such as (title or selling_status)
    # Throws    : no exceptions
    # Comments  : none
    # See Also  : n/a
    sub method_name_to_ebay_name {
        my ($pkg, $method_name) = @_;

        my $ebay_name = join('',
            map  { $_ eq 'id' ? uc : ucfirst }
            split(/_/, $method_name)
        );
        return $ebay_name;
    }

    ##########################################################################
    # Usage     : $result = Object::eBay->ask_ebay(
    #               'GetItem',
    #               { ItemID => 123455678 }
    #             );
    # Purpose   : dispatch an API call to eBay
    # Returns   : a hashref with eBay's response
    # Arguments : $api_call - the name of the eBay API call to make
    #             $inputs   - a hashref giving input fields for the API call
    # Throws    : "Unable to process the command ..."
    #             "eBay error (...): ..."
    # Comments  : throws an error if the API call couldn't be completed or
    #             if eBay returns an error value
    # See Also  : n/a
    sub ask_ebay {
        my ( $class, $command, $arguments ) = @_;

        my $result = $net_ebay->submitRequest( $command, $arguments );
        croak "Unable to process the command $command"
            if !$result;

        if ( exists $result->{Errors} ) {
            my $errors   = $result->{Errors};
            my $severity = $errors->{SeverityCode};
            if ( $severity ne 'Warning' ) {
                my $code     = $errors->{ErrorCode};
                my $message  = $errors->{LongMessage};
                croak "eBay error ($code): $message";
            }
        }

        return $result;
    }

    #########################################################################
    # Usage     : $details = $self->get_details()
    # Purpose   : Retrieves the details for this object from eBay and caches
    #             the results for later use.
    # Returns   : A hash reference representing the details (this is very
    #             similar to the result returned by Net::eBay::submitRequest
    # Arguments : none
    # Throws    : no exceptions
    # Comments  : none
    # See Also  : n/a
    sub get_details {
        my ($self) = @_;
        my $ident = ident $self;

        # look for a cached copy
        my $details = $details_for{$ident};
        return $details if $details;

        # otherwise, ask eBay for the details
        my $response = $self->ask_ebay(
            $self->api_call(),
            $self->api_inputs(),
        );

        # and cache the response
        return $details_for{$ident} = $response->{ $self->response_field() };
    }

    #############################################################################
    # Usage     : __PACKAGE__->simple_attributes('Title', 'Quantity')
    # Purpose   : Define simple attributes for an Object::eBay subclass
    # Returns   : none
    # Arguments : a list of method names to implement
    # Throws    : no exceptions
    # Comments  : none
    # See Also  : n/a
    sub simple_attributes {
        my ($pkg, @ebay_names) = @_;

        # install a method for each eBay name
        for my $ebay_name (@ebay_names) {
            no strict 'refs';
            my $method_name = $pkg->ebay_name_to_method_name($ebay_name);
            *{ $pkg . "::$method_name" } = sub {
                my ($self) = @_;
                my $value = eval { $self->get_details->{$ebay_name} };
                croak $@ if $@ && $@ =~ /\A eBay/xms;
                croak "Can't find '$ebay_name' via ${pkg}::$method_name()"
                    if !defined $value;
                return $value;
            };
        }
    }

    sub complex_attributes {
        my ($pkg, $args) = @_;

        while ( my ($ebay_name, $meta) = each %$args ) {
            no strict 'refs';
            my $method_name = $pkg->ebay_name_to_method_name($ebay_name);
            *{ $pkg . "::$method_name" } = sub {
                my ($self, $args) = @_;

                # return meta info if requested
                return $meta if $args && $args eq ':meta';

                my $value = eval { $self->get_details->{$ebay_name} };
                croak $@ if $@ && $@ =~ /\A eBay/xms;
                croak "Can't find '$ebay_name' via ${pkg}::$method_name()"
                    if !defined($value) and !$meta->{undefined_value_ok};

                return $value if blessed $value;  # already inflated the value

                # inflate value into an object
                if ( my $class_stub = $meta->{class} ) {
                    my $class = "Object::eBay::$class_stub";
                    $value = eval {
                        eval "require $class";
                        $class->new({ object_details => $value })
                    };
                    croak "Error inflating '$ebay_name': $@\n" if $@;
                    croak "Can't inflate '$ebay_name' via ${pkg}::$method_name()"
                        if !defined $value;
                    $self->get_details->{$ebay_name} = $value;
                    return $value;
                }
                elsif ( my $converter = $meta->{convert_value} ) {
                    croak "The value of 'convert_value' should be\n"
                        . "a code reference.\n" if ref($converter) ne 'CODE';
                    return $converter->($value);
                }

                return $value;
            };
        }
    }

    sub api_inputs { $_[0]->get_api_inputs() }
}

1;

__END__