The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Class-ReluctantORM-0.52_0
River stage zero No dependents
++
/ Class::ReluctantORM::Relationship

NAME

Class::ReluctantORM::Relationship - Represent links between classes

SYNOPSIS

  # Add relationships to a Class::ReluctantORM Class
  Pirate->has_one(...); # See Class::ReluctantORM::Relationship::HasOne
  Pirate->has_many(...); # See Class::ReluctantORM::Relationship::HasMany
  Pirate->has_many_many(...); # See Class::ReluctantORM::Relationship::HasManyMany
  Pirate->has_lazy(...); # See Class::ReluctantORM::Relationship::HasLazy

  # Get relationships from a defined Class::ReluctantORM Class
  $rel = Pirate->relationships('method_name');
  $rels_by_name_href = Pirate->relationships();
  @all_rels     = Pirate->relationships();

  # Get information from a relationship
  $str = $rel->type();                 # 'has_one'
  $str = $rel->linked_class();         # 'Ship'
  $str = $rel->linking_class();        # 'Pirate'
  $str = $rel->method_name();          # 'ship'
  $str = $rel->name();                 # 'ship' (alias for method_name)
  $int = $rel->lower_multiplicity()    # 0 for optionals, 1 for required
  $int = $rel->upper_multiplicity()    # 1 for one/lazy, undef for many/many-many

  # If Ship->has_many(Pirate), you'll get the opposite relation here
  # There's no requirement that relationships be invertable, so this is often undef
  $invrel = $rel->inverse_relationship();

  @fields = $rel->local_key_fields();  # fields in Pirate that link to Ship
  @fields = $rel->remote_key_fields(); # array of fields in Ship that link to Pirate
  $int = $rel->join_depth();           # 0, 1, or 2

  # SQL Support
  $tbl = $rel->local_sql_table();
  $tbl = $rel->remote_sql_table();
  $tbl = $rel->join_sql_table();
  @cols = $rel->local_key_sql_columns();
  @cols = $rel->remote_key_sql_columns();
  @cols = $rel->join_local_key_sql_columns();
  @cols = $rel->join_remote_key_sql_columns();
  @cols = $rel->additional_output_sql_columns();

DESCRIPTION

Represents a relationship between two Class::ReluctantORM classes.

TB Classes have instances of Relationships as class data. An instance of a Relationship does not contain data pertaining to a particular TB object; for that, see Collection.

INITIALIZATION

$rel_class->_initialize();

The relationship class should do any one-time setup, like registering methods with Class::ReluctantORM. Note that this is per-relationship-class initialization, not per relationship initialization.

The default implementation does nothing.

DELAYED LOADING FACILITY

Because Class::ReluctantORM classes are naturally interdependent, it's unlikely that a relationship will always be able to complete its setup, because the remote end may not be loaded yet. The Relationship base class provides a facility for the delayed execution of setup code.

Class::ReluctantORM::Relationship->notify_class_available($tb_class);

Notifies the delayed-loading subsystem that a Class::ReluctantORM class has become available. At this point, any relationships that were waiting on this class will finish their setup.

You should not override this method.

$rel_class->delay_until_class_is_available($tb_class, $coderef);

Registers a coderef to be executed later when the given Class::ReluctantORM class is loaded.

If the requested class has already been loaded, the code is executed immediately.

ATTRIBUTES OF RELATIONSHIPS

$str = $rel->type();

Returns the type of the relationship - 'has_one', 'has_many', etc.

$method_name = RelationshipClass->_setup_method_name();

Returns the name of a method you can call to set up a relationship. Default implementation is to just return the string returned by type().

$hashref = $rel->_original_args_hashref;

Returns a hashref of (possibly scrubbed) arguments passed to the setup method to initiate the relationship. You should set this value whenever a new relationship is created. This is used by CRO->clone_relationship().

$str = $rel->method_name();

$str = $rel->name();

The method that this relationship will add to the linking class (eg, $pirate->ship()). As this is unique on the class, this is also used as the name of the relationship.

$str = $rel->linking_class();

The class that initiated the relationship. This is the "parent" class.

$str = $rel->linked_class();

The string name of the class on the far end of the connection. The "child" class. For HasLazy, this may not be a Class::ReluctantORM subclass; it may even just be SCALAR.

$str = $rel->linking_class();

The class that initiated the relationship. This is the "parent" class.

$int = $rel->join_depth();

Count of how many joins are required by this relationship in a SQL query. May range from 0 (lazy) to 2 (has_many_many).

$int = $rel->lower_multiplicity()

Returns the lower bound on the multiplicty of the remote end relationship (ie, the "0" in "one to 0 or 1", or the "1" in "one to 1 or more").

$int = $rel->upper_multiplicity()

Returns the upper bound on the multiplicty of the remote end of the relationship (ie, the "1" in "one to 0 or 1", or the "more" in "one to 1 or more").

undef is used to represent "no limit".

$invrel = $rel->inverse_relationship();

Returns the inverse Relationship, if any. If you have defined Pirate->has_one(Ship) and Ship->has_many(Pirate), then you can use this method to obtain the inverse relationship. Note that you must manually make relationships bidirectional.

Inverse relationships are available by default whenever you have defined exactly one set of bidirectional relations between two classes. If you have multiple relations between classes, you can use the 'inverse' option to the relationship setup method to specifiy one.

See Class::ReluctantORM::Manual::Relationships for more details.

@fields = $rel->local_key_fields();

Returns an array of the field names used on the linking (local) end of the relationship.

@column_names = $rel->local_key_columns();

Returns an array of the column names used on the linking (local) end of the relationship.

@column_names = $rel->rmeote_key_columns();

Returns an array of the column names used on the remote (linked) end of the relationship.

@fields = $rel->remote_key_fields();

Returns an array of the field names used on the remote (linked) end of the relationship.

SQL SUPPORT

These functions provide support for the abstract SQL query representation system.

$int = $rel->join_depth();

Returns the number of join steps needed to perform a fetch deep inbolving this relationship. Will return 0 (for Lazy relationships), 1 (for has_one and has_many) or 2 (for has_many_many).

$tbl = $rel->local_sql_table();

Returns a Class::ReluctantORM::SQL::Table object representing the local table.

This is always available.

$tbl = $rel->remote_sql_table();

Returns a Class::ReluctantORM::SQL::Table object representing the table of the linked class.

This is only available if join_depth is 1 or greater.

$tbl = $rel->join_sql_table();

Returns a Class::ReluctantORM::SQL::Table object representing the join table.

This is only available if join_depth is 2.

The default implementation always returns undef.

$type = $rel->join_type();

Returns the join type for the (first) join required by this relationship, if any.

Default returns 'NONE'.

@cols = $rel->local_key_sql_columns();

Returns a list of Class::ReluctantORM::SQL::Columns involved in the relationship on the local table.

Always available.

@cols = $rel->remote_key_sql_columns();

Returns a list of Class::ReluctantORM::SQL::Columns involved in the relationship on the remote table.

Available if join_depth is greater than 1. If join depth is 2, refers to the farthest columns.

If not available, returns an empty list.

@cols = $rel->join_local_key_sql_columns();

Returns a list of Class::ReluctantORM::SQL::Columns involved in the relationship on the join table for the linking class.

Available if join depth is 2.

If not available, returns an empty list.

The default implementation returns an empty list.

@cols = $rel->join_remote_key_sql_columns();

Returns a list of Class::ReluctantORM::SQL::Columns involved in the relationship on the join table for the linked class.

Available if join depth is 2.

If not available, returns an empty list.

The default implementation returns an empty list.

@cols = $rel->additional_output_sql_columns();

Returns a list of columns that should also be selected when fetching items that make up this relationship.

Default implementation is to return nothing.

$int = $rel->matches_join_criterion($crit);

Given a SQL Criterion, returns an integer indicating which, if any, of the join levels the criterion could be used to represent. This is used to support SQL annotation.

The return value will be between 0 and $rel->join_depth(), inclusive. If there is no match, the return value will be 0.