[Summary view] [Print] [Text view]

   1  # Copyright (c) 1999-2004 Graham Barr <gbarr@pobox.com>. All rights reserved.
   2  # This program is free software; you can redistribute it and/or
   3  # modify it under the same terms as Perl itself.
   4  
   5  package Net::LDAP::Control::Sort;
   6  
   7  use vars qw(@ISA $VERSION);
   8  use Net::LDAP::Control;
   9  
  10  @ISA = qw(Net::LDAP::Control);
  11  $VERSION = "0.02";
  12  
  13  use Net::LDAP::ASN qw(SortRequest);
  14  use strict;
  15  
  16  sub init {
  17    my($self) = @_;
  18  
  19    if (exists $self->{value}) {
  20      $self->value($self->{value});
  21    }
  22    elsif (exists $self->{order}) {
  23      $self->order(ref($self->{order}) ? @{$self->{order}} : $self->{order});
  24    }
  25  
  26    $self;
  27  }
  28  
  29  sub value {
  30    my $self = shift;
  31  
  32    if (@_) {
  33      my $value = shift;
  34  
  35      delete $self->{value};
  36      delete $self->{order};
  37      delete $self->{error};
  38  
  39      my $asn = $SortRequest->decode($value);
  40  
  41      unless ($asn) {
  42        $self->{error} = $@;
  43        return undef;
  44      }
  45  
  46      $self->{order} = [ map {
  47        ($_->{reverseOrder} ? "-" : "")
  48        . $_->{type}
  49        . (defined($_->{orderingRule}) ? ":$_->{orderingRule}" : "")
  50      } @{$asn->{order}}];
  51  
  52      return $self->{value} = $value;
  53    }
  54  
  55    unless (defined $self->{value}) {
  56      $self->{value} = $SortRequest->encode(
  57        order => [
  58      map {
  59        /^(-)?([^:]+)(?::(.+))?/;
  60        {
  61          type => $2,
  62          (defined $1 ? (reverseOrder => 1)  : ()), 
  63          (defined $3 ? (orderingRule => $3) : ())
  64        }
  65      } @{$self->{order} || []}
  66        ]
  67      ) or $self->{error} = $@;
  68    }
  69  
  70    $self->{value};
  71  }
  72  
  73  sub valid { exists shift->{order} }
  74  
  75  sub order {
  76    my $self = shift;
  77  
  78    if (@_) {
  79      # @_ can either be a list, or a single item.
  80      # if a single item it can be a string, which needs
  81      # to be split on spaces, or a reference to a list
  82      #
  83      # Each element has three parts
  84      #  leading - (optional)
  85      #  an attribute name
  86      #  :match-rule (optional)
  87  
  88      my @order = (@_ == 1) ? split(/\s+/, $_[0]) : @_;
  89  
  90      delete $self->{'value'};
  91      delete $self->{order};
  92      delete $self->{error};
  93  
  94      foreach (@order) {
  95        next if /^-?[^:]+(?::.+)?$/;
  96  
  97        $self->{error} = "Bad order argument '$_'";
  98        return;
  99      }
 100  
 101      $self->{order} = \@order;
 102    }
 103  
 104    return @{$self->{order}};
 105  }
 106  
 107  1;
 108  
 109  __END__
 110  
 111  
 112  =head1 NAME
 113  
 114  Net::LDAP::Control::Sort - Server Side Sort (SSS) control object
 115  
 116  =head1 SYNOPSIS
 117  
 118   use Net::LDAP::Control::Sort;
 119   use Net::LDAP::Constant qw(LDAP_CONTROL_SORTRESULT);
 120  
 121   $sort = Net::LDAP::Control::Sort->new(
 122     order => "cn -phone"
 123   );
 124  
 125   $mesg = $ldap->search( @args, control => [ $sort ]);
 126  
 127   ($resp) = $mesg->control( LDAP_CONTROL_SORTRESULT );
 128  
 129   print "Results are sorted\n" if $resp and !$resp->result;
 130  
 131  =head1 DESCRIPTION
 132  
 133  C<Net::LDAP::Control::Sort> is a sub-class of
 134  L<Net::LDAP::Control>.  It provides a class
 135  for manipulating the LDAP Server Side Sort (SSS) request control
 136  C<1.2.840.113556.1.4.473> as defined in RFC-2891
 137  
 138  If the server supports sorting, then the response from a search
 139  operation will include a sort result control. This control is handled
 140  by L<Net::LDAP::Control::SortResult>.
 141  
 142  =head1 CONSTRUCTOR ARGUMENTS
 143  
 144  =over 4
 145  
 146  =item order
 147  
 148  A string which defines how entries may be sorted. It consists of
 149  multiple directives, spearated by whitespace. Each directive describes how
 150  to sort entries using a single attribute. If two entries have identical
 151  attributes, then the next directive in the list is used.
 152  
 153  Each directive specifies a sorting order as follows
 154  
 155    -attributeType:orderingRule
 156  
 157  The leading C<-> is optional, and if present indicates that the sorting order should
 158  be reversed. C<attributeType> is the attribute name to sort by. C<orderingRule> is optional and
 159  indicates the rule to use for the sort and should be valid for the given C<attributeType>.
 160  
 161  Any one attributeType should only appear once in the sorting list.
 162  
 163  B<Examples>
 164  
 165    "cn"         sort by cn using the default ordering rule for the cn attribute
 166    "-cn"        sort by cn using the reverse of the default ordering rule
 167    "age cn"     sort by age first, then by cn using the default ordering rules
 168    "cn:1.2.3.4" sort by cn using the ordering rule defined as 1.2.3.4
 169  
 170  =back
 171  
 172  
 173  =head1 METHODS
 174  
 175  As with L<Net::LDAP::Control> each constructor argument
 176  described above is also available as a method on the object which will
 177  return the current value for the attribute if called without an argument,
 178  and set a new value for the attribute if called with an argument.
 179  
 180  =head1 SEE ALSO
 181  
 182  L<Net::LDAP>,
 183  L<Net::LDAP::Control::SortResult>,
 184  L<Net::LDAP::Control>,
 185  http://www.ietf.org/rfc/rfc2891.txt
 186  
 187  =head1 AUTHOR
 188  
 189  Graham Barr E<lt>gbarr@pobox.comE<gt>
 190  
 191  Please report any bugs, or post any suggestions, to the perl-ldap mailing list
 192  E<lt>perl-ldap@perl.orgE<gt>
 193  
 194  =head1 COPYRIGHT
 195  
 196  Copyright (c) 1999-2004 Graham Barr. All rights reserved. This program is
 197  free software; you can redistribute it and/or modify it under the same
 198  terms as Perl itself.
 199  
 200  =cut