/ 
SeeAlso-Source-BeaconAggregator-0.2_83
River stage zero No dependents
/ SeeAlso::Source::BeaconAggregator::Publisher

NAME

SeeAlso::Source::BeaconAggregator::Publisher - additional methods for SeeAlso::Source::BeaconAggregator

SYNOPSIS

$source = SeeAlso::Source::BeaconAggregator::Publisher->new(...);

DESCRIPTION

This package provides the functionallity to export a BEACON file from the data connected with an SeeAlso::Source::BeaconAggregator instance and also the additional formats "redirect" and "sources" which universally can be used as callbacks for SeeAlso::Server (replacing the default "seealso" method yielding JSON data).

new ( ... )

Creates an SeeAlso::Source::BeaconAggregator object with additional methods from this package enabled

activate ()

Makes SeeAlso::Source::BeaconAggregator objects member of this class, globally enabling the additional methods

Usage:

$db = SeeAlso::Source::BeaconAggregator::Maintenance->new(...);
...
do stuff
...
require SeeAlso::Source::BeaconAggregator::Publisher
        or die "could not require Publisher extension";
SeeAlso::Source::BeaconAggregator::Publisher->activate();   # "recast" all objects
...
do more stuff

beacon ( [dumpmeta arguments] )

produces a BEACON file (however, $cgibase is mandatory)

dumpmeta ( [$cgibase, [$uAformatname, [$headersonly]]] [, $preset])

produces only the meta fields of a BEACON file

Meta fields are generated from the $preset Hashref, falling back to values stored in the database, falling back to reasonable default values.

Arguments:

$cgibase

URL of the SeeAlso service the BEACON file is provided for

$uAformatname

unAPI format name to be used as target (Default: "sources")

$headersonly

currently unused

$preset

Hashref of Beacon header fields overriding the contents of the database

Regular Usage:

$db = SeeAlso::Source::BeaconAggregator::Publisher->new(...);
binmode(STDOUT, ":utf8");
my $cgibase = "http://address/of/service";
my ( $error, $headerref) = $db->beacon($cgibase, @ARGV, {'FORMAT' => 'PND-BEACON'});

CGI Usage:

 $format = $CGI->param('format') || "";
 if ( $format eq "beacon" ) {  # bypass SeeAlso::Server->query() b/c performance / interim storage
                                 insert access restrictions here...
     do_beacon($source, $CGI);
   }
 ...

sub do_beacon {
  my ($self, $cgi) = @_;           # Of type SeeAlso::Source::BeaconAggregator
  unless ( $self->can("beacon") ) {
      croak "On the fly generation of beacon Files not supported by this service";}
  my $cgibase = $cgi->url(-path_info=>1);

  print $cgi->header( -status => 200,
                     -expires => '+1d',
                        -type => 'text/plain',
                     -charset => 'utf-8',
                     );
  return $self->beacon($cgibase, "sources", {});     # prints directly to stdout..., returns $error, $headerref
}

redirect ( $server, $format, $extra, $query )

Produces an HTTP redirect page, HTML content contains very terse details in case of multiple results.

This subroutine may be used as callback method in SeeAlso::Server

Usage is a bit cludgy due to author's lack of understanding of SeeAlso::Server

$source = SeeAlso::Sources::BeaconAggregator::Publisher->new(...);
$CGI = CGI->new();

$formats = {
  ...
  redirect => {
         type => "text/html", 
         docs => "http://www.endofthe.net/",
#        method => \&SeeAlso::Source::BeaconAggregator::Publisher::redirect,
#redirect_300 => 'sources',
              }
};

$server   = SeeAlso::Server->new (
        'cgi' => $CGI,
    'formats' => $formats,
     ...
);

# Closure as fix: Server.pm does not expose self, $source and the CGI object to the format methods
my $oref = \&SeeAlso::Source::BeaconAggregator::Publisher::redirect;
$server->{'formats'}->{'redirect'}->{method}
  = sub {return &$oref($source, $server, $method, $formats->{$method}, @_)};

my $result = $server->query($source);

Arguments:

$server

SeeAlso::Server object. Must contain a CGI object

$format

Name of a format registered with the $server object ()

$extra

Hashref with the following configuration directives

redirect_300 => CGI 'format' parameter to be used in HTML content (eg. format=sources)

force_single => Only regard the first hit (thus always redirect)
$query

Identifier to be queried

sources ( $server, $format, $extra, $query )

Produces an HTML page with details to the queried identifier (description of sources)

This subroutine may be used as callback method in SeeAlso::Server (cf. description of redirect above

$server

SeeAlso::Server object

$format

Format selected for $server

$extra

Hashref with the following configuration directives

css => URL of css file to be referenced
$query

Identifier to be queried

get_meta ()

Returns a pair of hash references:

  1. OSD fields

  2. Beacon header fields

AUTHOR

Thomas Berger
CPAN ID: THB
gymel.com
THB@cpan.org

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.