Code Generation

  1: my %config = (
  2:   book => {
  3:     class => 'My::Book', ...
  4:   },
  5:   publisher => {
  6:     class => 'My::Publisher', ...
  7:   },
  8:   user => {
  9:     class => 'My::User', ...
 10:   },
 11: );
 12: SPOPS::Initialize->process({ config => \%config });

You can always get the alias for a class by querying its configuration:

  1: SPOPS::Initialize->process({ config => \%config });
  2: my $book_alias = My::Book->CONFIG->{main_alias};
  3: my $pub_alias  = My::Publisher->CONFIG->{main_alias};
  4: my $user_alias = My::User->CONFIG->{main_alias};

Configuration

  1: # Given:
  2: 'contained' => {
  3:    class => 'My::ContainedClass',
  4:    id    => 'contained_id',
  5: }
  6: 
  7: # Basic usage
  8:    has_a => { class-name => 'id-field' },
  9:    has_a => { My::ContainedClass => 'contained_id' }
 10:    -- Creates method 'contained'
 11: 
 12: # Other ID field name
 13:    has_a => { class-name => 'id-field' },
 14:    has_a => { My::ContainedClass => 'original' }
 15:    -- Creates method 'original_contained'
 16: 
 17: # Multiple ID fields
 18:    has_a => { class-name => [ 'id-field', 'id-field' ] },
 19:    has_a => { My::ContainedClass => [ 'contained_id, 'original' ] }
 20:    -- Creates methods 'contained' and 'original_contained'
 21: 
 22: # Specific method to create and a default 
 23:    has_a => { class-name => { method-name => 'id-field' }, 'id-field' },
 24:    has_a => { My::ContainedClass =>
 25:                     { 'originally_contained_by' => 'original' },
 26:                     'contained_id' },
 27:    -- Creates methods 'originally_contained_by' and 'contained'
 28: 
 29: # Specific method to create and multiple other ID fields
 30:    has_a => { class-name => { method-name => 'id_field'},
 31:                             [ 'id-field', 'id-field' ]    },
 32:    has_a => { My::ContainedClass =>
 33:                     { 'originally_contained_by' => 'original' },
 34:                     [ 'contained_id', 'future' ] }
 35:    -- Creates methods 'originally_contained_by', 'contained' and
 36:       'future_contained'

The Basics

Generally this is defined through an object containing the ID for another object as one of its values. Therefore, to specify the relationship you need:

• the type of object contained (class)
• the ID field(s) defining the object contained

To use the book and publisher example:

  1: 'book' => {
  2:    class           => 'My::Book',
  3:    isa             => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
  4:    id              => 'book_id',
  5:    field_discover  => 'yes',
  6:    base_table      => 'book',
  7:    increment_field => 1,
  8:    no_insert       => [ 'book_id' ],
  9:    no_update       => [ 'book_id' ],
 10:    has_a           => { 'My::Publisher' => 'publisher_id' },
 11: }

  1: 'publisher' => {
  2:    class           => 'My::Publisher',
  3:    isa             => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
  4:    id              => 'publisher_id',
  5:    field_discover  => 'yes',
  6:    base_table      => 'publisher',
  7:    increment_field => 1,
  8:    no_insert       => [ 'publisher_id' ],
  9:    no_update       => [ 'publisher_id' ],
 10: }

So here we map the class we want our book object to contain ("My::Publisher") to the field in the book object which contains the ID of the object.

Once we process this, we can call:

  1: my $book = My::Book->fetch( $book_id );
  2: my $publisher = $book->publisher();

And retrieve the "My::Publisher" object contained in the $book object.

This method "publisher()" is created at class initialization. (See SPOPS::Manual::CodeGeneration for more information on this process.) SPOPS knows to call the method "publisher" from the alias attached to the class "My::Publisher" and because the name of the ID field in the "My::Book" object is the same as the ID field in the "My::Publisher" object.

More Complex Example: Different ID Field

To automatically create the relationship, you would add to your configuration so it looks like this:

  1: 'book' => {
  2:    class           => 'My::Book',
  3:    isa             => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
  4:    id              => 'book_id',
  5:    field_discover  => 'yes',
  6:    base_table      => 'book',
  7:    increment_field => 1,
  8:    no_insert       => [ 'book_id' ],
  9:    no_update       => [ 'book_id' ],
 10:    has_a           => { 'My::Publisher' => 'publisher_id',
 11:                         'My::User'      => 'updated_by' },
 12: }

SPOPS would create a method 'updated_by_user' that would return the "My::User" object with the ID equal to the 'updated_by' field of the "My::Book" object. How did it create this method name?

Without further customization (more below), SPOPS will take the field name originating the relationship ('updated_by'), append a '_' and then append the alias of the object being related to ('user').

 updated_by + _ + user => updated_by_user

This can be useful but somewhat clunky if you have long fieldnames and/or object aliases. So you can customize this by specifying the name of the method you'd like to create Say we wanted to call up the user who updated the "My::Book" object with the method 'updater'. To do this we'd change the configuration:

  1: 'book' => {
  2:    class           => 'My::Book',
  3:    isa             => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
  4:    id              => 'book_id',
  5:    field_discover  => 'yes',
  6:    base_table      => 'book',
  7:    increment_field => 1,
  8:    no_insert       => [ 'book_id' ],
  9:    no_update       => [ 'book_id' ],
 10:    has_a           => { 'My::Publisher' => 'publisher_id',
 11:                         'My::User'      => { updater => 'updated_by' } },
 12: }

More Complex Example: More Than One Contained Object

So after changing our schema we now have two publisher fields in our "My::Book" object: 'original_publisher_id' and 'current_publisher_id'. Here's what a first pass at the configuration would look like:

  1: 'book' => {
  2:    class           => 'My::Book',
  3:    isa             => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
  4:    id              => 'book_id',
  5:    field_discover  => 'yes',
  6:    base_table      => 'book',
  7:    increment_field => 1,
  8:    no_insert       => [ 'book_id' ],
  9:    no_update       => [ 'book_id' ],
 10:    has_a           => { 'My::Publisher' => [ 'original_publisher_id',
 11:                                              'current_publisher_id' ],
 12:                         'My::User'      => { updater => 'updated_by' } },
 13: }

This works, but the automatically created methods will be "original_publisher_id_publisher()" and "current_publisher_id_publisher()". Nasty. Let's fix that so we use the methods "original_publisher()" and "current_publisher()".

  1: 'book' => {
  2:    class           => 'My::Book',
  3:    isa             => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
  4:    id              => 'book_id',
  5:    field_discover  => 'yes',
  6:    base_table      => 'book',
  7:    increment_field => 1,
  8:    no_insert       => [ 'book_id' ],
  9:    no_update       => [ 'book_id' ],
 10:    has_a           => { 'My::Publisher' => [ { original_publisher => 'original_publisher_id' },
 11:                                              { current_publisher  => 'current_publisher_id' } ],
 12:                         'My::User'      => { updater => 'updated_by' } },
 13: }

It looks a little hairy, but you can see how we've built it up step by step. Fortunately, once you get the mapping down you never need to edit it again until a schema change, which is hopefully quite rare.

Configuration

  1: # Given:
  2: 'contained' => {
  3:    class => 'My::ContainedClass',
  4:    id    => 'contained_id',
  5: }
  6: 
  7: # Basic usage
  8:    links_to => { class-name => 'linking-table-name' }
  9:    links_to => { My::ContainedClass => 'contained_link' }
 10:    -- Creates method 'contained', 'contained_add' and 'contained_remove'

The Basics

Generally this is defined by a linking table. For instance, assume you have the following scaled down schema:

  1: CREATE TABLE book (
  2:    book_id      int not null,
  3:    name         varchar(255) not null,
  4:    primary key( book_id )
  5: )
  6: 
  7: CREATE TABLE publisher (
  8:    publisher_id int not null,
  9:    name         varchar(255) not null,
 10:    primary key( publisher_id )
 11: )
 12: 
 13: CREATE TABLE publisher_book (
 14:    publisher_id int not null,
 15:    book_id      int not null,
 16:    primary key( publisher_id, book_id )
 17: )

The 'publisher_book' table acts to link the 'publisher' and 'book' tables. (In the real world, you'd probably make the relationship its own object since it would contain additional information about the relationship.)

Using SQL, you'd fetch the books for a particular publisher with a statement like this:

  1: SELECT book.book_id, book.name
  2:   FROM publisher pub, book book, publisher_book link
  3:  WHERE pub.publisher_id = ?
  4:        AND link.publisher_id = pub.publisher_id
  5:        AND book.book_id = link.book_id

Since we're dealing with objects, we want to be able to perform something like this:

  1: my $publisher = My::Publisher->fetch( $pub_id );
  2: my $books = $publisher->book;
  3: print "Books published by $publisher->{name}:\n";
  4: foreach my $book ( @{ $books } ) {
  5:    print "  $book->{name}\n";
  6: }

The configuration to make this happen would look like this:

  1: 'book' => {
  2:    class           => 'My::Book',
  3:    isa             => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
  4:    id              => 'book_id',
  5:    field_discover  => 'yes',
  6:    base_table      => 'book',
  7:    increment_field => 1,
  8:    no_insert       => [ 'book_id' ],
  9:    no_update       => [ 'book_id' ],
 10:    links_to        => { 'My::Publisher' => 'publisher_book' },
 11: }

  1: 'publisher' => {
  2:    class           => 'My::Publisher',
  3:    isa             => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
  4:    id              => 'publisher_id',
  5:    field_discover  => 'yes',
  6:    base_table      => 'publisher',
  7:    increment_field => 1,
  8:    no_insert       => [ 'publisher_id' ],
  9:    no_update       => [ 'publisher_id' ],
 10:    links_to        => { 'My::Book' => 'publisher_book' },
 11: }

Adding and Removing Links

• $alias - Returns an arrayref of related objects
• "${alias}_add( $id | $object | \@id_list | \@object_list )" - Adds links to the related objects in $object or "\@object_list" or defined by the IDs in $id or "\@id_list".
• "{$alias}_remove( $id | $object | \@id_list | \@object_list )" - Removes links to the related objects in $object or "\@object_list" or defined by the IDs in $id or "\@id_list".

The first one is covered above. The "_add()" and "_remove()" methods remove the link between two objects rather than the object itself. To use your example, removing a link between the book and publisher would delete the record out of the 'publisher_book' table but leave the associated 'publisher' and 'book' records unchanged.

Code adding and removing a book from the publisher might look like:

  1: my $publisher = My::Publisher->fetch( $pub_id );
  2: my $books = $publisher->book;
  3: foreach my $book ( @{ $books } ) {
  4:     if ( $book->publication_date < 1990 ) {
  5:         $publisher->book_remove( $book );
  6:     }
  7: }
  8: 
  9: my @book_ids = ();
 10: open( REPORT, '< new_publications_report' );
 11: while ( <REPORT> ) {
 12:     chomp;
 13:     s/\s//g;
 14:     next if ( $_ eq '' );
 15:     push @book_ids, $_;
 16: }
 17: $publisher->book_add( \@book_ids );

Advanced 'links_to' configuration

To do this pass a hashref instead of a table name in the 'links_to' configuration. For instance, if in our 'publisher_book' table the publisher ID was 'p_id' and the book ID was 'b_id' we would use:

  1:    links_to        => { 'My::Book' =>
  2:                           { table         => 'publisher_book',
  3:                             to_id_field   => 'b_id',
  4:                             from_id_field => 'p_id', },
  5:                       }

The fields we can define are:

table (required)

You must still specify the table you're using as a linking table.

to_id_field (optional)

If the ID field of the object you're linking to is different than configured in the class you can specify it here. So in the above example the object linking to is 'book' and the new ID field for the book was 'b_id'.

from_id_field (optional)

If the ID field of the object you're linking from is different than configured in the class you can specify it here. So in the above example the object linking from is 'publisher' and the new ID field for the book was 'p_id'.

alias (optional)

You can change the names of the generated methods using this value. Instead of using the main alias of the class as configured you can specify something new here. So if you wanted the methods to be generated for your Spanish-speaking developers you can set this to 'libro' and the methods generated would be 'libro', 'libro_add' and 'libro_remove' instead of 'book', 'book_add' and 'book_remove'.