NAME

SeeAlso::Source::BeaconAggregator - Beacon files as source for SeeAlso::Server

SYNOPSIS

  use CGI;
  use SeeAlso::Identifier::ISSN;
  use SeeAlso::Server;
  use SeeAlso::Source::BeaconAggregator;

  my $srcdescription = {
        "ShortName" => "TestService",                               # 16 Characters
         "LongName" => "Sample SeeAlso Beacon Aggregator",          # 48 characters
#     "Description" => "The following services are contained: ...", # 1024 Characters
      "DateModfied" => "...",
    _dont_advertise => 1,
  };

  my $CGI = CGI->new(); binmode(STDOUT, ":utf8");

  my $source = SeeAlso::Source::BeaconAggregator->new(
            'file' => "/path/to/existing/database",
 'identifierClass' => SeeAlso::Identifier::ISSN->new(),
         'verbose' => 1,
     'description' => $srcdescription,
  );

  my $server = SeeAlso::Server->new (
        'cgi' => $CGI,
         xslt => "/client/showservice.xsl",    # => <?xml-stylesheet?> + <?seealso-query-base?>
   clientbase => "/client/",      # => <?seealso-client-base?>
      expires => "+2d",
  );

  my $rawid = $CGI->param('id') || "";
  my $identifier = $rawid ? SeeAlso::Identifier::ISSN->new($rawid) : "";
  my $result = $server->query($source, $identifier ? $identifier->value() : undef);
  print $result;

DESCRIPTION

This Module allows a collection of BEACON files (cf. http://de.wikipedia.org/wiki/Wikipedia:BEACON) to be used as SeeAlso::Source (probably in the context of an SeeAlso::Server application). Therefore it implements the four methods documented in SeeAlso::Source

The BEACON files (lists of non-local identifiers of a certain type documenting the coverage of a given online database plus means for access) are imported by the methods provided by SeeAlso::Source::BeaconAggregator::Maintenance.pm, usually by employing the script sasbactrl.pl as command line client.

Serving other formats than SeeAlso or providing a BEACON file with respect to this SeeAlso service is achieved by using SeeAlso::Source::BeaconAggregator::Publisher.

USAGE

Class methods

beaconfields ( [ $what ] )

(Class method) Called without parameter returns an array of all valid field names for meta headers

  @meta_supported = SeeAlso::Source::BeaconAggregator->beaconfields();

With given parameter $what in scalar context returns the column name of the database for the abstract field name. In array context additionally the column type and optional flag designating a mandatory entry are returned.

  $internal_col = SeeAlso::Source::BeaconAggregator->beaconfields('FORMAT');

  ($internal_col, $specs, $mandatory)
      = SeeAlso::Source::BeaconAggregator->beaconfields('FORMAT');

Fields are:

  # mandatory
 FORMAT, TARGET
  # as of BEACON spec
 VERSION, FEED, TIMESTAMP, REVISIT, UPDATE
 CONTACT, INSTITUTION, ISIL, 
  # from the experimental BEACON spec
 MESSAGE, ONEMESSAGE, SOMEMESSAGE
 PREFIX, EXAMPLES
  # later additions
 COUNT, REMARK
  # current practise
 NAME
  # experimental extension "Konkordanzformat"
 ALTTARGET, IMGTARGET

osdKeys ( [ $what ] )

(Class method) Called without parameter returns an array of all valid element names for the OpenSearchDescription:

  @meta_names = SeeAlso::Source::BeaconAggregator->osdKeys();

With given parameter $what returns the value for the given OpenSearchDescription element:

  $osd_value = SeeAlso::Source::BeaconAggregator->beaconfields('LongName');

OSD elements are

 ShortName, Description
 Contact, Tags, LongName, Developer, Attribution, SyndicationRight, AdultContent
 Language, InputEncoding, OutputEncoding
  # special for SeeAlso::Family
 Example, Examples, BaseURL, DateModified, Source

SeeAlso::Source methods

new( %accessor [, %options ] )

Creates the SeeAlso::Source::BeaconAggregator object and connects to an existing database previously created with the methods from SeeAlso::Source::BeaconAggregator::Maintenance (currently SQLlite)

Accessor options:

dbh

handle of a database already connected to

dbroot

optional path to prepend to dsn or file

dsn

directory name (directory contains the database file "<dsn>-db"

file

full path of the database

Other options:

identifierClass

contains an already instantiated object of that class

verbose (0|1)

description

Hashref with options to be piped through to SeeAlso::Source

aliasfilter

Hashref with aliases to be filtered out from query results

cluster

dsn of a beacon source of identical identifier type giving a mapping (hash / altid) e.g. invalidated identifiers -> current identifiers.

When the identifier supplied for query() is mentioned in this table, the query will be executed against the associated current identifier and all invalidated ones (backward translation of forward translation).

When not (the mapping might not necessarily include the identiy mapping), the query behaves as if no "cluster" was given.

For translation between different identifier schemes before querying, use an appropriate SeeAlso::Identifier class.

Returns undef if unable to DBI->connect() to the database.

description ()

Inherited from SeeAlso::Source.

about ()

Inherited from SeeAlso::Source.

set_aliasfilter ( @aliaslist )

Init the hash with

query( [ $identifier] )

Returns a SeeAlso::Response listing all matches to the given string or SeeAlso::Identifier $identifier.

Auxiliary Methods

Sequence numbers (Seqnos) are primary keys to the database table where each row contains the meta fields of one BEACON file

Seqnos ( $colname , $query )

Return Seqnos from querying the table with all beacon headers in column (field name) $colname for a $query (which may contain SQL placeholders '%').

RepoCols ( [ $colname [, $seqno_or_alias ]] )

Return a hashref indexed by seqence number of all values of column (header field) $colname [alias] optionally constrained by a SeqNo or Alias.

Default for $colname is '_alias'.

OSDValues ( [ $key ] )

Returns a hashref containing the OpenSearchDescription keywords and their respective values.

admhash ( )

Returns a hashref with the contents of the admin table (readonly, not tied).

autoIdentifier ()

Initializes a missing identifierClass from the IDENTIFIER_CLASS entry in the admin table.

findExample ( $goal, $offset, [ $sth ])

Returns a hashref

 {       id => identier,
   response => Number of beacon files matching "/" Sum of individual hit counts
 }

for the $offset'th identifier occuring in at least $goal beacon instances.

$sth will be initialized by a statement handle to pass to subsequent calls if defined but false.

BUGS

SUPPORT

Send mail to the author

AUTHOR

Thomas Berger <ThB@gymel.com>

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.

SEE ALSO

perl(1).

cpanm SeeAlso::Source::BeaconAggregator

perl -MCPAN -e shell
install SeeAlso::Source::BeaconAggregator