• Name
• Synopsis
• Description
• Interface
  • Constructors
  • Destructors
  • Public Class Methods
  • Public Instance Methods
• Private
  • Private Class Methods
  • Private Instance Methods
  • Private Functions
• Notes
• Author
• See Also

Name

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

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 Labels.
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:

  • org_id
  • type
  • city
  • state
  • code
  • country
  • lines

  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:

  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  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:

  • Too many Bric::Biz::Org::Parts::Addr objects found.
  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to select column into arrayref.
  • Unable to execute SQL statement.
  • Unable to bind to columns to statement handle.
  • Unable to fetch row from statement handle.

  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:

  • id

    Address ID. May use ANY for a list of possible values.

  • type

    The type of address. May use ANY for a list of possible values.

  • city

    The address city. May use ANY for a list of possible values.

  • state

    The address state. May use ANY for a list of possible values.

  • code

    The address postal code. May use ANY for a list of possible values.

  • country

    The address country. May use ANY for a list of possible values.

  • org_id

    The ID for a Bric::Biz::Org object with which addresses may be associated. May use ANY for a list of possible values.

  • person_id

    The ID of a Bric::Biz::Person object with which addresses may be associated. May use ANY for a list of possible values.

  Throws:

  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to select column into arrayref.
  • Unable to execute SQL statement.
  • Unable to bind to columns to statement handle.
  • Unable to fetch row from statement handle.

  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:

  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to select column into arrayref.
  • Unable to execute SQL statement.
  • Unable to bind to columns to statement handle.
  • Unable to fetch row from statement handle.

  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:

  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to select column into arrayref.
  • Unable to execute SQL statement.
  • Unable to bind to columns to statement handle.
  • Unable to fetch row from statement handle.

  Side Effects: NONE.

  Notes: NONE.

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

  Returns a list of active address parts.

  Throws:

  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to select column into arrayref.

  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:

  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to execute SQL statement.

  Side Effects: NONE.

  Notes: NONE.

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

  Deletes address parts.

  Throws:

  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to execute SQL statement.

  Side Effects: NONE.

  Notes: NONE.

• my $meths = Bric::Biz::Org::Parts::Addr->my_meths
• my (@meths || $meths_aref) = Bric::Biz:::Org::Parts::Addr->my_meths(TRUE)
• my (@meths || $meths_aref) = Bric::Biz:::Org::Parts::Addr->my_meths(0, TRUE)

  Returns an anonymous hash of introspection data for this object. If called with a true argument, it will return an ordered list or anonymous array of introspection data. If a second true argument is passed instead of a first, then a list or anonymous array of introspection data will be returned for properties that uniquely identify an object (excluding id, which is assumed).

  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:

  • name

    The name of the property or attribute. Is the same as the hash key when an anonymous hash is returned.

  • disp

    The display name of the property or attribute.

  • get_meth

    A reference to the method that will retrieve the value of the property or attribute.

  • get_args

    An anonymous array of arguments to pass to a call to get_meth in order to retrieve the value of the property or attribute.

  • set_meth

    A reference to the method that will set the value of the property or attribute.

  • set_args

    An anonymous array of arguments to pass to a call to set_meth in order to set the value of the property or attribute.

  • type

    The type of value the property or attribute contains. There are only three types:

    • short
    • date
    • blob
  • len

    If the value is a 'short' value, this hash key contains the length of the field.

  • search

    The property is searchable via the list() and list_ids() methods.

  • req

    The property or attribute is required.

  • props

    An anonymous hash of properties used to display the property or attribute. Possible keys include:

    • type

      The display field type. Possible values are

      • text
      • textarea
      • password
      • hidden
      • radio
      • checkbox
      • select
    • length

      The Length, in letters, to display a text or password field.

    • maxlength

      The maximum length of the property or value - usually defined by the SQL DDL.

  • rows

    The number of rows to format in a textarea field.

  • cols

    The number of columns to format in a textarea field.

  • vals

    An anonymous hash of key/value pairs reprsenting the values and display names to use in a select list.

  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:

  • Bad AUTOLOAD method format.
  • Cannot AUTOLOAD private methods.
  • Access denied: READ access for field 'id' required.
  • No AUTOLOAD method.

  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:

  • Bad AUTOLOAD method format.
  • Cannot AUTOLOAD private methods.
  • Access denied: READ access for field 'type' required.
  • No AUTOLOAD method.

  Side Effects: NONE.

  Notes: NONE.

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

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

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

• my $ = $addr->get_city

  Returns the address city.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

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

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

  Throws:

  • Bric::_get() - Problems retrieving fields.

  Side Effects: NONE.

  Notes: NONE.

• my $state = $addr->get_state

  Returns the address state.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

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

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

  Throws:

  • Bric::_get() - Problems retrieving fields.

  Side Effects: NONE.

  Notes: NONE.

• my $code = $addr->get_code

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

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  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:

  • Bric::_get() - Problems retrieving fields.

  Side Effects: NONE.

  Notes: NONE.

• my $country = $addr->get_country

  Returns the addresse country.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

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

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

  Throws:

  • Bric::_get() - Problems retrieving fields.

  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:

  • Bric::_get() - Problems retrieving fields.

  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:

  • Bric::_get() - Problems retrieving fields.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  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:

  • Bad AUTOLOAD method format.
  • Cannot AUTOLOAD private methods.
  • Access denied: READ access for field 'parts' required.
  • No AUTOLOAD method.

  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:

  • Bric::_get() - Problems retrieving fields.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  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:

  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  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:

  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  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:

  • Bric::_get() - Problems retrieving fields.

  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:

  • Bric::_get() - Problems retrieving fields.
  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to execute SQL statement.
  • Unable to select row.
  • Incorrect number of args to _set.
  • Bric::_set() - Problems setting fields.

  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:

  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to select column into arrayref.
  • Unable to execute SQL statement.
  • Unable to bind to columns to statement handle.
  • Unable to fetch row from statement handle.

  Side Effects: NONE.

  Notes: NONE.

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

  Instantiates a new object.

  Throws:

  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

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

  Sets an address part.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

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

  Gets an address part.

  Throws:

  • Bric::_get() - Problems retrieving fields.

  Side Effects: NONE.

  Notes: NONE.

• $success = &$save_main($self)

  Saves the primary properties of the object.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to execute SQL statement.
  • Unable to select row.
  • Incorrect number of args to _set.
  • Bric::_set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

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

  Saves the address parts.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to execute SQL statement.
  • Unable to select row.
  • Incorrect number of args to _set.
  • Bric::_set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

• $success = &$save_lines($self)

  Saves the address lines.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Unable to connect to database.
  • Unable to prepare SQL statement.
  • Unable to execute SQL statement.
  • Unable to select row.
  • Incorrect number of args to _set.
  • Bric::_set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

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

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

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Unable to connect to database.
  • Unable to prepare SQL statement.

  Side Effects: NONE.

  Notes: NONE.

Notes

NONE.

Author

David Wheeler

See Also

Bric, Bric::Biz::Org, Bric::Biz::Person