The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MyLibrary-3.0.4
River stage zero No dependents
++
/ 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(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 allow 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 manipulation 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 context. 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');

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 integer 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);

resource_id()

This method can be used either to retrieve or set the resource id which is related to this location. The resource 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 Resource.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.

        # 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 exist in the database will not be created. The key id for each new location type is generated by incrementing 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);

SEE ALSO

For more information, see the MyLibrary home page: http://dewey.library.nd.edu/mylibrary/.

AUTHORS

Eric Lease Morgan <emorgan@nd.edu> Robert Fox <rfox2@nd.edu>