# Limit.pm: Class Used for Managing Collection Limits

package RDA::Object::Limit;

# $Id: Limit.pm,v 1.12 2015/11/16 16:15:43 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/RDA/Object/Limit.pm,v 1.12 2015/11/16 16:15:43 RDA Exp $
#
# Change History
# 20151116  MSC  Improve the documentation.

=head1 NAME

RDA::Object::Limit - Class Used for Managing Collection Limits

=head1 SYNOPSIS

 require RDA::Object::Limit;

=head1 DESCRIPTION

The objects of the C<RDA::Object::Limit> class are used to manage collection
limits. It is a subclass of L<RDA::Object|RDA::Object>.

The following methods are available:

=cut

use strict;

BEGIN
{ use Exporter;
  use RDA::Text qw(debug get_string);
  use RDA::Handle::Timing;
  use RDA::Object;
  use RDA::Object::Buffer;
}

# Define the global public variables
use vars qw($DUMP $STRINGS $VERSION @DUMP @ISA %SDCL);
$DUMP    = 0;
$VERSION = sprintf('%d.%02d', q$Revision: 1.12 $ =~ /(\d+)\.(\d+)/);
@DUMP    = (
  hsh => {
    'RDA::Limit::Default' => 1,
    'RDA::Limit::Estrict' => 1,
    'RDA::Limit::Efast'   => 1,
    'RDA::Limit::Pstrict' => 1,
    'RDA::Limit::Pfast'   => 1,
    },
  str => {_bkp => 0},
  );
@ISA     = qw(RDA::Object Exporter);
%SDCL    = (
  als => {
    ## no critic (Interpolation)
    'openAlertLog'    => ['$[LIM]', 'open_alert_log'],
    'openListenerLog' => ['$[LIM]', 'open_listener_log'],
    'resumeLimit'     => ['$[LIM]', 'resume'],
    'setLimit'        => ['$[LIM]', 'set_limit'],
    'suspendLimit'    => ['$[LIM]', 'suspend'],
    },
  beg => \&_begin_control,
  dep => [qw(RDA::Object::Buffer RDA::Object::Timing)],
  end => \&_end_control,
  inc => [qw(RDA::Object)],
  met => {
    'open_alert_log'    => {ret => 0},
    'open_listener_log' => {ret => 0},
    'resume'            => {ret => 0},
    'set_limit'         => {ret => 0},
    'suspend'           => {ret => 0},
    },
  top => 'LIM',
  );

# Define the global private constants

# Define the global private variables
my %tb_cls = (
  D => 'RDA::Limit::Default',
  E => 'RDA::Limit::Estrict',
  e => 'RDA::Limit::Efast',
  P => 'RDA::Limit::Pstrict',
  p => 'RDA::Limit::Pfast',
 );

# Report the package version
sub Version
{ return $VERSION;
}

=head2 S<$h = RDA::Object::Limit-E<gt>new($collector)>

The limit control object constructor. This method takes the collector reference
as an argument.

It is represented by a blessed hash reference. The following special keys are
used:

=over 12

=item S<    B<'col' > > Reference to the collector object

=item S<    B<'oid' > > Object identifier

=item S<    B<'_lim'> > Reference to the limit object

=back

Internal keys are prefixed by an underscore.

=cut

sub new
{ my ($cls, $col) = @_;

  # Create the control object and return its reference
  return bless {
    col  => $col,
    oid  => 'LIM',
    _lim => _set_limit($col, $tb_cls{'D'}),
    }, ref($cls) || $cls;
}

=head2 S<$h-E<gt>resume>

This method restores the original limit treatment. It returns the object
reference.

=cut

sub resume
{ my ($slf) = @_;
  my ($bkp);

  die get_string('NO_BACKUP') unless exists($slf->{'_bkp'});
  return _switch($slf, {}, $slf->{'_bkp'});
}

sub _switch
{ my ($slf, $bkp, $rec) = @_;

  foreach my $key (keys(%{$rec}))
  { $slf->{$key} = $bkp->{$key} if exists($bkp->{$key});
    if (defined($rec->{$key}))
    { ($slf->{$key}, $bkp->{$key}) = ($rec->{$key}, $slf->{$key});
    }
    else
    { $bkp->{$key} = delete($slf->{$key});
    }
  }
  return $slf;
}

=head2 S<$h-E<gt>set_limit([mode])>

This method defines the limit mode when the argument represents a valid
mode. It supports the following modes:

=over 9

=item B<    'D' > Default mode

=item B<    'E' > Strict Event mode

=item B<    'e' > Fast Event mode

=item B<    'P' > Strict period mode

=item B<    'p' > Fast period mode

=back

It returns the active mode.

=cut

sub set_limit
{ my ($slf, $mod) = @_;

  $slf->{'_lim'} = _set_limit($slf->{'col'}, $tb_cls{$mod})
    if defined($mod) && exists($tb_cls{$mod});
  return $slf->{'_lim'}->get_oid;
}

sub _set_limit
{ my ($col, $cls) = @_;

  eval "require $cls";
  die get_string('ERR_REQUIRE', $cls, $@) if $@;
  return $cls->new($col);
}

=head2 S<$h-E<gt>suspend([$mod])>

This method suspends the limit treatment. You can specify a new mode as an
argument. It returns the object reference.

=cut

sub suspend
{ my ($slf, $mod) = @_;
  my ($bkp);

  $bkp = {};
  return _switch($slf, $bkp, {
    _bkp => $bkp,
    _lim => _set_limit($slf->{'col'},
              (defined($mod) && exists($tb_cls{$mod})) ? $tb_cls{$mod}
                                                       : ref($slf->{'_lim'})),
    });
}

=head1 LIMIT METHODS

=head2 S<$h-E<gt>get_age_limit($age)>

This method defines the approach for selecting files based on their age.

=cut

sub get_age_limit
{ return shift->{'_lim'}->get_age_limit(@_);
}

=head2 S<$h-E<gt>get_file_limit($context)>

This method defines the approach for selecting file based on a context
strategy.

=cut

sub get_file_limit
{ return shift->{'_lim'}->get_file_limit(@_);
}

=head2 S<$h-E<gt>open_alert_log($file[,$vms])>

This method returns a buffer on the specified alert log file. It returns an
undefined value in case of errors.

=cut

sub open_alert_log
{ return shift->{'_lim'}->open_alert_log(@_);
}

=head2 S<$h-E<gt>open_listener_log($file[,$size])>

This method returns a buffer on the specified listener log file. It returns an
undefined value in case of errors.

=cut

sub open_listener_log
{ return shift->{'_lim'}->open_listener_log(@_);
}

# --- SDCL extensions ---------------------------------------------------------

# Attach the limit control object
sub _begin_control
{ my ($pkg) = @_;

  $pkg->set_top('LIM', $pkg->get_collector->get_limit);
  return;
}

# Detach the limit control object
sub _end_control
{ my ($pkg) = @_;

  $pkg->set_top('LIM');
  return;
}

1;

__END__

=head1 SEE ALSO

L<RDA::Agent|RDA::Agent>,
L<RDA::Handle::Timing|RDA::Handle::Timing>,
L<RDA::Limit::Common|RDA::Limit::Common>,
L<RDA::Limit::Default|RDA::Limit::Default>,
L<RDA::Limit::Efast|RDA::Limit::Efast>,
L<RDA::Limit::Estrict|RDA::Limit::Estrict>,
L<RDA::Limit::Event|RDA::Limit::Event>,
L<RDA::Limit::Period|RDA::Limit::Period>,
L<RDA::Limit::Pfast|RDA::Limit::Pfast>,
L<RDA::Limit::Pstrict|RDA::Limit::Pstrict>,
L<RDA::Object|RDA::Object>,
L<RDA::Object::Buffer|RDA::Object::Buffer>,
L<RDA::Object::Timing|RDA::Object::Timing>,
L<RDA::Text|RDA::Text>

=head1 COPYRIGHT NOTICE

Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved.

=head1 TRADEMARK NOTICE

Oracle and Java are registered trademarks of Oracle and/or its
affiliates. Other names may be trademarks of their respective owners.

=cut