NAME

WebService::ISBNDB::API - Base class for the WebService::ISBNDB API classes

SYNOPSIS

    require WebService::ISBNDB::API;

    $handle = WebService::ISBNDB::API->new({ protocol => REST =>
                                      api_key => $key });

    $book = $handle->new(Books => { isbn => '0596002068' });
    $all_lotr = $handle->search(Books =>
                                { title => 'lord of the rings ' });

DESCRIPTION

The WebService::ISBNDB::API class is the base for the classes that handle books, publishers, authors, categories and subjects. It also acts as a factory-class for instantiating those other classes. Any of the data classes can be created from the constructor of this class, using the syntax described below.

This class manages the common elements of the data classes, including the handling of the communication agent used to make requests of isbndb.com. This class (and all sub-classes of it) are based on the Class::Std inside-out objects pattern. See Class::Std for more detail.

All error conditions in the methods of this class are handled using the exception model provided by the Error module. Most errors are thrown in the form of Error::Simple exception objects. See Error for more detail.

USING THE ISBNDB.COM SERVICE

In order to access the isbndb.com web service programmatically, you must first register an account on their site (see <https://isbndb.com/account/create.html>) and then create an access key. You can create more than one key, as needed. All the API calls require the access key be part of the parameters.

More information is available at <http://isbndb.com>. You can also view the documentation for their API at <http://isbndb.com/docs/api/>.

METHODS

The following methods are provided by this class, usable by all derived classes. Private methods are not documented here.

Constructor

The constructor for this class behaves a little differently than the default constructor provided by Class::Std.

new([ $TYPE, ] $ARGS): Constructs a new object, returning the referent. The value of $ARGS is a hash-reference of key/value pairs that correspond to the attributes for the class. If $TYPE is provided, then the value must match one of the known data-types, and the new object will be created from that class rather than WebService::ISBNDB::API. Likewise, $ARGS will be passed to that class' constructor and not processed at all by this one.
If $TYPE is not a known type (see "Managing Types"), then an exception of type Error::Simple is thrown.

The class also defines:

copy($TARGET): Copies the target object into the calling object. All attributes (including the ID) are copied. This method is marked "CUMULATIVE" (see Class::Std), and any sub-class of this class should provide their own copy() and also mark it "CUMULATIVE", to ensure that all attributes at all levels are copied.

This method copies only the basic attributes. Each of the implementation classes must provide additional copy() methods (also marked "CUMULATIVE") to ensure that all attributes are copied.

Accessors

The accessor methods are used to set and retrieve the attributes (instance data) stored on the object. While a few of them have special behavior, most operate as simple get or set accessors as described in Class::Std. The attributes for this class are:

protocol: This attribute identifies the communication protocol this object will use for making requests of the isbndb.com service. The value for it is always forced to upper-case, as all protocols are regarded in that manner. (See "Default Attribute Values".)
api_key: To use the isbndb.com service, you must register on their web site and obtain an API key. The key must be used on all data requests to their API. This attribute stores the API key to be used on all requests made by the object. (See "Default Attribute Values".)
agent: This attribute stores the object used for communicating with the service. The value must be a sub-class of the WebService::ISBNDB::Agent class. (See "Default Attribute Values".)
agent_args: When the WebService::ISBNDB::Agent-based object is instantiated, any arguments stored in this attribute will be passed to the constructor. If set, this attribute's value must be a hash-reference (otherwise the constructor will throw an exception). (See "Default Attribute Values".)
type: This attribute is read-only by users that are not sub-classes of this class. It identifies the class-type of the object, which is generally the last element of the class name ("API", "Books", etc.). It allows the WebService::ISBNDB::Agent sub-classes to make choices based on the type of the object. ("Type" in this context should not be confused with "types" as they pertain to mapping books, publishers, etc. to specific data classes.)

The following accessor methods are provided by this class:

get_protocol: Retrieve the current value of the protocol attribute.
set_protocol($PROTO [ , $AGENT ]): Set the protocol to use for communication. Optionally, you can also provide an agent instance at the same time, and set both values. If an agent is specified, it will be tested against the new protocol value, to make sure it works with that protocol. If the agent does not match the protocol, an exception will be thrown.
get_api_key: Retrieve the current API key.
set_api_key: Set the API key to use when contacting the service. If this value is not recognized by the isbndb.com service, you will not be able to retrieve any data.
get_agent: Retrieve the current WebService::ISBNDB::Agent-derived object used for communication. Unless the agent was explicitly provided as an argument to the constructor, the agent object is constructed lazily: it is only instantiated upon the first call to this method.
set_agent: Set a new agent object for use when this object makes requests from the service. An agent object must derive from the WebService::ISBNDB::Agent class (that class itself cannot act as an agent). When a new agent is assigned, its protocol method is called with the current value of the "protocol" attribute of the object, to ensure that the agent matches the protocol. If not, an exception is thrown.
get_agent_args: Get the arguments that are to be passed to agent-instantiation.
set_agent_args: Provide a new set of arguments to be used when instantiating an agent object. The value must be a hash reference, or the constructor for the agent class will thrown an exception.
get_type: Get the class' "type". In most cases, this is the last component of the class name. Note that there is no set-accessor for this attribute; it cannot be set by outside users.

Default Attribute Values

In addition to the above, the following accessors are provided to allow users to set default values for the protocol, the API key, the agent and the defaut arguments for agent construction. This allows you to set these once, at the start of the application, and not have to pass them to every new object instantiation:

set_default_protocol($PROTO): Sets the default protocol to the value of $PROTO. Unlike the API key, there is already a default value for this when the module is loaded (REST).
get_default_protocol: Returns the current default protocol.
set_default_api_key($KEY): Sets a new default API key. There is no built-in default for this, so you must either call this, set it via module-import (see below), or provide the key value for each individual object creation.
get_default_api_key: Returns the current default API key.
set_default_agent($AGENT): Sets a new value for the default agent. Any object created without an "agent" attribute will inherit this value. The value must be an instance of LWP::UserAgent or a derivative class.
get_default_agent: Get the default agent. If it hasn't been set the first time this is called, one is created (possibly using the default agent arguments).
set_default_agent_args($ARGS): Sets a new value for the default arguments to agent creation. Any time an agent is created without the object having an explicit value for arguments to pass, this value is read and used. The value must be a hash reference.
get_default_agent_args: Get the set of default agent arguments, if any.

Besides using these accessors to provide the defaults, you can also specify them when loading the module:

    use WebService::ISBNDB::API (api_key => 'abc123');

"agent", "agent_args", "api_key" and "protocol" are recognized at use-time.

Managing Types

As the root of the data-class hierarchy, this package also provides the methods for managing the data-types known to the overall module.

The built-in data-types are:

Authors: This type covers the author data structures returned by isbndb.com. It is covered in detail in WebService::ISBNDB::API::Authors. =item Books
This type covers the book data structures returned by isbndb.com. It is covered in detail in WebService::ISBNDB::API::Books.
Categories: This type covers the category data structures returned by isbndb.com. It is covered in detail in WebService::ISBNDB::API::Categories.
Publishers: This type covers the publisher data structures returned by isbndb.com. It is covered in detail in WebService::ISBNDB::API::Publishers.
Subjects: This type covers the subject data structures returned by isbndb.com. It is covered in detail in WebService::ISBNDB::API::Subjects.

Note that the types are case-sensitive.

The following methods operate on the internal types map:

add_type($TYPE, $CLASS): Add a mapping for the type specified by $TYPE to the class specified in $CLASS. $TYPE may be one of the core types listed above; if so, then the new class will override the built-in class for that type. You cannot remove a type/class mapping for any of the core types; you can only re-override them by calling the method again. If you want to temporarily redirect a type, you must save the original value (using class_for_type) and manually restore it by called add_type again.
class_for_type($TYPE): Returns the class-name for the given $TYPE. Throws an exception if $TYPE is not in the mapping table.
remove_type($TYPE): Removes the type/class mapping for the given $TYPE. Note that you cannot remove the mappings for any of the core types listed above, even if you have already overridden them with add_type. If you pass any of the core types, an exception will be thrown.

All of the type-map methods may be called as static methods.

Retrieving Data

WebService::ISBNDB::API and its sub-classes support the retrieval of data in two ways: single-record and searching.

Single-record retrieval is for getting just one result from the service, usually from a known unique key (such as fetching a book by the ISBN). The interface for it always returns a single result, even when the criteria are not specific-enough and more than one record is returned. In these cases, the first record is used and the rest discarded.

Searching returns zero or more results from a search of the service using the provided criteria. Presently, the return is in the form of a list-reference (even when the result-set has only one element or no elements). This will change in the future, to an object-base result-set that offers iterators and delayed-loading of results.

The data-retrieving methods are:

find($TYPE, $IDENT|$ARGS): Finds a single record, using either a scalar identifying value ($IDENT) or a hash reference ($ARGS) with one or more key/value pairs. The value of $TYPE tells "WebService::ISBNDB::API") which data class to do the find-operation on. If the value is not a known type, an exception is thrown.
How the scalar value $IDENT is used in the data-retrieval is dependent on the value of $TYPE. See the documentation for the various data classes for more detail.
search($TYPE, $ARGS): Search for items of type $TYPE using the key/value pairs in the hash reference $ARGS. $ARGS must be a hash reference, there is no corner-case for a scalar as with find.
normalize_args($ARGS): In this class, this method does nothing. It is available for sub-classes to overload. If a class overloads it, the requirement is that any changes to the arguments be made in-place, altering $ARGS, and that the return value be either $ARGS itself or a copy.
The purpose of this method is to allow implementation classes to make any translation of user-space argument names to the names used by isbndb.com. Most of the implementation classes also use it to add more arguments in order to retrieve extra data from the service.

These methods may be called as static methods.

CAVEATS

The data returned by this class is only as accurate as the data retrieved from isbndb.com.

The list of results from calling search() is currently limited to 10 items. This limit will be removed in an upcoming release, when iterators are implemented.

AUTHOR

Randy J. Ray <rjray@blackperl.com>

LICENSE

This module and the code within are released under the terms of the Artistic License 2.0 (http://www.opensource.org/licenses/artistic-license-2.0.php). This code may be redistributed under either the Artistic License or the GNU Lesser General Public License (LGPL) version 2.1 (http://www.opensource.org/licenses/lgpl-license.php).