NAME

$full_module_name - Methods for processing data from the GeneX DB $LINKING table: $module_name

SYNOPSIS

  use $full_module_name;

EOT if ($IS_LINKING_TABLE) { print OUT <<"EOT"; # instantiating a linking table instance my \$$module_name = $full_module_name->new(id=>47,pkey_link=>'$LINK1_FKEY_NAME'); # or my \$$module_name = $full_module_name->new(id=>47,pkey_link=>'$LINK2_FKEY_NAME'); EOT } else { print OUT <<"EOT"; # instantiating an instance my \$$module_name = $full_module_name->new(id=>47); EOT } print OUT <<"EOT";

  # retrieve data from the DB for all columns
  \$$module_name->fetch();

EOT if ($IS_LINKING_TABLE) { print OUT <<"EOT"; # creating an instance, without pre-fetching all columns my \$$module_name = new $full_module_name(id=>47, 'pkey_link'=>'$attributes[0]');

  # creating an instance with pre-fetched data
  my \$$module_name = new $full_module_name(id=>47, 
                                            'fetch_all'=>1,
                                            'pkey_link'=>'$attributes[0]');

  # retrieving multiple instances via primary keys
  my \@objects = $full_module_name->get_objects('pkey_link'=>'$attributes[0]',
                                                  23,57,98);

EOT } else { print OUT <<"EOT"; # creating an instance, without pre-fetching all columns my \$$module_name = new $full_module_name(id=>47);

  # creating an instance with pre-fetched data
  my \$$module_name = new $full_module_name(id=>47, 'fetch_all'=>1);

  # retrieving multiple instances via primary keys
  my \@objects = $full_module_name->get_objects(23,57,98)

EOT } print OUT <<"EOT";

  # retrieving all instances from a table
  my \@objects = $full_module_name->get_all_objects();

  # retrieving the primary key for an object, generically
  my \$primary_key = \$$module_name->id();

EOT if ($IS_LINKING_TABLE) { print OUT " \# retrieving other DB column attributes\n"; foreach (map {$_->fkey_name} @link_fkeys) { print OUT " my \$${_}_val = \$$module_name->$_();\n"; print OUT " \$$module_name->$_(\$value);\n\n"; } } else { print OUT " # or specifically\n"; print OUT " my \$${PKEY}_val = \$$module_name->$PKEY();\n\n"; print OUT " \# retreving other DB column attributes\n"; }

foreach (@non_pkey_attributes) { print OUT " my \$$_", "_val = \$$module_name->$_();\n"; print OUT " \$$module_name->$_(\$value);\n\n"; }

print OUT <<"EOT";

DESCRIPTION

Each Genex class has a one to one correspondence with a GeneX DB table of the same name (i.e. the corresponding table for $full_module_name is $module_name).

EOT if ($IS_LINKING_TABLE) { # start a section with variable expansion *enabled* print OUT <<"EOT";

NOTE: Class $full_module_name is linking table class. This means that it represents a table in the Genex DB which has no primary key. Instead, there are two foreign keys that can be used to lookup a value from the database. In $full_module_name, those two columns are '$attributes[0]' and '$attributes[0]'. When an instance of $full_module_name is instantiated, either via new() or get_objects(\@id_list), the 'pkey_link' parameter must be specified as one of these two values, otherwise, an error will result.

EOT }

# start a section with variable expansion *enabled* print OUT <<"EOT";

Most applications will first create an instance of $full_module_name and then fetch the data for the object from the DB by invoking fetch(). However, in cases where you may only be accessing a single value from an object the built-in delayed fetch mechanism can be used. All objects are created without pre-fetching any data from the DB. Whenever an attribute of the object is accessed via a getter method, the data for that attribute will be fetched from the DB if it has not already been. Delayed fetching happens transparently without the user needing to enable or disable any features.

Since data is not be fetched from the DB until it is accessed by the calling application, it could presumably save a lot of access time for large complicated objects when only a few attribute values are needed.

ATTRIBUTES

There are three different types of attributes which instances of $full_module_name can access: raw foreign key attributes, Obect-Oriented foreign key attributes, and simple column attributes.

Raw Foreign Keys Attributes

Object Oriented Foreign Key Attributes

This mode presents foreign key attributes in a special way, with all non-foreign key attributes presented normally. Foreign keys are first retrieved from the DB, and then objects of the appropriate classes are created and stored in slots. This mode is useful for applications that want to process information from the DB because it automates looking up information.

Specifying the 'recursive_fetch' parameter when calling new(), modifies the behavior of this mode. The value given specifies the number of levels deep that fetch will be invoked on sub-objects created.

Simple Column Attributes

CLASS VARIABLES

Class $full_module_name defines the following utility variables for assisting programmers to access the $module_name table.

\$$ {full_module_name}::LIMIT

If defined, \$LIMIT will set a limit on any select statements that can return multiple instances of this class (for example get_objects() or any call to a ONE_TO_MANY or LOOKUP_TABLE foreign key accessor method).

\$$ {full_module_name}::USE_CACHE

This variable controls whether the class will cache any objects created in calls to new(). Objects are cached by primary key. The caching is very simple, and no effort is made to track whether different invocations of new() are being made for an object with the same primary key value, but with different options set. If you desire to reinstantiate an object with a different set of parameters, you would need to undefine \$USE_CACHE first.

WARNING: variables other than those listed here are for internal use only and are subject to change without notice. Use them at your own risk.

DELAYED FETCH

It is possible to retrieve only the subset of attributes one chooses by simply creating an object instance and then calling the appropriate getter function. The object will automatically fetch the value from the DB when requested. This can potentially save time for large complicated objects. This triggers a separate DB query for each attribute that is accessed, whereas calling fetch() will retrieve all fields of the object with a single query.

For example:

  my \$$module_name = $full_module_name->new(id=>47);
  my \$val = \$$module_name->$attributes[0]();

The attribute\'s value is then cached in the object so any further calls to that attribute\'s getter method do not trigger a DB query.

NOTE: Methods may still return undef if their value in the DB is NULL.

CLASS METHODS

The following methods can all be called without first having an instance of the class via the $full_module_name->methodname() syntax.

new(%args)

new() accepts the following arguments:

id

Numeric or string value. The value of the primary key for looking up the object in the DB.

EOT

if ($IS_LINKING_TABLE) { # start a section with variable expansion *enabled* print OUT <<"EOT";

pkey_link

For linking tables this specifies which of the two possible values should be used as the primary key to fetch an instance from the DB. For class $full_module_name, 'pkey_link' can be either '$LINK1_FKEY_NAME' or '$LINK2_FKEY_NAME'.

table2pkey()

For linking table classes, this method returns a hash table (not a hashref) that defines the fkey access map. Linking tables have no class-wide primary key, instead the column which is used to fetch rows from the DB is determined on a per-instance basis depending on which of the two linked-to tables is accessing the data. For example, in $full_module_name if a method in class $TABLE2PKEY_KEY invokes its foreign key accessor function, the column '$TABLE2PKEY_VALUE' will be used to fetch values from the DB.

linking_table()

Used by generic functions to determine if a specified class is a linking table class. For $full_module_name it returns 1, since it is a linking table class.

EOT

# # pkey_name() is an instance method of linking table classes #

} else { # start a section with variable expansion *enabled* print OUT <<"EOT"; =back

linking_table()

Used by generic functions to determine if a specified class is a linking table class. For $full_module_name it returns 0, since it is not a linking table class.

pkey_name()

This method returns the name of the column which is used as the primary key for this DB table. This method only exists for non-linking table classes, and for $full_module_name it returns the value '$PKEY';

EOT

}

# start a section with variable expansion *enabled* print OUT <<"EOT";

table_name()

Returns the name of the DB table represented by this class. For $full_module_name it returns '$module_name';

column2name()

This method returns a hashref that translates DB column names into human readable format.

name2column()

This method returns a hashref that is a reverse lookup table to translate the human readable version of a DB column name back into the column_name. This is useful for preparing table output in CGI scripts:

EOT # start a section with *no* variable expansion print OUT <<'EOT';

    %column2name = %{$class->column2name()};
    if (exists $column2name{$_}) {
      push(@column_copy,$column2name{$_});
    }
    
    # now that we've translated the names, we sort them
    @column_copy = sort @column_copy;
    
    # make a header element. 
    push(@rows,th(\@column_copy));

EOT # start a section with variable expansion *enabled* print OUT <<"EOT";

fkeys()

This method returns a hashref that holds all the foreign key entries for the $module_name table.

column_names()

This method returns an array ref which holds the names of all the columns in table $module_name.

EOT # start a section with *no* variable expansion print OUT <<'EOT';

    # first retrieve the data from the DB
    $object = $full_module_name->new(id=>$id);
    $object->fetch();

    # now extract the data from the object
    foreach (@{$class->column_names}) {
    # we use this to temporarily relax the strict pragma
    # to use symbolic references
      no strict 'refs';
      $tmp_values{$_} = $object->$_;

    # back to our regularily scheduled strictness
    }

EOT if ($HAS_LT_FKEY) { # start a section with *no* variable expansion print OUT <<'EOT';

get_matrix($id)

get_matrix([$col_name=>[@allowed_list], [$other_col=>[@list]]])

For efficiency reasons, lookup table classes, like $full_module_name need to be able to return their data in a matrix of values, and not a list of objects.

The simple form is called with a single parameter, $id, that specifies the the value of the LOOKUP_TABLE foreign key to use in DB query.

The more complex interface allows a user to restrict the values returned by $column_names and a @list of allowed values that that column may have. Multiple $column_name/@list pairs may be specified and the restrictions will all be AND\'ed together in the SQL WHERE clause.

EOT }

if ($IS_LINKING_TABLE) { # start a section with variable expansion *enabled* print OUT <<"EOT";

get_objects({pkey_link=>'$attributes[0]'}, \@id_list)

get_all_objects()

get_objects({column=>'col_name',value=>'val'})

This method is used to retrieve multiple instances of class $full_module_name simultaneously. For linking tables, there are three different ways to invoke this method.

By passing in an \@id_list, get_objects() uses each element of the list as a primary key for the $module_name table and returns a single instance for each entry. This form of the method requires a hash reference as the first argument. The hash must have the 'pkey_link' key defined.

WARNING: Passing incorrect id values to get_objects() will cause a warning from $ {full_module_name}::initialize(). Objects will be created for other correct id values in the list.

ERROR: When using the \@id_list form of this method with a linking table, the 'pkey_list' attribute must be specified, otherwise an error will result. This is because linking tables have two possible columns to lookup from.

By passing a hash reference that contains the 'column' and 'name' keys, the method will return all objects from the DB whose that have the specified value in the specified column.

NOTE: When passing a hash reference with the 'column' and 'value' keys specified, it is not necessary to specify the 'pkey_link' attribute.

EOT

} else { # start a section with variable expansion *enabled* print OUT <<"EOT";

insert_db(\$dbh)

This method inserts the data for the object into the database specified by the DB handle \$dbh. To use this method, create a blank object with new(), set the attributes that you want, and then call insert_db().

  my \$dbh = Bio::Genex::current_connection(USER=>\$SU_USERNAME,
                                      PASSWORD=>\$SU_PASSWORD);
  my $module_name = $full_module_name->new();
  $module_name->$attributes[1]('some_value');
  $module_name->insert_db(\$dbh);

NOTE: You must log into the DB with a user/password that has INSERT priveleges in the DB, otherwise you will get a DBI error.

WARNING: fetch() will not be called, so if you are using this method to insert a copy of an existing DB object, then it is up to you to call fetch(), otherwise, only the attributes that are currently set in the object will be inserted.

update_db(\$dbh)

This method update the data for an object already in the database specified by the DB handle \$dbh. To use this method, fetch an object from the DB, change the attributes that you want, and then call update_db().

  my \$dbh = Bio::Genex::current_connection(USER=>\$SU_USERNAME,
                                      PASSWORD=>\$SU_PASSWORD);
  my $module_name = $full_module_name->new(id=>43);
  $module_name->$attributes[1]('some_value');
  $module_name->update_db(\$dbh);

NOTE: You must log into the DB with a user/password that has INSERT priveleges in the DB, otherwise you will get a DBI error.

NOTE: Any modification of the primary key value will be discarded ('$attributes[0]' for module $full_module_name).

get_objects(\@id_list)

get_all_objects()

get_objects({column=>'col_name',value=>'val'})

This method is used to retrieve multiple instances of class $full_module_name simultaneously. There are three different ways to invoke this method.

By passing in an \@id_list, get_objects() uses each element of the list as a primary key for the $module_name table and returns a single instance for each entry.

WARNING: Passing incorrect id values to get_objects() will cause a warning from $ {full_module_name}::initialize(). Objects will be created for other correct id values in the list.

get_all_objects() returns an instance for every entry in the table.

By passing an anonymous hash reference that contains the 'column' and 'name' keys, the method will return all objects from the DB whose that have the specified value in the specified column.

EOT

} # start a section with variable expansion *enabled* print OUT <<"EOT";

NOTE: All objects must have the 'id' parameter set before attempting to use fetch() or any of the objects getter functions.

INSTANCE METHODS

The following methods can only be called by first having valid instance of class $full_module_name.

fetch()

This method triggers a DB query to retrieve ALL columns from the DB associated with this object.

EOT

# start a section with *no* variable expansion print OUT <<'EOT';

WARNING: methods other than those listed here are for internal use only and are subject to change without notice. Use them at your own risk.

EOT

if ($HAS_FOREIGN_KEYS) { # start a section with variable expansion *enabled* print OUT <<"EOT";

FOREIGN KEY ACCESSOR METHODS

There are two major categories of foreign key accessor methods: Object Oriented foreign key methods, and raw foreign key methods.

Each foreign key column in the table is represented by two methods, one OO method and one raw method. The raw method enables fethcing the exact numeric or string values stored in the DB. The OO method creates objects of the class the fkey column refers to. The idea is that if only the numeric fkey value is desired, the raw fkey method can be used. If it is necessary to get attributes from the table referred to by the fkey column, then the OO method should be invoked, and the necessary methods on that object can be queried.

The names of the raw fkey methods is the same as the fkey columns in the DB table they represent (all fkey columns end in the suffix '_fk'). The OO methods have the same names as the column they represent, with the difference that they have the suffix '_obj' instead of '_fk'.

So for example, in class Bio::Genex::ArrayMeasurement the 'primary_es_fk' column is represented by two methods, the raw method primary_es_fk(), and the OO method primary_es_obj.

The following foreign key accessors are defined for class $full_module_name:

EOT

  foreach my $fkey (@FKEY_LIST) {
    next if $fkey->fkey_name() =~ /_obj$/;
    my $fkey_name = $fkey->fkey_name();
    my $oo_fkey_name = $fkey->fkey_name();
    $oo_fkey_name =~ s/_fk$/_obj/;
    my $fkey_type = $fkey->fkey_type();
    my $table_name = $fkey->table_name();
    my $class = "Bio::Genex::$table_name";

    if ($fkey_type eq FKEY_OTM ||
        $fkey_type eq FKEY_OTM_LINK ||
        $fkey_type eq FKEY_OTM_LT
       ) {
      # start a section with variable expansion *enabled*
      print OUT <<"EOT";

\@id_list = $fkey_name()

\@obj_list = $oo_fkey_name()

This is an attribute of type $fkey_type and refers to class $class. The raw accessor method, $fkey_name() returns a list of foreign key ids. The OO accessor method, $oo_fkey_name() returns a list of objects of class $class.

EOT } else { # start a section with variable expansion *enabled* print OUT <<"EOT";

\$id = $fkey_name()

\$obj = $oo_fkey_name()

This is an attribute of type $fkey_type and refers to class $full_module_name. The raw accessor method, $fkey_name() returns a single foreign key id. The OO accessor method, $oo_fkey_name() returns a single object of class $class.

EOT } }

  # start a section with *no* variable expansion
  print OUT <<'EOT';

Every foreign key in a DB table belongs to a certain class of foreign keys. Each type of foreign key confers a different behavior on the class that contains it. The classifications used in Genex.pm are:

• MANY_TO_ONE

  If a class contains a foreign key of this type it will not be visible to the API of that class, but instead it confers a special method to the class that it references.

  For example, the Chromosome table has a MANY_TO_ONE foreign key, spc_fk, that refers to the species table. Class Bio::Genex::Chromosome, has it\'s normal spc_fk() attribute method, but no special foreign key accessor method. However, class Bio::Genex::Species is given a special foreign key accessor method, chromosome_fk() of type ONE_TO_MANY. When invoked, this method returns a list of objects of class Bio::Genex::Species.

• ONE_TO_MANY

  The inverse of type MANY_TO_ONE. It is not an attribute inherent to a given foreign key in any DB table, but instead is created by the existence of a MANY_TO_ONE foreign key in another table. See the above discussion about MANY_TO_ONE foreign keys.

• LOOKUP_TABLE

  This type of key is similar to type ONE_TO_MANY. However, However the API will never retrieve an object of this type. Instead it retrieves a matrix of values, that represent the list of objects. It is used in only two places in the API: Bio::Genex::ArrayMeasurement and Bio::Genex::ArrayLayout classes with the am_spots() and al_spots() accessor functions.

• LINKING_TABLE

  Foreign keys of this type appear in tables without primary keys. The foreign keys are each of type LINKING_TABLE, and when invoked return an object of the class referred to by the foreign key.

• FKEY

  A generic foreign key with no special properties. When invoked it returns an object of the class referred to by the foreign key.

EOT

}

# start a section with variable expansion *enabled* print OUT <<"EOT";

ATTRIBUTE METHODS

These are the setter and getter methods for attributes in class $full_module_name.

NOTE: To use the getter methods, you may either invoke the fetch() method to retrieve all the values for an object, or else rely on delayed fetching to retrieve the attributes as needed.

EOT if ($IS_LINKING_TABLE) { print OUT <<"EOT";

id()

id() is a special attribute method that is common to all the Genex classes. This method returns the primary key of the given instance. Class $full_module_name is a linking table and therefore it can two possible columns that represent the 'id' ('$LINK1_FKEY_NAME' and '$LINK2_FKEY_NAME'). When an instance of class $full_module_name is created using either new() or get_objects(\@id_list) the 'pkey_link' attribute must specified as one of the two possible values.

The id() method can be useful in writing generic methods because it avoids having to know the name of the primary key column.

$attributes[0]()

$attributes[0](\$value)

Methods for the $attributes[0] attribute. This attribute is the first possible value for the 'pkey_link' attribute at object creation time.

$attributes[1]()

$attributes[1](\$value)

Methods for the $attributes[1] attribute. This attribute is the second possible value for the 'pkey_link' attribute at object creation time.

EOT

} else { print OUT <<"EOT";

id()

id() is a special attribute method that is common to all the Genex classes. This method returns the primary key of the given instance (and for class $full_module_name it is synonomous with the $attributes[0]()method). The id() method can be useful in writing generic methods because it avoids having to know the name of the primary key column.

$attributes[0]()

This is the primary key attribute for $full_module_name. It has no setter method.

EOT

} foreach (@non_pkey_attributes) { # start a section with variable expansion *enabled* print OUT <<"EOT";

\$value = $_();

$_(\$value);

Methods for the $_ attribute.

EOT

}

# start a section with variable expansion *enabled* print OUT <<"EOT";

WARNING: methods other than those listed here are for internal use only and are subject to change without notice. Use them at your own risk.

IMPLEMENTATION DETAILS

These classes are automatically generated by the create_genex_classes.pl script. Each class is a subclass of the Class::ObjectTemplate::DB class (which is in turn a subclass of Class::ObjectTemplate written by Sriram Srinivasan, described in Advanced Perl Programming, and modified by Jason Stewart). ObjectTemplate implements automatic class creation in perl (there exist other options such as Class::Struct and Class::MethodMaker by Damian Conway) via an attributes() method call at class creation time.

BUGS

Please send bug reports to genex\@ncgr.org

LAST UPDATED

on $time by $0 $arguments

AUTHOR

Jason E. Stewart (jes\@ncgr.org)

SEE ALSO

perl(1).

cpanm Bio::Genex::Fkey

perl -MCPAN -e shell
install Bio::Genex::Fkey