##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

DiaColloDB::Upgrade::Base - DiaColloDB utilities: auto-magic upgrade: base class / API

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Upgrade::Base;
 
 ##========================================================================
 ## API
 
 $up      = $CLASS_OR_OBJECT->new($dbdir?, %opts);
 $pkg     = $CLASS_OR_OBJECT->label();
 $version = $up->toversion();
 $bool    = $up->needed();
 $bool    = $up->upgrade();
 
 ##========================================================================
 ## Backup & Revert
 
 $bool  = $up->backup();
 $dir   = $up->backupdir();
 
 $bool  = $up->revert();
 @files = $up->revert_created();
 @files = $up->revert_updated();
 
 ##========================================================================
 ## Utilities
 
 \%hdr   = $CLASS_OR_OBJECT->dbheader($dbdir?);
 \%uinfo = $up->uinfo($dbdir?,%info);
 $bool   = $up->updateHeader(\%extra_uinfo, \%extra_header_data);
 

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

DiaColloDB::Upgrade::Base
provides an API specification and common base class for
automatic upgrade packages used by
the L<dcdb-upgrade.perl|dcdb-upgrade.perl> script
via the L<DiaColloDB::Upgrade|DiaColloDB::Upgrade> package.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Upgrade::Base: API
=pod

=head2 API

=over 4

=item new

 $up = $CLASS_OR_OBJECT->new($dbdir?, %opts);

Create and return new upgrader-instance for the local L<DiaColloDB|DiaColloDB> directory C<$dbdir>.
If C<$dbdir> is specified, it is stored in C<$up-E<gt>{dbdir}> and its header is loaded to C<$up-E<gt>{hdr}>.
Common %opts, %$up:

 backup   => $bool,   ##-- perform auto-backup? (default=1)
 keep     => $bool,   ##-- keep temporary files? (default=0)
 timestamp=> $stamp,  ##-- timestamp of this upgrade operation (default:DiaColloDB::Utils::timestamp(time))

=item label

 $pkg = $CLASS_OR_OBJECT->label();

Returns upgrade package name.

=item toversion

 $version = $CLASS_OR_OBJECT->toversion();

Returns default target version; default just returns C<$DiaColloDB::VERSION>.
By convention, auto-applied upgrades use a target version with an all-zero final
version component, e.g. C<0.09.000> or C<0.10.000>.

=item needed

 $bool = $up->needed();

Returns true iff the upgrade C<$up> needs to be applied to the local L<DiaColloDB|DiaColloDB> index in C<$dbdir>.
Default implementation returns true iff C<$up-E<gt>L<dbheader|/dbheader>($dbdir)-E<gt>{version} E<lt> $up-E<gt>L<toversion|/toversion>()>,
using the L<version|version> package to parse and compare version strings.

=item upgrade

 $bool = $up->upgrade();

Performs upgrade in-place on the local L<DiaColloDB|DiaColloDB> index in C<$up-E<gt>{dbdir}>, returns true on success.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Upgrade::Base: Backup & Revert
=pod

=head2 Backup & Revert

=over 4

=item backup

 $bool = $up->backup();

Backup any files we expect to change during L<upgrade|/upgrade>() to C<$up-E<gt>L<backupdir|/backupdir>()>.
Subclasses should call this from their L<upgrade|/upgrade>() method.
Default implementation just backs up C<"$dbdir/header.json">, emitting a warning
if C<$up-E<gt>{backup}> is false.

=item backupdir

 $dir = $up->backupdir();

Returns name of a backup directory for this upgrade.
Default generates a reasonably unique directory name by concatenating
the upgrader's L<label>() suffix with the "wordlike" characters of C<$up-E<gt>{timestamp}>.
For L<revert|/revert>() to work, this directory name should be unique given C<$dbdir>
and the HASH-ref returned by the L<uinfo|/uinfo>() method.

=item revert

 $bool = $up->revert();

Reverts a previous upgrade by C<$up> on the local DB directory C<$up-E<gt>{dbdir}>.
Default implementation deletes files returned by L<$up-E<gt>revert_created|/revert_created>()
and copies files returned by L<$up-E<gt>revert_updated|/revert_updated>() from L<$up-E<gt>backupdir|/backupdir>().

=item revert_created

 @files = $up->revert_created();

Returns list of files created by this upgrade, for use with default L<revert|/revert>() implementation

=item revert_updated

 @files = $up->revert_updated();

Returns list of files updated by this upgrade, for use with default L<revert|/revert>() implementation.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Upgrade::Base: Utilities
=pod

=head2 Utilities

=over 4

=item dbheader

 \%hdr = $CLASS_OR_OBJECT->dbheader($dbdir?);

Reads, parses, and returns the header information C<$dbdir/header.json> for the
local L<DiaColloDB|DiaColloDB> index in C<$dbdir>.
Wraps L<DiaColloDB::Utils::loadJsonFile()|DiaColloDB::Utils/loadJsonFile>.
Default implementation uses cached C<$CLASS_OR_OBJECT-E<gt>{hdr}> if available.

=item uinfo

 \%uinfo = $up->uinfo($dbdir?,%info);

Returns a default upgrade-info C<%uinfo> structure for this upgrade, conventions:

 version_from => $vfrom,    ##-- source version (default='unknown')
 version_to   => $vto,      ##-- target version (default=$CLASS_OR_OBJECT->_toversion)
 timestamp    => $time,     ##-- timestamp (default=DiaColloDB::Utils::timestamp(time))
 by           => $who,      ##-- upgrade class or DiaColloDB::Upgrade:: suffix
 #...         => ...,       ##-- additional data from %info

=item updateHeader

 $bool = $up->updateHeader(\%extra_uinfo, \%extra_header_data);

Updates L<DiaColloDB|DiaColloDB> header C<"$up-E<gt>{dbdir}/header.json">
by prepending the upgrade-info structure returned by
C<$up-E<gt>L<uinfo|/uinfo>($coldb,%extra_uinfo)> onto
the headers C<"upgraded"> array and setting
header "version" to C<$uinfo-E<gt>{version_to}> if that value is true.
Subclasses may call this from their L<upgrade|/upgrade>() method.

=back

=cut



##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<dcdb-upgrade.perl(1)|dcdb-ugprade.perl>,
L<DiaColloDB::Upgrade(3pm)|DiaColloDB::Upgrade>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
