view release on metacpan or  search on metacpan

lib/Apache2/SSI/Notes.pm  view on Meta::CPAN

sub shem { return( shift->_set_get_object_without_init( 'shem', 'Apache2::SSI::SharedMem', @_ ) ); }

sub size { return( shift->_set_get_scalar( 'size', @_ ) ); }

sub supported { return( Apache2::SSI::SharedMem->supported ); }

sub unset
{
    my $self = shift( @_ );
    my $key  = shift( @_ );
    return( $self->error( "Key provided to unset value is empty." ) ) if( !length( $key ) );
    my $data = $self->read_mem || return;
    delete( $data->{ $key } );
    $self->write_mem( $data ) || return;
    return( $self );
}

sub write_mem
{
    my $self = shift( @_ );
    my $shem = $self->shem ||
        return( $self->error( "Oh no, the shared memory object is gone! That should not happen." ) );
    my $data = shift( @_ );
    return( $self->error( "I was expecting an hash reference and got instead '$data'" ) ) if( ref( $data ) ne 'HASH' );
    if( !defined( $shem->lock( ( LOCK_EX | LOCK_NB ) ) ) )
    {
        return( $self->pass_error( $shem->error ) );
    }
    my $rc = $shem->write( $data );
    $shem->unlock;
    return( $self->pass_error( $shem->error ) ) if( !defined( $rc ) );
    return( $self );
}

1;
# NOTE: POD
__END__

=encoding utf-8

=head1 NAME

Apache2::SSI::Notes - Apache2 Server Side Include Notes

=head1 SYNOPSIS

    my $notes = Apache2::SSI::Notes->new(
        # 100K
        size => 102400,
        debug => 3,
    ) || die( Apache2::SSI::Notes->error );
    
    $notes->add( key => $val );
    
    $notes->clear;
    
    $notes->do(sub
    {
        # $_[0] = key
        # $_[1] = value
        $_[1] = Encode::decode( 'utf8', $_[1] );
    });
    
    # Or specify the keys to check
    $notes->do(sub
    {
        # $_[0] = key
        # $_[1] = value
        $_[1] = Encode::decode( 'utf8', $_[1] );
    }, qw( first_name last_name location ) );

    my $val = $notes-get( 'name' );

    # Get all as an hash reference
    my $hashref = $notes->get;

    $notes->set( name => 'John Doe' );

    # remove entry. This is different from $notes->set( name => undef() );
    # equivalent to delete( $hash->{name} );
    $notes->unset( 'name' );

=head1 VERSION

    v0.1.3

=head1 DESCRIPTION

L<Apache2::SSI::Notes> provides a mean to share notes in and out of Apache/mod_perl2 environment.

The interface is loosely mimicking L<APR::Table> on some, but not all, methods.

So you could have in your script, outside of Apache:

    $notes->set( API_ID => 1234567 );

And then, under mod_perl, in your file:

    <!--#if expr="note('API_ID')" -->

Normally, the C<note> function would work only for values set and retrieved inside the Apache/mod_perl2 framework, but with L<Apache2::SSI::Notes>, you can set a note, say, in a command line script and share it with your Server-Side Includes files.

To achieve this sharing of notes, L<Apache2::SSI::Notes> uses shared memory (see L<perlipc>) with L<Apache2::SSI::SharedMem> that does the heavy work.

However, this only works when L<Apache2::SSI> is in charge of parsing SSI files. Apache mod_includes module will not recognise notes stored outside of Apache/mod_perl framework.

=head1 METHODS

=head2 new

This instantiates a notes object. It takes the following parameters:

=over 4

=item C<debug>

A debug value will enable debugging output (equal or above 3 actually)

=item C<size>

The fixed size of the memory allocation. It defaults to 524,288 bytes which is 512 Kb, which should be ample enough.

=back

An object will be returned if it successfully initiated, or undef() upon error, which can then be retrieved with C<Apache2::SSI::Notes->error>. You should always check the return value of the methods used here for their definedness.

    my $notes = Apache2::SSI::Notes->new ||
        die( Apache2::SSI::Notes->error );

=head2 add

This is an alias for set.

=head2 clear

Empty all the notes. Beware that this will empty the notes for all the processes, since the notes are stored in a shared memory.

=head2 do

Provided with a callback as a code reference, and optionally an array of keys, and this will loop through all keys or the given keys if any, and call the callback passing it the key and its value.

For example:

    $notes->do(sub
    {
        my( $n, $v ) = @_;
        if( $n =~ /name/ )
        {
            $_[1] = Encode::decode( 'utf8', $_[1] );
        }
    });

=head2 get

Provided with a key and this retrieve its corresponding value, whatever that may be.

    my $val = $notes->get( 'name' );

If no key is provided, it returns all the notes as an hash reference.

    my $all = $notes->get;
    print( "API id is $all->{api}\n" );

Or maybe

    print( "API id is ", $notes->get->{api}, "\n" );

=head2 key

Set or get the shared memory key value.

=head2 read_mem

Access the shared memory and return the hash reference stored.

If an error occurred, C<undef()> is returned and an L<Module::Generic/error> is set, which can be retrieved like:

    die( $notes->error );

Be careful however, that L</get> may return C<undef()> not because an error would have occurred, but because this is the value you would have previously set.

=head2 remove

Removes the shared memory for this note.

=head2 set

Provided with a key and value pair, and this will set its entry into the notes hash accordingly.

    $notes->set( name => 'John Doe' );

It returns the notes object to enable chaining.

=head2 shem

Returns the current value of the L<Apache2::SSI::SharedMem> object.

You can also set an alternative value, but this is not advised unless you know what you are doing.

=head2 size

Sets or gets the shared memory block size.

This should really not be changed. If you do want to change it, you first need to remove the shared memory.

    $notes->shem->remove;

And then create a new L<Apache2::SSI::Notes> object with a different size parameter value.