NAME

StorageBase - base class for filter storage plugins

SYNOPSIS

   package List::Filter::Storage::NewFormat;
   use base qw( List::Filter::StorageBase );

   sub init {
   }

   sub lookup {
     # ...
   }

   sub save {
     # ...
   }

   sub list_filters {
     # ...
   }


   1;

DESCRIPTION

This is module is purely an interface, which the storage plugins are intended to inherit from. The documentation of this module is thus oriented toward people interested in writing new storage plugins, see the existing plugins for documentation on how to use them.

OBJECT DATA

The main fields inside the object:

connect_to

In the case of DBI, this will be the database connection string, indicating the DBD driver and the database name.

owner

A user name, when required to make the connection.

password

A password, to go with the user name.

attributes

A hash reference of additional attributes to be used by the storage back-end in any way that seems appropriate.

In the case of DBI, this hash ref might contain something like this:

   { RaiseError => 1, AutoCommit => 1 }

(Though there's no particular point in manipulating AutoCommit with storage needs this simple).

type

The type of the filters being stored (e.g. 'filter', 'transform'). Not to be confused with the data storage format (e.g 'YAML', 'DBI')

extra

A catch-all hash reference intended to be used primarily for internal storage purposes by the subclasses, e.g. in the case of YAML, this will contain a reference to the contents of an entire YAML file that has been slurped into memory. Writing additional accessors for the data inside of "extra" is strongly advised, to make it easier to modifiy the internal structure at a later date.

METHODS

There are two main methods that need to be implemented:

new

Instantiates a new object.

Takes an optional hashref as an argument, with named fields identical to the names of the object attributes.

With no arguments, the newly created filter will be empty.

init

Initialize object attributes and then lock them down to prevent accidental creation of new ones.

Note: there is no leading underscore on name "init", though it's arguably an "internal" routine (i.e. not likely to be of use to client code).

Optionally, a plugin may run additional initialization code inside of an init method that overrides this stub.

define_filter_class

From the type of the stored filters (e.g. 'filter', 'transform'), determine the appropriate class.

This implements the convention: List::Filter::<type>, except that for type 'filter' the class is just "List::Filter".

main methods (stubs)

lookup

Given a name, returns the first filter found with a matching name.

save

Given a filter saves it to the storage location indicated by the "write_storage" setting of the List::Filter::Storage object, using the name indicated by the "name" field inside of the filter.

list_filters

Returns a list of all available filters.

basic accessors

connect_to

Getter for object attribute connect_to

owner

Getter for object attribute owner

set_owner

Setter for object attribute set_owner

password

Getter for object attribute password

set_password

Setter for object attribute set_password

set_connect_to

Setter for object attribute set_connect_to

attributes

Getter for object attribute attributes

set_attributes

Setter for object attribute set_attributes

type

Getter for object attribute type

set_type

Setter for object attribute set_type

extra

Getter for object attribute extra

set_extra

Setter for object attribute set_extra

SEE ALSO

List::Filter List::Filter::Storage::YAML List::Filter::Storage::DBI

AUTHOR

Joseph Brenner, <doom@kzsu.stanford.edu>, 18 May 2007

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Joseph Brenner

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.

BUGS

None reported... yet.