NAME

Model - The superclass for all Solstice data models.

SYNOPSIS

  package Model;

  use Model;
  our @ISA = qw(Model);

  sub new {
    my $pkg = shift;
    my $self = $pkg->SUPER::new(@_);
    return $self;
  }

  sub store {
    my $self = shift;
    my $retval = FALSE;

    return TRUE unless $self->_isTainted;

    # pseudocode...
    my $datastore = MyDatastore->new;

    if ($datastore->put($self)) {
      $self->_setID($datastore->get_last_id);
      $self->_untaint;
      $retval = TRUE;
    }

    return $retval;
  }

  sub delete {
    my $self = shift;
    my $retval = FALSE;

    # pseudocode...
    my $datastore = MyDatastore->new;

    if ($datastore->remove($self)) {
      $self->_setID(undef);
      $retval = TRUE;
    }

    return $retval;
  }

  sub clone {
    my $self = shift;
    my $clone = $self->SUPER::clone(@_);

    return $clone;
  }

DESCRIPTION

This should be used by all models in Solstice. It provides some basic application functionality, such as getting and setting ids, managing taintedness, cloning, and store() and delete() stubs.

Here taintedness describes whether or not the object has been altered since it was loaded from the datastore. New, "blank" object are tainted. New objects loaded from a datastore are not. Set-accessors and other methods that alter the object should use the _taint() method. The store() method can use the _isTainted() method for optimization -- there's no reason to do the work of storing the object if it hasn't changed.

Export

No symbols exported.

Methods

new()

Constructor; should only be called by a subclass. Returns a Model object.

getClassName()

Return the class name for the model. This method should be sub-classed to avoid using ref().

getErrorMessages()

Returns a reference to a list of error strings.

clearErrorMessages()

Empty the list of error strings.

store()

This is a stub method, expected to be implemented by a subclass. It serializes the object to some datastore and assigns to the object an ID local to that datastore. Returns true upon success, false otherwise.

delete()

This is a stub method, expected to be implemented by a subclass. It removes this object from a datastore and clears the object's ID. It does not, however, reinitialize this object, destroy it, or undefine it; only it's ID is undefined. Returns true upon success, false otherwise.

clone()

Returns a deep copy of this object, without any IDs.

processPersistenceValues ($exception_hash_ref)

Takes all persistence values and stores them into the model, except those specified by the exception list. Only works for models with public sets.

    $self->processPersistenceValues({
        method_3 => TRUE,
        method_6 => TRUE,
    });

clearPersistenceValues()

Removes all persistence values for this model, to make it easy to revert.

createSearchField($name, $content)

Creates a search field with the given name and content. Returns the search field object so you can set further options. See the Solstice::SearchField API

storeSearchIndex()

This gathers the values from the searchfields you have created and adds or updates this model's entry in the index.

createSearch ( $search_string )

Builds a Solstice::Search object that will return objects of this type.

See the Solstice::Search API

Private Methods

_loadSearchLibrary

Enables graceful failure of searching if the prerequisites are not installed

_getSearchIndexFilename()

Builds the file path used to store search indexes - specific to each model class.

_addErrorMessage($string)

Add an error message.

_taint()

Sets the model as having been changed by user data, and therefore in need of saving, when a store method is called. Returns undef.

_untaint()

Unsets the model as having been tainted. Returns undef.

_isTainted()

Returns true if the model has been tainted by user data (as set by _taint()), false otherwise.

_deprecate()

Sets the model as having been deprecated, and therefore in need of deletion, when a store method is called. Returns undef.

_undeprecate()

Unsets the model as having been deprecated. Returns undef.

_isDeprecated()

Returns true if the model has been deprecated (as set by _deprecate()), false otherwise.

_areEqual($arg1, $arg2)

Returns true if $arg1 and $arg2 are equal, false otherwise.

_initAttributes()

Initializes attributes and accessor methods for the model. This method also initializes attributes for any superclasses that haven't already been initialized, to ensure that inherited accessors are available to nitthe model.

Private Functions

_createAttributes($class)

Creates accessors for $class. Attribute data is fetched using the method _getAccessorDefinition(), which returns an arrayref. Each element in the array is a hashref with the format:

  {
    name  => 'Name',    # method name suffix: getName/setName in this example
    key   => '_name',   # object key
    type  => 'String',  # data type, see explanation below
    taint => 0|1,       # public set taints model, false by default
    private_set => 0|1, # specifies that set is private, false by default
    private_get => 0|1, # specifiies that get is private, false by default
  },

The required keys are 'name', 'key', and 'type'. All others are optional. Acceptable values for 'type' are: Integer, PositiveInteger, Float, String, Boolean, ArrayRef, HashRef, List, Tree, Person, DateTime. Object package names are also ok, when it is desired that an attribute accept only a specific class.

If an accessor already exists in the model, it will not be overwritten.

_getAccessorDefinition()

Returns an array ref containing attribute data. Subclasses will override this method to generate specialized accessor methods.

Attribute Validation Methods

Model Templates

Solstice::ModelTemplates - a set of functions that get globbed into subclasses of Model.

_publicGet($key)

_publicSet($name, $taint)

_publicSetTaint($name)

_privateSetNumber($key)

_privateSetInteger($key)

_privateSetPositiveInteger($key)

_privateSetNonNegativeInteger($key)

_privateSetFloat($key)

_privateSetString($key)

_privateSetEmail($key)

_privateSetURL($key)

_privateSetBoolean($key)

_privateSetArrayRef($key)

_privateSetHashRef($key)

_privateSetList($key)

_privateSetTree($key)

_privateSetPerson($key)

_privateSetGroup($key)

_privateSetDateTime($key)

_privateSetObject($key, $class)

This creates a generic object accessor, that will validate a ref() of the passed arg against $class.

Modules Used

Carp, Class::ISA, Devel::Symdump.

AUTHOR

Catalyst Group, <catalyst@u.washington.edu>

VERSION

$Revision: 2393 $

COPYRIGHT

Copyright 1998-2007 Office of Learning Technologies, University of Washington

Licensed under the Educational Community License, Version 1.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: http://www.opensource.org/licenses/ecl1.php

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.