NAME

NameRotator - date based name manipulator, as for a rolling backup destination directory


SYNOPSIS

        use NameRotator;
        
        # Windows, local
        #   $whelper updates names on local Windows box under c:\bak\xyz\
        my $whelper = WinNamer->winNamerCmds("c:\\bak", "xyz");
        my $wnamer = NameRotator->new($whelper, "err.log");
        my $wstoredir = $wnamer->setNextName( );
        # Unix, remote
        
        #   $xhelper uses ssh to update names under bkop@bkpstore:/bak/abc/
        my $xhelper = NixNamer->nixNamerCmds("/bak", "abc","bkpstore","bkop");
        my $xnamer = NameRotator->new($xhelper, "err.log");
        my $xstoredir = $xnamer->setNextName( );


DESCRIPTION

A NameRotator instance updates names according to contained rules. This was developed as part of a daily backup script, so default names and rules make the most sense in that context. The default rules serve to automatically generate a sequence of daily, weekly and monthly directory names for storing routine backups.

NameRotator uses a helper object (derived from class NamerCmds) to do the actual target naming operations: create, list,move, delete. Two helper class definitions are provided.

WinNamer

Runs on a Windows box -- manipulates local directory names.

NixNamer

Runs on a linux box -- manipulates dir names on a remote linux box via ssh

Additional helpers can be readily defined for different purposes. (Different storage target, different transport mechanism, etc)

A user generates rule compliant names via the NameRotator::setNextName method. (The 'daily' tag of the default initial rule is only accurately descriptive when setNextName happens to be invoked daily.) Directory names generated by the default daily rule are of the form:

 daily.100.2010010202153456
 daily.101.2010010302153457
 daily.102.2010010402153455

The rules designate a fixed number of slots available for daily backup (default: 6) and when all daily slots are full, the oldest slot gets reused. (Note in the example daily names given above that the middle tags, 100-102, are slot ID's, end tag indicates a name creation time of the form YYYYMMDDhhmmss.) Prior to overwriting a slot, the next rule gets applied. In this case, when all daily slots are full, the rule indicates that if a week has elapsed between the oldest daily name and the most recent weekly name creation, the oldest daily slot (and associated directory content) is automatically moved to a new weekly slot. A similar rule exists for moving the oldest weekly slot to a new monthly slot.

The rules aren't currently exposed via methods, so to update rules, one must make the appropriate @rotconfig tweak.

METHODS

NameRotator::new($myHelper, $logfile)

The constructor. Returns a reference to a new NameRotator instance.

$myHelper is a reference to an instance subclassed from NamerCmds.

$logfile is the filename where errors will get redirected.

NameRotator::setNextName()

This is the main function. It generates and returns a new name [slot] according to current context and rules. The new slot will have been put in a usable state. (e.g., the corresponding directory would be created and emptied).

NamerCmds::qName( $name )

Returns a fully qualified name in the target context. Any concrete subclass of NamerCmds must implement a consistent set of these name manipulation methods:

 x->dNew( $fspec [,$errlog] ) # create new name w/any associated context
 x->dLst( $fspec [,$errlog] ) # list names matching $fspec (ctime order)
 x->dMov( $fspecSrc, $fspecDst [,$errlog] ) # move (use fully qualified specs)
 x->dDel( $fspec [,$errlog] ) # delete name $fspec and its associated context
WinNamer::winNamerCmds($basedir, $myId);

Constructor. Returns reference to a new WinNamer instance. (Subclass of NamerCmds) Names will be manipulated in the context of local Windows directory at "$basedir\\$myId"

NixNamer::nixNamerCmds($basedir, $myId, $storehost, $storeuser);

Constructor. Returns reference to a new NixNamer instance. (Subclass of NamerCmds) Names will be manipulated in the context of remote unix host as seen from a local unix ssh connection to "$storehost@storeuser:$basedir\\$myId". Note that deaing with passwords is out of scope here. Consider using keyfiles if that's an issue.


CAVEATS

The directory deleters in current NamerCmds implementations will fail if the target directory contains subdirectories. (For my initial implementation, content was just a collection of tarfiles, which do get deleted correctly). The general error handling and constraint checking really ought to be improved before enabling support for recursive deletes.


LICENSE

This is released under the Artistic License...


AUTHOR

Steve Hardy -- shardy@@differentchairs.com -- http://www.differentchairs.com/NameRotator.pm.txt