#
# Copyright (C) 2006-2008  Georgia Public Library Service
# 
# Author: David J. Fiander
# 
# This program is free software; you can redistribute it and/or
# modify it under the terms of version 2 of the GNU General Public
# License as published by the Free Software Foundation.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY 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 program; if not, write to the Free
# Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
# MA 02111-1307 USA

=head1 NAME

ILS::Item - Portable Item status object class for SIP

=head1 SYNOPSIS

	use ILS;
	use ILS::Item;

	# Look up item based on item_id
	my $item = new ILS::Item $item_id;

	# Basic object access methods
	$item_id = $item->id;
	$title = $item->title_id;
	$media_type = $item->sip_media_type;
	$bool = $item->magnetic;
	$locn = $item->permanent_location;
	$locn = $item->current_location;
	$props = $item->sip_item_props;
	$owner = $item->owner;
	$str = $item->sip_circulation_status;
	$bool = $item->available;
	@hold_queue = $item->hold_queue;
	$pos = $item->hold_queue_position($patron_id);
	$due = $item->due_date;
	$pickup = $item->hold_pickup_date;
	$recall = $item->recall_date;
	$fee = $item->fee;
	$currency = $item->fee_currency;
	$type = $item->sip_fee_type;
	$mark = $item->sip_security_marker;
	$msg = $item->screen_msg;
	$msg = $item->print_line;

	# Operations on items
	$status = $item->status_update($item_props);

=head1 DESCRIPTION

An C<ILS::Item> object holds the information necessary to
circulate an item in the library's collection.  It does not need
to be a complete bibliographic description of the item; merely
basic human-appropriate identifying information is necessary
(that is, not the barcode, but just a title, and maybe author).

For the most part, C<ILS::Item>s are not operated on directly,
but are passed to C<ILS> methods as part of a transaction.  That
is, rather than having an item check itself in:

	$item->checkin;

the code tells the ILS that the item has returned:

	$ils->checkin($item_id);

Similarly, patron's don't check things out (a la,
C<$patron-E<gt>checkout($item)>), but the ILS checks items out to
patrons.  This means that the methods that are defined for items
are, almost exclusively, methods to retrieve information about
the state of the item.

=over

=item C<$item_id = $item-E<gt>id>

Return the item ID, or barcode, of C<$item>.

=item C<$title = $item-E<gt>title_id>

Return the title, or some other human-relevant description, of
the item.

=item C<$media_type = $item-E<gt>media_type>

Return the SIP-defined media type of the item.  The specification
provides the following definitions:

	000 Other
	001 Book
	002 Magazine
	003 Bound journal
	004 Audio tape
	005 Video tape
	006 CD/CDROM
	007 Diskette
	008 Book with diskette
	009 Book with CD
	010 Book with audio tape

The SIP server does not use the media type code to alter its
behavior at all; it merely passes it through to the self-service
terminal.  In particular, it does not set indicators related to
whether an item is magnetic, or whether it should be
desensitized, based on this return type.  The
C<$item-E<gt>magnetic> method will be used for that purpose.

=item C<magnetic>

Is the item some form of magnetic media (eg, a video or a book
with an accompanying floppy)?  This method will not be called
unless 

    $ils->supports('magnetic media')

returns C<true>.

If this method is defined, it is assumed to return either C<true>
or C<false> for every item.  If the magnetic media indication is
not supported by the ILS, then the SIP server will indicate that
all items are 'Unknown'.

=item C<$locn = $item-E<gt>permanent_location>

Where does this item normally reside?  The protocol specification
is not clear on whether this is the item's "home branch", or a
location code within the branch, merely stating that it is, "The
location where an item is normally stored after being checked
in."

=item C<$locn = $item-E<gt>current_location>

According to the protocol, "[T]he current location of the item.
[A checkin terminal] could set this field to the ... system
terminal location on a Checkin message."

=item C<$props = $item-E<gt>sip_item_props>

Returns "item properties" associated with the item.  This is an
(optional) opaque string that is passed between the self-service
terminals and the ILS.  It can be set by the terminal, and should
be stored in the ILS if it is.

=item C<$owner = $item-E<gt>owner>

The spec says, "This field might contain the name of the
institution or library that owns the item."

=item C<$str = $item-E<gt>sip_circulation_status>

Returns a two-character string describing the circulation status
of the item, as defined in the specification:

	01 Other
	02 On order
	03 Available
	04 Charged
	05 Charged; not to be recalled until earliest recall date
	06 In process
	07 Recalled
	08 Waiting on hold shelf
	09 Waiting to be re-shelved
	10 In transit between library locations
	11 Claimed returned
	12 Lost
	13 Missing

=item C<$bool = $item-E<gt>available>

Is the item available?  That is, not checked out, and not on the
hold shelf?

=item C<@hold_queue = $item-E<gt>hold_queue>

Returns a list of the C<$patron_id>s of the patrons that have
outstanding holds on the item.

=item C<$pos = $item-E<gt>hold_queue_position($patron_id)>

Returns the location of C<$patron_id> in the hold queue for the
item, with '1' indicating the next person to receive the item.  A
return status of '0' indicates that C<$patron_id> does not have a
hold on the item.

=item C<$date = $item-E<gt>recall_date>
=item C<$date = $item-E<gt>hold_pickup_date>

These functions all return the corresponding date as a standard
SIP-format timestamp:

	YYYYMMDDZZZZHHMMSS

Where the C<'Z'> characters indicate spaces.

=item C<$date = $item-E<gt>due_date>

Returns the date the item is due.  The format for this timestamp
is not defined by the specification, but it should be something
simple for a human reader to understand.

=item C<$fee = $item-E<gt>fee>

The amount of the fee associated with borrowing this item.

=item C<$currency = $item-E<gt>fee_currency>

The currency in which the fee type above is denominated.  This
field is the ISO standard 4217 three-character currency code.  It
is highly unlikely that many systems will denominate fees in more
than one currency, however.

=item C<$type = $item-E<gt>sip_fee_type>

The type of fee being charged, as defined by the SIP protocol
specification:

	01 Other/unknown
	02 Administrative
	03 Damage
	04 Overdue
	05 Processing
	06 Rental
	07 Replacement
	08 Computer access charge
	09 Hold fee

=item C<$mark = $item-E<gt>sip_security_marker>

The type of security system with which the item is tagged:

	00 Other
	01 None
	02 3M Tattle-tape
	03 3M Whisper tape

=item C<$msg = $item-E<gt>screen_msg>
=item C<$msg = $item-E<gt>print_line>

The usual suspects.

=back
