Accessors/Mutators

 # Accessor
 my $value = $object->fieldname;
 
 # Mutator
 $object->fieldname( 'new value' );
 
 # This won't do what you want (clear the field value)...
 $object->fieldname( undef );
 
 # ... but this will
 $object->fieldname_clear;

The return value of the mutator is the new value of the field which is the same value you passed in.

Generic accessors ("get()") and mutators ("set()") are available but deprecated, probably to be removed before 1.0:

You can modify how the accessors/mutators get generated by overriding the method:

 sub _internal_create_field_methods {
     my ( $self, $class, $field_name ) = @_;
     ...
 }

This method must create two methods in the class namespace, '${fieldname}' and '${fieldname}_clear'. Since the value returned from "AUTOLOAD" depends on these methods being created, failure to create them will probably result in an infinite loop.

get( $fieldname )

Returns the currently stored information within the object for $fieldname.

 my $value = $obj->get( 'username' );
 print "Username is $value";

It might be easier to use the hashref interface to the same data, since you can inline it in a string:

 print "Username is $obj->{username}";

You may also use a shortcut of the parameter name as a method call for the first instance:

 my $value = $obj->username();
 print "Username is $value";

set( $fieldname, $value )

Sets the value of $fieldname to $value. If value is empty, $fieldname is set to undef.

 $obj->set( 'username', 'ding-dong' );

Again, you can also use the hashref interface to do the same thing:

 $obj->{username} = 'ding-dong';

You can use the fieldname as a method to modify the field value here as well:

 $obj->username( 'ding-dong' );

Note that if you want to set the field to "undef" you will need to use the hashref interface:

 $obj->{username} = undef;

id()

Returns the ID for this object. Checks in its config variable for the ID field and looks at the data there. If nothing is currently stored, you will get nothing back.

Note that we also create a subroutine in the namespace of the calling class so that future calls take place more quickly.

Serialization

Implemented by subclass.

This method should be called from either a class or another object with a named parameter of 'id'.

Returns on success: an SPOPS object.

Returns on failure: undef; if the action failed (incorrect fieldname in the object specification, database not online, database user cannot select, etc.) a SPOPS::Exception object (or one of its subclasses) will be thrown to raise an error.

The \%params parameter can contain a number of items -- all are optional.

Parameters:

• (datasource) (obj) (optional)

  For most SPOPS implementations, you can pass the data source (a DBI database handle, a GDBM tied hashref, etc.) into the routine. For DBI this variable is "db", for LDAP it is "ldap", but for other implementations it can be something else.

• data (\%) (optional)

  You can use fetch() not just to retrieve data, but also to do the other checks it normally performs (security, caching, rulesets, etc.). If you already know the data to use, just pass it in using this hashref. The other checks will be done but not the actual data retrieval. (See the "fetch_group" routine in SPOPS::DBI for an example.)

• skip_security (bool) (optional)

  A true value skips security checks, false or default value keeps them.

• skip_cache (bool) (optional)

  A true value skips any use of the cache, always hitting the data source.

In addition, specific implementations may allow you to pass in other parameters. (For example, you can pass in 'field_alter' to the SPOPS::DBI implementation so you can format the returned data.)

Example:

 my $id = 90192;
 my $data = eval { MyClass->fetch( $id ) };
 
 # Read in a data file and retrieve all objects matching IDs
 
 my @object_list = ();
 while ( <DATA> ) {
   chomp;
   next if ( /\D/ );
   my $obj = eval { ObjectClass->fetch( $_ ) };
   if ( $@ ) { ... report error ... }
   else      { push @object_list, $obj  if ( $obj ) }
 }

fetch_determine_limit()

This method has been moved to SPOPS::Utility.

save( [ \%params ] )

Implemented by subclass.

This method should save the object state in whatever medium the module works with. Note that the method may need to distinguish whether the object has been previously saved or not -- whether to do an add versus an update. See the section "TRACKING CHANGES" for how to do this. The application should not care whether the object is new or pre-owned.

Returns on success: the object itself.

Returns on failure: undef, and a SPOPS::Exception object (or one of its subclasses) will be thrown to raise an error.

Example:

 eval { $obj->save };
 if ( $@ ) {
   warn "Save of ", ref $obj, " did not work properly -- $@";
 }

Since the method returns the object, you can also do chained method calls:

 eval { $obj->save()->separate_object_method() };

Parameters:

• (datasource) (obj) (optional)

  For most SPOPS implementations, you can pass the data source (a DBI database handle, a GDBM tied hashref, etc.) into the routine.

• is_add (bool) (optional)

  A true value forces this to be treated as a new record.

• skip_security (bool) (optional)

  A true value skips the security check.

• skip_cache (bool) (optional)

  A true value skips any caching.

• skip_log (bool) (optional)

  A true value skips the call to 'log_action'

remove()

Implemented by subclass.

Permanently removes the object, or if called from a class removes the object having an id matching the named parameter of 'id'.

Returns: status code based on success (undef == failure).

Parameters:

• (datasource) (obj) (optional)

  For most SPOPS implementations, you can pass the data source (a DBI database handle, a GDBM tied hashref, etc.) into the routine.

• skip_security (bool) (optional)

  A true value skips the security check.

• skip_cache (bool) (optional)

  A true value skips any caching.

• skip_log (bool) (optional)

  A true value skips the call to 'log_action'

Examples:

 # First fetch then remove

 my $obj = MyClass->fetch( $id );
 my $rv = $obj->remove();

Note that once you successfully call "remove()" on an object, the object will still exist as if you had just called "new()" and set the properties of the object. For instance:

 my $obj = MyClass->new();
 $obj->{first_name} = 'Mario';
 $obj->{last_name}  = 'Lemieux';
 if ( $obj->save ) {
     my $saved_id = $obj->{player_id};
     $obj->remove;
     print "$obj->{first_name} $obj->{last_name}\n";
 }

Would print:

 Mario Lemieux

But trying to fetch an object with $saved_id would result in an undefined object, since it is no longer in the datastore.

Object Information

Returns a hashref with metadata about a particular object. The keys of the hashref are:

• class ($)

  Class of this object

• object_id ($)

  ID of this object. (Also under 'oid' for compatibility.)

• id_field ($)

  Field used for the ID.

• name ($)

  Name of this general class of object (e.g., 'News')

• title ($)

  Title of this particular object (e.g., 'Man bites dog, film at 11')

• url ($)

  URL that will display this object. Note that the URL might not necessarily work due to security reasons.

  url_edit ($)

  URL that will display this object in editable form. Note that the URL might not necessarily work due to security reasons.

You control what's used in the 'display' class configuration variable. In it you can have the keys 'url', which should be the basis for a URL to display the object and optionally 'url_edit', the basis for a URL to display the object in editable form. A query string with 'id_field=ID' will be appended to both, and if 'url_edit' is not specified we create it by adding a 'edit=1' to the 'url' query string.

So with:

 display => {
   url      => '/Foo/display/',
   url_edit => '/Foo/display_form',
 }

The defaults put together by SPOPS by reading your configuration file might not be sufficiently dynamic for your object. In that case, just override the method and substitute your own. For instance, the following adds some sort of sales adjective to the beginning of every object title:

  package My::Object;
 
  sub object_description {
      my ( $self ) = @_;
      my $info = $self->SUPER::object_description();
      $info->{title} = join( ' ', sales_adjective_of_the_day(),
                                  $info->{title} );
      return $info;
  }

And be sure to include this class in your 'code_class' configuration key. (See SPOPS::ClassFactory and SPOPS::Manual::CodeGeneration for more info.)

as_string

Represents the SPOPS object as a string fit for human consumption. The SPOPS method is extremely crude -- if you want things to look nicer, override it.

as_html

Represents the SPOPS object as a string fit for HTML (browser) consumption. The SPOPS method is double extremely crude, since it just wraps the results of "as_string()" (which itself is crude) in '<pre>' tags.

Lazy Loading

Returns true if $fieldname has been loaded from the datastore, false if not.

set_loaded( $fieldname )

Flags $fieldname as being loaded.

set_all_loaded()

Flags all fieldnames (as returned by "field_list()") as being loaded.

Field Checking

Returns true if this class is doing field checking (setting 'strict_field' equal to a true value in the configuration), false if not.

Modification State

Returns true if this object has been changed since being fetched or created, false if not.

has_change()

Set the flag telling this object it has been changed.

clear_change()

Clear the change flag in an object, telling it that it is unmodified.

Serialization State

Return true if this object has ever been saved, false if not.

has_save()

Set the saved flag in the object to true.

clear_save()

Clear out the saved flag in the object.

Configuration

We have simple methods here just returning the basic CONFIG information.

no_cache() (bool)

Returns a boolean based on whether this object can be cached or not. This does not mean that it will be cached, just whether the class allows its objects to be cached.

field() (\%)

Returns a hashref (which you can sort by the values if you wish) of fieldnames used by this class.

field_list() (\@)

Returns an arrayref of fieldnames used by this class.

Subclasses can define their own where appropriate.

"Global" Configuration

global_cache

A caching object. Caching in SPOPS is not tested but should work -- see Caching below.

Caching

 SPOPS->set_global_use_cache(1);

You will also need to make a caching object accessible to all of your SPOPS classes via a method "global_cache()". Each class can turn off caching by setting a true value for the configuration variable "no_cache" or by passing in a true value for the parameter 'skip_cache' as passed to "fetch", "save", etc.

The object returned by "global_cache()" should return an object which implements the methods "get()", "set()", "clear()", and "purge()".

The method "get()" should return the property values for a particular object given a class and object ID:

 $cache->get({ class => 'SPOPS-class', object_id => 'id' })

The method set() should saves the property values for an object into the cache:

 $cache->set({ data => $spops_object });

The method clear() should clear from the cache the data for an object:

 $cache->clear({ data => $spops_object });
 $cache->clear({ class => 'SPOPS-class', object_id => 'id' });

The method purge() should remove all items from the cache.

This is a fairly simple interface which leaves implementation pretty much wide open.

Timestamp Methods

Debugging

Please see SPOPS::Manual::Configuration under LOGGING for information on how to configure it.