NAME

Pixie::Store -- Factory & abstract base class for Pixie stores

SYNOPSIS

  # you should never have to use this class directly!

  use Pixie;
  Pixie->deploy( $dsn, %args );
  my $px = Pixie->connect( $dsn, %args );

DESCRIPTION

Pixie::Store provides Pixie with an abstract interface to the physical storage used to actually store the objects that Pixie manages. It is not a 'public' class; most Pixie users will never have to touch it.

However, if you want to add another storage medium to Pixie, start here. (If you want to add specific methods for storing in a particular RDBMS, you should take a look at DBIx::AnyDBD before diving into Pixie::Store::DBI and its woefully underdocumented friends.

The Public Interface

There is no public interface to Pixie::Store. You should be able to get by with Pixie::deploy() and Pixie::connect() for all your storage needs.

Data Source Names (Storage Specs)

Pixie's Data Source Names (or Storage Specs) are typically similar in form to the classic DBI data source spec. But the only fixed part of a Pixie DSN is that the storage type comes first:

    type:path

The DSN's type is used by Pixie::Store to identify which subclass to use. "The Typemap" details which class to use for each type.

CLASS METHODS

Pixie::Store operates as a factory/dispatch class when using the class methods below. Subclasses are loaded as needed, and "The Typemap" is used to determine which class to dispatch the request to.

$class = Pixie::Store->deploy( $dsn [, @ARGS] )

Deploys the Pixie store specified. Loads the $dsn's class on demand (see "The Typemap"). Dies on error.

Note: This will likely change to return a new, connected store object.

$store = Pixie::Store->connect( $dsn [, @ARGS] )

Connect to the Pixie store specified. Loads the $dsn's class on demand (see "The Typemap"). Returns a new store object of the appropriate class. Dies on error.

The Subclassable Interface

Pixie::Store operates as an abstract base class for Pixie stores to inherit from. Pixie depends on the following methods existing and working as described.

INSTANCE METHODS

$class = $class->deploy( $dsn [, @ARGS] )

Deploy the Pixie store specified. Returns this class, or dies on error.

Note: This will likely change to return a new, connected store object.

$store = $class->connect( $dsn [, @ARGS] )

Connect to the Pixie store specified. Returns a new Pixie::Store object, or dies on error.

$store = $store->clear()

Empties the datastore, removes all stored objects and any associated metadata. Use with caution. (It is remarkably handy when one is writing test scripts though...)

$store->store_at( $OID, $FLATTENED_OBJECT )

Take the FLATTENED_OBJECT and stash it where it can be found via the given OID. The FLATTENED_OBJECT is guaranteed to be an arbitrarily long string of bytes (just to make life easy...). An OID is a string of up to 255 characters. Overwrites any existing entry at that OID.

Currently returns an array containing the OID and FLATTENED_OBJECT, though this may change in the future.

Note: looks like this takes an OBJECT rather than a FLATTENED_OBJECT; flattening is done here. Also, a LOCKING_STRATEGY is sometimes passed in.

$obj = $store->get_object_at( $OID )

Returns the object associated with the given OID if it exists; returns undef/the empty list if no object can be found and throws an exception if it finds more than one object associated with that OID. (OIDs are supposed to be unique after all).

$bool = $store->delete( $OID )

Deletes the object associated with OID. Returns true if an object existed, or false if there was no such object.

Note: looks like this is actually implemented as _delete().

$store->lock()

Possibly misnamed. Locks the database so that nobody else can interfere.

Note: often implemented as begin_transaction()...

$store->unlock()

Again, possibly misnamed. Ensures that all the changes that have been inserted really have been inserted, and frees the database for other users. Should possibly be called 'commit'.

$store->rollback()

Rolls the database back to the state it was in at the last 'lock'. Not misnamed. (Hurrah).

Note

Note that there are other methods you must override that are not yet documented here. You should read through the source before you attempt to write a subclass.

The Typemap

Once you have subclassed Pixie::Store you need to let it know about your new subclass so it can make connect work. To do that, pick an appropriate prefix string to identify your subclass and add something like the following -- after the use base 'Pixie::Store'; part, or things will break -- to your code:

  $Pixie::Store::typemap{prefix} = __PACKAGE__;

Once you have done this, the code given in the synopsis should work, as if by magic.

AUTHORS

James Duncan <james@fotango.com>, Piers Cawley <pdcawley@bofh.org.uk> and Leon Brocard <acme@astray.com>.

COPYRIGHT

Copyright 2002-2004 Fotango Ltd

This software is released under the same license as Perl itself.

cpanm Pixie

perl -MCPAN -e shell
install Pixie