/ 
FTN-Message-serialno-20141120
River stage zero No dependents
/ FTN::Message::serialno::File

NAME

FTN::Message::serialno::File - handles FTN message serialno via file in dedicated directory

VERSION

Version 20141120

SYNOPSIS

use FTN::Message::serialno::File ();

my $serialno = FTN::Message::serialno::File -> new( directory => '/home/user/ftn/_serialno' );

my $new_serialno = $serialno -> get_serialno;

die 'cannot get new serialno' unless defined $new_serialno;

# use $new_serialno value for constructing new message

DESCRIPTION

This class is for handling serialno value for new FTN messages. Assigns consecutive unique values.

USAGE

This class has the following methods:

new

Class constructor. Has the following options:

  • directory

    The only mandatory option. Specifies directory where files with serialno are being created and removed. It is recommended to have it as a dedicated directory and not to keep any other files in it.

    FTN::Message::serialno::File -> new( directory => '/some/dir' );

  • file_extension

    Serialno files extension. Dot before its value will be added.

    FTN::Message::serialno::File -> new( directory => '/some/dir',
                                     file_extension => 'seq',
                                   );

    Default value is 'sn'.

  • filename_pattern

    Defines pattern and matching files in the directory are considered as serialno files and hence can be removed/renamed. File extension shouldn't be specified as it's added automatically.

  • filename_format

    Defines filename format (as in printf) with encoded serialno value. File extension shouldn't be specified as it's added automatically. Filename created with filename_format should match filename_pattern.

    Default value is '%x'.

  • max_tries

    Defines how many times renaming of the file is tried before it is considered failed.

    Default value is 5.

  • very_first_init

    Defines reference to a function for generating very first serialno value in case there are no matching files in the directory.

    The possible values:

    • CURRENT_UNIXTIME

      use current unixtime as a starting value.

      FTN::Message::serialno::File -> new( directory => '/some/dir',
                                     very_first_init => 'CURRENT_UNIXTIME',
                                   );

    • CURRENT_UNIXTIME_MINUS_3_YEARS

      use current unixtime minus 3 years as a starting value.

    • user defined function

      FTN::Message::serialno::File -> new( directory => '/some/dir',
                                     very_first_init => sub {
                                       42; # voices in my head tell me to use 42
                                     },
                                   );

    Default value is function returning 1.

  • serialno_format

    serialno format (as in printf) for a return value. Can be changed in case you want another casing ('%08X') or no leading zeroes ('%x') for example.

    Default value is '%08x'.

get_serialno()

Method that does all the work and returns either new valid serialno value or undef.

If this is the very first run and no signs of previous serialno values, creates new file with starting value and returns it.

If there is just one file with previous serialno value, tries to rename it to a new value (up to defined value (constructor option) times due to parallel execution) and returns that new value on success.

If there are more than one file with previous serialno values, sorts them and removes all but last one. Then tries previous approach with last value.

If renaming fails more than allowed count, undef is returned.

AUTHOR

Valery Kalesnik, <valkoles at gmail.com>

BUGS

Please report any bugs or feature requests to bug-ftn-message-serialno-file at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=FTN-Message-serialno-File. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc FTN::Message::serialno::File

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2014 Valery Kalesnik.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.