Apache2::Translation::_base - The Apache2::Translation provider interface
A translation provider must implement the following interface. It is free to support more functions.
the constructor. It is called once from the master Apache during its configuration.
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.
This method is called at start of each uri translation. The DB provider checks the cache here.
is called after each uri translation.
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.
returns true if a provider supports notes in its current configuration.
returns a sorted list of known keys.
$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.
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.
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.
deletes all entries from the provider. Is to be called within a begin
- commit
wrapper. Returns boolean.
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.
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.
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.
Does the same as the diff
method but differs in the output format.
For more information see sdiff()
in Algorithm::Diff.
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:
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> }
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.