GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  WEBSERVICE::ISBNDB::API::BOOKS (3)

.ds Aq ’

NAME

WebService::ISBNDB::API::Books - Data class for book information

CONTENTS

SYNOPSIS



    use WebService::ISBNDB::API::Books;

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



DESCRIPTION

This class represents book data from <B>isbndb.comB>. It is a sub-class of <B>WebService::ISBNDB::APIB> (see WebService::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 <B>Class::StdB> mechanics. If the value is a scalar, it is tested to see if it is a valid ISBN (using the <B>Business::ISBNB> 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 = WebService::ISBNDB::API::Books->new({ isbn => 0596002068 });

    $book = WebService::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 WebService::ISBNDB::API.

    Accessors

The following attributes are used to maintain the content of a book object:
id The unique ID within the <B>isbndb.comB> 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 <B>WebService::ISBNDB::API::AuthorsB> 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 <B>WebService::ISBNDB::API::PublisherB> 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 <B>WebService::ISBNDB::API::SubjectsB> objects that refer to the subjects this book is associated with. As with the authors, the actual objects are not loaded until requested.
dewey_decimal The book’s Dewey Decimal classification number.
dewey_decimal_normalized The normalized form of the Dewey Decimal number for the book.
lcc_number The Library of Congress Classification number for the book.
language The language the book is printed in. The form and content of this field may not be standardized.
physical_description_text Text describing the physical dimensions of the book.
edition_info Any additional information on the particular edition of the book.
change_time A string representation of the time when this record was last changed. The string is in ISO 8601 form, with no explicit time-zone specified. UTC time is assumed in internal manipulations.
change_time_sec If the <B>Date::ParseB> module is available, this attribute will hold the value from change_time, converted to seconds since the UNIX Epoch. Otherwise, this attribute will always be undef.
price_time A string representation of the time when the price information for this record was last updated. As above, the string is in ISO 8601 format with no time-zone, and it assumed to be UTC internally.
price_time_sec As with change_time_sec, only for the price-change value. Requires the availability of <B>Date::ParseB>, or else the value will always be undef.
summary The content of the <Summary> tag, which is free-form text. The text has leading and trailing white-space removed, and all new-lines converted to spaces, to yield a single-line string value.
notes Another free-form text field, similar to summary, but less used.
urlstext Fairly free-form text, used to specify URLs related to the book.
awardstext More free-form text, this to specify any awards the book has received.
prices If price information is available for the book, this attribute will contain a list-reference containing zero or more hash references. Each hash reference will have the following keys (all will be present on every hash reference, but some may be empty or undef):
store_isbn The ISBN for the book at the store, if different from the book’s regular ISBN. Not set if the two are the same.
store_title The book’s title at the store, if different from the book’s regular title. Not usually set if the two are the same.
store_url URL for the book. This may be a relative URL, in which case it is relative to the store’s website. If it is an absolute URL (complete URL), it is a redirector URL originating at <B>isbndb.comB>. The URL is used for purchasing the book, and the redirect URLs allow <B>isbndb.comB> to collect small commissions off of sales they facilitate, which in turn helps to keep their service available and free.
store_id Unique identifier for the store.
currency_code The code for the currency the price is expressed in.
is_in_stock A boolean value indicating whether the book is in stock.
is_historic A boolean value indicating whether the price this record describes is considered historic. Any price older than 24 hours should generally be considered historic, even if this value is true.
is_new A boolean value indicating whether the book offered is new or used.
currency_rate Currency rate against the US dollar, only set if the currency_code is not USD.
price The price of the book (expressed in the currency indicated by currency_code, above).
check_time String representation of the time when this price was last checked. As with the other time-oriented values, this is in ISO 8601 format with no explicit time-zone.
check_time_sec If the <B>Date::ParseB> package is available, this is the value of check_time expressed in seconds, suitable for use with the Perl <B>localtimeB> keyword.
marc If MARC information is available for the book, this attribute will contain a list-reference containing zero or more hash references. Each hash reference will have the following keys (all will be present on every hash reference, but some may be empty or undef):
library_name Name of the library this record is taken from.
last_update ISO 8601 string representing the last time the record was updated from the library.
last_update_sec If <B>Date::ParseB> is available, this will be the last_update attribute converted to seconds, measured from the UNIX epoch.
marc_url The URL to the MARC record on the library’s site.
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 <B>isbndb.comB> 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 <B>Business::ISBNB> 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 <B>WebService::ISBNDB::API::AuthorsB> 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 <B>WebService::ISBNDB::API::PublishersB> 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 <B>WebService::ISBNDB::API::SubjectsB> 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.
get_dewey_decimal Get the Dewey Decimal number.
set_dewey_decimal($DEWEY) Set the Dewey Decimal number.
get_dewey_decimal_normalized Get the normalized Dewey Decimal number.
set_dewey_decimal_normalized($DEWEY_NORM) Set the normalized Dewey Decimal number.
get_lcc_number Get the Library of Congress Classification number.
set_lcc_number($LCC) Set the Library of Congress Classification number.
get_language Get the language code for the book’s text.
set_language($LANG) Set the language code.
get_physical_description_text Get the book’s physical description text.
set_physical_description_text($PHYS) Set the book’s physical description text.
get_edition_info Get any information on the specific edition of the book.
set_edition_info($INFO) Set the edition information for the book.
get_change_time Get the change-time of the book record (an ISO 8601 string, no explicit time-zone, presumed to be UTC).
set_change_time($TIME) Sets the change-time of the book record. If <B>Parse::DateB> is available, and the value passed in $TIME is parsable, then the change_time_sec attribute will also be updated with the equivalent value.
get_change_time_sec Get the change-time as a number of seconds since the Epoch (as defined in UNIX terms, see Parse::Date). This attribute is only set if the <B>Date::ParseB> module is available.
set_change_time_sec($TIME) Set the seconds-since-Epoch representation of the change-time to the new value. This will also update the change_time attribute, setting it to an ISO 8601-style string that is the textual representation of $TIME.
get_price_time
set_price_time($TIME)
get_price_time_sec
set_price_time_sec($TIME) These are identical to the previous four, only they apply to the time-stamp marking when the price information was last updated. The same restrictions apply to the price_time_sec attribute (<B>Parse::DateB> is required for it to be set when data is read from the source).
get_summary Get the summary text for this book. The summary is free-form text that has has leading and trailing white-space removed, as well as having any internal new-lines or tabs converted to single spaces.
set_summary($SUMMARY) Set the summary text to the new content in $SUMMARY.
get_notes Get the notes for the book. The notes are also free-form text, and are trimmed in the same fashion as summary.
set_notes($NOTES) Set the notes text for the book.
get_urlstext Get the urlstext attribute. This text should provide URLs related to the book, when present.
set_urlstext($URLS) Set the urlstext attribute to the new value.
get_awardstext Get the awards-text data for the book. If present, this should refer to any awards the book has won.
set_awardstext($AWARDS) Set the awards-text to the new data given.
get_prices Get the price data for the book. This comes in the form of a list-reference of hash-references (see earlier description of the keys).
set_prices($PRICELIST) Set the price data. The value passed in must be a list reference, and every element in the list mush be a hash reference. Otherwise an exception will be thrown.
get_marc Get the MARC data for the book. MARC data comes in the form of a list-reference of hash-references (see above for description of the keys).
set_marc($MARCLIST) Set the MARC data. The value passed in must be a list reference, and every element in the list mush be a hash reference. Otherwise an exception will be thrown.

    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 <B>isbndb.comB> 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 <B>WebService::ISBNDB::API::AuthorsB> 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 <B>WebService::ISBNDB::API::PublishersB> 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 <B>WebService::ISBNDB::API::SubjectsB> 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 = WebService::ISBNDB::API::Books->
                     search({ title => "perl" });



Search for all books by Edgar Allan Poe:



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



Find the record for Progamming Web Services With Perl:



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



CAVEATS

The data returned by this class is only as accurate as the data retrieved from <B>isbndb.comB>.

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

WebService::ISBNDB::API, WebService::ISBNDB::API::Authors, WebService::ISBNDB::API::Publishers, WebService::ISBNDB::API::Subjects, Business::ISBN, Date::Parse

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).
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 WEBSERVICE::ISBNDB::API::BOOKS (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.