NAME

Persistent::Oracle - A Persistent Class implemented using an Oracle database

SYNOPSIS

  use Persistent::Oracle;
  use English;  # import readable variable names like $EVAL_ERROR

  eval {  ### in case an exception is thrown ###

    ### allocate a persistent object ###
    my $emp = new Persistent::Oracle('dbi:Oracle:ORCL',
				     'scott', 'tiger', 'emp');

    ### define attributes of the object ###
    $emp->add_attribute('empno',    'ID',         'Number',   undef, 4);
    $emp->add_attribute('ename',    'Persistent', 'VarChar',  undef, 10);
    $emp->add_attribute('job',      'Persistent', 'VarChar',  undef, 9);
    $emp->add_attribute('mgr',      'Persistent', 'Number',   undef, 4);
    $emp->add_attribute('hiredate', 'Persistent', 'DateTime', undef);
    $emp->add_attribute('sal',      'Persistent', 'Number',   undef, 7, 2);
    $emp->add_attribute('comm',     'Persistent', 'Number',   undef, 7, 2);
    $emp->add_attribute('deptno',   'Persistent', 'Number',   undef, 2);

    ### query the datastore for some objects ###
    $emp->restore_where(qq{
                              sal > 1000 and
                              job = 'CLERK' and
                              ename LIKE 'M%'
                          }, "sal, ename");
    while ($emp->restore_next()) {
      printf "ename = %s, emp# = %s, sal = %s, hiredate = %s\n",
             $emp->ename, $emp->empno, $emp->sal, $emp->hiredate;
    }
  };

  if ($EVAL_ERROR) {  ### catch those exceptions! ###
    print "An error occurred: $EVAL_ERROR\n";
  }

ABSTRACT

This is a Persistent class that uses an Oracle database table to store and retrieve objects. This class can be instantiated directly or subclassed. The methods described below are unique to this class, and all other methods that are provided by this class are documented in the Persistent documentation. The Persistent documentation has a very thorough introduction to using the Persistent framework of classes.

This class is part of the Persistent Oracle package which is available from:

http://www.bigsnow.org/persistent
ftp://ftp.bigsnow.org/pub/persistent

DESCRIPTION

Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the Persistent documentation for more information on exception handling in Perl.

METHODS

new -- Object Constructor

use Persistent::Oracle;

eval {
  $obj = new Persistent::Oracle($data_source, $username, $password, $table);
  ### or ###
  $obj = new Persistent::Oracle($dbh, $table);
};
croak "Exception caught: $@" if $@;

Allocates an object. This method throws Perl execeptions so use it with an eval block.

Parameters:

These are the same as for the datastore method below.

datastore -- Sets/Returns the Data Store Parameters

eval {
  ### set the data store ###
  $obj->datastore($data_source, $username, $password, $table);
  ### or ###
  $obj->datastore($dbh, $table);

  ### get the data store ###
  $dbh = $obj->datastore();
};
croak "Exception caught: $@" if $@;

Returns (and optionally sets) the data store of the object. This method throws Perl execeptions so use it with an eval block.

Parameters:

$data_source

DBI data source name for the database. Please refer to the DBD::Oracle documentation for valid data source names.

$username

Connect to the database with this given username

$password

Password for the username

$table

Table in the database that contains the objects. This table should exist prior to instantiating a Persistent class that will use it.

$dbh (also a return value)

DBI handle to the database

restore_where -- Conditionally Restoring Objects

  use Persistent::Oracle;

  eval {
    my $emp = new Persistent::Oracle('dbi:Oracle:ORCL',
				     'scott', 'tiger', 'emp');
    $emp->restore_where(
      " job = 'CLERK' and sal > 1000",
      "sal DESC, ename"
    );
    while ($emp->restore_next()) {
      print "Restored: ";  print_person($person);
    }
  };
  croak "Exception caught: $@" if $@;

Restores objects from the data store that meet the specified conditions. The objects are returned one at a time by using the restore_next method and in a sorted order if specified. This method throws Perl execeptions so use it with an eval block.

Since this is a SQL based Persistent class, the restore_where method expects a valid SQL WHERE clause for the first argument, $where, and a valid SQL ORDER BY clause for the optional second argument, $order_by.

Parameters:

$where

Conditional expression for the requested objects. The format of this expression is a SQL WHERE clause without the WHERE keyword. This argument is optional.

$order_by

Sort expression for the requested objects. The format of this expression is a SQL ORDER BY clause with the ORDER BY keywords. This argument is optional.

Returns:

$num_of_objs

The number of objects that match the conditions.

See the Persistent documentation for more information.

OTHER METHODS

For a description of the other methods that this subclass provides, please refer to the Persistent::DBI documentation which is the parent class. Or refer to the Persistent documentation for a very thorough introduction and reference to the Persistent Framework of Classes.

SEE ALSO

Persistent, Persistent::DBI, Persistent::DataType::DateTime

BUGS

This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at:

winters@bigsnow.org

And you know, include the regular stuff: OS, Perl, Oracle versions, snippet of code, etc.

AUTHORS

David Winters <winters@bigsnow.org>

COPYRIGHT

Copyright (c) 1998-2000 David Winters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Persistent::Oracle

perl -MCPAN -e shell
install Persistent::Oracle