/ 
Object-eBay-0.0.1
River stage zero No dependents
/ Object::eBay

NAME

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

VERSION

This documentation refers to Object::eBay version 0.0.1

SYNOPSIS

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

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.

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

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

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

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

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

  • Class::Std

  • Net::eBay

INCOMPATIBILITIES

None known.

HELPING OUT

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

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

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

perldoc Object::eBay

You can also look for information at:

SEE ALSO

ACKNOWLEDGEMENTS

Igor Chudov for writing Net::eBay.

AUTHOR

Michael Hendricks <michael@ndrix.org>

LICENSE AND COPYRIGHT

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

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