Apache2::Translation::_base - The Apache2::Translation provider interface

A translation provider must implement the following interface. It is free to support more functions.

new( NAME=>VALUE, ... )

the constructor. It is called once from the master Apache during its configuration.

child_init

This method is optional. If defined it is called from a PerlChildInitHandler and can be used to do some initializations. The DB provider connects here to the database and decides to use a singleton or not.

start

This method is called at start of each uri translation. The DB provider checks the cache here.

stop

is called after each uri translation.

fetch( $key, $uri, $with_notes )

is called to fetch a list of blocks. The result is a list of arrays:

 ([block, order, action],
  [block, order, action],
  ...)

If the adminstration WEB interface is to be used fetch must return a list of:

 ([block, order, action, id],
  [block, order, action, id],
  ...)

where id is a unique key.

If the $with_notes parameter is true fetch is called from the admin interface and wants to fetch also notes. In this case the return value is a list like this:

 ([block, order, action, id, note],
  [block, order, action, id, note],
  ...)

Notes are comments on actions for the user of the admin interface. They are not evaluated otherwize.

The following interface is optional. It has to be implemented if the provider is to be used also with the administration WEB interface.

can_notes

returns true if a provider supports notes in its current configuration.

list_keys

returns a sorted list of known keys.

list_keys_and_uris( $key )

$key is a string.

The function returns a sorted list of [KEY, URI] pairs. If $key is empty all pairs are returned. Otherwise only pairs where $key eq KEY are returned.

begin

commit

rollback

A change conducted via the WEB interface is a sequence of update, insert or delete operations. Before it is started begin is called. If there has no error occured commit is called otherwise rollback. commit must save the changes to the storage. rollback must cancel all changes.

update( [@old], [@new] )

insert( [@new] )

delete( [@old] )

All these functions return something >0 on success. @old is a list of KEY, URI, BLOCK, ORDER, ID that specifies an existing action. If there is no such action the functions must return 0. @new is a list of KEY, URI, BLOCK, ORDER, ACTION that is to be inserted or has to replace an existing action.

The following interface is optional.

clear

deletes all entries from the provider. Is to be called within a begin - commit wrapper. Returns boolean.

iterator

returns a function reference that can be used the following way to step all entries currently hold by the provider. Lists of blocks are traversed in ascending alphabetical order with KEY as the major ordering element and URI the minor. Within a block list elements are traversed in ascending numerical order with BLOCK as the major ordering element and ORDER the minor.

 my $iterator=$other->iterator;
 while( my $el=$iterator->() ) {
   # $el is an array ref as expected by insert().
 }

The following interface is implemented by Apache2::Translation::_base itself and can be used.

append( $other_provider, %options )

Expects a provider object that implements the iterator function. append then insert()s all elements of $other_provider.

If drop_notes is passed as a true value in %options then notes are not copied.

diff( $other_provider, %options )

If Algorithm::Diff and JSON::XS are installed this method computes a difference between 2 providers. If key or uri are given in %options they act as filters. The difference is calculated only for elements that pass that filter. The value of key or uri can either be a string in which case the matching operation is a simple eq or a Regexp object (qr/.../).

If notes is specified in %options as a false value differences in notes only are disregarded.

If numbers is specified in %options as a false value differences in BLOCK and ORDER numbers only are disregarded.

For more information about the output format see diff() in Algorithm::Diff.

sdiff( $other_provider, %options )

Does the same as the diff method but differs in the output format.

For more information see sdiff() in Algorithm::Diff.

dump( $format, $filehandle )

Requires the iterator function to be implemented and dumps all elements formatted according to $format to $filehandle.

Both parameters are optional. Standard $filehandle is STDOUT, standard format is:

 ######################################################################
 %{KEY} & %{URI} %{BLOCK}/%{ORDER}/%{ID}
 %{paction> ;ACTION}
 %{pnote> ;NOTE}

$format is an arbitrary string that contains substrings of the form

  %{flags NAME}

where NAME is on of KEY, URI, BLOCK, ORDER, ACTION, NOTE or ID. These substrings are then replaced by the values for KEY, etc.

flags is optional. It is a semicolon separated list of strings. If given it must also be separated from NAME by a semicolon.

Currently 2 flags are known:

* p string

Trailing spaces are cut from the current value. Then all occurences of \r?\n are replaced by \nstring. Also, string is inserted at start if the current value.

Example:

Suppose an ACTION holds a multilined value:

 PerlHandler: sub {
   my $r=shift;
   $r->content_type( 'text/plain' );
   $r->print( "OK\n" );
   return 0;
 }

Then %{paction> ;ACTION} will be formatted as:

 action> PerlHandler: sub {
 action>   my $r=shift;
 action>   $r->content_type( 'text/plain' );
 action>   $r->print( "OK\n" );
 action>   return 0;
 action> }

* s l|t

sl strips off leading spaces and st trailing spaces.

Torsten Foertsch, <torsten.foertsch@gmx.net>

Copyright (C) 2005-2008 by Torsten Foertsch

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.