MyLibrary Tutorial _amp; PERL API by ghkgkyyt

VIEWS: 4 PAGES: 79

									MyLibrary Tutorial & PERL API




          Eric Lease Morgan
              Robert Fox
MyLibrary Tutorial & PERL API
by Eric Lease Morgan and Robert Fox

Abstract

The PERL API contains documentation on version 3.0 of the MyLibrary module on which MyLibrary is based. It is
part of the MyLibrary manual. For current information on the PERL API, consult the online version at:
The MyLibrary manual is part of a system of files called MyLibrary, a database-driven website application intended to facilitate digital library
collections and services.

This manual is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any later version.

This manual is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MER-
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this manual if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more information about this MyLibrary and this manual, see: http://dewey.library.nd.edu/mylibrary/ [http://dewey.library.nd.edu/mylibrary/] .
Table of Contents
I. Tutorial .................................................................................................................................. 7
       1. MyLibrary Tutorial .......................................................................................................... 9
             Initialization ............................................................................................................... 9
             Configuration ............................................................................................................. 9
             Facets ....................................................................................................................... 9
             Terms ..................................................................................................................... 11
             Librarians ................................................................................................................ 12
             Location types .......................................................................................................... 14
             Resources ................................................................................................................ 15
             Terms and resources revisited ...................................................................................... 17
             Implementing search .................................................................................................. 21
             MyLibrary and OAI ................................................................................................... 24
             Summary ................................................................................................................. 26
II. Perl API .............................................................................................................................. 27
       2. MyLibrary::Core ........................................................................................................... 31
             NAME .................................................................................................................... 31
             SYNOPSIS .............................................................................................................. 31
             DESCRIPTION ........................................................................................................ 31
       3. MyLibrary::DB ............................................................................................................. 32
             NAME .................................................................................................................... 32
             SYNOPSIS .............................................................................................................. 32
             DESCRIPTION ........................................................................................................ 32
             FUNCTIONS ........................................................................................................... 32
                     dbh() .............................................................................................................. 32
       4. MyLibrary::Facet ........................................................................................................... 33
             NAME .................................................................................................................... 33
             SYNOPSIS .............................................................................................................. 33
             DESCRIPTION ........................................................................................................ 33
             METHODS .............................................................................................................. 33
                     new() .............................................................................................................. 34
                     facet_id() ......................................................................................................... 34
                     facet_name() .................................................................................................... 34
                     facet_note() ...................................................................................................... 34
                     delete_facet_note() ............................................................................................ 35
                     commit() ......................................................................................................... 35
                     delete() ........................................................................................................... 35
                     get_facets() ...................................................................................................... 35
                     related_terms() ................................................................................................. 36
       5. MyLibrary::Term ........................................................................................................... 37
             NAME .................................................................................................................... 37
             SYNOPSIS .............................................................................................................. 37
             DESCRIPTION ........................................................................................................ 38
             METHODS .............................................................................................................. 38
                     new() .............................................................................................................. 38
                     term_id() ......................................................................................................... 38
                     term_name() .................................................................................................... 39
                     term_note() ...................................................................................................... 39
                     delete_term_note() ............................................................................................ 39
                     facet_id() ......................................................................................................... 39
                     commit() ......................................................................................................... 40
                     delete() ........................................................................................................... 40
                     get_terms() ...................................................................................................... 40
                     related_resources() ............................................................................................ 40

                                                                           iv
                                             MyLibrary Tutorial & PERL API


           suggested_resources() ........................................................................................ 42
           librarians() ....................................................................................................... 43
           sort() .............................................................................................................. 43
           overlap() ......................................................................................................... 44
           distinct_terms() ................................................................................................. 44
6. MyLibrary::Resource ..................................................................................................... 45
     NAME .................................................................................................................... 45
     SYNOPSIS .............................................................................................................. 45
     DESCRIPTION ........................................................................................................ 47
     METHODS .............................................................................................................. 47
           new() .............................................................................................................. 47
           name() ............................................................................................................ 48
           note() .............................................................................................................. 48
           access_note() .................................................................................................... 48
           coverage_info() ................................................................................................ 49
           full_text() ........................................................................................................ 49
           reference_linking() ............................................................................................ 49
           lcd() ............................................................................................................... 49
           fkey() .............................................................................................................. 50
           qsearch_prefix() and qsearch_suffix() ................................................................... 50
           date() .............................................................................................................. 51
           id() ................................................................................................................. 51
           commit() ......................................................................................................... 52
           delete_[attribute_name]() .................................................................................... 52
           delete() ........................................................................................................... 52
           get_resources() ................................................................................................. 52
           lcd_resources() ................................................................................................. 53
           qsearch_redirect() ............................................................................................. 54
           get_fkey() ........................................................................................................ 54
           test_relation() ................................................................................................... 55
           related_terms() ................................................................................................. 55
           proxied() ......................................................................................................... 56
           creator() .......................................................................................................... 57
           publisher() ....................................................................................................... 57
           contributor() ..................................................................................................... 57
           coverage() ....................................................................................................... 57
           rights() ............................................................................................................ 58
           language() ....................................................................................................... 58
           source() ........................................................................................................... 58
           relation() ......................................................................................................... 58
           add_location() .................................................................................................. 59
           delete_location() ............................................................................................... 59
           resource_locations() .......................................................................................... 59
           modify_location() ............................................................................................. 59
           get_location() ................................................................................................... 60
7. MyLibrary::Resource::Location ........................................................................................ 61
     NAME .................................................................................................................... 61
     SYNOPSIS .............................................................................................................. 61
     DESCRIPTION ........................................................................................................ 62
     METHODS .............................................................................................................. 62
           new() .............................................................................................................. 62
           commit() ......................................................................................................... 63
           id() ................................................................................................................. 63
           location() ......................................................................................................... 63
           location_note() ................................................................................................. 63
           resource_location_type() .................................................................................... 63
           resource_id() .................................................................................................... 64
           get_locations() .................................................................................................. 64


                                                                 v
                                                     MyLibrary Tutorial & PERL API


                    id_list() ........................................................................................................... 64
                    delete() ........................................................................................................... 65
                    location_type() ................................................................................................. 65
       8. MyLibrary::Resource::Location::Type ............................................................................... 66
            NAME .................................................................................................................... 66
            SYNOPSIS .............................................................................................................. 66
            DESCRIPTION ........................................................................................................ 66
            METHODS .............................................................................................................. 66
                    new() .............................................................................................................. 66
                    name() ............................................................................................................ 67
                    description() ..................................................................................................... 67
                    location_type_id() ............................................................................................. 67
                    commit() ......................................................................................................... 68
                    delete() ........................................................................................................... 68
                    all_types() ....................................................................................................... 68
       9. MyLibrary::Librarian ..................................................................................................... 69
            NAME .................................................................................................................... 69
            SYNOPSIS .............................................................................................................. 69
            DESCRIPTION ........................................................................................................ 70
            METHODS .............................................................................................................. 70
                    new() .............................................................................................................. 70
                    id() ................................................................................................................. 70
                    name() ............................................................................................................ 70
                    telephone() ...................................................................................................... 70
                    email() ............................................................................................................ 71
                    url() ................................................................................................................ 71
                    term_ids() ........................................................................................................ 71
                    commit() ......................................................................................................... 72
                    delete() ........................................................................................................... 72
                    get_librarians() ................................................................................................. 72
            ACKNOWLEDGEMENTS ........................................................................................ 73
III. License .............................................................................................................................. 74
       A. GNU General Public License .......................................................................................... 76
            Preamble ................................................................................................................. 76
            GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRI-
            BUTION AND MODIFICATION ................................................................................ 76
            NO WARRANTY ..................................................................................................... 79




                                                                          vi
Part I. Tutorial
Table of Contents
1. MyLibrary Tutorial .................................................................................................................. 9
           Initialization ............................................................................................................... 9
           Configuration ............................................................................................................. 9
           Facets ....................................................................................................................... 9
           Terms ..................................................................................................................... 11
           Librarians ................................................................................................................ 12
           Location types .......................................................................................................... 14
           Resources ................................................................................................................ 15
           Terms and resources revisited ...................................................................................... 17
           Implementing search .................................................................................................. 21
           MyLibrary and OAI ................................................................................................... 24
           Summary ................................................................................................................. 26




                                                                        8
Chapter 1. MyLibrary Tutorial
Eric Lease Morgan, University of Notre Dame

       This tutorial gives the reader an overview of how to use the MyLibrary modules. It is only an introduc-
       tion. The reader is expected to understand the principles of basic object-oriented Perl programming.

       By the end of the tutorial the reader should be able to: create sets of facets, create sets of terms, create
       sets of librarians, create sets of location types, create sets of resources, classify librarians and resources
       with terms, work with sets of resources assoicated with particular sets of terms, output the resources'
       titles, descriptions and locations, create a freetext index of MyLibrary content, harvest OAI repositories
       and cache the content in a MyLibrary database.


Initialization
       To include MyLibrary into your scripts you "use" it:

       # include the whole of MyLibrary
       use MyLibrary::Core;


       This will enable all the necessary modules. You can use selected modules if you so desire. This will save
       you a bit of RAM and compile time, but not a whole lot. For example:

       # include just selected modules
       use MyLibrary::Facet;
       use MyLibrary::Term;


       Make your life easy. Just include the whole of MyLibrary. See MyLibrary::Core's pod for more informa-
       tion.


Configuration
       Each installation of the MyLibrary modules is configured, by default, to work against at least one
       MyLibrary instance. This instance was created during the make process. When you include MyLib-
       rary::Core, the default instance will be read from and written to.

       If you want to read and write to a different instance of MyLibrary, then you will need to use the MyLib-
       rary::Config methods to specify the database options for that instance.


Facets
       One of the first things you will want to do with any MyLibrary instance is create a set of facets.

       Facets are a set of broad classification headings. Most instances of MyLibrary will contain some sort of
       Subjects facet to denote the "aboutness" of items. Other possible facets include Formats or Audiences.
       Formats could denote the physical manifestations of information resources. Audiences might denote
       who are the intended users of information resources.

       Here are a number of ways to create and manipulate facet objects:

       # create a facet object
       $facet = MyLibrary::Facet->new;

                                                       9
                                      MyLibrary Tutorial




# set the facet's name and note
$facet->facet_name('Subjects');
$facet->facet_note('The "aboutness" of items');
# save the facet to the database
$code = $facet->commit;
if ($code ne 1) { die 'commit failed' }
# get the facet's id; think "database key"
$id = $facet->facet_id;
# get the facet's name and note
$name = $facet->facet_name;
$note = $facet->facet_note;
# get a specific facet based on an id
$facet = MyLibrary::Facet->new(id => 1);


Given the methods outlined above, you could use the following code to create, save, retrieve, and then
display a facet:

# configure
$name = 'Formats';
$note = 'The physical manifestation of resources';
# create, save, retrieve, and display
$facet = MyLibrary::Facet->new;
$facet->facet_name($name);
$facet->facet_note($note);
# save
$facet->commit;
$id = $facet->facet_id;
# retrieve
$facet = MyLibrary::Facet->new(id => $id);
# display
print ' ID: ' . $facet->facet_id    . "\n";
print 'Name: ' . $facet->facet_name . "\n";
print 'Note: ' . $facet->facet_note . "\n";


You will often want to get a list of all the facets in your system in order to facilitate browsable interfaces
to your collection of resources. The get_facets method is used for this purpose. Since get_facets returns
an array of objects, you can now loop through the array and process each item. This is how you might
display them:

# create a list of all the facets in the system
@facets = MyLibrary::Facet->get_facets;
print "ID\tName\t(Note)\n";
foreach $f (@facets) {
      print $f->facet_id   . "\t" .
          $f->facet_name . "\t(" .
          $f->facet_note . ")\n"
      }


Read the scripts named manage-facets.pl and subroutines.pl to see an example of how to manage sets of

                                               10
                                       MyLibrary Tutorial



   facets from a terminal-based interface. For more information read the pod of MyLibrary::Facets.


Terms
   Terms are a set of narrower classification headings, and each term is associated with one and only one
   facet -- its parent. Terms are expected to be the controlled vocabulary of your MyLibrary implementa-
   tion, and consequently they are expected to be assigned to one or more information resources. Terms
   might include Astronomy, Music, or Mathematics, and these terms may have a parent facet named Sub-
   jects. Other terms might be Book, Journal, or Image, and these terms might be associated with a facet
   called Formats. Still other examples include Catalog, Dictionary, or Encyclopedia, and could associated
   with a facet named Research Tools.

   The methods of MyLibrary term objects are very similar to the methods of facet objects:

   # create a term object
   $term = MyLibrary::Term->new;
   # set the term's name and note
   $term->term_name('Dictionary');
   $term->term_note('A list of word definitions');
   # create a facet named Research Tools
   $facet = MyLibrary::Facet->new;
   $facet->facet_name('Research Tools');
   $facet->facet_note('Traditional library objects like dictionaries.');
   $facet->commit;
   # associate (join) this term to that facet
   $term->facet_id($facet->facet_id);
   # save the term to the database
   $code = $term->commit;
   if ($code ne 1) { die 'commit failed' }
   # get the term's id; think "database key"
   $id = $term->term_id;
   # get the term's name and note
   $name = $term->term_name;
   $note = $term->term_note;
   # get a specific term based on its id
   $term = MyLibrary::Term->new(id => 1);


   Given the methods outlined above, you could use the following code to create, save, retrieve, and then
   display relevant term data:

   # configure
   $term_name       =   'Sophomores';
   $term_note       =   'Students in the second year of college';
   $facet_name      =   'Audiences';
   $facet_note      =   'People who use your services';
   # create a term
   $term = MyLibrary::Term->new;
   $term->term_name($term_name);
   $term->term_note($term_note);
   # create a facet
   $facet = MyLibrary::Facet->new;


                                               11
                                          MyLibrary Tutorial



    $facet->facet_name($facet_name);
    $facet->facet_note($facet_note);
    $facet->commit;
    # join and save
    $term->facet_id($facet->facet_id);
    $term->commit;
    # get and display
    $id = $term->term_id;
    $term = MyLibrary::Term->new(id => $id);
    $facet = MyLibrary::Facet->new(id => $term->facet_id);
    print '    ID: ' . $term->term_id     . "\n";
    print ' Name: ' . $term->term_name    . "\n";
    print ' Note: ' . $term->term_note    . "\n";
    print 'Parent: ' . $facet->facet_name . "\n";


    Like the facets, you will often want to get a list of all the terms in your system in order to facilitate some
    sort of browse function. The get_terms method is used for this purpose:

    # get all the terms
    @terms = MyLibrary::Term->get_terms;
    foreach $term (@terms) { print 'Term: ' . $term->term_name . "\n" }


    Creating a list of sorted terms involves creating a list of term ids and calling the sort method denoting
    the sorting field, usually name:

    # get all terms
    @terms = MyLibrary::Term->get_terms;
    # print
    foreach $t (@terms) { print 'Term: ' . $t->term_name . "\n" }
    # create a list of term ids
    foreach $t (@terms) { push @term_ids, $t->term_id }
    # get a sorted list of term id
    @terms = MyLibrary::Term->sort(term_ids => [@term_ids],
                                           type => 'name');
    # print, again
    foreach $t (@terms) {
          $term = MyLibrary::Term->new(id => $t);
          print 'Term: ' . $term->term_name . "\n";
          }


    After terms have been assigned to MyLibrary resource objects a number of other useful term methods
    present themselves, but they are outlined in a later section named "Terms and resources revisited".

    Read the scripts named manage-terms.pl and subroutines.pl to see how you can manage sets of terms
    from a terminal-based interface. For more detail read the MyLibrary::Term pod.


Librarians
    Question: What do libraries have that Yahoo and Google don't have? Answer: Librarians -- people who
    are willing and able to address the information needs of others. That is why librarian objects are a part of


                                                   12
                                     MyLibrary Tutorial



MyLibrary.

Think of librarian objects as information resources with the characteristics of people: name, address,
telephone number, and URL of home page. In libraries librarians usually have subject specialties, and
that is why it is possible to "catalog" librarians with facet/term combinations.

The setting and getting of MyLibrary librarian objects works like this:

# create a librarian
$librarian = MyLibrary::Librarian->new;
# give the librarian characteristics
$librarian->name('Fred Kilgour');
$librarian->email('kilgour@oclc.org');
$librarian->telephone('1 (800) 555-1212');
$librarian->url('http://oclc.org/~kilgour/');
# create an astronomy term as a child of the subjecs facet
$term = MyLibrary::Term->new;
$term->term_name('Astronomy');
$term->term_note('Studying the stars');
$facet = MyLibrary::Facet->new(name => 'Subjects');
$term->facet_id($facet->facet_id);
$term->commit;
# associate (join) the librarian with astronomy
$librarian->term_ids(new => [$term->term_id]);
# save the librarian
$librarian->commit;
# get the librarian
$id = $librarian->id;
$librarian = MyLibrary::Librarian->new(id => $id);
# display basic information about the librarian
print '       ID: ', $librarian->id, "\n";
print '     Name: ', $librarian->name, "\n";
print '    Email: ', $librarian->email, "\n";
print 'Telephone: ', $librarian->telephone, "\n";
print 'Home page: ', $librarian->url, "\n";
# display each of their associated subject areas
@term_ids = $librarian->term_ids;
foreach $id (@term_ids) {
      $term = MyLibrary::Term->new(id => $id);
      print '    Term: ', $term->term_name, "\n";
      }


Just like everything else, you might want to pull all of the librarians out of the system. The class method
get_librarians is used for this purpose. It returns an array of librarian objects:

# get all librarians
@librarians = MyLibrary::Librarian->get_librarians;
# print each librarian's name and email address
foreach $l (@librarians) { print $l->name . ' <' . $l->email . ">\n" }


Question: Who are you going to call? Answer: The Librarian. By creating a set of facet/term combina-

                                              13
                                         MyLibrary Tutorial



    tions and associating them with information resources you can effectively group like things together. By
    associating the same facet/term combinations to librarians you can begin to make connections between
    information resources and librarians. Thus, when displaying lists of information resources, consider
    adding the associated librarian's name and contact information to the list.

    For more detail regarding librarian objects read the MyLibrary::Librarian pod.


Location types
    The world of information resources is made up of many different types. For example there are books,
    journals, and websites. To complicate matters, things like the same books or journals can be manifested
    in physical or digital form. Heck, the book or journal could even exist in a number of physical forms
    such as a codex or microfiche or maybe even a film. Because of these things a single information re-
    source may have many different locations and each of these locations may be of different types: call
    numbers, URL's, buildings, etc. Because all information resources have some sort of location will need
    to create at least one location type in your MyLibrary implementation.

    Location types are just labels for different types of locations. For example, almost all MyLibrary imple-
    mentations will have a location type such as Internet Resource, or URL. If the information resources in
    your MyLibrary implementation includes books -- physical, every-day books -- then another location
    type for your implementation might be Call Numbers. Suppose you have an electronic journal and one
    URL associated with the journal is a pointer to the content and another URL points to a help file. In this
    case you might want to have an additional location type such as Help Location.

    Here are an example of how you might implement a simple Internet resource location type:

    # create a location type
    $location_type = MyLibrary::Resource::Location::Type->new;
    # give it characteristics
    $location_type->name('URL');
    $location_type->description('A type of Internet resource');
    # save it and get its id
    $location_type->commit;
    $id = $location_type->location_type_id;
    # get a location by an id and display its data
    $location_type = MyLibrary::Resource::Location::Type->new(id => $id);
    print '   ID: ' . $location_type->location_type_id . "\n";
    print ' Type: ' . $location_type->name . "\n";
    print ' Note: ' . $location_type->description . "\n";


    Like most of the other modules, MyLibrary::Resource::Location::Type provide a class method for get-
    ting everything. In this case it is all_types, and it returns an array of location type ids:

    # get all location types
    @location_types = MyLibrary::Resource::Location::Type->all_types;
    # display them
    foreach $l (@location_types) {
          $location = MyLibrary::Resource::Location::Type->new(id => $l);
          print 'Type: ' . $location->name . "\n";
          }


    You can also create a location type object by calling it by name, but the name must exist in the underly-

                                                 14
                                         MyLibrary Tutorial



    ing database. To do this you supply the name parameter to the new method:

    # get the location type object named URL
    $location_type = MyLibrary::Resource::Location::Type->new(name => 'URL');
    # print
    print ' Location type ID: ' . $location_type->location_type_id . "\n";
    print 'Location type name: ' . $location_type->name            . "\n";
    print 'Location type note: ' . $location_type->description     . "\n";


    Because information resources are manifested in many ways, and since each of these ways are usually
    associated with different types of "addresses" (such as URLs or call numbes) MyLibrary provides as
    means of creating and listing such types.

    See the terminal-based program called location-types.pl as well as the pod for MyLib-
    rary::Resource::Location::Type for more detail.


Resources
    Now the fun really begins.

    With the exception of the librarians, all of the previous sections essentially described how to create sets
    of controlled vocabularies. Facets. Terms. Location types. You are now ready to create lists of informa-
    tion resources, describe them, classify them, and save them to the underlying database. Once you have
    built your collection you are expected to write reports against it implementing various services such as:
    browse, search, What's New?, Find More Like This One, most popular, most useful, export subsets to a
    file, send subsets as email, create RSS feeds, etc. In today's world of changing user expectations it is not
    only about collections. It is more about the effective combination of collections and services.

    MyLibrary resource objects include methods for setting and getting the objects' characteristics, and these
    characteristics are a superset of the basic fifteen Dublin Core elements. There is an implicit one-to-one
    relationship between the basic Dublin Core element names and many of the MyLibrary resource object
    methods/objects, listed below:

    1.    contributor       -->   MyLibrary::Resource->contributor
    2.    coverage          -->   MyLibrary::Resource->coverage
    3.    creator           -->   MyLibrary::Resource->creator
    4.    date              -->   MyLibrary::Resource->date
    5.    description       -->   MyLibrary::Resource->note
    6.    format            -->   MyLibrary::Resource->format
    7.    identifier        -->   MyLibrary::Resource::Location
    8.    language          -->   MyLibrary::Resource->language
    9.    publisher         -->   MyLibrary::Resource->publisher
    10.   relation          -->   MyLibrary::Resource->relation
    11.   rights            -->   MyLibrary::Resource->rights
    12.   source            -->   MyLibrary::Resource->source
    13.   subject           -->   MyLibrary::Resource->subject
    14.   title             -->   MyLibrary::Resource->name
    15.   type              -->   MyLibrary::Resource->type


    This mapping makes it relatively easy to store Dublin Core-based descriptions of information resources
    into a MyLibrary implementation. The items described in OAI-PMH data repositories come immedi-
    ately to mind.

    As a simple example of setting and getting values of MyLibrary resource objects, let's set and get a link
    to a fictional electronic version of The Adventures of Huckleberry Finn:

    # create a resource object

                                                  15
                                       MyLibrary Tutorial



$resource = MyLibrary::Resource->new;
# describe it
$resource->creator('Mark Twain');
$resource->format('ebook');
$resource->language('en');
$resource->name('The Adventures of Huckleberry Finn');
$resource->note('This is a coming of age story.');
$resource->subject('young adult reading');
$resource->type('text/html');
# give it a URL
$location_type = MyLibrary::Resource::Location::Type->new(name => 'URL');
$resource->add_location(location      => 'http://library.org/finn.html',
                      location_type => $location_type->location_type_id);
# save it
$resource->commit;
# get it
$id = $resource->id;
$resource = MyLibrary::Resource->new(id => $id);
# output the data
print '      Author:           '   .   $resource->creator            .   "\n";
print '      Format:           '   .   $resource->format             .   "\n";
print '    Language:           '   .   $resource->language           .   "\n";
print '       Title:           '   .   $resource->name               .   "\n";
print ' Description:           '   .   $resource->note               .   "\n";
print '     Subject:           '   .   $resource->subject            .   "\n";
print '   MIME type:           '   .   $resource->type               .   "\n";
# get the url; assume there is only one
@locations = $resource->resource_locations;
print '         URL: ' . $locations[0]->location . "\n";


With the exception of the location attributes, this should be pretty straight-forward. (Remember, inform-
ation resources can have more than one location and more than one location type. This is why setting
and getting the location of resource objects is not as simple as the other attributes.)

While the procedure outlined above is functional, it is not necessarily complete. It does not take advant-
age of your facet/term combinations. Let's assume you have a facet called Subjects. Let's also assume
you have the terms American Literature and Young Adult Reading assigned to the Subjects facet. Given
this you can use the related_terms method to classify a resource with these terms. Very, very important!
To get the terms back out you again use the related_terms method. It returns an array of term ids (keys):

# get the facet id for subjects
$facet = MyLibrary::Facet->new(name => 'Subjects');
$facet_id = $facet->facet_id;
# create the subject term amerian literature
$term = MyLibrary::Term->new;
$term->term_name('American Literature');
$term->term_note('Writings of the New World');
$term->facet_id($facet_id);
$term->commit;
$american_literature = $term->term_id;
# create the subject term young adult reading
$term = MyLibrary::Term->new;
$term->term_name('Young Adult Reading');
$term->term_note('Literature for the middle schoolers');

                                              16
                                           MyLibrary Tutorial



    $term->facet_id($facet_id);
    $term->commit;
    $young_reading = $term->term_id;
    # get huck finn and assume there is only one matching record
    @resources = MyLibrary::Resource->new(
                               name => 'The Adventures of Huckleberry Finn');
    $resource = $resources[0];
    $resource->related_terms(new => [$american_literature, $young_reading]);
    $resource->commit;
    # output the data
    print '      Author:           '   .   $resource->creator              .   "\n";
    print '      Format:           '   .   $resource->format               .   "\n";
    print '    Language:           '   .   $resource->language             .   "\n";
    print '       Title:           '   .   $resource->name                 .   "\n";
    print ' Description:           '   .   $resource->note                 .   "\n";
    print '     Subject:           '   .   $resource->subject              .   "\n";
    print '   MIME type:           '   .   $resource->type                 .   "\n";
    # get the url; assume there is only one
    @locations = $resource->resource_locations;
    print '         URL: ' . $locations[0]->location . "\n";
    # get the related terms
    @related_terms = $resource->related_terms;
    foreach $rt (@related_terms) {
         # print the term name
         $term = MyLibrary::Term->new(id => $rt);
         print '       Term : ' . $term->term_name . "\n";
         }


    Read manage-resources.pl, subroutines.pl to learn how to implement these ideas in a terminal-based en-
    vironment. See the pod of MyLibrary::Resource for more detail because there are many more methods
    to be found there.

    A Zen Master once said, "Collections without services are useless, and services without collections are
    empty." Use MyLibrary to create a collection of information resources, and then use MyLibrary to
    provide services against the collection. Both are necessary in order to meet the expectations of today's
    users of libraries.


Terms and resources revisited
    Once you have created sets of MyLibrary resources and associated them with sets of MyLibrary terms
    you can exploit a couple more term methods to query your MyLibrary database.

    You can use the MyLibrary::Term class method called related_resources to create a list of resources as-
    sociated with a term. For example, suppose you have a term named Astronomy, then you could use the
    following code to list the names and descriptions of all those resources:

    # require the necessary modules
    use MyLibrary::Term;
    use MyLibrary::Resource;
    # get the id for the astronomy term, assume there is only one
    @terms = MyLibrary::Term->get_terms(field => 'name', value => 'Astronomy');
    $term = MyLibrary::Term->new(id => @terms[0]->term_id);
    $astronomy = $term->term_id;

                                                  17
                                    MyLibrary Tutorial




# create astronomy resources, #1 of 3
$resource = MyLibrary::Resource->new;
$resource->name('Stars amoung us');
$resource->note('No, not movie stars');
$resource->related_terms(new => [$astronomy]);
$resource->commit;
# resource #2 of 3
$resource = MyLibrary::Resource->new;
$resource->name('Guiding lights');
$resource->note('Soap operas and beyond');
$resource->related_terms(new => [$astronomy]);
$resource->commit;
# resource #3 of 3
$resource = MyLibrary::Resource->new;
$resource->name('My Guide the the Galaxy');
$resource->note('As if the Hitchhikers was not good enough');
$resource->related_terms(new => [$astronomy]);
$resource->commit;
# get all astronomy resources through the term
$term = MyLibrary::Term->new(id => $astronomy);
@resource_ids = $term->related_resources;
# display information about the resources
foreach $id (@resource_ids) {
      $resource = MyLibrary::Resource->new(id => $id);
      print ' Name: ' . $resource->name . "\n";
      print ' Note: ' . $resource->note . "\n\n";
      }


The suggested_resources method allows you to set and get lists of resource ids determined to be particu-
larly useful. Think recommendations. For example, suppose there is a resource called Most Cool Astro-
nomy Site. Suppose also it is determined that this particular site lives up to its name and when display-
ing lists of astronomy resources you would like to highlight this one in particular. To do this you would
first use the suggested_resources method set this value:

# get the id for astronomy; assume there is only one astronomy-like term
@terms = MyLibrary::Term->get_terms(field => 'name', value => 'Astronomy');
$term = MyLibrary::Term->new(id => @terms[0]->term_id);
$astronomy = $term->term_id;
# create an astronomy resource
$resource = MyLibrary::Resource->new;
$resource->name('Most Cool Astronomy Site');
$resource->related_terms(new => [$astronomy]);
# save and get its id (key)
$resource->commit;
$id = $resource->id;
# get the astronomy term
$term = MyLibrary::Term->new(id => $astronomy);
# denote our resource as a suggested item for astronomy, and save
$term->suggested_resources(new => [$id]);
$term->commit;



                                             18
                                     MyLibrary Tutorial



You can then list all the resources associated with a term and then specify which ones are recommended:

# get the id for astronomy; assume there is only one astronomy-like term
@terms = MyLibrary::Term->get_terms(field => 'name', value => 'Astronomy');
$term = MyLibrary::Term->new(id => @terms[0]->term_id);
# get all astronomy resource ids and suggestion ids
@resources   = $term->related_resources(sort => 'name');
@suggestions = $term->suggested_resources;
# process each resource
foreach $r (@resources) {
      # get the resource and print its name
      $resource = MyLibrary::Resource->new(id => $r);
      print ' Name: ' . $resource->name;
      # loop through each suggestion
      foreach $s (@suggestions) {
            # compare suggestion and resource ids
            if ($s == $r) {
                  # specify this as suggested resource
                      print ' (suggested)';
                      last;
                  }
            }
            print "\n";
      }


You will often want work with entire sets or subsets of resources from your MyLibrary implementation,
and the get_resources method is used for this purpose. Once you get the set of resources you are expec-
ted to loop through them and extract the ones you really need. Here is a simple way to get all the re-
sources as objects and print their names:

# get all resources and display
@resources = MyLibrary::Resource->get_resources;
foreach $resource (@resources) { print $resource->name . "\n" }


You can do the same thing, but return a sorted list

# get a sorted list, by name, of resources
@resources = MyLibrary::Resource->get_resources(sort => 'name');
foreach $resource (@resources) { print $resource->name . "\n" }


Besides the basic Dublin Core elements, MyLibrary allows you to assign additional attributes to re-
sources. The first of note is foreign key through the fkey method. This is intended to store things like
OCLC numbers, catalog record numbers, or OAI identifiers in MyLibrary resource objects. By combin-
ing the fkey values with things like URL it is often possible to link to back to some other list of informa-
tion resources. You set and get fkey values just like most of the other attributes:

# create a resource
$resource = MyLibrary::Resource->new;
# set the name and fkey value

                                              19
                                     MyLibrary Tutorial



$resource->name('Tom Sawyer Rides Again');
$resource->fkey('123457');
$resource->commit;
# print it
print ' Foreign key: ' . $resource->fkey . "\n";


The lcd ("lowest common denominator") method is intended to denote information resources that are
useful to anybody, not restricted to any MyLibrary term. For example, most librarians will believe the
catalog is a tool useful for everybody for every discipline. A general encyclopedia and dictionary are
other examples. Denote a resource as a "lowest common denominator" resource like this:

# create and denote a resource as an "lcd" resource
$resource = MyLibrary::Resource->new;
$resource->name('Library catalog');
$resource->lcd(1);
$resource->commit;


To get a list of all the resource objects denoted as lowest common denominator resources, use the class
method lcd_resources:

# get all "lcd" resources and display
@lcd_resources = MyLibrary::Resource->lcd_resources;
print "These resources are useful to everyone:\n";
foreach $r (@lcd_resources) { print "\t" . $r->name . "\n" }


Through the qsearch_prefix, qsearch_suffix, and qsearch_redirct methods you are able to reverse engin-
eer many Internet search engines. Take a simple Google search for the word cat, ht-
tp://www.google.com/search?q=cat. This URL can be divided into at least three parts: 1) the root (ht-
tp://www.google.com/), 2) a prefix (search?q=), 3) the query itself (cat), and 4) an optional suffix (null
in this example).

You might use this code to create a resource for Google and add a search prefix to it:

# create a resource describing Google
$resource = MyLibrary::Resource->new;
$resource->name('Google');
$resource->note('A very popular Internet index');
# get the location type of URL
$location_type = MyLibrary::Resource::Location::Type->new(name => 'URL');
$type_id = $location_type->location_type_id;
# give the resource a URL
$resource->add_location(location => 'http://www.google.com/',
                location_type => $type_id);
# add a quick search prefix and save
$resource->qsearch_prefix('search?q=');
$resource->commit;
$id = $resource->id;
# begin echoing results
$resource = MyLibrary::Resource->new(id => $id);
print ' Title: ' . $resource->name . "\n";
print '   Note: ' . $resource->note . "\n";
# get the location; assume there is only one
@locations = $resource->resource_locations;


                                             20
                                         MyLibrary Tutorial




    # echo more results
    print '    URL: ' . $locations[0]->location . "\n";
    print ' Prefix: ' . $resource->qsearch_prefix . "\n";


    Now suppose you have some sort of HTML form that accepts text input. Using the qsearch_redirect
    method the input can be transformed into a URL to search the resource. Something like this:

    # get a query
    $query = 'foobar';
    # get the Google resource; assume there is only one
    @resources = MyLibrary::Resource->new(name => 'Google');
    $resource = $resources[0];
    # get the location; assume there is only one
    @locations = $resource->resource_locations;
    $root_url = $locations[0]->location;
    # build a URL to search
    $url = $resource->qsearch_redirect(resource_id => $resource->id,
                                       qsearch_arg => $query,
                                       primary_location => $root_url);
    # display in an HTML snippet
    print "<a href='$url'>Click here</a> to search Google for '$query'.\n";


    Take this technique a step further. Suppose your MyLibrary implementation contains records from your
    library catalog. Suppose each MyLibrary resource record includes an fkey value pointing to the full re-
    cord in the catalog. Suppose that you also have a MyLibrary record describing your catalog, and that re-
    cord is complete with a qsearch_prefix and optional qsearch_suffix values. Using the qsearch_redirect
    method you could display brief records on a Web page and link back to the full record in your library
    catalog by using the fkey value as the qsearch_arg attribute.


Implementing search
    This section outlines a method for making the content of your MyLibrary implementation searchable.

    MyLibrary is essentially a relational database application. As such, searching the database requires quer-
    ies be converted into SQL. By definition these SQL queries must specify what fields to search. Unfortu-
    nately people expect to perform freetext queries against sets of content, not necessarily fielded searches.
    Moreover, people increasingly expect relevancy ranked output as well as output sorted by this, that, and
    the other thing. For these reasons you are encouraged to use an intermediary indexing application to im-
    plement searchability instead of querying the database directly.

    Making your MyLibrary content searchable through an intermediate indexer uses this process:

    1.   Write a report against MyLibrary.
    2.   Feed the report to the indexer.
    3.   Index the report.
    4.   Provide a Perl interface to search the index.
    5.   Search results are integers -- MyLibrary database keys.
    6.   Use the keys to get data from MyLibrary.
    7.   Reformat the data for display and return it to the user.


    Swish-e is a good indexer. Simple, fast, and it comes with a Perl API. This will be the indexer in this ex-
    ample, but something like Plucene would work just as well.

                                                  21
                                      MyLibrary Tutorial



The first step is to write a report against the MyLibrary database. Swish-e expects its input to look much
like HTML. The following code outputs a very simple report containing only the titles and notes of
every resource in a MyLibrary instance. The report is in a form swish-e expects:

# require
use MyLibrary::Resource;
# first, get all of the resource ids
@resource_ids = MyLibrary::Resource->get_ids;
# process each id
foreach $resource_id (@resource_ids) {
      # get a resource
      $resource = MyLibrary::Resource->new(id => $resource_id);
      # get its id, title, and note
      $id    = $resource->id;
      $title = $resource->name;
      $note = $resource->note;
      # build     the report
      $output     = '';
      $output     .= '<html>';
      $output     .= '<head>';
      $output     .= "<meta name='title' content='$title' />";
      $output     .= "<meta name='note' content='$note' />";
      $output     .= '</head>';
      $output     .= '<body>';
      $output     .= "<h1>$title</h1>";
      $output     .= "<p>$note</p>";
      $output     .= '</body>';
      $output     .= '</html>';
      # output a swish-e header
      print "Path-Name: $id\n";
      print "Content-length: " . scalar(length $output) . "\n";
      print "Document-Type: HTML*\n";
      print "\n";
      # output the report
      print "$output";
      }


The next step is to build a configuration file telling swish-e what to look for in the report. In our case the
configuration needs to know about the title and note, and the configuration could be this simple:

# define fields to index and make searchable
MetaNames title note
PropertyNames title note
# define the location and name of the resulting index
IndexFile ./mylibrary.idx


Finally, you need to run your report generator and pipe the output to swish-e specifying the configura-
tion file. You can do this from the command line. Assuming your report generator is called mylib-
rary2swish.pl and your swish-e configuration file is called mylibrary2swish.cfg, then the command
might look like this:

./mylibrary2swish.pl | swish-e -c ./mylibrary2swish.cfg -S prog -i stdin


                                               22
                                     MyLibrary Tutorial



The result should be a two files, mylibrary.idx and mylibrary.idx.prop. These files are your swish-e in-
dex and you should be able to search them from the command line using the swish-e binary. Remember,
you only included name and note in your output so only those fields will be searched. Also, queries will
only return ids, not words.

The next step is to provide the ability to search the index. As queries are accepted the swish-e Perl API
is used to search the index. Queries return MyLibrary keys, and these keys are used to look up the values
of resources:

# require the necessary modules
use MyLibrary::Resource;
use SWISH::API;
# define the location of your index
$INDEX = './mylibrary.idx';
# get the input
print "Enter a query. ";
chop (my $query = <STDIN>);
# search     the index
$swish       = SWISH::API->new($INDEX);
$results     = $swish->Query($query);
$hits        = $results->Hits;
# branch according to the number of hits
if ($hits) {
      print "Your search ($query) returned $hits hit(s).\n\n";
      $counter = 0;
      # process each result
      while ($result = $results->NextResult) {
            # get the id (key)
            $id = $result->Property("swishdocpath");
            # get the      resource, title, and note
            $resource      = MyLibrary::Resource->new(id => $id);
            $title         = $resource->name;
            $note          = $resource->note;
            # increment the counter
            $counter++;
            # print the result
            print "$counter. $title - $note\n\n";
            }
      }
      else {
            print "No hits. Sorry.\n";
      }


This section has outlined the most basic of search interfaces. Your reports sent to swish-e will want to be
much more verbose.

For more information see index-resources.pl, index-resources.cfg, resources2swish.pl, and search.pl that

                                              23
                                           MyLibrary Tutorial



    came with the distribution. These files implement a more full-featured, terminal-based program for
    search.


MyLibrary and OAI
    Because the MyLibrary database so closely resembles the basic Dublin Core elements, and because OAI
    requires data repositories to support Dublin Core, it is almost trivial to harvest the content of OAI repos-
    itories and cache it to a MyLibrary database.

    The following script does just that, and in a nutshell here is how it works:

    1.    Define the repository to harvest.
    2.    Create a facet called Formats, if it doesn't exist.
    3.    Create a term called Images, if it doesn't exist.
    4.    Create a location type called URL, if it doesn't exist.
    5.    Harvest all the records from the repository.
    6.    Loop through each harvested record.
    7.    Create a MyLibrary resource object.
    8.    Fill the resource with attributes.
    9.    Save the resource.
    10.   Go to Step #6 'till done.


    # include the necessary modules
    use MyLibrary::Core;
    use Net::OAI::Harvester;
    # define the repository
    $repository = 'http://infomotions.com/gallery/oai/index.pl';
    # check for a facet called Formats
    $facet = MyLibrary::Facet->new;
    if (! MyLibrary::Facet->get_facets(value => 'Formats', field => 'name')) {
           # create it
           $facet->facet_name('Formats');
           $facet->facet_note('Types of physical items embodying information.');
           $facet->commit;
           print "\nThe facet Formats was created.\n";
           }
    else {
           # already exists
           $facet = MyLibrary::Facet->new(name => 'Formats');
           print "\nThe facet Formats already exists.\n";
           }
    # remember this facet id
    $facetID = $facet->facet_id;
    # check for a term named Images
    $term = MyLibrary::Term->new;
    if (! MyLibrary::Term->get_terms(value => 'Images', field => 'name')) {
           # create it
           $term->term_name('Images');
           $term->term_note('These are things like photographs or paintings.');
           $term->facet_id($facetID);

                                                    24
                         MyLibrary Tutorial



    $term->commit;
    print "The term Images was created.\n";
    }
else {
    # it already exists
    $term = MyLibrary::Term->new(name => 'Images');
    print "The term Images already exists.\n";
    }
# remember this term id
$imageTermID = $term->term_id;
# check for a location type called URL
$location_type = MyLibrary::Resource::Location::Type->new;
if (! MyLibrary::Resource::Location::Type->new(name => 'URL')) {
    # create it
    $location_type->name('URL');
    $location_type->description('A type of Internet resource.');
    $location_type->commit;
    print "The location type URL was created.\n";
    }
else {
    # it already exists
    $location_type = MyLibrary::Resource::Location::Type->new(name => 'URL');
    print "The location type URL already exists.\n";
    }
# remember the location type id
$location_type_id = $location_type->location_type_id;
# create a harvester and get the data
$harvester = Net::OAI::Harvester->new('baseURL' => $repository);
$records = $harvester->listAllRecords('metadataPrefix' => 'oai_dc');
# process each record
while ($record = $records->next) {
    $FKey         = $record->header->identifier;
    $metadata     = $record->metadata;
    $name         = $metadata->title;
    @description = $metadata->description;
    $description = join (' ', @description);
    $location     = $metadata->identifier;
    print "$name...";
    # check to see if it already exits
    if (! MyLibrary::Resource->new(fkey => $FKey)) {
         # create it
         $resource = MyLibrary::Resource->new;
         $resource->name($name);
         $resource->note($description);
         $resource->fkey($FKey);
         $resource->related_terms(new => [$imageTermID]);
         $resource->add_location(location => $location,
                                        location_type => $location_type_id);

                                 25
                                         MyLibrary Tutorial



               $resource->commit;
               print "added (", $resource->id, ").\n";
               }
         else {
               # already got it
               print "already exists.\n";
               }
         }
         # done
         print "\nDone\n";
         exit;


   While this was the longest example in this tutorial, this particular OAI to MyLibrary interface is very
   rudimentary. See the script named images2mylibrary.pl from the distribution to see how you can harvest
   OAI sets. See doaj2mylibrary.pl to see how you can more accurately classify incoming resources based
   on set names. The really enterprising reader will figure out ways to read the incoming Dublin Core sub-
   ject fields and create facet/term combinations accordingly.


Summary
   Unlike version 2.x of MyLibrary, version 3.x is more like a toolbox and less like a turn-key application.
   Developers are expected to read and write values to the MyLibrary database, manipulate these values to
   create sets of information services.

   The examples above point to terminal-based scripts implementing the described concepts. The distribu-
   tion comes with another set of scripts implementing these ideas using a Web-based interface. They use
   all of the concepts outlined above but they are CGI scripts implemented in a more graphical interface.

   Use MyLibrary in conjunction with other Perl modules. In a more traditional library you might consider
   reading sets of MARC records to create a sort of online catalog. Provide an SRU interface to your in-
   dexed content and then transform the XML returned from the SRU server into email messages or RSS
   feeds. Create CGI scripts that return Javascript that simply write to the document window. Then call
   these CGI scripts from within HTML elements. This will enable HTML authors to incorporate MyLib-
   rary content into their pages. You might harvest data from various but similar OAI repositories to create
   subject-specific collections. Index the collection and provide an interface to it. You might create Web-
   based input screens allowing authors to submit information about publications thus implementing a sort
   of institutional repository. Use your imagination. Think a bit outside the box.

   When you've got a hammer everything looks like a nail. While MyLibrary is not necessarily a perfect
   hammer, it can address many of the needs in libraries to create, maintain, and distribute classified lists of
   information resources. The key to success is discovering ways to re-purpose these lists meeting the ex-
   pressed needs of library users.

   --

   Eric Lease Morgan

   January 21, 2006




                                                 26
Part II. Perl API
Table of Contents
2. MyLibrary::Core ................................................................................................................... 31
           NAME .................................................................................................................... 31
           SYNOPSIS .............................................................................................................. 31
           DESCRIPTION ........................................................................................................ 31
3. MyLibrary::DB ..................................................................................................................... 32
           NAME .................................................................................................................... 32
           SYNOPSIS .............................................................................................................. 32
           DESCRIPTION ........................................................................................................ 32
           FUNCTIONS ........................................................................................................... 32
           dbh() ...................................................................................................................... 32
4. MyLibrary::Facet ................................................................................................................... 33
           NAME .................................................................................................................... 33
           SYNOPSIS .............................................................................................................. 33
           DESCRIPTION ........................................................................................................ 33
           METHODS .............................................................................................................. 33
           new() ...................................................................................................................... 34
           facet_id() ................................................................................................................. 34
           facet_name() ............................................................................................................ 34
           facet_note() .............................................................................................................. 34
           delete_facet_note() .................................................................................................... 35
           commit() ................................................................................................................. 35
           delete() ................................................................................................................... 35
           get_facets() .............................................................................................................. 35
           related_terms() ......................................................................................................... 36
5. MyLibrary::Term ................................................................................................................... 37
           NAME .................................................................................................................... 37
           SYNOPSIS .............................................................................................................. 37
           DESCRIPTION ........................................................................................................ 38
           METHODS .............................................................................................................. 38
           new() ...................................................................................................................... 38
           term_id() ................................................................................................................. 38
           term_name() ............................................................................................................ 39
           term_note() .............................................................................................................. 39
           delete_term_note() .................................................................................................... 39
           facet_id() ................................................................................................................. 39
           commit() ................................................................................................................. 40
           delete() ................................................................................................................... 40
           get_terms() .............................................................................................................. 40
           related_resources() .................................................................................................... 40
           suggested_resources() ................................................................................................ 42
           librarians() ............................................................................................................... 43
           sort() ...................................................................................................................... 43
           overlap() ................................................................................................................. 44
           distinct_terms() ......................................................................................................... 44
6. MyLibrary::Resource ............................................................................................................. 45
           NAME .................................................................................................................... 45
           SYNOPSIS .............................................................................................................. 45
           DESCRIPTION ........................................................................................................ 47
           METHODS .............................................................................................................. 47
           new() ...................................................................................................................... 47
           name() .................................................................................................................... 48
           note() ...................................................................................................................... 48
           access_note() ............................................................................................................ 48

                                                                        28
                                                                    Perl API


           coverage_info() ........................................................................................................ 49
           full_text() ................................................................................................................ 49
           reference_linking() .................................................................................................... 49
           lcd() ....................................................................................................................... 49
           fkey() ...................................................................................................................... 50
           qsearch_prefix() and qsearch_suffix() ........................................................................... 50
           date() ...................................................................................................................... 51
           id() ......................................................................................................................... 51
           commit() ................................................................................................................. 52
           delete_[attribute_name]() ............................................................................................ 52
           delete() ................................................................................................................... 52
           get_resources() ......................................................................................................... 52
           lcd_resources() ......................................................................................................... 53
           qsearch_redirect() ..................................................................................................... 54
           get_fkey() ................................................................................................................ 54
           test_relation() ........................................................................................................... 55
           related_terms() ......................................................................................................... 55
           proxied() ................................................................................................................. 56
           creator() .................................................................................................................. 57
           publisher() ............................................................................................................... 57
           contributor() ............................................................................................................. 57
           coverage() ............................................................................................................... 57
           rights() .................................................................................................................... 58
           language() ............................................................................................................... 58
           source() ................................................................................................................... 58
           relation() ................................................................................................................. 58
           add_location() .......................................................................................................... 59
           delete_location() ....................................................................................................... 59
           resource_locations() .................................................................................................. 59
           modify_location() ..................................................................................................... 59
           get_location() ........................................................................................................... 60
7. MyLibrary::Resource::Location ................................................................................................ 61
           NAME .................................................................................................................... 61
           SYNOPSIS .............................................................................................................. 61
           DESCRIPTION ........................................................................................................ 62
           METHODS .............................................................................................................. 62
           new() ...................................................................................................................... 62
           commit() ................................................................................................................. 63
           id() ......................................................................................................................... 63
           location() ................................................................................................................. 63
           location_note() ......................................................................................................... 63
           resource_location_type() ............................................................................................ 63
           resource_id() ............................................................................................................ 64
           get_locations() .......................................................................................................... 64
           id_list() ................................................................................................................... 64
           delete() ................................................................................................................... 65
           location_type() ......................................................................................................... 65
8. MyLibrary::Resource::Location::Type ....................................................................................... 66
           NAME .................................................................................................................... 66
           SYNOPSIS .............................................................................................................. 66
           DESCRIPTION ........................................................................................................ 66
           METHODS .............................................................................................................. 66
           new() ...................................................................................................................... 66
           name() .................................................................................................................... 67
           description() ............................................................................................................. 67
           location_type_id() ..................................................................................................... 67
           commit() ................................................................................................................. 68
           delete() ................................................................................................................... 68


                                                                        29
                                                                    Perl API


           all_types() ............................................................................................................... 68
9. MyLibrary::Librarian ............................................................................................................. 69
           NAME .................................................................................................................... 69
           SYNOPSIS .............................................................................................................. 69
           DESCRIPTION ........................................................................................................ 70
           METHODS .............................................................................................................. 70
           new() ...................................................................................................................... 70
           id() ......................................................................................................................... 70
           name() .................................................................................................................... 70
           telephone() .............................................................................................................. 70
           email() .................................................................................................................... 71
           url() ........................................................................................................................ 71
           term_ids() ................................................................................................................ 71
           commit() ................................................................................................................. 72
           delete() ................................................................................................................... 72
           get_librarians() ......................................................................................................... 72
           ACKNOWLEDGEMENTS ........................................................................................ 73




                                                                        30
Chapter 2. MyLibrary::Core
NAME
   MyLibrary - a database-driven website application for libraries


SYNOPSIS

       use MyLibrary::Core;



DESCRIPTION
   MyLibrary is a set of object-oriented Perl modules designed to facilitate I/O against a specific, underly-
   ing database structure. At its heart, the database contains a table for information resources, and this table
   is described, for the most part, using Dublin Core. The database also contains tables for creating a con-
   trolled vocabulary of your own design. This controlled vocabulary, in the shape of facets and terms, are
   used to describe and classify the items in the resources table.

   These modules facilitate the normal get and set methods found in other database interfaces. The modules
   also facilitate various find methods allowing you to extract sets of information resources. the developer
   is expected to loop through these sets of data and output them in format so desired which might include
   HTML, XML, plain text, etc.

   Using these modules the developer could:


   •   import data from MARC records

   •   import data from OAI repositories

   •   develop an interface for manual data-entry

   •   create reports, feed them to an indexer, and facilitate search

   •   create reports, format them as HTML, and save them to the file system

   •   write CGI scripts that generate dynamic pages

   •   write CGI scripts and output XML thus implementing a Web Service


   To get started, read the PODs for MyLibrary::Facet, MyLibrary::Term, and MyLibrary::Resource.




                                                  31
Chapter 3. MyLibrary::DB
NAME
        MyLibrary::DB


SYNOPSIS

        use MyLibrary::DB;
        my $dbh = MyLibrary::DB->dbh();



DESCRIPTION
        This package connects to MyLibrary and returns the database handle.


FUNCTIONS
dbh()
        Returns database handle to MyLibrary.




                                                   32
Chapter 4. MyLibrary::Facet
NAME
   MyLibrary::Facet


SYNOPSIS

   # require the necessary module
   use MyLibrary::Facet;
   # create a new Facet object
   my $facet = MyLibrary::Facet->new();
   # set attributes of facet object
   $facet->facet_name('Facet Name');
   $facet->facet_note('This is a facet note');
   # delete a facet note
   $facet->delete_facet_note();
   # commit facet to database
   $facet->commit();
   # delete facet from database
   $facet->delete();
   # get all facets
   my @facets = MyLibrary::Facet->get_facets();
   my @facets = MyLibrary::Facet->get_facets(sort => 'name');
   # get specific facets based on criteria
   my @facets = MyLibrary::Facet->get_facets(value => 'Discipline', field =>
          'name');
   # return related terms
   my @related_terms = $facet->related_terms();
   # return a sorted list of related terms
   my @related_terms = $facet->related_terms(sort => 'name');




DESCRIPTION
   The purpose of this module is to manipulate MyLibrary Facet objects and perform database I/O against
   the facets table of a MyLibrary database. You may also retrieve a list of facet objects by using a special
   class method. A list of term ids with which a particular facet is associated can be retrieved as well and
   manipulated independently. All changes to either the facet descriptive data can be commited to the data-
   base.


METHODS
                                                33
                                              MyLibrary::Facet



new()
        This method creates a new facet object. Called with no input, this constructor will return a new, empty
        facet object:



        # create empty facet
        $facet = MyLibrary::Facet->new();




        The constructor can also be called using a known facet id or facet name:



        # create a facet object using a known facet id
        $facet = MyLibrary::Facet->new(id => $id);
        # create a facet object using a known facet name
        $facet = MyLibrary::Facet->new(name => 'Disciplines');




facet_id()
        This object method is used to retrieve the facet id of the current facet object. This method cannot be used
        to set the facet id.



        # get facet id
        my $facet_id = $facet->facet_id();




facet_name()
        This is an attribute method which allows you to either get or set the name attribute of a facet. The names
        for facets will be created by the institutional team tasked with the responsibility of designating the broad
        categories under which resources will be categorized. To retrieve the name attribute:



        # get the facet name
        $facet->facet_name();
        # set the facet name
        $facet->facet_name('Format');




facet_note()
        This method allows one to either retrieve or set the facet descriptive note.


                                                      34
                                            MyLibrary::Facet



      To retrieve the note attribute:



      # get the facet note
      $facet->facet_note();
      # set the facet note
      $facet->facet_note('The subject area under which a resource may be
              classified.');




delete_facet_note()
      This object attribute method allows the removal of the facet note



      # delete the facet note
      $facet->delete_facet_note()




commit()
      Use this method to commit the facet in memory to the database. Any updates made to facet attributes
      will be saved and new facets created will be saved. This method does not take any parameters.



      # commit the facet
      $facet->commit();




      A numeric code will be returned upon successfull completion of the operation. A return code of 1 indic-
      ates a successful commit. Otherwise, the method will cease program execution and die with an appropri-
      ate error message.

delete()
      Use this method to remove a facet record from the database. The record will be deleted permanently.



      # delete the facet
      $facet->delete();




get_facets()
      This method can be used to retrieve a list of all of the facets currently in the database. Individual facet
      objects will be created and can be cycled through. This is a class method, not an object method. If the

                                                    35
                                            MyLibrary::Facet



     sort parameter is supplied, the list of facet ids will be sorted. Currently, the list can only be sorted by fa-
     cet name. A specific list of facets can also be queried for by using the field and value parameters.
     Searchable fields are name and description. Examples are demonstrated below.



     # get all facets
     my @facets = MyLibrary::Facet->get_facets();
     # sort the returned list
     my @facets = MyLibrary::Facet->get_facets(sort => 'name');
     # find all facets based on criteria
     my @facets = MyLibrary::Facet->get_facets(value => 'Discpline', field =>
             'name');




related_terms()
     This method should be used to return an array (a list) of term ids to which this facet is related. It requires
     no parameter input. If the facet is not related to any terms in the database, the method will return undef.
     The array of term ids can then be used to process the list of related terms. The returned list of term ids
     can also be sorted. This is an object method.



     # return related terms
     my @related_terms = $facet->related_terms();
     # return sorted list of related terms
     my @related_terms = $facet->related_terms(sort => 'name');




                                                    36
Chapter 5. MyLibrary::Term
NAME
   MyLibrary::Term


SYNOPSIS
   # require the necessary module
   use MyLibrary::Term;
   # create a new Term object
   my $term = MyLibrary::Term->new();
   # set the attributes of a Term object
   $term->term_name('Term One');
   $term->term_note('Sample note for a term');
   $term->facet_id(9999);
   # delete the term note
   $term->delete_term_note();
   # commit Term data to database
   $term->commit();
   # get a list of all term objects
   my @terms = MyLibrary::Term->get_terms();
   # get list of term objects based on criteria
   my @terms = MyLibrary::Term->get_terms(field => 'name', value =>
          'Chemistry');
   # get a list of all related resource ids
   my @related_resources = $term->related_resources();
   # delete relations between terms and resources
   my @related_resources = $term->related_resources(del => [@resource_ids]);
   # set new relations between a term and resources
   my @related_resources = $term->related_resources(new => [@resource_ids]);
   # sort a list of returned resource ids according to name
   my @related_resources = $term->related_resources(sort => 'name');
   # get a list of all related suggested resource ids
   my @suggested_resources = $term->suggested_resources();
   # retrieve a sorted list of related suggested resource ids
   my @suggested_resources = $term->suggested_resources(sort => 'name');
   # return a list of related librarian objects
   my @librarians = $term->librarians();
   # return a list of related librarian ids
   my @librarians = $term->librarians(output => 'id');
   # add a list of librarians to this term, dismissing database relational
          integrity
   $term->librarians(new => [@librarian_ids], strict => 'off');


                                    37
                                              MyLibrary::Term




        # sort a list of supplied term ids according to specific criteria
        my @sorted_terms = MyLibrary::Term->sort(term_ids => [@term_ids], type =>
                'name');
        # return overlapping resources with this term (~30 term ids max)
        my @overlap_resources = $term->overlap(term_ids => [@term_ids]);
        # return a distinct set of related terms within a resource group
        my @distinct_terms = MyLibrary::Term->distinct_terms(resource_ids =>
                [@resource_ids]);
        # delete a list of librarians from this term
        $term->librarians(del => [@librarians_ids]);
        # delete a Term object from the database
        $term->delete();


DESCRIPTION
        Use this module to get and set the terms used to classify things in a MyLibrary database. You can also
        retrieve a list of all term objects in the database, as well as get, set or delete relations between term ob-
        jects and resource objects.


METHODS
new()
        This method creates a new term object. Called with no input, this constructor will return a new, empty
        term object:



        # create empty term object
        my $term = MyLibrary::Term->new();




        The constructor can also be called using a known term id or term name:



        # create a term object using a known term id
        my $term = MyLibrary::Term->new(id => $id);
        # create a term object using a known term name
        my $term = MyLibrary::Term->new(name => $name);




term_id()
        This method can be used to retrieve the term id for the current term object. It cannot be used to set the id
        for the term.



                                                      38
                                            MyLibrary::Term




      # get term id
      my $term_id = $term->term_id();




term_name()
      This is an attribute method which allows you to either get or set the name attribute of a term. The names
      for terms will be created by the institutional team tasked with the responsibility of designating the more
      specific categories under which resources will be categorized. A term is related to one and only one par-
      ent facet. To retrieve the name attribute:



      # get the term name
      my $term_name = $term->term_name();




term_note()
      This method allows one to either retrieve or set the term descriptive note.



      # get the term note
      my $term_note = $term->term_note();
      # set the term note
      $term->term_note('This is a term note.');




delete_term_note()
      Use this method to delete the term note



      # delete term note
      $term->delete_term_note();




facet_id()
      This method may be used to either set or retrieve the value of the related facet id for this term. When the
      term is commited to the database, if the facet id is changed, the relation between this term and the facets
      will also be changed.



      # get the related facet id

                                                    39
                                            MyLibrary::Term



      my $related_facet_id = $term->facet_id();
      # set the related facet id
      $term->facet_id(25);




commit()
      This object method is used to commit the current term object in memory to the database. If the term
      already exists in the database, it will be updated. New terms will be inserted into the database.



      # commit the term
      $term->commit();




delete()
      This object method should be used with caution as it will delete an existing term from the database. Any
      associations with the Resources will also be deleted with this method in order to maintain referential in-
      tegrity. If an attempt is made to delete a term which does not yet exist in the database, a return value of
      '0' will result. A successful deletion will result in a return value of '1'.



      # delete the term
      $term->delete();




get_terms()
      This class method can be used to retrieve an array of all term objects. The array can then be used to se-
      quentially process through all of the existing terms. This method can also be used to retrieve a list of ob-
      jects based on object attributes such as name or description. This can be accomplished by supplying the
      field and value parameters to the method. Examples are demonstrated below.



      # get all the terms
      my @terms = MyLibrary::Term->get_terms();
      # get all terms based on criteria
      my @terms = MyLibrary::Term->get_terms(field => 'name', value => 'Biology
              and Life Sciences');




related_resources()
      This object method can be used to retrieve an array (a list) of resource ids to which this term is related.
      This list can then be used to sequentially process through all related resources (for example in creating a

                                                    40
                                      MyLibrary::Term



list of related resources). No parameters are necessary for this method to retrieve related resources,
however, new relatetions can be created by supplying a list of resource ids using the 'new' parameter. If
the term is already related to a supplied resource id, that resource id will simply be discarded. Upon a
term commit (e.g. $term->commit()), the new relations with resources will be created. Also, the input
must be in the form of numeric digits. Care must be taken because false relationships could be created.
A list of the currently related resources will always be returned (if such relations exist).



# get all related resources
my @related_resources = $term->related_resources();
# supply new related resources
$term->related_resources(new => [10, 12, 14]);




or



my @new_related_resource_list = $term->related_resources(new =>
       [@new_resources]);




The method will by default check to make sure that the new resources to which this term should be re-
lated exist in the database. This feature may be switched off by supplying the strict => 'off' parameter.
Changing this parameter to 'off' will switch off the default behavior and allow bogus resource relations
to be created.



# supply new related resources with relational integrity switched off
$term->related_resources(new => [10, 12, 14], strict => 'off');




Resources which do not exist in the database will simply be rejected if strict relational integrity is turned
on.

The method can also be used to delete a relationship between a term and a resource. This can be accom-
plished by supplying a list of resources via the 'del' parameter. The methodology is the same as the 'new'
parameter with the primary difference being that referential integrity will be assumed (for example, that
the resource being severed already exists in the database). This will not delete the resource itself, it will
simply delete the relationship between the current term object and the list of resources supplied with the
'del' parameter.



# sever the relationship between this term and a list of resource ids
$term->related_resources(del => [10, 11, 12]);




or



                                              41
                                            MyLibrary::Term




     $term->related_resources(del => [@list_to_be_severed]);




     If the list includes resources to which the current term is not related, those resource ids will simply be ig-
     nored. Priority will be given to resource associations added to the object; deletions will occur during the
     commit() after new associations have been created.

     Finally, a returned list of related resources can be sorted.



     # sort a returned list of resource ids according to resource name
     my @related_resources = $term->related_resources(sort => 'name');




suggested_resources()
     This is an object method which can be used to retrieve, set or delete suggested resource relationships
     between terms and resources. The return set will always be an array of resource ids which can then be
     used to process through the resources to which the ids correspond. This method functions similarly to
     the related_resource() method and uses similar parameters to change method functionality. If no para-
     meters are submitted, the method simply returns a list of resource_ids or undef if there are no suggested
     resources for this term. As with the related_resources() method, passing a sort parameter will sort the re-
     turned list according to the parameter value. Currently, only 'name' is acceptable as a parameter value.



     # get all suggested resources
     my @suggested_resources = $term->suggested_resources();
     # get a sorted list of suggested resources
     my @suggested_resources = $term->suggested_resources(sort => 'name');
     # supply new suggested resources
     my @new_suggested_resource_list = $term->suggested_resources(new =>
             [@new_suggested_resource_list]);




     As with related_resources(), this method will by default check to make sure that the new resources to
     which this term should be related exist in the database. The strict => 'off' parameter may also be sup-
     plied to the method to turn off relational integrity checks.



     # turn off relational integrity checks
     $term->suggested_resources(new => [@new_suggested_resources], strict =>
             'off');




     Turning off this feature will allow for bogus relations to be created.


                                                    42
                                                MyLibrary::Term



         The parameter to delete suggested resource relationships is del => [@set_to_delete]. The list supplied
         will be automatically deleted when the term is commited with commit(). This parameter does not delete
         the resources themselves, only their relationship as a 'suggested resource'. If the list includes resource ids
         to which the term is not related, they will simply be discarded and ignored.



         # remove suggested resource relationships
         $term->suggested_resources(del => [@list_to_be_deleted]);




         Priority for processing the list will be given to resources associations added to the term, but the overall
         effect on the data should be transparent.

librarians()
         This object method will return a list of related librarian objects/ids or undef if no librarians are associ-
         ated with this term. The type of data returned is controlled by the 'output' parameter. If 'id' is chosen as
         the preferred output, a simple list of related librarian ids will be returned. If the output type of 'object' is
         preferred, the returned librarian object can be manipulated using the librarian object methods. This
         method can also be used to add or delete librarian associations with this term. The 'new' and 'del' para-
         meters exist for this purpose (see examples below). A list of librarian ids should be provied for these
         parameters. Relational integrity can be abandoned by using the 'strict' parameter and giving it a value of
         off.



         # return a list of librarian objects
         my @librarians = $term->librarians();
         # return a list of librarian ids
         my @librarians = $term->librarians(output => 'id');
         # add a list of librarian associations to this term
         $term->librarians(new => [@librarian_ids]);
         $term->librarians(new => [@librarian_ids], strict => 'off');
         # remove a list of librarian associations from this term
         $term->librarians(del => [@librarian_ids]);




sort()
         This class method performs a simple sort on a supplied list of term ids according to specific criteria,
         which is indicated as a parameter value for the method.



         # sort term ids by term name
         my @sorted_terms = MyLibrary::Term->sort(term_ids => [@term_ids], type =>
               'name');




                                                         43
                                           MyLibrary::Term



overlap()
     This object method returns a list of overlapping resources with a provided list of term ids. If there are no
     overlapping resources, the method returns null. If submitted term ids do not exist in the database, the
     method will ignore that input. Since some databases are limited by how many table joins they can per-
     form in one query, limit the number of term ids to approximately 25-30 at a time. Otherwise, the method
     will likely fail.



     # return overlapping resources with this term
     my @overlap_resources = $term->overlap(term_ids => [@term_ids]);




distinct_terms()
     This class method returns a unique list of term ids (which can be sorted using the sort() method) that
     correspond to a specific group of resource ids.



     # return a distinct set of related terms within a resource group
     my @distinct_terms = MyLibrary::Term->distinct_terms(resource_ids =>
             [@resource_ids]);




                                                   44
Chapter 6. MyLibrary::Resource
NAME
   MyLibrary::Resource - A class for representing a MyLibrary resource


SYNOPSIS
   # require the necessary module
   use MyLibrary::Resource;
   # create a new Resource object
   my $resource = MyLibrary::Resource->new();
   # set attributes of the newly created object
   $resource->contributor('The Whole Internet Community');
   $resource->coverage('Items in the Catalogue date from 600 BC to the
          1800\'s');
   $resource->creator('Infomotions, Inc.');
   $resource->date('2003-11-20');
   $resource->fkey('0002345');
   $resource->language('en');
   $resource->lcd(0);
   $resource->name('Alex Catalogue');
   $resource->note('This is a list of public domain classic literature');
   $resource->proxied(0);
   $resource->publisher('Infomotions, Inc.');
   $resource->qsearch_prefix('http://infomotions.com/alex?term=');
   $resource->qsearch_suffix('sortby=10');
   $resource->relation('http://www.promo.net/pg');
   $resource->rights('Items in the Catalogue are in the public domain');
   $resource->source('Materials of the Catalogue were gathered from all
                                                   over the Internet.');
   $resource->access_note('Freely available on the World Wide Web');
   $resource->coverage_info('Aug. 1996-');
   $resource->full_text(1);
   $resource->reference_linking(1);
   # all appropriate object attribute can be changed to NULL values using
                                                   the delete_* methods
   $resource->delete_note();
   $resource->delete_access_note();
   # save the data
   $resource->commit();
   # delete a resource
   $resource->delete();
   # get the id of this object
   $id = $resource->id();
   # create a new object with a specific id
   my $resource = MyLibrary::Resource->new(id => $id);
   # create a new object with a specific name
   my $resource = MyLibrary::Resource->new(name => 'Web of Science');
   # create a new object with a specific fkey


                                              45
                       MyLibrary::Resource



my $resource = MyLibrary::Resource->new(fkey => '00123456');
# get selected data from the object
my $name = $resource->name();
my $note = $resource->note();
# add a location
$resource->add_location(location => 'http://mysite.com',
         location_type => $type_id, location_note => 'This is mysite.');
# modify a location
$resource->modify_location($resource_location, resource_location =>
         'http://mysite2.com');
$resource->modify_location($resource_location, location_note => 'This is
         my other site');
# get a specific location by id or location string
my $location = $resource->get_location(id => $id);
my $location = $resource->get_location(resource_location =>
         $location_string);
# delete a location
$resource->delete_location($resource_location);
# get full array of related locations
my @resource_locations = $resource->resource_locations();
# get array of all resources
@resource_objects = MyLibrary::Resource->get_resources();
@resource_objects = MyLibrary::Resource->get_resources(sort => 'name');
@resource_objects = MyLibrary::Resource->get_resources(field => 'name',
            value => 'Web of science');
# get array of specific list of resources
@resource_objects = MyLibrary::Resource->get_resources(list =>
            [@list_resource_ids], sort => 'name');
@resource_objects = MyLibrary::Resource->get_resources(list =>
            [@list_resource_ids], sort => 'name', output => 'id');
# get array of all resource ids
@resource_ids = MyLibrary::Resource->get_ids();
# test for group membership based on term name
my $return = $resource->test_relation(term_name => 'Biology');
# get array of all lcd resources
@lcd_resource_objects = MyLibrary::Resource->lcd_resources();
# set new lcd resource flags
MyLibrary::Resource->lcd_resources(new => @lcd_resources);
# turn off lcd resource flags
MyLibrary::Resource->lcd_resources(del => @lcd_resources);
# return the appropriate quick search redirection string
my $qsearch_redirect = MyLibrary::Resource->qsearch_redirect
         (resource_id => $id, qsearch_arg => $qsearch_string,
         primary_location => $primary_url);
# get array of fkey tagged resources
@fkey_resources = MyLibrary::Resource->get_fkey();
# get array of related term ids
my @related_terms = $resource->related_terms();

                               46
                                           MyLibrary::Resource




DESCRIPTION
        This class is used to represent a MyLibrary resource.


METHODS
new()
        This method creates a new resource object. Called with no input, this method returns a new, empty re-
        source:



        # create empty resource
        my $resource = MyLibrary::Resource->new();




        Called with an id, this method returns a resource object containing the information from the underlying
        database:



        # create a resource from the underlying database
        my $resource = MyLibrary::Resource->new(id => 123);




        The method returns undef if the id is invalid. The method can also be used to create a new object of an
        existing resource by supplying either a name or fkey parameter to the method. For example:



        # create a resource using an fkey parameter
        my $resource = MyLibrary::Resource->new(fkey => 12345);




        If name is passed as a parameter, the result returned will be based on the context in which the method
        was called. If called in a scalar context, the method will return the number of records found or undef if
        no records were found. If called in list context, and records are found, an array of resource objects will
        be returned.



        # number of records in database matching name criteria
        my $number_resources = MyLibrary::Resource->new(name => 'My Resource');
        # array of records matching name criteria
        my @resources = MyLibrary::Resource->new(name => 'My Resource');




                                                     47
                                              MyLibrary::Resource



name()
         This method gets and sets the name of a resource object. The values of name is intended to be analogous
         to the Dublin Core name element. To set the name attribute:



          # set the name of a resource
          $resource->name('DAIAD Home Page');




         To get the value of the name, try:



          # get the name
          my $name = $resource->name;




note()
         Sets and gets the note attribute of a resource object. To set the note's value, try:



         $resource->note('This is a simple note.');




         To get the value of the note attribute, do:



         my $note = $resource->note;




         The sorts of values intended to be stored in note attributes correspond to the sorts of values assigned to
         Dublin Core description elements.

access_note()
         The access_note method can be used either to retrieve or assign an access note to a resource:



          # set the access note value
          $resource->access_note('Available to Notre Dame patrons only.');
          # get the access note value
          my $access_note = $resource->access_note;




                                                         48
                                             MyLibrary::Resource



coverage_info()
        The coverage_info method can be used either to retrieve or assign coverage info to a resource:



         # set the coverage info value
         $resource->coverage_info('Feb. 1996 - Aug. 2001');
         # get the coverage info value
         my $coverage_info = $resource->coverage_info;




full_text()
        The full_text method can be used either to retrieve or assign a full text flag to a resource:



         # set the full text flag (on)
         $resource->full_text(1); # the resource supports full text access
         # set the full text flag (off)
         $resource->full_text(0); # the resource does not support full text access
         # get the full text flag value
         my $full_text_flag = $resource->full_text;



reference_linking()
        The reference_linking method can be used to retrieve or assign a reference linking flag to a resource.
        The reference

        linking flag indicates whether the resource is listed in a find text aggregator such as SFX FindText. This
        flag can

        then be used to inform the patron of this availability for the given institution.



         # set the reference linking flag (on)
         $resource->reference_linking(1); # the resource is supported by a
                 reference linker
         # set the reference linking flag (off)
         $resource->reference_linking(0); # the resource is not supported by a
                 reference linker
         # get the reference linking value
         my $reference_linking_val = $resource->reference_linking;



lcd()
        This method is used to set and get the "lowest common denominator" (LCD) value of a resource. LCD

                                                       49
                                              MyLibrary::Resource



         resources are resources intended for any audience, not necessarily discipline-specific audiences. Good
         candidates for LCD resources are generic dictionaries, encyclopedias, a library catalog, or multi-
         disciplinary bibliographic databases. LCD resoruces are useful to anybody.

         lcd attributes are Boolean in nature; valid values for lcd attributes are 0 and 1.

         To set a resource's lcd attribute:



          $resource->lcd(1); # is an LCD resource
          $resource->lcd(0); # is not an LCD resource



         To get the lcd resource:



          $lcd = $resource->lcd;



         This method will "croak" if there is an attempt to set the value of lcd to something other than 0 or 1.

fkey()
         Gets and sets the fkey value of a resource. Fkey's are "foreign keys" and intended to be the unique value
         (database key) of a resource from a library catalog. The combination of this attribute and the MARION
         field of the preferences table should create a URL allowing the user to see the cataloging record of this
         resource.

         Setting and getting the fkey attribute works like this:



          # set the fkey
          $resource->fkey('0002345');
          # getting the fkey
          my $fkey = $resource->fkey;



qsearch_prefix() and qsearch_suffix()
         These methods set and get the prefix and suffix values for "Quick Searches".

         Quick Search resources result in an HTML form allowing the end-user to query a remote Internet data-
         base with one input box and one button. Quick Search resources are reverse-engineered HTML forms
         supporting the HTTP GET method. By analyzing the URL's of Internet searches it becomes apparent
         that the searches can be divided into three parts: the prefix, the query, and the suffix. For example, the
         prefix for a Google search looks like this:



          http://www.google.com/search?hl=en&ie=ISO-8859-1&q=




                                                        50
                                              MyLibrary::Resource



         A query might look like this:



          mylibrary



         The suffix might look like this:



         &btnG=Google+Search



         By concatonating these three part together a URL is formed. Once formed a Web browser (user agent in
         HTTP parlance) can be redirected to the newly formed URL and the search results can be displayed.

         The qsearch_prefix() and qsearch_suffix() methods are used set and get the prefixes and suffixes for
         Quick Searches, and they work just like the other methods:



          # set the prefix and suffix
          $resource->qsearch_prefix('http://www.google.com/search?hl=en&ie=
                   ISO-8859-1&q=');
          $resource->qsearch_suffix('&btnG=Google+Search');
          # create a Quick Search URL by getting the prefixes and suffixes of a
                                                                   resource
          my $query = 'mylibrary';
          my $quick_search = $resource->qsearch_prefix . $query . $resource->
                   qsearch_suffix;



date()
         Use this method to set and get the date attribute of a resource. This value is intended to correspond to the
         the Dublin Core date element and is used in the system as a date stamp representing when this resource
         was last edited thus facilitating a "What's new?" functionality. Date values are intended to be in a
         YYYY-MM-DD format.

         Setting and getting date attributes works like this:



          # set the date
          $resource->date('2003-10-28');
          # get the date
          my $date = $resource->date;



id()
         Use this method to get the ID (database key) of a resource. Once committed, a resource will have a data-
         base key, and you can read the value of this key with this method:


                                                        51
                                             MyLibrary::Resource




       # get the ID of a resource
       my $id = $resource->id;



      It is not possible to set the value of the id attribute.

commit()
      Use this method to save a resource's attributes to the underlying database, like this:



       # save the resource
       $resource->commit;



      If the resource already exists in the database (it has an id attribute), then this method will do an SQL UP-
      DATE. If this is a new resource (no previously assigned id attribute), the method will do an SQL IN-
      SERT.

delete_[attribute_name]()
      This is a generic object attribute method that can be used to apply NULL values to a given attribute such
      as name and access_note. However, the boolean attribute will be excluded from this method. Examples
      are given below:



      # delete note value
      $resource->delete_note();
      # delete coverage value
      $resource-> delete_coverage();



delete()
      This method deletes a resource from the underlying database like this:



      # delete this resource
      $resource->delete;



      Once called this method will do an SQL DELETE operation for the given resource denoted by its id at-
      tribute.

get_resources()
      This method returns an array of resource objects or ids, specifically, an array of all the resources in the
      underlying database. Once called, the programmer is intended to sort, filter, and process the items in the


                                                       52
                                          MyLibrary::Resource



     array as they see fit. The return set from this method can either be an array of resource objects or ids as
     indicated by the 'output' parameter. This method does not require input:



     # get all the resources
     my @all_resources = MyLibrary::Resource->get_resources(output => 'id');
     # process each resource
     foreach my $r (@all_resources) {
           # check for resources from edu domains
           # change this
           if ($r->url =~ /edu/) {
                 # print them
                 print $r->name . "\n"
                 }
           }
     # sort retrieved list of resource objects by name
     my @all_resources = MyLibrary::Resource->get_resources(sort => 'name');



     A defined list of resources may also be retrieved using this method, if the sum total of resources is not
     desired or required. The list parameter can be used to retrieve such a list. Simply enclose the list in a pair
     of brackets.



     # retrieve specific list of resources
     my @specific_resources = MyLibrary::Resource->get_resources(list =>
              [@resource_ids],
     output => 'object');



     Also, a certain field in the resource record can be queried to determine if a resource with the specified
     criteria exists in the data set. This parameter cannot be used with the 'list' parameter. However, use of the
     method in this way requires that both a 'field' parameter and a 'value' parameter be supplied. If the cor-
     rect combination of parameters is not supplied, incorrectly used parameters will simply be ignored. Ex-
     ample:



     # retrieve a list of resources matching title criteria
     my @criteria_specific_resources = MyLibrary::Resource->get_resources(field
               => 'name', value => 'Web of science');



lcd_resources()
     This class method will allow the retrieval of an array of recource objects which have been designated
     "lcd" or "lowest common denominator". These are resources that are useful to anyone in any discipline
     of study. The method will always return a list (an array) of object references corresponding to the appro-
     priate category. This method is very similar to the get_resources() method.



                                                    53
                                         MyLibrary::Resource




     # get all lcd resources
     @lcd_resources = MyLibrary::Resource->lcd_resources();



     The method may also be used to set or delete lcd_resource flags. The first parameter should indicate
     whether lcd resource flags are being switched to true ('new') or false ('del). The second parameter should
     be a list or array of resources upon which the indicated operation will be performed. As mentioned pre-
     viously, a list of current lcd resources will be returned upon successful execution of the method.



     # add new lcd resource flags
     MyLibrary::Resource->lcd_resources('new', @lcd_resources);
     # delete old lcd resource flags
     MyLibrary::Resource->lcd_resources('del', @lcd_resources);



     If new flags are indicated which are already positive, they will simply be ignored. Flags set to be turned
     off which are not positive will not be modified. If a resource id is indicated which does not exist in the
     database, a fatal exception will be thrown in the calling application.

qsearch_redirect()
     Quick Searches in MyLibrary are really a combination of four URL components. Thus, this class meth-
     od will apply only to those resources that are related to a URL typed location. The four components of a
     quick search are: the primary or base URL of the resource, the search prefix, the search argument and if
     necessary, the search suffix. This method takes as an argument, the base URL of the resource to be used
     for the quick search, the resource id, and the argument to be used for the search. Each of these paramet-
     ers is necessary or the method will return null.

     The string returned from this method should be used to redirect the brower using the string as the redir-
     ection URL.



     # return the appropriate quick search redirection string
     my $qsearch_redirect = MyLibrary::Resource->qsearch_redirect(resource_id =>
           $id, qsearch_arg => $qsearch_string, primary_location => $primary_url);



get_fkey()
     This class method will allow the retrieval of an array of lightweight objects with only two attributes: re-
     source_id and fkey. The array will contain only those objects which correspond to resource records asso-
     ciated with an fkey (foreign database key). This array (or list) can then be used to process through the
     fkey resources by calling the class constructor and operating on the full resource objects or to otherwise
     process through the list of resource ids which are associated with an external system record. Unlike the
     lcd_resources() class mothod, these objects are lightweight for faster processing in deference to the latter
     processing option.

     This method cannot be used to set fkeys for specific resources, it can only be used to retrieve a list rep-
     resenting the current list of resources with fkeys.


                                                   54
                                           MyLibrary::Resource




      # get lightweight fkey resource objects
      @fkey_resources = get_fkey();



test_relation()
      This object method is used to quickly test whether a relation exists between the current resource and a
      term or facet identified either by the term/facet name or id number. It will always return a boolean value
      of either '0' (no relation exists) or '1' (relation exists). The method was designed so that group member-
      ship based upon a set of criteria can easily be determined. Multiple tests can be run to determine com-
      plex sets of criteria for group membership among a set of resources. Please note that only the first para-
      meter submitted will be considered as test criteria.



      # test for group membership based on term_name
      my $return = $resource->test_relation(term_name => 'Biology');
      # test for group membership based on term id
      my $return = $resource->test_relation(term_id => 16);
      # test for group membership based on facet id
      my $return = $resource->test_relation(facet_id => 13);



related_terms()
      This object method will allow the retrieval, addition and deletion of term relations with a given resource
      object. The return set is always a list (or array) of term ids which are currently related to this resource.
      The list can then be used to retrieve the related terms or otherwise process through the list. No paramet-
      ers are necessary in order to retrieve a list of related term ids, however, new relations can be created by
      supplying a list of resource ids using the 'new' parameter. If a term is already related to this resource, the
      supplied term id will simply be ignored. Upon a resource commit (e.g. resource->commit()), the new re-
      lations will be created. Also, the input must be in the form of numeric digits. Care must be taken because
      false relationships could be created.



      # get all related terms
      my @related_terms = $resource->related_terms();
      # supply new related terms
      $resource->related_terms(new => [10, 11, 12]);



      or



      my @new_related_terms = $resource->related_terms(new => [@new_terms]);



      The method will by default check to make sure that the new terms to which this resource should be re-
      lated exist in the database. However, this may be switched off by supplying the strict => 'off' parameter.

                                                     55
                                         MyLibrary::Resource



     Changing this parameter to 'off' will switch off the default behavior and allow bogus term relations to be
     created.



     # supply new related terms with relational integrity switched off
     $resource->related_terms(new => [10, 12, 14], strict => 'off');



     Terms which do not exist in the database will simply be rejected if strict relational integrity is turned on.

     The method can also be used to delete a relationship between a term and a resource. This can be accom-
     plished by supplying a list of terms via the 'del' parameter. The methodology is the same as the 'new'
     parameter with the primary difference being that referential integrity will be assumed (for example, that
     the term being severed already exists in the database). This will not delete the term itself, it will simply
     delete the relationship between the current resource object and the list of terms supplied with the para-
     meter.



     # sever the relationship between this resource and a list of term ids
     $resource->related_terms(del => [10, 11, 12]);



     or



     $resource->related_terms(del => [@list_to_be_severed]);



     If the list includes terms to which the current resource is not related, those term ids will simply be ig-
     nored. Priority will be given to term associations added to the object; deletions will occur during the
     commit() after new associations have been created.

proxied()
     Gets and sets the value of the proxied attribute of a resource:



      # set the value of proxied
      $resource->proxied(0); # not proxied
      $resource->proxied(1); # is proxied
      # get the proxied attribute
      my $proxied = $resource->proxied;



     If a particular resource is licensed, then user agents (Web browsers) usually need to go through a proxy
     server before accessing the resources. This attribute denotes whether or not a resource needs to be prox-
     ied. If true (1), then the resource's URL is intended to be prefixed with value of the proxy_prefix field in
     the preferences table. If false (0), then the URL is intended to stand on its own.

     This method will "croak" if the value passed to it is not 1 or 0.



                                                    56
                                          MyLibrary::Resource



creator()
      Use this method to set and get the creator of a resource. The creator attribute is intended to correspond to
      the Dublin Core creator element. The method works just like the note method:



      # set the creator value
      $resource->creator('University Libraries of Notre Dame');
      # get the creator
      my $creator = $resource->creator;



publisher()
      Use this method to set and get the publisher of a resource. The publisher attribute is intended to corres-
      pond to the Dublin Core publisher element. The method works just like the note method:



      # set the publisher value
      $resource->publisher('O\'Reilly and Associates');
      # get the publisher
      my $publisher = $resource->publisher;



contributor()
      Use this method to set and get the contributor of a resource. The contributor attribute is intended to cor-
      respond to the Dublin Core contributor element. The method works just like the note method:



      # set the contributor value
      $resource->contributor('The Whole Internet');
      # get the contributor
      my $contributor = $resource->contributor;



coverage()
      Use this method to set and get the coverage of a resource. The coverage attribute is intended to corres-
      pond to the Dublin Core coverage element. The method works just like the note method:



      # set the coverage value
      $resource->coverage('Items in the Catalogue date from 600 BC to the 1800\'s.');
      # get the coverage
      my $coverage = $resource->coverage;




                                                    57
                                          MyLibrary::Resource



rights()
      Use this method to set and get the rights of a resource. The rights attribute is intended to correspond to
      the Dublin Core rights element. The method works just like the note method:



      # set the rights value
      $resource->rights('This item is in the public domain.');
      # get the rights
      my $rights = $resource->rights;



language()
      Use this method to set and get the language of a resource. The language attribute is intended to corres-
      pond to the Dublin Core language element. The method works just like the note method:



      # set the language value
      $resource->language('eng');
      # get the language
      my $language = $resource->language;



source()
      Use this method to set and get the source of a resource. The source attribute is intended to correspond to
      the Dublin Core source element. The method works just like the note method:



      # set the source value
      $resource->source('This items originated at Virginia Tech.');
      # get the source
      my $source = $resource->source;



relation()
      Use this method to set and get the relation of a resource. The relation attribute is intended to correspond
      to the Dublin Core relation element. The method works just like the note method:



      # set the relation value
      $resource->relation('http://www.promo.net/pg/');
      # get the relation
      my $relation = $resource->relation;




                                                    58
                                         MyLibrary::Resource



add_location()
     This method will add a location to the resource object using supplied parameters. Required parameters
     are 'location' and 'location_type'. 'location note' may also be supplied as an optional parameter. The 'loca-
     tion_type' supplied must be a location type id. This id may be obtained using the Resource/Location.pm
     methods or supplied from an interface. The type must pre-exist in the database for this parameter to be
     valid. 'location_note' may be any string, but is usually some descriptive text about the location which
     may later be used as the string for the active URL or pointer to the specified location. This method will
     check to make sure that the location entered is unique to this resource. This method will return a '1' if the
     record was added, a '2' if a record with a duplicate location for this resource was found and a '0' for an
     unspecified problem.



     # add a location to a resource
     $resource->add_location(location => 'http://mysite.com',
         location_type => $location_type_id, location_note => 'This is my site.');



delete_location()
     This object method will delete a location from the list of locations associated with a resource. The re-
     quired parameter is the resource location object to be deleted.



     # delete a location from a resource
     $resource->delete_location($resource_location);



resource_locations()
     This object method will allow the retrieval of an array of location objects associated with this resource.
     The objects returned can then be operated on using any Resource/Location.pm object methods. For ex-
     ample, you could cycle through the list of objects to perform other operations on them such as append-
     ing a proxy prefix.



     # obtain a list of resource location objects
     my @resource_locations = $resource->resource_locations();
     # cycle through list to process
     foreach my $resource_location (@resource_locations) {
         if ($resource_location->location() eq 'http://mysite.com') {
             $resource->delete_location($resource_location->id());
             }
         }



modify_location()
     This method takes two parameters. The first parameter is a valid location object to be updated. The
     second parameter is the name of the location attribute to change. The second input parameter can be one
     (and only one) of the following: 'resource_location' and 'location_note'. The location type cannot be
     changed using this method. It is suggested that if the type changes, the resource location be deleted and a

                                                   59
                                         MyLibrary::Resource



     new resource location created. A location type change seems like a rare possibility indeed. Only one loc-
     ation attribute can be changed at a time.



     # modify a related location
     $resource->modify_location($resource_location, resource_location =>
              'http://mysite2.com');
     $resource->modify_location($resource_location, location_note => 'This is
              my other note.');



get_location()
     Use this method to retrieve a specific location object associated with the current resource. The method
     can accept one of two parameters: id and resource_location. 'id' is the resource location id (key) and 're-
     source_location' is the string that matches the location desired. After retrieval, all of the attribute meth-
     ods found in MyLibrary::Resource::Location will be available to the object. Other Resource class meth-
     ods associated with locations can also be used to manipulate the object.



     # retrieve a specific location
     my $location = $resource->get_location(id => $id);
     my $location = $resource->get_location(resource_location => $resource_
              location_string);




                                                   60
Chapter 7. MyLibrary::Resource::Location
NAME
   MyLibrary::Resource::Location - A class for representing MyLibrary resource locations


SYNOPSIS
   # module may be called explicitly
   use MyLibrary::Resource::Location;
   # create a new resource location object
   my $resource_location = MyLibrary::Resource::Location->new();
   # set attributes of object
   $resource_location->location('http://mysite.com');
   $resource_location->location_note('This is mysite');
   $resource_location->resource_location_type(25);
   $resource_location->resource_id(45);
   # remove value for location note
   $resource_location->delete_location_note();
   # save to database
   $resource_location->commit();
   # retrieve resource location id
   my $resource_location_id = $resource_location->id();
   # retrieve object by location id
   my $resource_location = MyLibrary::Resource::Location->new(id =>
            $resource_location_id);
   # retrieve object attributes
   my $resource_location_location = $resource_location->location();
   my $resource_location_note = $resource_location->location_note();
   my $resource_location_type_id = $resource_location->resource_location_type();
   # retrieve all location objects associated with a resource
   my @resource_location_objects = MyLibrary::Resource::Location->get_locations
            (id => $resource_id);
   # retrieve list (array) of all resource location ids
   my @resource_location_ids = MyLibrary::Resource::Location->id_list();
   # delete a specific resource location
   $resource_location->delete();
   # create a new resource location type
   MyLibrary::Resource::Location->location_type(action => 'set', name => 'Call
             Number', description => 'Call number location using the Library of
             Congress System');
   # retrieve a location type name based on location type id
   my $location_type_name = MyLibrary::Resource::Location->location_type(action =>
            'get_name', id => 25);
   # retrieve a location type id based on a location type name
   my $location_type_id = MyLibrary::Resource::Location->location_type


                                              61
                                       MyLibrary::Resource::Location



                      (action => 'get_id', name => 'Call Number');
        # retrieve a location type description based on a locatin type id
        my $location_type_desc = MyLibrary::Resource::Location->location_type
                 (action => 'get_desc', id => 25);
        # retrieve an array of all resource location type ids
        my @resource_location_types = MyLibrary::Resource::Location->location_type
                (action => 'get_all');
        # delete a location type based on location type id
        MyLibrary::Resource::Location->location_type(action => 'delete', id => 25);


DESCRIPTION
        This is a sub-class of the Resource class which is used to represent individual resource locations and al-
        low manipulation of resource location data. Several locations can be related to a particular resource.
        Each location has several attributes which describe the location and give the location information itself.
        Each location has a location type, and class methods are provided in this package which allow manipula-
        tion of the resource location types as well.


METHODS
new()
        This constructor method is used to create a resource location object. The object can then be manipulated
        using the various accessor methods supplied with this module.


        # create a new resource location object
        my $resource_location = MyLibrary::Resource::Location->new();


        This method can also be called using an id parameter which will then return an object using the persisten
        data store. If the called location does not exist, this method will return 'undef'.


        # create an object from persistent data using the location id
        my $resource_location = MyLibrary::Resource::Location->new(id => $loc_id);


        The method can also retrieve and build an object or objects using the location text for the location.
        Please note that this will return 'undef' if an exact match is not found. The type returned is based on con-
        text. If the method is called in scalar context, a single value representing either 'undef' for no results or
        the number of locations matching the criteria will be returned. If called in list context, the result will be
        an array of location objects matching the criteria.


        # determine the number of objects matching the location parameter (scalar
                    context)
        my $resource_location = MyLibrary::Resource::Location->new(location =>
                    'http://mysite.com');
        # retrieve an array of location objects based on location string criteria
                    (list context)
        my @resource_locations = MyLibrary::Resource::Location->new(location =>
                    'http://mysite.com');


                                                      62
                                       MyLibrary::Resource::Location




commit()
       This method will save resource location object data to the database.


       # commit the resource location
       $resource_location->commit();


id()
       This method can be used simply to retrieve the id (unique key) for the current object. It cannot be used
       to set the id, which is determined by the database.


       # retrieve the resource location id
       my $resource_loc_id = $resource_location->id();


location()
       This attribute method can be used to either retrieve or set the resource location attribute. The value
       entered should match the type of location chosen for the object.


       # get location name
       my $location_name = $resource_location->location();
       # set the location
       $resource_location->location('http://mysite.com');


location_note()
       This attribute method is used to either get or set the note for the resource.


       # get the resource location note
       my $resource_loc_note = $resource_location->location_note();
       # set the resource location note
       $resource_location->location_note('This is the note for my resource');


resource_location_type()
       This method should be used to get or set the resource type id for this location. The input must be an in-
       teger that matches a location type id from the database.


       # get the resource location type id
       my $resource_loc_type_id = $resource_location->resource_location_type();
       # set the resource location type id
       $resource_location->location_type($type_id);


                                                      63
                                      MyLibrary::Resource::Location



resource_id()
       This method can be used either to retrieve or set the resource id which is related to this location. The re-
       source which corresponds to this id must already exist in the database or this method will fail when used
       as a 'set' method. For various reasons, this behavior can also be turned off using the 'strict => 'off'' flag.
       Keep in mind that turning off relational integrity checks could compromise the data.


       # get the related resource id
       my $resource_id = $resource_location->resource_id();
       # set the related resource id
       $resource_location->resource_id($resource_id);
       # turn relational integrity checking off
       $resource_location->resource_id($resource_id, strict => 'off');


get_locations()
       This class method serves, primarily, the requirements of the parent resource object (defined in Re-
       source.pm). This method will retrieve all of the resource objects associated with a particular resource.
       The accessor methods in this package are then used to access the attributes of the location objects. This
       method returns an array of object references.


       # retrieve the complete set of resource location objects
       my @resource_locations = MyLibrary::Resource::Location->get_locations();
       # via a specific resource id
       my @resource_locations = MyLibrary::Resource::Location->get_locations(id =>
                 27);
       # the method called from Resource.pm is similar
       my @resource_locations = $resource->get_locations();


       The attributes of the objects can be manipulated using either the local package methods or methods
       which are supplied with the resource module itself. In the latter instance, only locations associated with
       that particular resource can be accessed.


       # access attributes using local (Resource::Location.pm) methods
       my $resource_location = $resource_location->location();
       my $resource_location_note = $resource_location->note();
       # manipulate the attributes (Resource.pm methods)
       my $location_name = $resource->location_name();
       my $location_note = $resource->location_note();


id_list()
       If only the list of resource location ids is required in order to avoid the overhead of dealing with fully
       fleged objects, that array can be retrieved using this class method. As implied, this method will simply
       return a list of location ids which can then be subsequently used to process through the list of location
       ids.




                                                      64
                                    MyLibrary::Resource::Location



      # get full list of location ids
      my @resource_loc_ids = MyLibrary::Resource::Location->id_list();


delete()
      This method can be used to delete a specific resource location.


      # delete a resource location
      $resource_location->delete();


location_type()
      Location types for resource locations may be retrieved, set or deleted with this method. The required
      parameter is the type name. A description may also optionally be supplied. This is a class method.

      Location types can be created by supplying the required parameter and a flag must be set to indicate that
      this location type should be created. Location types that have identical names with types that already ex-
      ist in the database will not be created. The key id for each new location type is generated by increment-
      ing the highest key integer in the set of location type keys.

      A list of all of the current location type ids can be obtained by passing the action parameter 'get_all'.
      This will return an array of location type ids.

      NOTE: The MyLibrary::Resource::Location::Type class also allows for direct manipulation of location
      types. That class was developed after these methods, and thus, these methods are now deprecated. Use
      these class methods at your own risk.


      # create a resource location type
      MyLibrary::Resource::Location->location_type(action => 'set', name =>
             'Call Number', description => 'Call number location using the
             Library of Congress System');
      # retrieve a location type name based on location type id
      my $location_type_name = MyLibrary::Resource::Location->location_type
            (action => 'get_name', id => 25);
      # retrieve a location type id based on a location type name
      my $location_type_id = MyLibrary::Resource::Location->location_type
            (action => 'get_id', name => 'Call Number');
      # retrieve a location type description based on a locatin type id
      my $location_type_desc = MyLibrary::Resource::Location->location_type
            (action => 'get_desc', id => 25);
      # retrieve an array of all location type ids
      my @resource_location_types = MyLibrary::Resource::Location->
            location_type(action => 'get_all');
      # delete a location type based on location type id
      MyLibrary::Resource::Location->location_type(action => 'delete',
            id => 25);




                                                   65
Chapter              8.
MyLibrary::Resource::Location::Type
NAME
        MyLibrary::Resource::Location::Type


SYNOPSIS

        # require the necessary module
        use MyLibrary::Resource::Location::Type;
        # create a new Location Type object
        my $location_type = MyLibrary::Resource::Location::Type->new();
        # set the attributes of a Location Type object
        $location_type->name();
        $location_type->description();
        # commit Location Type
        $location_type->commit();
        # output the Location Type id
        my $location_type_id = $location_type->location_type_id();
        # delete a Location Type from the database
        $location_type->delete();
        # return a list of all type ids for processing
        my @location_type_ids = MyLibrary::Resource::Location::Type->all_types();



DESCRIPTION
        This is a sub-class of the Location class which is used to represent individual resource location types and
        allow manipulation of resource location type data. Each location will be assigned one location type.
        Multiple location types can exist, each representing a method by which a resource can be accessed. Cer-
        tain resources will be accessed only via physical methods, while others will be purely digital. Each type
        should have a description assigned which clearly states the mode of access for that type.


METHODS
new()
        This constructor method is used to create a resource location type object. The object can then be manip-
        ulated using the various accessor methods supplied with this module.



        # create a new resource location type object

                                                      66
                                MyLibrary::Resource::Location::Type



     my $resource_location_type = MyLibrary::Resource::Location::Type->new();



     This method can also be called using an id parameter which will then return an object using the persist-
     ent data store. If the called location does not exist, this method will return 'undef'.



     # create an object from persistent data using the location type id
     my $resource_location_type = MyLibrary::Resource::Location::Type->new
              (id => $loc_id);



     This method can also be called using the 'name' parameter, so that an object can be created based on the
     name of the location type. Each location type name must be unique, so only one type will be retrieved
     using the method in this fashion.



     # create an object from persistent data using the location type name
     my $resource_location_type = MyLibrary::Resource::Location::Type->new
              (name => $loc_name);



name()
     This attribute method should be used to either set or retrieve the name for this location type. This name
     will appear in any context where location type labeling is required.



     # get location type name
     my $location_type_name = $location_type->name();
     # set the location type name
     $location_type->name('URL WEB SITE');



description()
     The description should indicate the mode of access for a location type. This will assist in the usage of a
     particular type.



     # retrieve the current location type
     my $location_type_description = $location_type->description();
     # set the location type description
     $location_type->description('This location type applies to any resource
              which is web accessible.');



location_type_id()

                                                  67
                                 MyLibrary::Resource::Location::Type



      This method can only be used to retrieve the location type id of the current location type. It cannot be
      used to set the location type id, as this is set internally.



      # get the current location type id
      my $location_type_id = location_type_id();



commit()
      This method is used to save a location type to the database.



      # commit the location type
      $location_type->commit();



delete()
      Use this method to remove a location type from the database



      # remove a location type from the database
      $location_type->delete();



all_types()
      This is a class method which will return upon invocation the full list of location type ids. If no location
      types exist in the databse, the method will return undef.



      # return a list of all location type ids
      my @location_type_ids = MyLibrary::Resource::Location::Type->all_types();




                                                    68
Chapter 9. MyLibrary::Librarian
NAME
   MyLibrary::Librarian


SYNOPSIS

   # use the module
   use MyLibrary::Librarian;
   # create a new librarian
   my $librarian = MyLibrary::Librarian->new();
   # give the librarian characteristics
   $librarian->name('Fred Kilgour');
   $librarian->email('kilgour@oclc.org');
   $librarian->telephone('1 (800) 555-1212');
   $librarian->url('http://oclc.org/~kilgour/');
   # associate (classify) the librarian with term ids
   $librarian->term_ids(new => [3, 614, 601]);
   # disassociate certain term ids from this librarian
   $librarian->term_ids(del => [@del_term_ids]);
   # retrieve list of term ids with sort parameter
   my @term_ids = $librarian->term_ids(sort => 'name');
   # save the librarian to the database; create a new record
   $librarian->commit();
   # get the id of the current librarian object
   $id = $librarian->id();
   # get a librarian based on an id
   my $librarian = MyLibrary::Librarian->new(id => $id);
   # display information about the librarian
   print '       ID: ', $librarian->id(), "\n";
   print '     Name: ', $librarian->name(), "\n";
   print '    Email: ', $librarian->email(), "\n";
   print 'Telephone: ', $librarian->telephone(), "\n";
   print '      URL: ', $librarian->url(), "\n";
   # retrieve complete, sorted list of librarian objects
   my @librarians = MyLibrary::Librarian->get_librarians();
   # process each librarian
   foreach my $l (@librarians) {
        # print each librarian's name and email address
        print $l->name(), ' <', $l->email(), "> \n";
        }




                                   69
                                            MyLibrary::Librarian



DESCRIPTION
        Use this module to get and set the characteristics of librarians to a MyLibrary database. Characteristics
        currently include: ID (primary database key), name, email address, telephone number, home page URL,
        and a set of integers (primary database keys) denoting what terms the librarian has been classified under.


METHODS
        This section describes the methods available in the package.

new()
        Use this method to create a librarian object. Called with no options, this method creates an empty object.
        Called with an id option, this method uses the id as a database key and fills the librarian object with data
        from the underlying database.



        # create a new librarian object
        my $librarian = MyLibrary::Librarian->new();
        # create a librarian object based on a previously existing ID
        my $librarian = MyLibrary::Librarian->new(id => 3);



id()
        This method returns an integer representing the database key of the currently created librarian object.



        # get id of current librarian object
        my $id = $librarian->id();



        You cannot set the id attribute.

name()
        This method gets and sets the name from the librarian from the current librarian object:



        # get the name of the current librarian object
        my $name = $librarian->name();
        # set the current librarian object's name
        $librarian->name('Melvile Dewey');



telephone()
        Use this method to get and set the telephone number of the current librarian object:


                                                      70
                                            MyLibrary::Librarian




        # get the telephone number
        my $phone = $librarian->telephone();
        # set the current librarian object's telephone number
        $librarian->telephone('1 (800) 555-1212');



email()
        Like the telephone and name methods, use this method to get and set the librarian object's email attrib-
        ute:



        # get the email address
        my $email_address = $librarian->email();
        # set the current librarian object's email address
        $librarian->email('info@library.org');



url()
        Set or get the URL attribute of the librarian object using this method:



        # get the URL attribute
        my $home_page = $librarian->url();
        # set the URL
        $librarian->url('http://dewey.library.nd.edu/');



term_ids()
        This method gets and sets the term ids with which this libraian object is associated. Given no input, it re-
        turns a list of integers or undef if no term associations exist. Any input given is expected to be a list of
        integers. Related terms can be added or deleted given the correct input parameter. The returned list of
        term ids can be sorted by name using the sort parameter.



        # set the term id's
        $librarian->term_ids(new => [33, 24, 83]);
        # get the term id's of the current librarian object
        my @ids = $librarian->term_ids();
        # get the term id's of the current librarian object sorted by name
        my @ids = $librarian->term_ids(sort => 'name');
        # require the Term package
        use MyLibrary::Term;


                                                      71
                                         MyLibrary::Librarian



      # process each id
      foreach my $i (@ids) {
            # create a term object
            my $term->MyLibrary::Term->new(id => $i);
            # print the term associated with the librarian object
            print $librarian->name, ' has been classified with the term: ',
                   $term->name, ".\n";
            }
      # remove term associations
      $librarian->term_ids(del => [@removed_term_ids]);



commit()
      Use this method to save the librarian object's attributes to the underlying database. If the object's data
      has never been saved before, then this method will create a new record in the database. If you used the
      new and passed it an id option, then this method will update the underlying database.

      This method will return true upon success.



      # save the current librarian object to the underlying database
      $librarian->commit();



delete()
      This method simply deletes the current librarian object from the underlying database.



      # delete (drop) this librarian from the database
      $librarian->delete();



get_librarians()
      Use this method to get all the librarians from the underlying database sorted by their name. This method
      returns an array of objects enabling you to loop through each object in the array and subsequent charac-
      teristics of each object;



      # get all librarians
      my @librarians = MyLibrary::Librarian->get_librarians();
      # process each librarian
      foreach my $l (@librarians) {
            # print the name
            print $l->name, "\n";


                                                   72
                                    MyLibrary::Librarian



        }



ACKNOWLEDGEMENTS
   I would like to thank the following people for providing input on how this package can be improved:
   Brian Cassidy and Ben Ostrowsky.




                                             73
Part III. License
Table of Contents
A. GNU General Public License .................................................................................................. 76
         Preamble ................................................................................................................. 76
         GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRI-
         BUTION AND MODIFICATION ................................................................................ 76
         NO WARRANTY ..................................................................................................... 79




                                                                     75
Appendix                    A.            GNU                  General                         Public
License
    Version 2, June 1991

    Copyright (c) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA
    02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document,
    but changing it is not allowed.


Preamble
    The licenses for most software are designed to take away your freedom to share and change it. By con-
    trast, the GNU General Public License is intended to guarantee your freedom to share and change free
    software--to make sure the software is free for all its users. This General Public License applies to most
    of the Free Software Foundation's software and to any other program whose authors commit to using it.
    (Some other Free Software Foundation software is covered by the GNU Library General Public License
    instead.) You can apply it to your programs, too.

    When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are
    designed to make sure that you have the freedom to distribute copies of free software (and charge for
    this service if you wish), that you receive source code or can get it if you want it, that you can change
    the software or use pieces of it in new free programs; and that you know you can do these things.

    To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask
    you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute
    copies of the software, or if you modify it.

    For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the
    recipients all the rights that you have. You must make sure that they, too, receive or can get the source
    code. And you must show them these terms so they know their rights.

    We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which
    gives you legal permission to copy, distribute and/or modify the software.

    Also, for each author's protection and ours, we want to make certain that everyone understands that there
    is no warranty for this free software. If the software is modified by someone else and passed on, we
    want its recipients to know that what they have is not the original, so that any problems introduced by
    others will not reflect on the original authors' reputations.

    Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that
    redistributors of a free program will individually obtain patent licenses, in effect making the program
    proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free
    use or not licensed at all.

    The precise terms and conditions for copying, distribution and modification follow.


GNU GENERAL PUBLIC LICENSE TERMS AND
CONDITIONS FOR COPYING, DISTRIBUTION
AND MODIFICATION
    0. This License applies to any program or other work which contains a notice placed by the copyright

                                                   76
                                    GNU General Public License



   holder saying it may be distributed under the terms of this General Public License. The "Program", be-
   low, refers to any such program or work, and a "work based on the Program" means either the Program
   or any derivative work under copyright law: that is to say, a work containing the Program or a portion of
   it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation
   is included without limitation in the term "modification".) Each licensee is addressed as "you".

   Activities other than copying, distribution and modification are not covered by this License; they are
   outside its scope. The act of running the Program is not restricted, and the output from the Program is
   covered only if its contents constitute a work based on the Program (independent of having been made
   by running the Program). Whether that is true depends on what the Program does.

   1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any
   medium, provided that you conspicuously and appropriately publish on each copy an appropriate copy-
   right notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the ab-
   sence of any warranty; and give any other recipients of the Program a copy of this License along with
   the Program.

   You may charge a fee for the physical act of transferring a copy, and you may at your option offer war-
   ranty protection in exchange for a fee.

   2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based
   on the Program, and copy and distribute such modifications or work under the terms of Section 1 above,
   provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices stating that you changed the files
and the date of any change.

b) You must cause any work that you distribute or publish, that in whole or in part contains or is
derived from the Program or any part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

c) If the modified program normally reads commands interactively when run, you must cause it,
when started running for such interactive use in the most ordinary way, to print or display an an-
nouncement including an appropriate copyright notice and a notice that there is no warranty (or
else, saying that you provide a warranty) and that users may redistribute the program under these
conditions, and telling the user how to view a copy of this License. (Exception: if the Program it-
self is interactive but does not normally print such an announcement, your work based on the Pro-
gram is not required to print an announcement.)


   These requirements apply to the modified work as a whole. If identifiable sections of that work are not
   derived from the Program, and can be reasonably considered independent and separate works in them-
   selves, then this License, and its terms, do not apply to those sections when you distribute them as separ-
   ate works. But when you distribute the same sections as part of a whole which is a work based on the
   Program, the distribution of the whole must be on the terms of this License, whose permissions for other
   licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

   Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by
   you; rather, the intent is to exercise the right to control the distribution of derivative or collective works
   based on the Program.

   In addition, mere aggregation of another work not based on the Program with the Program (or with a
   work based on the Program) on a volume of a storage or distribution medium does not bring the other
   work under the scope of this License.

   3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or
   executable form under the terms of Sections 1 and 2 above provided that you also do one of the follow-
   ing:


                                                  77
                                    GNU General Public License



a) Accompany it with the complete corresponding machine-readable source code, which must be
distributed under the terms of Sections 1 and 2 above on a medium customarily used for software
interchange; or,

b) Accompany it with a written offer, valid for at least three years, to give any third party, for a
charge no more than your cost of physically performing source distribution, a complete machine-
readable copy of the corresponding source code, to be distributed under the terms of Sections 1
and 2 above on a medium customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer to distribute corresponding
source code. (This alternative is allowed only for noncommercial distribution and only if you re-
ceived the program in object code or executable form with such an offer, in accord with Subsec-
tion b above.)


   The source code for a work means the preferred form of the work for making modifications to it. For an
   executable work, complete source code means all the source code for all modules it contains, plus any
   associated interface definition files, plus the scripts used to control compilation and installation of the
   executable. However, as a special exception, the source code distributed need not include anything that
   is normally distributed (in either source or binary form) with the major components (compiler, kernel,
   and so on) of the operating system on which the executable runs, unless that component itself accom-
   panies the executable.

   If distribution of executable or object code is made by offering access to copy from a designated place,
   then offering equivalent access to copy the source code from the same place counts as distribution of the
   source code, even though third parties are not compelled to copy the source along with the object code.

   4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under
   this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and
   will automatically terminate your rights under this License. However, parties who have received copies,
   or rights, from you under this License will not have their licenses terminated so long as such parties re-
   main in full compliance.

   5. You are not required to accept this License, since you have not signed it. However, nothing else
   grants you permission to modify or distribute the Program or its derivative works. These actions are pro-
   hibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or
   any work based on the Program), you indicate your acceptance of this License to do so, and all its terms
   and conditions for copying, distributing or modifying the Program or works based on it.

   6. Each time you redistribute the Program (or any work based on the Program), the recipient automatic-
   ally receives a license from the original licensor to copy, distribute or modify the Program subject to
   these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the
   rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

   7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason
   (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or oth-
   erwise) that contradict the conditions of this License, they do not excuse you from the conditions of this
   License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and
   any other pertinent obligations, then as a consequence you may not distribute the Program at all. For ex-
   ample, if a patent license would not permit royalty-free redistribution of the Program by all those who
   receive copies directly or indirectly through you, then the only way you could satisfy both it and this Li-
   cense would be to refrain entirely from distribution of the Program.

   If any portion of this section is held invalid or unenforceable under any particular circumstance, the bal-
   ance of the section is intended to apply and the section as a whole is intended to apply in other circum-
   stances.

   It is not the purpose of this section to induce you to infringe any patents or other property right claims or


                                                 78
                                    GNU General Public License



   to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the
   free software distribution system, which is implemented by public license practices. Many people have
   made generous contributions to the wide range of software distributed through that system in reliance on
   consistent application of that system; it is up to the author/donor to decide if he or she is willing to dis-
   tribute software through any other system and a licensee cannot impose that choice.

   This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this
   License. 8. If the distribution and/or use of the Program is restricted in certain countries either by patents
   or by copyrighted interfaces, the original copyright holder who places the Program under this License
   may add an explicit geographical distribution limitation excluding those countries, so that distribution is
   permitted only in or among countries not thus excluded. In such case, this License incorporates the limit-
   ation as if written in the body of this License.

   9. The Free Software Foundation may publish revised and/or new versions of the General Public License
   from time to time. Such new versions will be similar in spirit to the present version, but may differ in de-
   tail to address new problems or concerns.

   Each version is given a distinguishing version number. If the Program specifies a version number of this
   License which applies to it and "any later version", you have the option of following the terms and con-
   ditions either of that version or of any later version published by the Free Software Foundation. If the
   Program does not specify a version number of this License, you may choose any version ever published
   by the Free Software Foundation.

   10. If you wish to incorporate parts of the Program into other free programs whose distribution condi-
   tions are different, write to the author to ask for permission. For software which is copyrighted by the
   Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for
   this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our
   free software and of promoting the sharing and reuse of software generally.


NO WARRANTY
   11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
   FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
   OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
   PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EX-
   PRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK
   AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
   PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
   REPAIR OR CORRECTION.

   12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR RE-
   DISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
   INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
   ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
   LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUS-
   TAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
   WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
   ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

   END OF TERMS AND CONDITIONS




                                                  79

								
To top