NAME

Bric::Biz::Org::Parts::Addr - Organizational Addresses

VERSION

$Revision: 1.2.2.2 $

DATE

$Date: 2001/11/06 23:18:33 $

SYNOPSIS

# Constructors are private - construct from Bric::Biz::Org objects.
my $org = Bric::Biz::Org->lookup({ id => $org_id });
my @addr = $org->get_addresses;
my $addr = $org->new_address;

# Instance Methods.
my $id $addr->get_id;
my $type = $addr->get_type;
$addr = $addr->set_type($type);
my $city = $addr->get_city;
$addr = $addr->set_city($city);
my $state = $addr->get_state;
$addr = $addr->set_state($state);
my $code = $addr->get_code;
$addr = $addr->set_code($code);
my $country = $addr->get_country;
$addr = $addr->set_country($country);
my @lines = $addr->get_lines;
$addr = $addr->set_lines(@lines);

$addr = $addr->activate;
$addr = $addr->deactivate;
$addr = $addr->is_active;

# Print Address Lables.
my $p = Bric::Biz::Person->lookup({ id => $person_id });
foreach my $porg ($p->get_orgs) {
    foreach my $addr ($porg->get_addresses($id)) {
        print $p->format_name("%f% M% l"), "\n";
        print $porg->title, "\n" if $porg->title;
        print $porg->dept, "\n" if $porg->dept;
        map { print "$_\n" } $addr->get_lines;
        print $addr->get_city, ", ", $addr->get_state, "\n";
        print $addr->get_code, "  ", $addr->get_country, "\n\n";
    }
}

DESCRIPTION

This class represents organizational addresses as objects. Organizations are represented as Bric::Biz::Org or subclassed Bric::Biz::Org objects, and a given Bric::Biz::Org object may have an unlimited number of addresses associated with it, each represented by a Bric::Biz::Org::Parts::Addr object.

Bric::Biz::Org::Parts::Addr objects can only be instantiated via the Bric::Biz::Org get_addresses() or add_address() method calls. The Bric::Biz::Org::Parts::Addr constructors are therefore private.

INTERFACE

Constructors

$addr = Bric::Biz::Org::Parts::Addr->new($init)

Instantiates a Bric::Biz::Org::Parts::Addr object. A hashref of initial values may be passed. The supported initial value keys are:

If lines is passed, a single line may be passed, and multiple lines may be passed as an anonymous array. Call $add->_save to save the new object.

Throws:

Side Effects: NONE.

Notes: To be called from Bric::Biz::Org only.

my $addr = Bric::Biz::Org::Parts::Addr->lookup({ id => $id })

Looks up and instantiates a new Bric::Biz::Org::Parts::Addr object based on the Bric::Biz::Org::Parts::Addr object ID passed. If $id is not found in the database, lookup() returns undef. If the ID is found more than once, lookup() returns zero (0). This should not happen.

Throws:

Side Effects: If $id is found, populates the new Bric::Biz::Org object with data from the database before returning it.

Notes: There may actually be no use for this method, since Bric::Biz::Org::Parts::Addr objects will be stored internally in a Bric::Biz::Org object, and therefore may not need to be implemented.

my (@orgs || $orgs_aref) = Bric::Biz::Org::Parts::Addr->list($params)

Returns a list of Bric::Biz::Org::Parts::Addr objects based on the search criteria passed via a hashref. The lookup searches are case-insensitive. The supported lookup parameter keys are:

Throws:

Side Effects: Populates each Bric::Biz::Org::Parts::Addr object with data from the database before returning them all. To be called from Bric::Biz::Org only.

Notes: NONE.

Bric::Biz::Org::Parts::Addr->href($params)

Exactly the same as list(), except that it returns all the Bric::Biz::Org::Parts::Addr objects in an anonymous hash, where the hash keys are the object IDs and the values are the objects. See list() for syntax.

Throws:

Side Effects: NONE.

Notes: NONE.

Destructors

$addr->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Class Methods

my (@aids || $aids_aref) = Bric::Biz::Org::Parts::Addr->list_ids($params)

Returns a list or anonymous array of Bric::Biz::Org::Parts::Addr object IDs based on the search criteria passed. The search parameters are the same as those for list() above.

Throws:

Side Effects: NONE.

Notes: NONE.

my (@parts || $parts_aref) Bric::Biz::Org::Parts::Addr->list_parts

Returns a list of active address parts.

Throws:

Side Effects: NONE.

Notes: NONE.

$success = Bric::Biz::Org::Parts::Addr->add_parts(@parts)

Adds new address parts to the Bric::Biz::Org::Parts::Addr object. These parts will be available exclusively through the get_parts() instance method.

Throws:

Side Effects: NONE.

Notes: NONE.

$success = Bric::Biz::Org::Parts::Addr->del_parts(@parts)

Deletes address parts.

Throws:

Side Effects: NONE.

Notes: NONE.

$meths = Bric::Biz::Org::Parts::Addr->my_meths

Returns an anonymous hash of instrospection data for this object. The format for the introspection is as follows:

Each hash key is the name of a property or attribute of the object. The value for a hash key is another anonymous hash containing the following keys:

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Instance Methods

my $id = $addr->get_id

Returns the ID of the Bric::Biz::Org::Parts::Addr object.

Throws:

Side Effects: NONE.

Notes: If the Bric::Biz::Org::Parts::Addr object has been instantiated via the new() private constructor and has not yet been saved, via the Bric::Biz::Org save() method, the object will not yet have an ID, so this method call will return undef.

my $type = $addr->get_type

Returns the type of address it is. Intended to distinguish between different addresses for a given organization. Examples might be "New York Shipping" or "San Francisco Billing."

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->set_type($type)

Sets the type attributte. Returns $self on success and undef on failure.

Throws:

Side Effects: NONE.

Notes: NONE.

my $ = $addr->get_city

Returns the address city.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->set_city($city)

Sets the address city. Returns $self on success and undef on failure.

Throws:

Side Effects: NONE.

Notes: NONE.

my $state = $addr->get_state

Returns the address state.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->set_state($state)

Sets the address state. Returns $self on success and undef on failure.

Throws:

Side Effects: NONE.

Notes: NONE.

my $code = $addr->get_code

Returns the address postal code, such as US Zip Code.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->set_code($code)

Sets the address postal code, such as US Zip Code. Returns $self on success and undef on failure.

Throws:

Side Effects: NONE.

Notes: NONE.

my $country = $addr->get_country

Returns the addresse country.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->set_country($country)

Sets the address country. Returns $self on success and undef on failure.

Throws:

Side Effects: NONE.

Notes: Countries are stored in the database by their ISO 3166 code names. See http://wmbr.mit.edu/stations/ISOcodes.html. We'll need to finagle some sort of database lookup, perhaps through a trigger.

my @lines = $addr->get_lines

Returns an ordered list of individual address lines for the addres. An infinite number of address lines are supported, though it is assumed that most addresses will have 1-3 address lines.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->set_lines(@lines)

Sets the address lines for the address. An infinite number of address lines are supported, though it is assumed that most addresses will have 1-3 address lines.

Throws:

Side Effects: Stores new address lines internally to the object. The lines will not persist until the address object is saved via the Bric::Biz::Org object's save() method.

Notes: NONE.

my (%parts || $parts_href) = $addr->get_parts;

Returns a hash (list) or anonymous hash of the parts of this address.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->set_part($part, $value);

Sets a part to a value. The part must exist in the database. To add a part, use the add_parts() class method.

Throws:

Side Effects: NONE.

Notes: I could grab a list of all the parts from the database here (using list_parts() and then make sure each part exists before assigning it, but I didn't want to waste the query. Instead, there'll be a failure when save() is called and there's a non-valid part name.

$self = $addr->activate

Activates the Bric::Biz::Org::Parts::Addr object. The change will not persist until the Bric::Biz::Org object's save() method is called. Bric::Biz::Org::Parts::Addr objects instantiated by new() are active by default.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->deactivate

Deactivates (deletes) the Bric::Biz::Org::Parts::Addr object. The change will not persist until the Bric::Biz::Org object's save() method is called.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->is_active

Returns $self if the Bric::Biz::Org::Parts::Addr object is active, and undef if it is not.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $addr->save

Saves any changes to the Bric::Biz::Org::Parts::Addr object, including changes to associated address (Bric::Biz::Org::Parts::Addr) objects. Returns $self on success and undef on failure.

Throws:

Side Effects: Cleans out internal cache of address lines and parts to reflect what is in the database.

Notes: NONE.

PRIVATE

Private Class Methods

NONE.

Private Instance Methods

NONE.

Private Functions

my $orgs_aref = &$get_em( $pkg, $search_href )
my $org_ids_aref = &$get_em( $pkg, $search_href, 1 )

Function used by lookup() and list() to return a list of Bric::Biz::Org objects or, if called with an optional third argument, returns a list of Bric::Biz::Org object IDs (used by list_ids()).

Throws:

Side Effects: NONE.

Notes: NONE.

my $addr = &$make_obj($pkg, $init)

Instantiates a new object.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = &$set_part($self, $part, $value)

Sets an address part.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = &$get_part($self, $part)

Gets an address part.

Throws:

Side Effects: NONE.

Notes: NONE.

$success = &$save_main($self)

Saves the primary properties of the object.

Throws:

Side Effects: NONE.

Notes: NONE.

$success = &$save_parts($self, $parts)

Saves the address parts.

Throws:

Side Effects: NONE.

Notes: NONE.

$success = &$save_lines($self)

Saves the address lines.

Throws:

Side Effects: NONE.

Notes: NONE.

($ins, $upd, $del) = &$part_sql

Prepares and returns SQL statements for inserting, updating, and deleting address parts.

Throws:

Side Effects: NONE.

Notes: NONE.

NOTES

NONE.

AUTHOR

David Wheeler <david@wheeler.net>

SEE ALSO

perl(1), Bric (2), Bric::Biz::Org(3) Bric::Biz::Person(4)

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 1329:

=back doesn't take any parameters, but you said =back 4