NAME

Litigation::Database::Object - Object stored in the Litigation::Database system.

SYNOPSIS

  use Litigation::Database;

  my $db = Litigation::Database::Connection->login_new
    ('01', 'jsmith', 'mysecretpassword');
  my $list = Litigation::Database::Object::List->new();
  $list->set_t("A list of fruit");
  $list->save({db => $db});
  my $apple = Litigation::Database::Object->new();
  $apple->set_t("Apple");
  my $orange = Litigation::Database::Object->new();
  $orange->set_t("Orange");
  $list->add_Member_Of(
                        {obj => $apple},
                        {obj => $orange},
                      );
  $list->save_new_relns();
  my $top = $list->get_top_object();
  $top->add_Item_Of({obj => $list});
  $top->save_new_relns();

DESCRIPTION

The Litigation::Database::Object is the base class for all objects stored in the Litigation::Database system.

INTERFACE

Constructor

my $obj = Litigation::Database::Object->new( \%args )

Called in this fashion without arguments, the constructor only creates a bare object in memory. It does not create the object in a database. You need to call save() to save an object to the database.

In order to save an object to a database, the object needs to know the database (the Litigation::Database::Connection) to which it belongs. There are several ways to do this.

First, you can pass the argument db to new.

  my $obj = Litigation::Database::Object->new({db => $db});

where $db is a Litigation::Database::Connection. db is the only argument that new understands.

Second, you can set the database explicitly using set_db.

  $obj->set_db($db);

Third, you can call the constructor from an object that already belongs to a database.

  my $obj = $another_object->new();

Then, calling $obj->save() will save $obj to the database associated with $another_object.

Fourth, you can wait until you call save to indicate the database.

  $obj->save({db => $db});

Technical note: since Litigation::Database uses inside-out objects, the constructor returns a reference to an anonymous scalar. Running Data::Dumper::Dumper on the object will not show any information. All access to an object's data is through method calls.

Property methods

The properties of a Litigation::Database::Object represent static information that is unique to the object. Relationships, by contrast, represent information about an object's relationship to other objects.

The properties with one-letter names (t, d, i, f, and b) are stored in their own PostgreSQL columns (of type text, timestamp without time zone, integer, double precision, and boolean, respectively). The most-used of these properties is t, which represents the title of the object.

All other properties are packed with Data::Dumper into a single text column. As a result, properties can be used to store complex Perl data structures, such as arrays of hashes. A property can store any data that Data::Dumper::Dumper can export and Safe::reval can import. (Note: Data::Dumper will export blessed references, but when Safe imports them, the references will not function properly as objects until they are re-blessed into their classes. Inside-out objects, such as all Litigation::Database objects, look empty from the perspective of Data::Dumper.)

Setting properties does not automatically save the new properties in the database. You will need to call save() in order to save your changes.

$obj->get_t()
$obj->set_t( $title )

Return/set the title of $obj. The format is plain text without HTML. It is stored in a PostgreSQL column of type "text."

$obj->get_d()
$obj->set_d( $date )

Return/set the date value of $obj. It needs to be in a format that can be understood by PostgreSQL when it is inserted into a PostgreSQL column of type "timestamp without time zone."

$obj->get_i()
$obj->set_i( $integer )

Return/set the integer value of $obj. It needs to be in a format that can be understood by PostgreSQL when it is inserted into a PostgreSQL column of type "integer."

$obj->get_f()
$obj->set_f( $float )

Return/set the floating point value of $obj. It needs to be in a format that can be understood by PostgreSQL when it is inserted into a PostgreSQL column of type "double precision."

$obj->get_b()
$obj->set_b( $boolean )

Return/set the boolean value of $obj. It needs to be in a format that can be understood by PostgreSQL when it is inserted into a PostgreSQL column of type "boolean."

$obj->get_desc()
$obj->set_desc( $desc )

Return/set the description of $obj. This can use HTML.

$obj->get_color()
$obj->set_color( $color )

Return/set the color of $obj. $color must be a text string with a standard color name (e.g., "black", "red", "blue") or a CSS color (e.g., "#000", "#F0F0F0", "#777777").

Color-coding is used by Litigation::Database::Object::Highlight and is available to other object types.

$obj->get_importId()
$obj->set_importId( $original_id )

Return/set the integer ID that the object had in its original database before it was exported and imported into another database. Used by Litigation::Database::Object::Exporter and Litigation::Database::Object::Importer.

$obj->get_sort()
$obj->set_sort( $sort_info )

Return/set the data structure indicating how relationships should be sorted. (Not implemented yet.)

Relationship methods

Relationship connects one object to another object. Each object type has zero or more relationship types associated with it.

Relationships have inherent directionality. One party to the relationship is a "parent," while the other is a "child." The relationship goes by a different name depending on the perspective. For example,

To take a literal example of this, consider a mother, Sandra, and her child, Jimmy. Sandra and Jimmy are two objects, and there is a single relationship between them, a parent/child relationship. Jimmy is the "child of" Sandra. Sandra is the "parent of" Jimmy. The relationship type goes by two different names depending on the perspective.

In Litigation::Database, we can model this as two objects, $sandra and $jimmy. We have accessor methods available to us hat allow us to write code like:

  ($son)    = @{$sandra->get_Child_Of()}; # $son->{obj}    == $jimmy
  ($parent) = @{$jimmy->get_Parent_Of()}; # $parent->{obj} == $sandra

Suppose Sandra has a new child named Katie. We could write:

  $sandra->add_Child_Of({obj => $katie});

Or, equivalently, we could write:

  $katie->add_Parent_of({obj => $sandra});

These methods exist within the namespace of the Litigation::Database::Object::Person::Individual module.

The Litigation::Database::Object has four relationships, Item_Of, Comment_On, Tag_Of, and LD_Job_Result_Of, which are inherited by all subclasses. Many more (and more interesting) relationships exist within the subclasses of Litigation::Database::Object.

The following explains the methods of the Item_Of relationship, a generic relationship used for putting one object within another. The other relationships work in the same way.

$parent->get_Item_Of()
$parent->add_Item_Of( $rel_obj )
$parent->remove_Item_Of( $rel_obj )

The get_Item_Of() methods returns a reference to an array of relationship-object references. The add_Item_Of() and remove_Item_Of() methods take a relationship-object reference as input.

The relationship-object reference bundles an object with a relationship to it. It is a hash with three keys: obj, rel, and (if applicable) pobj.

For example, consider an object called "Ingredients for bread" that contains the following objects as items: "flour," "salt", "yeast," and "water."

  foreach my $ingredient (@{$ingredients->get_Item_Of()}){
    print "rel is a " . ref($ingredient->{rel}) . "\n";
    print "obj is a " . ref($ingredient->{obj}) . "\n";
    print "obj is called " . $ingredient->{obj}->get_t() . "\n\n";
  }

This would print:

  rel is a Litigation::Database::Relationship
  obj is a Litigation::Database::Object
  obj is called flour
  
  rel is a Litigation::Database::Relationship
  obj is a Litigation::Database::Object
  obj is called salt
  
  rel is a Litigation::Database::Relationship
  obj is a Litigation::Database::Object
  obj is called yeast

  rel is a Litigation::Database::Relationship
  obj is a Litigation::Database::Object
  obj is called water

Adding relationships does not automatically save the new relationship in the database. You will need to call save_new_relns() in order for your add_ calls to take effect in the database.

By contrast, remove_ calls take effect in the database immediately.

$child->get_Object_Containing()
$child->add_Object_Containing( $hashref )
$child->remove_Object_Containing( $hashref )

These accessors act on the same relationships, except from the other perspective.

$parent->get_Items_Of()
$parent->add_Items_Of( $hashref )
$parent->remove_Items_Of( $hashref )
$child->get_Objects_Containing()
$child->add_Objects_Containing( $hashref )
$child->remove_Objects_Containing( $hashref )

Methods for saving objects to the database

$obj->save( \%args )

Saves the object in the database. If you created the object without indicating its database, you will need to supply the database as an argument to save:

  $obj->save({db => $db})

where $db is a Litigation::Database::Connection.

$obj->save_new_relns()

Saves new relationships of $obj to the database. save_new_relns() looks at all the relationship-object references you added with add_ methods and saves them to the database.

If it encounters an object that is new and has never been saved to the database, it saves it to the database for you. However, it does not call save on objects that were loaded from the database. So, if you make changes to an existing object's properties, do not expect save_new_relns to save those changes for you.

$obj->get_db()
$obj->set_db( $db )

Returns/sets the Litigation::Database::Connection associated with the object. If the object already has a connection to a database, this does nothing.

$obj->get_perms()
$obj->set_perms( $perms )
$obj->get_owner()
$obj->set_owner( $owner_id )
$obj->get_group()
$obj->set_group( $group_id )

Acccessors for the object's security information. For more information about the Litigation::Database access control system, see Object-level security.

If you do not set the security information, defaults will be provided. See the set_default_perms and set_default_group methods.

The permissions flags $perms are in traditional octal Unix format.

  my $perms = $obj->get_perms();
  $perms |= 0400; # Owner can read
  $perms |= 0200; # Owner can write
  $perms |= 0100; # Owner can execute
  $perms |= 0040; # Group can read
  $perms |= 0020; # Group can write
  $perms |= 0010; # Group can execute
  $perms |= 0004; # Others can read
  $perms |= 0002; # Others can write
  $perms |= 0001; # Others can execute
  $obj->set_perms( $perms );
  $obj->save();

The owner $owner_id must refer to the ID of a Litigation::Database::Object::LDUser object that exists in the database.

The group $group_id must refer to the ID of a Litigation::Database::Object::LDGroup object that exists in the database.

If you do not have permissions to change the security on an object, running save will trigger an exception.

Before you can set security information, the object must be associated with a database, or else an error will occur. See "Constructor" for more information about associating an object with a database.

$obj->get_modtime()

Returns the date and time, in epoch seconds, when the object was last modified.

Methods for retrieving information from the database

Loading information about an object

$obj->load( $flags );

Loads object properties (but not relationships) from the database.

The $flags argument to this method and the other methods in this section will be explained in the next section.

$obj->load_relns( $flags );

Loads child relationships from the database. The properties (but not the relationships) of child objects are loaded.

$obj->load_relns_backward( $flags );

Loads parent relationships from the database. The properties (but not the relationships) of parent objects are loaded.

$obj->load_all( $flags );

Loads object properties and child relationships from the database. The properties (but not the relationships) of child objects are loaded.

$obj->load_all_with_grandchildren( $flags, $rel_type );

Loads object properties, child relationships, and grandchild relationships from the database. The properties and child relationships of child objects of $obj are loaded, along with the properties of these child objects' child objects.

Since the database query could potentially return a very large number of results, you can limit the query by providing an optional $rel_type. This is either the integer ID of a relationship type or the package name of a relationship (e.g., "Litigation::Database::Object::ItemOf"). If you supply a $rel_type, only the grandchild objects that are related to child objects with the relationship type $rel_type will be loaded.

$obj->load_all_both_relns( $flags );

Loads object properties, child relationships, and parent relationships from the database. The properties (but not the relationships) of child objects and parent objects are loaded.

Controlling what information is loaded

By default, information about properties and relationships is not loaded unless you call one of the load methods.

For example, to retrieve information about nested objects you normally have to write:

  foreach my $a (@{$obj->get_Items_Of()}){
    $a->{obj}->load_relns();
    foreach my $b (@{$a->{obj}->get_Items_Of()}){
      $b->{obj}->load_relns_backward();
      foreach my $c (@{$b->{obj}->get_Objects_Containing()}){
        print $c->get_t() . " contains " . $b->{obj}->get_t() . "\n";
      }
    }
  }

However, there is a global setting that causes Litigation::Database to load relationships automatically. You could have written:

  local $Litigation::Database::Connection::Auto_load = 1;
  foreach my $a (@{$obj->get_Items_Of()}){
    foreach my $b (@{$a->{obj}->get_Items_Of()}){
      foreach my $c (@{$b->{obj}->get_Objects_Containing()}){
        print $c->get_t() . " contains " . $b->{obj}->get_t() . "\n";
      }
    }
  }

This code has the same effect, and is easier to write and read. $Litigation::Database::Connection::Auto_load is set to 0 by default because it imposes slightly higher overhead.

Some relationship types are loaded by a method call instead of a database query. These are called automatic relationships. Since these method calls may be time-consuming, you can turn them off by setting:

  local $Litigation::Database::Connection::Skip_auto = 1;

You can also skip automatic relationships for a particular call by using the SKIP_AUTO flag:

  use Litigation::Database qw(SKIP_AUTO);

  # ...

  $obj->load_relns( SKIP_AUTO );

For more information about automatic relationships, see the auto property of Litigation::Database::Object::LDObject::LDRelationship.

To avoid making unnecessary queries of the database, the load methods will return without querying the database if the information had been loaded earlier. If you believe that information in the database may have changed and you want to load the information again, you can call the appropriate load method with the FORCE flag.

  use Litigation::Database qw(FORCE);

  # ...

  $obj->load_relns();

  $obj->load_relns();        # has no effect because of earlier call

  $obj->load_relns( FORCE ); # queries the database no matter what

If you want all calls to load methods to query the database, you can set $Litigation::Database::Connection::No_reload to 1:

  local $Litigation::Database::Connection::No_reload = 1;

  # ...

  $obj->load_relns();        # queries the database

  $obj->load_relns();        # queries the database

If you want to use more than one flags, combine them with logical "or." For example:

  use Litigation::Database qw(FORCE SKIP_AUTO);
  
  # ...

  $obj->load_all(FORCE | SKIP_AUTO);  

The following methods access the global settings.

$obj->auto_load()

Returns true when the global setting is to automatically load properties and relationships. Otherwise, returns false.

$obj->no_reload()

Returns true when the global setting is not to reload properties and relationships that have already been loaded. Otherwise, returns false.

$obj->skip_auto()

Returns true when the global setting is to skip the loading of automatic relationships. Otherwise, returns false.

See Litigation::Database::Connection for more information about the global settings.

Retrieving objects and relationships

In most cases, you can retrieve objects using "Relationship methods".

$obj->get_objects_of_reltype( $rel_type_id, $direction );

Returns a reference to an array of relationship-object references. These relationship-object references are

$obj->get_object_by_id( $id );

Returns the object with ID $id from the database associated with $obj. If the object has already been loaded, it returns the object from the Litigation::Database::Connection object cache.

$obj->get_relationship_by_id( $id );

Returns the relationship with ID $id from the database associated with $obj. If the relationship has already been loaded, it returns the relationship from the Litigation::Database::Connection relationship cache.

$obj->get_top_object();

Returns the user's default top object ("Home Node"), or if that is not defined, returns the result of get_system_top_object. See Litigation::Database::LDUser.

$obj->get_work_object();

Returns the user's default workplace object ("Work Node"), or if that is not defined, returns the result of get_system_work_object. See Litigation::Database::LDUser.

If you need to create an object for the user, and you do not want the garbage collector to clean it up, this is a good place to put it when you have no other place to put it.

$obj->get_system_top_object();

Returns the database's default top object.

$obj->get_system_work_object();

Returns the database's default workplace object.

If you need to create an object in the system, and you do not want the garbage collector to clean it up, this is a good place to put it when you have no other place to put it.

Caching of objects and relationships

All objects and relationships that are ever loaded are cached within your Litigation::Database::Connection object. This means that when you retrieve an object or relationship from the database by calling a relationship method, or methods like get_object_by_id and get_relationship_by_id, you may receive a reference to an object that already exists in memory. For example:

  my $obj_one = $database->get_object_by_id( 1402 );
  print "1st object is called "     . $obj_one->get_t() . "\n";
  $obj_one->set_t("Orange");
  print "1st object is renamed "    . $obj_one->get_t() . "\n";
  print "Retrieving 2nd object"                         . "\n";
  my $obj_two = $database->get_object_by_id( 1402 );
  print "2nd object is called "     . $obj_two->get_t() . "\n";
  print "Reloading 2nd object"                          . "\n";
  $obj_two->load( FORCE );
  print "1st object is now called " . $obj_two->get_t() . "\n";
  print "2nd object is now called " . $obj_two->get_t() . "\n";
  print "1st object is "            . scalar($obj_one)  . "\n";
  print "2nd object is "            . scalar($obj_two)  . "\n";

This code produces the following output (or something like it):

  1st object is called Apple
  1st object is renamed Orange 
  Retrieving 2nd object
  2nd object is called Orange
  Reloading 2nd object from database
  1st object is now called Apple
  2nd object is now called Apple
  1st object is Litigation::Database::Object=SCALAR(0x3069900)
  2nd object is Litigation::Database::Object=SCALAR(0x3069900)

Calling get_object_by_id( 1402 ), or any other method that retrieves object number 1402, returns the same object -- not just a copy of the same information, but literally the same object in memory.

This is convenient in many ways, but it is also something that could cause unexpected behavior. For example, if you make changes to an object's properties and do not save them, those changes could be wiped out by a load operation that you thought would have no effect on your object.

$obj->get_object_from_cache( $id );

Returns an object from the cache by its integer ID $id.

$obj->get_relationship_from_cache( $rel_id );

Returns a relationship from the cache by its integer ID $rel_id.

See Litigation::Database::Connection for methods that operate on the object and relationship cache.

Methods that act on the database connection

Some methods do not directly affect $obj, but change settings for the session. They act on the Litigation::Database::Connection underlying the object ($obj->get_db()).

$obj->get_default_perms()
$obj->set_default_perms( $perms )
$obj->get_default_group()
$obj->set_default_group( $group_id )

Returns/sets the default security information that will be used for any new objects added to the underlying database.

The default permissions flags set with set_default_perms will be used for objects that do not have built-in "Default Permissions." See the defaultPerms property of Litigation::Database::Object::LDObject and Litigation::Database::Includes::default_permissions_for().

Web application methods

$obj->update_content_command()

Returns a Javascript command that will cause the web application to reload the properties of the object from the server.

$obj->obj_to_json( $hashref )

Returns a Javascript command that will update the web browser's information about the relationship-object $hashref.

$obj->obj_as_array( $hashref )

Returns the relationship-object $hashref in an array format expected by the web application.

$obj->find_in_family_tree( $package, $args )

In a call from the web browser, the "family tree" of an object is the context in which the user found the object. This function searches up the family tree for the first object it can find of type $package, where $package is a string like "Litigation::Database::Object::List." It returns a hash reference with the following keys:

obj

The object that was found, or undef if no object was found.

rel

The forward relationship to the object that was found, or undef if no object was found or if the object that was found is a root object that has no forward relationship.

local_node

The localId of the LocalNode within the family tree for the object that was found, or undef if no object was found.

$obj->find_self_in_family_tree( $args )

This function looks up the "family tree" until it finds the object $obj. Then it looks through the loaded relationships of $obj for the relationship with an ID that matches the relationship ID associated with the object $obj in the family tree. If it finds the relationship, it returns the relationship-object reference for that relationship. This is a reference to a hash with keys rel, obj, and (if applicable) pobj.

$obj->get_method_name ( $method )

Returns the "Name on Menu" of the method $method as applied to an object of $obj's type. See the menuName property of Litigation::Database::Object::LDMethod.

$obj->queue_method_call_as_job ( $method, ... )

See "Background jobs".

$obj->trigger_daemon()

See "Background jobs".

$obj->trigger( $method, $args, $output_ref )

See "Triggers".

$obj->trigger_up( $args, $output_ref )

See "Triggers".

Writing methods for menu commands

In the web interface, every object has a pull-down menu in the upper-right corner. You can add a command to this menu to run a method that you have written. For example, if you wanted to add a command for a method special_action that acts on a Litigation::Database::Object::Document, you could:

  1. Log in to the Definitions Database as a superuser.
  2. Find the Document object in Core (LD Package) -> Object (LD Object) -> Document (LD Object).
  3. Add a new LD Method called "special_action."
  4. Set the "Source Code" property of "special_action" to the body of the method:
      my ($obj) = @_;
      print STDERR "The special_action method was called on "
        . $obj->get_t() . "\n";
      return("alert('Hello from the web server!');\n");
  5. Set the "Name on Menu" property to "Special Action". This will add a menu item called "Special Action" to all Document objects.
  6. Go to an LD Dashboard object and run "Reread Objects." This may take 30 seconds or more.
  7. A message will pop up telling you to refresh the page. When you refresh the page, the web application will show "Special Action" as a menu item for all Document objects.

    When you write methods that are called in this fashion, there are additional arguments that you can access if necessary:

      ($obj, $argref, $local_id, $rel_id, $direction, $args) = @_;

    The arguments are:

    $obj

    The object on which the method is being called.

    $argref

    This is a variable passed from Javascript through to the method. It can be a reference or a scalar.

    $local_id

    The localId of the LocalNode of the object in the web application. This can be useful when writing output that runs Javascript commands.

    $rel_id

    The integer ID of the relationship associated with the LocalNode.

    $direction

    The direction of the relationship associated with the LocalNode. Forward (parent to child) is 1 and backward (child to parent) is 0.

    $args

    A reference to a hash containing all of the variables passed from the web application to the server, including family_tree.

The family tree array

When the web application sends a command to Litigation::Database::RequestHandler and the command relates to a specific Litigation::Database::Object, the web application supplies the context of the object as the user found it. This context is known as the "family tree" because it starts with the object itself and goes all the way up to the window's "home" object, covering every object that the user clicked on in order to find the object.

For example, suppose the user logged in and was presented with a window in which the initial object, at the top of the window, was called "Important things." Then the user clicked one of that object's items called "Essential documents," and within that object, the user clicked "Lease." Then the user used the pull-down menu to run a command on the "lease" object. When the web browser communicates this command to the web server, it gives the web server the following information, among other things:

  1. The name of the command to run;
  2. The object ID of the "lease" object; and
  3. The context in which the user is looking at the "lease" object, namely that the user found it within "Essential Documents," which was within "Important Things." This context is called the "family tree."

The "family tree" is a reference to an array. Each member of the array is itself a reference to an array whose elements are:

  ( $obj_id, $rel_id, $direction, $obj_type, $rel_type, $local_id )

The meaning of these variables is as follows:

$obj_id

The integer ID of the object.

$rel_id

The integer ID of the relationship that the user followed to get to the object.

$direction

The direction of the relationship that the user followed to get to the object. The $direction is 1 for the parent-to-child direction and 0 for the child-to-parent direction. (In the web application, users can follow child-to-parent relationships in the same way that they can follow parent-to-child relationships.)

$obj_type

The integer ID of the object's type.

$rel_type

The integer ID of the relationship's type.

$local_id

The localId of the LocalNode for the object within the web application.

The elements of the family_tree are ordered starting with the object that is the subject of the command and ending with the "home" object of the user's window.

Triggers

For some object types, you may want certain things to happen every time an object's property or relationship is changed. For example, you may want object properties to be filled in with default values if the user creates a new object. You may want a validation function to run to prevent the user from entering improper data. You may want an object's name to be automatically set based on the object's properties or relationships.

These purposes can be accomplished with trigger methods.

( $found, $output ) = $obj->trigger( $method, $args, $output_ref )

Attempts to run the method $method (a string with the name of the method) on $obj, passing $args as an argument. If the method is defined for the object type, $found is set to 1 and $output is set to the return value of the method. If the method is not defined, $found is set to 0 and $output is set to the empty string.

The $args argument must be a reference to a hash. This hash can be used to pass arguments to $method.

If the optional $output_ref argument is supplied, the $output, if any, is concatenated onto the scalar referred to by $output_ref. ($output_ref must be a reference to a scalar.)

( $found, $output ) = $obj->trigger_up( $args, $output_ref )

This is primarily a web application method for making changes to an object when its relationships change, or when objects it relates to change. It goes up the object's "family tree" (the specific hierarchy in which the object was found) starting with the parent, and attempts to call the "on_local_child_change" method on the parent object, passing $args as an argument. If a relationship object exists for the parent object's relationship with its child object, it calls "on_local_child_change" on the relationship object, passing $args as an argument. If the "on_local_child_change" method exists for either of these object types, then trigger_up goes to the next generation in the "family tree" and repeats the same process. Otherwise, it stops.

The $args argument must be a reference to a hash. This hash can be used to pass arguments to the "on_local_child_change". The only required key is family_tree, the format of which is specified above.

The return values of the "on_local_child_change" calls are concatenated together into $output. If the optional $output_ref argument is supplied, the $output, if any, is concatenated onto the scalar referred to by $output_ref. ($output_ref must be a reference to a scalar.)

( $found, $output ) = $rel->trigger( $method, $args, $output_ref )
( $found, $output ) = $rel->trigger_up( $args, $output_ref )

Triggers work on relationships in a similar way, except that they act on the relationship object associated with the relationship $rel, not on $rel itself. ($rel is always a Litigation::Database::Relationship, so you cannot write methods for it.)

Thus, if you want to write a method that is triggered by changes to a relationship, you need to write the method in the namespace of the relationship object. For example, if you want a method to be triggered when a Litigation::Database::Object::ItemOf relationship is unlinked, you would write the method in the Litigation::Database::Object::ItemOf namespace.

If the relationship object does not exist, a dummy relationship object is created in memory and the method is called on that object. If the job of your method is to create an actual relationship object for the relationship, the method can call make_actual on the relationship object. See Litigation::Database::Object::Relationship for other methods you may wish to use when writing relationship triggers.

Writing trigger methods

Methods called from a trigger should expect just two arguments, the object itself $obj and a reference to a hash $args containing information from the web browser, such as the $args->{family_tree}. For example:

  sub on_save {
    my ($obj, $args) = @_;
    # Do something
  }

Background jobs

$obj->queue_method_call_as_job ( $method, ... )
$obj->trigger_daemon()

Sends a message to ld-daemon(8) to look for new jobs in the job queue of the database associated with $obj. See "Background jobs".

Low-level methods

You will probably not need to use these methods, but they are available if you need them.

$new_obj = $obj->transform_into( $package );

Returns a new object of type $package with the properties of $obj.

$obj->get_id()

Returns the integer ID of the object. If $obj is not associated with a database, an error will result.

$obj->type_id()

Returns the integer ID of the object type.

$obj->get_node()
$obj->set_node()

Returns/sets the Litigation::Database::Node underlying the object $obj. The Litigation::Database::Node is a low-level object within the Litigation::Database system, so you should not need to access it.

$obj->save_node()

Saves the Litigation::Database::Node underlying the object $obj.