• NAME
• VERSION
• DATE
• 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 - Bricolage Interface to Organizations

VERSION

$LastChangedRevision$

DATE

$LastChangedDate$

SYNOPSIS

# Constructors.
my $org = Bric::Biz::Org->new;
my $org = Bric::Biz::Org->lookup({ id => $id });
my @orgs = Bric::Biz::Org->list($search_href);

# Class Methods.
my @org_ids = Bric::Biz::Org->list_ids($search_href);

# Instance Methods.
my $id = $org->get_id;
my $name = $org->get_name($name);
$org = $org->set_name($name);
my $long_name = $org->get_long_name($long_name);
$org = $org->set_long_name($long_name);

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

my $porg = $org->add_object($person);

my @addr = $org->get_addr;
my $addr = $org->new_addr;
$org = $org->del_addr;

$org->save;

DESCRIPTION

This class represents organizations in Bricolage. Organizations may be the companies for whom a person represented by a Bric::Biz::Person object works, or an organization that owns the rights to a given asset, or with whom a product is associated (this last use will be included in a future version).

The primary use for Bric::Biz::Org as of this writing, however, is to associate people (Bric::Biz::Person objects) with companies and their addresses. These associations are created by the Bric::Biz::Org add_object() method, and by the Bric::Biz::Org::Person subclass it returns. See Bric::Biz::Org::Person for its additions to the Bric::Biz::Org API.

INTERFACE

Constructors

• $org = Bric::Biz::Org->new
• my $org = Bric::Biz::Org->new($init)

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

  • name
  • long_name

  Call $org->save to save the new object.

  Throws:

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

  Side Effects: NONE.

  Notes: NONE.

• my $org = Bric::Biz::Org->lookup({ id => $id })

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

  Throws:

  • Too many Bric::Biz::Org objects found.
  • Unable to prepare SQL statement.
  • Unable to connect to database.
  • 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: NONE.

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

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

  • id

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

  • name

    The organization's name. May use ANY for a list of possible values.

  • long_name

    The long name of the organization. May use ANY for a list of possible values.

  • personal

    A boolean indicating whether or not the oganization is a person.

  • grp_id

    A Bric::Util::Grp::Keyword object ID. May use ANY for a list of possible values.

  Throws:

  • Unable to prepare SQL statement.
  • Unable to connect to database.
  • 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 object with data from the database before returning them all.

  Notes: This method is overridden by the list() method of the Bric::Biz::Org::Person class.

Destructors

• $org->DESTROY

  Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

  Throws: NONE.

  Side Effects: NONE.

  Notes: NONE.

Public Class Methods

• my (@org_ids || $org_ids_aref) = Bric::Biz::Org->list_ids($params)

  Functionally identical to list(), but returns Bric::Biz::Org object IDs rather than objects. See list() for a description of its interface.

  Throws:

  • Unable to prepare SQL statement.
  • Unable to connect to database.
  • 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.

• $meths = Bric::Biz::Org >my_meths
• (@meths || $meths_aref) = Bric::Biz::Org->my_meths(TRUE)
• my (@meths || $meths_aref) = Bric::Biz::Org->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 = $org->get_id

  Returns the ID of the Bric::Biz::Org 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 object has been instantiated via the new() constructor and has not yet been saved, the object will not yet have an ID, so this method call will return undef.

• my $name = $org->get_name

  Returns the common name for the Bric::Biz::Org object.

  Throws:

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

  Side Effects: NONE.

  Notes: NONE.

• $self = $org->set_name($name)

  Sets the common name of the Bric::Biz::Org object. Returns $self on success and undef on failure.

  Throws:

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

  Side Effects: NONE.

  Notes: NONE.

• my $long_name = $org->get_long_name

  Returns the formal name for the Bric::Biz::Org object.

  Throws:

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

  Side Effects: NONE.

  Notes: NONE.

• $self = $org->set_long_name($long_name)

  Sets the formal name for the Bric::Biz::Org object. Returns $self on success And Undef on failure

  Throws:

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

  Side Effects: NONE.

  Notes: NONE.

• $self = $org->activate

  Activates the Bric::Biz::Org object. Call $org->save to make the change persistent. Bric::Biz::Org 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 = $org->deactivate

  Deactivates (deletes) the Bric::Biz::Org object. Call $org->save to make the change persistent.

  Throws:

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

  Side Effects: NONE.

  Notes: NONE.

• $self = $org->is_active

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

  Throws:

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

  Side Effects: NONE.

  Notes: NONE.

• $self = $org->is_personal

  Returns $self if the Bric::Biz::Org object is personal, and undef if it is not. By personal I mean that it is directly related to an individual person, and all the addresses are associated with that person. This setting cannot be changed; it is set to true for the personal organization created for a person whenever a person is created.

  Throws:

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

  Side Effects: NONE.

  Notes: NONE.

• my $obj_org = $org->add_object($object)

  Associates a Bricolage object with the Bric::Biz::Org object, returning the relevant subclassed Bric::Biz::Org object. See the Bric::Biz::Org::* subclasses for the relevant methods for associating specific Bric::Biz::Org::Parts::Addresses with other Bricolage objects.

  Throws:

  • Unable to instantiate new object.
  • Bric::_get() - Problems retrieving fields.

  Side Effects: Returns a subclassed Bric::Biz::Org object with methods for managing the association with the Bricolage object. Currently, only Bric::Biz::Person objects may be passed, thus returning Bric::Biz::Org::Person objects.

  Notes: NONE.

• my (@addr || $addr_aref) = $org->get_addr
• my (@addr || $addr_aref) = $org->get_addr(@address_ids)

  Returns a list of Bric::Biz::Org::Parts::Address objects. Returns an empty list when there are no addresses associated with this object, and undef upon failure. See the Bric::Biz::Org::Parts::Address documentation for its API.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Unable to prepare SQL statement.
  • Unable to connect to database.
  • 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.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: Stores the list of Bric::Biz::Org::Parts::Address objects internally in the Bric::Biz::Org object the first time it or any other address method is called on a given Bric::Biz::Org instance.

  Notes: Changes made to Bric::Biz::Org::Parts::Address objects retreived from this method can be persistently saved to the database only by calling the Bric::Biz::Org object's save() method.

• my $address = $org->new_addr

  Adds and returns a new Bric::Biz::Org::Parts::Address object associated with the Bric::Biz::Org object. Pass in an optional list of parameters for attributes to be assigned to the object. Returns undef on failure. See Bric::Biz::Org::Parts::Address for its API.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • Unable to prepare SQL statement.
  • Unable to connect to database.
  • 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.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: Uses Bric::Util::Coll internally.

  Notes: Changes made to $address objects retreived from this method can be persistently saved to the database only by calling the Bric::Biz::Org object's save() method.

• my $self = $org->del_addr
• my $self = $org->del_addr(@address_ids)

  If called with no arguments, deletes all Bric::Biz::Org::Parts::Address objects associated with the Bric::Biz::Org object. Pass Bric::Biz::Org::Parts::Address object IDs to delete only those Bric::Biz::Org::Parts::Address objects.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • 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.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: Deletes the Bric::Biz::Org::Parts::Address objects from the Bric::Biz::Org object's internal structure, but retains a list of the IDs. These will be used to delete the Bric::Biz::Org::Parts::Address objects from the database when $org->save is called, then are deleted from the Bric::Biz::Org object's internal structure. The Bric::Biz::Org::Parts::Address objects will not actually be deleted from the database until $org->save is called.

  Notes: If called with a list of Bric::Biz::Org::Parts::Address object IDs, del_address() will only delete those address object if they're associated with the current Bric::Biz::Org object.

• $self = $org->save

  Saves any changes to the Bric::Biz::Org object, including changes to associated address (Bric::Biz::Org::Parts::Address) 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 Bric::Biz::Org::Parts::Address objects 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_col = &$get_addr_coll($self)

  Returns the collection of addresses for this organization. The collection is a Bric::Util::Coll::Addr object. See that class and its parent, Bric::Util::Coll, for interface details.

  Throws:

  • Bric::_get() - Problems retrieving fields.
  • 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.
  • Incorrect number of args to Bric::_set().
  • Bric::set() - Problems setting fields.

  Side Effects: NONE.

  Notes: NONE.

NOTES

NONE.

AUTHOR

David Wheeler

SEE ALSO

Bric, Bric::Biz::Person