/ 
Net-ISBNDB-0.10
/ Net::ISBNDB::API::Books

NAME

Net::ISBNDB::API::Books - Object representation of book data from isbndb.com

SYNOPSIS

use Net::ISBNDB::API::Books;

my $book = Net::ISBNDB::API->new({ api_key => $key,
                                   isbn => '0596002068' });

DESCRIPTION

This class represents book data from isbndb.com. It is a sub-class of Net::ISBNDB::API (see Net::ISBNDB::API), and inherits all the attributes and methods from that class.

METHODS

The following methods are specific to this class, or overridden from the super-class.

Constructor

The constructor for this class may take a single scalar argument in lieu of a hash reference:

new($ISBN|$TITLE|$ARGS)

This constructs a new object and returns a referent to it. If the parameter passed is a hash reference, it is handled as normal, per Class::Std mechanics. If the value is a scalar, it is tested to see if it is a valid ISBN (using the Business::ISBN module). If it is, it is used as a search key to find the corresponding book. If it is not a valid ISBN, it is assumed to be the title, and is likewise used as a search key. Since the title may return more than one match, the first matching record from the source is used to construct the object.

If the argument is the hash-reference form, then a new object is always constructed; to perform searches see the search() and find() methods. Thus, the following two lines are in fact different:

$book = Net::ISBNDB::API::Books->new({ isbn => '0596002068' });

$book = Net::ISBNDB::API::Books->new('0596002068');

The first creates a new object that has only the isbn attribute set. The second returns a new object that represents the book with ISBN 0596002068, with all data present.

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.

See the copy() method in Net::ISBNDB::API.

Accessors

The following attributes are used to maintain the content of a book object:

id

The unique ID within the isbndb.com system for this book.

isbn

The ISBN (International Standard Book Number) for the book (without hyphens).

title

The title of the book.

longtitle

The full title of the book, including any sub-title.

authors

An array (stored as a reference) of the Net::ISBNDB::API::Authors objects that refer to the authors of the book. These are not actually loaded from the service until they are first fetched.

authors_text

A simple textual representation of the authors, as returned by the service. This may be more convenient to use than the author objects, if you only want to display the names themselves.

publisher

The Net::ISBNDB::API::Publisher object that refers to the book's publisher. This is not loaded until the first request to fetch it is made.

publisher_text

A simple textual representation of the publisher, as returned by the service. This may be more convenient to use than the object, if you only wish to display the publisher's name.

subjects

An array (stored as a reference) of the Net::ISBNDB::API::Subjects objects that refer to the subjects this book is associated with. As with the authors, the actual objects are not loaded until requested.

The following accessors are provided to manage these attributes:

get_id

Return the book ID.

set_id($ID)

Sets the book ID. This method is restricted to this class, and cannot be called outside of it. In general, you shouldn't need to set the ID after the object is created, since isbndb.com is a read-only source.

get_isbn

Return the ISBN of the book. In general, the ISBN has had any hyphens removed.

set_isbn($ISBN)

Set the book ISBN. The value is tested with Business::ISBN to ensure that the value is a valid ISBN.

get_title

Return the common title of the book.

set_title($TITLE)

Set the title of the book.

get_longtitle

Return the long title of the book. This will include subtitles, for example.

set_longtitle($LONGTITLE)

Set the long title of the book.

get_authors

Get the list of author objects (instances of Net::ISBNDB::API::Authors or a sub-class) for the book. The objects are not fetched from the source until the first call to this method.

set_authors($LIST)

Set the list of authors for this book. The value must be a list-reference. If the values in the list reference are strings instead of objects, then the first call to get_authors() will convert them into objects. The strings must be the author ID values as returned by the service.

get_authors_text

Return the text-representation of the authors, as returned by the service.

set_authors_text($TEXT)

Set the text-representation of the authors.

get_publisher

Return the publisher object (instance of Net::ISBNDB::API::Publishers or a sub-class) for this book. The object is not loaded from the source until the first request to this method.

set_publisher($PUBLISHER)

Set the publisher for this book. The value should be either a publisher object or a string containing the publisher ID. If the ID is set as the value, the next call to get_publisher() will resolve it into an object.

get_subjects

Get the list of subject objects (instances of Net::ISBNDB::API::Subjects or a sub-class) for the book. The objects are not fetched from the source until the first call to this method.

set_subjects($LIST)

Set the list of subjects. The value must be a list-reference, and may contain either the objects themselves or the subject ID values as returned by the source. If the content is the ID values, then the next call to get_subjects() will resolve them to objects.

Utility Methods

Besides the constructor and the accessors, the following methods are provided for utility:

find($ARG|$ARGS)

This is a specialization of find() from the parent class. It allows the argument passed in to be a scalar in place of the usual hash reference. If the value is a scalar, it is tested to see if it is a valid ISBN, and if so the search is made against the ISBN with that value. If the scalar value is not a valid ISBN, the search is made against the title instead. If the value is a hash reference, it is passed to the super-class method.

normalize_args($ARGS)

This method maps the user-visible arguments as defined for find() and search() into the actual arguments that must be passed to the service itself. In addition, some arguments are added to the request to make the service return extra data used for retrieving subjects, publisher information, etc. The method changes $ARGS in place, and also returns $ARGS as the value from the method.

See the next section for an explanation of the available keys for searches.

SEARCHING

Both find() and search() allow the user to look up data in the isbndb.com database. The allowable search fields are limited to a certain set, however. When either of find() or search() are called, the argument to the method should be a hash reference of key/value pairs to be passed as arguments for the search (the exception being that find() can accept a single string, which has special meaning as detailed earlier).

Searches in the text fields are done in a case-insensitive manner.

The available search keys are:

title

The value should be a text string. The search returns books whose title matches the string.

isbn

The value should be a text string. The search returns the book whose ISBN matches the string. The string is not checked for validity, so a bad ISBN will simply not return any records.

author

The value for this key should be either an object of the Net::ISBNDB::API::Authors class (or sub-class thereof), or a text string. If the value is an object, the search is done against the specific author ID. If the value is a string, the search is done using the "combined" search key, and may return results unrelated to the intended query.

publisher

The value for this key may be an object of the Net::ISBNDB::API::Publishers class (or sub-class thereof) or a text string. If it is an object, the ID is used in a specific search. If the value is a string, it is used with the "combined" search-key, and may return unexpected results.

subject

The value for this key is expected to be either an object (of the Net::ISBNDB::API::Subjects class or sub-class thereof) or a literal subject ID as a string. The subject cannot be searched for using the "combined" key.

combined

The value should be a text string, and is searched against a combined field that includes titles, authors and publisher names.

full

The value should be a text string, and is searched against almost all of the textual data, including title, authors, publishers, summary, notes, award information, etc.

dewey_decimal

The value should be a Dewey Decimal Classification number, and is used directly in the search.

lcc_number

The value should be a Library of Congress Classification number, and is used directly in the search.

Note that the names above may not be the same as the corresponding parameters to the service. The names are chosen to match the related attributes as closely as possible, for ease of understanding.

EXAMPLES

Search for all books with "perl" in the title:

$perlbooks = Net::ISBNDB::API::Books->search({ title => "perl" });

Search for all books by Edgar Allan Poe:

$poebooks = Net::ISBNDB::API::Books->search({ author =>
                                              'edgar allan poe' });

Find the record for "Progamming Web Services With Perl":

$pwswp = Net::ISBNDB::API::Books->find('0596002068');

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.

SEE ALSO

Net::ISBNDB::API, Net::ISBNDB::API::Authors, Net::ISBNDB::API::Publishers, Net::ISBNDB::API::Subjects, Business::ISBN

AUTHOR

Randy J. Ray <rjray@blackperl.com>

COPYRIGHT

This module and the code within are copyright (c) 2006 by Randy J. Ray and released under the terms of the Artistic License (http://www.opensource.org/licenses/artistic-license.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).