SPOPS: Simple Perl Object Persistence with Security

QUICK INSTALL NOTE
====================

Installing via the CPAN shell is always a good thing, otherwise just
do the standard:

 perl Makefile.PL
 make 
 make test
 make install

Note that the first step will ask you a few questions that determine
which tests are run.

Also, there is a 'Bundle' for SPOPS. If you're using the CPAN shell,
just do:

 perl -MCPAN -e 'install Bundle::SPOPS'

Easy!

WHAT IS IT?
====================

SPOPS is a robust and powerful module that allows you to serialize
objects. It is unique in that it also allows you to apply security to
these objects using a fairly simple but powerful scheme of users and
groups. (You can, of course, turn off security if you want.)

It's also unique in that for most objects, you will not need to write
any code. It's true! A fairly simple configuration file is all you
need which you can then feed to SPOPS and have a class for your object
ready to go, right out of thin air.

The configuration you specify not only lists the properties of the
object and possibly some information about where its data should be
stored, but can also describe the relationship an object might have
with another object (or objects).

One great benefit is that you can retrofit SPOPS to existing data. If
you don't use any of the metadata layers or security, you can simply
describe your data in a configuration file, process the configuration
and start making (and processing) objects! If you want to add security
to these objects later, it's easy!


SHOW ME THE CODE!
====================

Here's a sample session. In it, we have a simple configuration file
which names the table in our database and the fields in the table,
along with the primary key field. We process the config, then create a
new object with our just-created class.

(Note that this code is copied directly from the file
'eg/fatbomb_dbi.pl'. See it for more details or to run it yourself.)

 my $spops = {
      fatbomb => {
        class        => 'My::ObjectClass',
        isa          => [ qw/ SPOPS::DBI::MySQL SPOPS::DBI / ],
        field        => [ qw/ fatbomb_id calories cost name servings / ],     
        base_table   => 'fatbomb',
        id_field     => 'fatbomb_id',
        increment_field => 1,
        skip_undef   => [ 'servings' ],
        sql_defaults => [ 'servings' ],
      },
 };
 
 SPOPS::Initialize->process({ config => $spops });

 my $object = My::ObjectClass->new;
 $object->{calories} = 1500;
 $object->{cost}     = '$3.50';
 $object->{name}     = "Super Deluxe Jumbo Big Mac";
 my $fb_id = eval { $object->save({ db => $db }) };
 if ( $@ ) {
    my $ei = SPOPS::Error->get;
    die "Error found! ($@) Error information: ", Dumper( $ei ), "\n";
 }
 print "Object saved ok!\n",
       "Object ID: $fb_id\n",
       "Servings:  $object->{servings}\n";

We can strip out the 'skip_undef' and 'sql_defaults' items in the
configuration and we'd have the bare minimum configuration for a
SPOPS::DBI object. (The 'increment_field' key exists because we're
using the AUTO_INCREMENT feature of MySQL.)


APPLICATION-SPECIFICITY 
====================

Up to now, this library has been tied relatively closely to the
OpenInteract project (www.openinteract.org, or check out the CPAN
module OpenInteract). However, it should be able to stand on its own
two feet -- we've used it like this without any problem. But there
might be a few assumptions lurking around the code somewhere. If you
spot something that looks totally out of place or appears to have no
real purpose, let us know!



WHAT DATABASES ARE SUPPORTED RIGHT NOW?
====================

Currently supported databases include (in alphabetical order):

 * MS SQL Server (using DBD::ODBC and SPOPS::DBI::Sybase)

 * MySQL (using DBD::mysql and SPOPS::DBI::MySQL

 * PostgreSQL (using DBD::Pg and SPOPS::DBI::Pg)

 * Sybase Adaptive Server Enterprise (using DBD::Sybase and
   SPOPS::DBI::Sybase)

 * Sybase Adaptive Server Anywhere (using DBD::ASAny and
   SPOPS::DBI::Sybase)

We also support:

 * LDAP (using Net:::LDAP -- if you have a need for access using
   another client, let us know)

 * GDBM (using GDBM_File)


DO YOU HAVE A LIBRARY FOR <insert name here>?
========================

Maybe. Future development should include:

 * Oracle (using DBD::Oracle)

 * DB2 (using DBD::DB2)

 * Interbase (using DBD::Interbase)

 * CORBA (likely using CORBA::ORBit in the beginning)

Have something you want implemented? Let us know! We might be able to
help you out. Or you might be able to give something back to the
community by funding development -- all LDAP functionality in SPOPS
was funded by MSN Marketing Service Nordwest, GmbH.


HOW DO I SAY IT?
====================

It's usually pronounced so it rhymes with 'mess mops', although you're
free to make up your own.


WHERE CAN I LEARN MORE?
====================

If you want to learn more about how to use SPOPS, read the
documentation! It's quite substantial, and we're always working on
it. Here are some guidelines:

Overview and examples

 perldoc SPOPS

Initializing objects

 perldoc SPOPS::Initialize

Class Factory

 perldoc SPOPS::ClassFactory
 perldoc SPOPS::ClassFactory::DefaultBehavior

Error handling

 perldoc SPOPS::Error

Security

 perldoc SPOPS::Security
 perldoc SPOPS::Security::Hierarchy

DBI issues

 perldoc SPOPS::ClassFactory::DBI
 perldoc SPOPS::DBI
 perldoc SPOPS::SQLInterface
 perldoc SPOPS::DBI::MySQL
 perldoc SPOPS::DBI::Sybase
 perldoc SPOPS::DBI::Pg
 Perldoc SPOPS::Iterator::DBI
 perldoc SPOPS::Key::DBI::HandleField
 perldoc SPOPS::Key::DBI::Identity
 perldoc SPOPS::Key::DBI::Pool
 perldoc SPOPS::Key::DBI::Sequence

LDAP issues

 perldoc SPOPS::ClassFactory::LDAP
 perldoc SPOPS::Iterator::LDAP
 perldoc SPOPS::LDAP
 perldoc SPOPS::LDAP::MultiDatasource

Iterators

 perldoc SPOPS::Iterator

Utilities that might be useful:

 perldoc SPOPS::Key::Random
 perldoc SPOPS::Utility

More information about how data are stored in an object

 perldoc SPOPS::Tie
 perldoc SPOPS::Tie::StrictField


IDEAS? SUGGESTIONS? PATCHES?
========================

Send them in! We welcome patches and try to keep on top of new
developments (such as new DBD drivers) as much as possible. Send
everything to the openinteract-dev mailing list (info below).


CONTACT
========================

This module is supported by the openinteract-help (for help) and
openinteract-dev (for developers) mailing lists. Find out more about
them at:

  http://lists.sourceforge.net/lists/listinfo/openinteract-help
  http://lists.sourceforge.net/lists/listinfo/openinteract-dev

Also check out the SPOPS section of the OpenInteract website for
up-to-date versions, support information, party hat designs, etc.
 
 http://www.openinteract.org/SPOPS/


AUTHORS
=========================

Chris Winters <chris@cwinters.com> is the primary author of
SPOPS. (Sourceforge name: 'lachoy')

Other folks who have had a hand to some degree or other:

=over 4

=item *

Ray Zimmerman <rz10@cornell.edu>

=item *

Christian Lemburg <lemburg@aixonix.de>

=item *

Marcus Baker <mbaker@intes.net>

=item *

Rusty Foster <rusty@kuro5hin.org>

=item *

Rick Myers <rik@sumthin.nu>

=item *

Harry Danilevsky <hdanilevsky@DeerfieldCapital.com>

=item *

Leon Brocard <acme@astray.com>

=item *

David Boone <dave@bis.bc.ca>

=back


COPYRIGHT AND DISCLAIMER
========================

SPOPS is Copyright (c) 2001 by intes.net, inc. All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of the Perl Artistic License or the GNU General
Public License as published by the Free Software Foundation; either
version 2 of the License (see 'COPYING'), or (at your option) any
later version.

=========================
$Id: README,v 1.6 2001/08/28 21:09:54 lachoy Exp $