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::SUBJECTS (3)

.ds Aq ’

NAME

WebService::ISBNDB::API::Subjects - Data class for subject information

CONTENTS

SYNOPSIS



    use WebService::ISBNDB::API::Subjects;

    $net_prog = WebService::ISBNDB::API::Subjects->
                    find(internet_programming);



DESCRIPTION

The <B>WebService::ISBNDB::API::SubjectsB> class extends the <B>WebService::ISBNDB::APIB> class to add attributes specific to the data <B>isbndb.comB> provides on subjects.

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($SUBJECT_ID|$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 assumed to be the subject’s ID within the system, and is looked up by that.

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::Subjects->
        new({ id => "internet_programming" });

    $book = WebService::ISBNDB::API::Subjects->new(internet_programming);



The first creates a new object that has only the id attribute set. The second returns a new object that represents the given subject, 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 subject object:
id The unique ID within the <B>isbndb.comB> system for this subject.
name The name of the subject.
book_count The number of books listed under this subject.
marc_field
marc_indicator_1
marc_indicator_2 These three attributes make up the subject’s MARC (MAchine-Readable Cataloging) information.
categories A list of category objects for the categories the subject is listed in.
The following accessors are provided to manage these attributes:
get_id Return the category ID.
set_id($ID) Sets the category 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_name Return the author’s name. This is the full name, as would appear in the author_text field of a <B>WebService::ISBNDB::API::BooksB> object.
set_name($NAME) Set the name to the value in $NAME.
get_book_count Returns the number of books under this subject.
set_book_count($COUNT) Set the number of books under this subject.
get_marc_field Get the MARC field value.
set_marc_field($MARC) Set the MARC field value.
get_marc_indicator_1 Get the value for the first MARC indicator.
set_marc_indicator_1($MARC_1) Set the value for the first MARC indicator.
get_marc_indicator_2 Get the value for the second MARC indicator.
set_marc_indicator_2($MARC_1) Set the value for the second MARC indicator.
get_categories Return a list-reference of the categories this aubject is listed in. Each element of the list will be an instance of <B>WebService::ISBNDB::API::CategoriesB>.
set_categories($CATEGORIES) Set the categories to the list-reference given in $CATEGORIES. When the author object is first created from the XML data, this list is populated with the IDs of the categories. They are not converted to objects until requested (via get_categories()) by the user.

    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 searched for as if it were the ID. 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 categories, location, 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:
name The value should be a text string. The search returns authors whose name matches the string.
id|subject_id The value should be a text string. The search returns the author whose ID in the system matches the value.
category|category_id You can search for subjects in a given category. If the search-key is category, the value may be either the ID or a category object. If it is an object, the ID is derived from it. If the search-key is category_id, the value must be the ID itself.
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

Get the record for the subject, perl_computer_program_language:



    $perl = WebService::ISBNDB::API::Subjects->
                find(perl_computer_program_language);



Find all subject with perl in their name:



    $allperl = WebService::ISBNDB::API::Subjects->
                   search({ name => perl });



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::Categories

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::SUBJECTS (3) 2016-04-03

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