Net::StarezServer::BaseSQLModule

NAME
DESCRIPTION
MAY-OVERRIDE METHODS
MUST-OVERRIDE METHODS
NON-OVERRIDE METHODS
AUTHOR

NAME

Net::StarezServer::BaseSQLModule - Base module for Starez modules that use SQL

This module is imported by some of the Starez modules that use standard SQL queries. Because most of the contents of these modules are the same, it is easier and safer to put the general code for these modules in a base module, and have the other modules define their own methods for their own stuff.

This section will be extended to describe the general SQL interface for Starez modules.

MAY-OVERRIDE METHODS

load (%args)

This method starts loading data. You may override this method if you want something else to happen before running the query. The default method just calls _loadData().

Args are in the same syntax as _loadData().

create (%args)

This method starts creating data. You may override this method if you want something else to happen before running the query. The default method just calls _createData().

Args are in the same syntax as _createData().

_instantiate ()

This method may be overridden to do something more than just creating an empty object and blessing it to the package this method was called upon. (e.g. set default values.)

_fillObject ($values)

This method by default receives all requested SQL values in the $values hashref, and fills the object with those values. If you want to do some post-processing, you can override this method.

MUST-OVERRIDE METHODS

You must override these methods, or loading or creating data may not be possible.

Note that invalid data may cause this module to emit syntax failures in SQL. Make sure that you escape your stuff if you need to.

_table ()

This method returns the default table to do lookups to (e.g. 'users')

_elements ()

This method returns the list of to-load elements as an arrayref. If an equal sign ('=') character is found in 'elements', the SQL data for the value before the equal sign is requested and stored in the object under the name after the equal sign. (e.g. ['userid', 'username', 'password=hashedpass'])

_idname ()

This method returns the column name of the 'identifier' of a row (e.g. 'userid').

NON-OVERRIDE METHODS

These methods are not to be defined in the child modules.

_loadData

The loadData subroutine wants a hash with 'idvalue' which is the value of the column 'idname' for the row you wish to load. Optional values in the hash are:

  table    - the table that contains the required data.
  elements - list of elements you want to receive in an arrayref
  idname   - the column to check for the ID value

Also, as always, I want a subroutine in 'returnto'. It will be called with a hashref as the first argument containing either 'error' or 'idvalue', 'object' and 'exists'. If the row didn't exist, exists will be zero and object will not be set.

If you give a 'database' element, that handle will be used, otherwise this method will try to fetch a Net::StarezServer::Database handle through its new() method, but one must already have been created for that to work. If that doesn't work, a warning is emitted and the returnto coderef will be called with an error set.

_createData

This method creates a new object in the database. You do this by giving a 'values' hashref, containing elements as described by the SQLModule's documentation.

In %args, I want at least a 'returnto' element and a 'values' element. The optional arguments 'table', 'elements', 'idname' can be given just like in _loadData. The 'returnto' element will be called with a hashref, containing either an 'error' element or an 'object' element pointing at the object created with this data.

Every element in the values hashref will be checked for its existence in the SQLModule's elements list. If it does not appear, a warning will be issued and the element will not be added to the object. Elements that are not given or are undefined will be added as null. This may result in "column may not be null" errors.

TODO: Give insert_id, once Database.pm supports this.