Wombat::Realm::DBIRealm - internal realm base clas

- NAME
- SYNOPSIS
- DESCRIPTION
- CONSTRUCTOR
- ACCESSOR METHODS
- PUBLIC METHODS
- PACKAGE METHODS
- LIFECYCLE METHODS
- SEE ALSO
- AUTHOR

# NAME

Wombat::Realm::DBIRealm - internal realm base clas

# SYNOPSIS

# DESCRIPTION

Implementation of Wombat::Realm that works with any DBI supported database.

# CONSTRUCTOR

`new()`
  Construct and return a Wombat::Realm::RealmBase instance, initializing fields appropriately. If subclasses override the constructor, they must be sure to call

        $self->SUPER::new();

# ACCESSOR METHODS

`setConnectionName($connectionName)`
  Set the username to use to connect to the database.

  Parameters:

  $connectionName
    the database username

`setConnectionPassword($connectionPassword)`
  Set the password to use to connect to the database.

  Parameters:

  $connectionPassword
    the database password

`setConnectionURL($connectionURL)`
  Set the URL to use to connect to the database. The URL is the part of the DBI data source after the driver name. In this example

        DBI:mysql:hostname=localhost;port=12345;database=hi

  the URL is

        hostname=localhost;port=12345;database=hi

  Parameters:

  $connectionURL
    the database URL

`setDriverName($driverName)`
  Set the DBI driver to use.

  Parameters:

  $driverName
    the DBI driver name

`setRoleNameCol($roleNameCol)`
  Set the column in the user role table that names a role.

  Parameters:

  $roleNameCol
    the column name

`setUserCredCol($userCredCol)`
  Set the column in the user table that holds the user's credentials.

  Parameters:

  $userCredCol
    the column name

`setUserNameCol($userNameCol)`
  Set the column in the user table that holds the user's name.

  Parameters:

  $userNameCol
    the column name

`setUserRoleTable($userRoleTable)`
  Set the table that holds the relation between users and roles.

  Parameters:

  $userRoleTable
    the table name

`setUserTable($userTable)`
  Set the table that holds user data.

  Parameters:

  $userTable
    the table name

# PUBLIC METHODS

authenticate ($username, $credentials)
  Return the Principal associated with the specified username and credentials, if there is one, or `undef` otherwise.

  If there are any errors with the DBI connection, executing the query or anything else, do not authenticate and return `undef`. This event is also logged, and the connection will be closed so that a subsequent request will automatically re-open it.

  Parameters

  $username
    username of the principal to be looked up

  $credentials
    password or other credentials to use in authenticating this username

# PACKAGE METHODS

`close()`
  Close the database connection.

`getName()`
  Return a short name for this Realm implementation.

`open()`
  Open the database connection.

# LIFECYCLE METHODS

`start()`
  Prepare for active use of this Realm, opening the database connection. This method should be called before any of the public methods of the Realm are utilized.

  Throws:

  Servlet::Util::Exception
    if the Realm has already been started

`stop()`
  Gracefully terminate active use of this Realm, closing the database connection. Once this method has been called, no public methods of the Realm should be utilized.

  Throws:

  Servlet::Util::Exception
    if the Realm is not started

# SEE ALSO

DBI, the Wombat::Realm::RealmBase manpage

# AUTHOR

Brian Moseley, bcm@maz.org