cvs commit: httpd-apreq/Request Request.pm

[jo...@apache.org]

joes        2003/04/30 10:46:48

  Modified:    .        Changes
               Request  Request.pm
  Log:
  Add Steve Hay's documentation on subclassing Apache::Request.
  
  Revision  Changes    Path
  1.51      +4 -0      httpd-apreq/Changes
  
  Index: Changes
  ===================================================================
  RCS file: /home/cvs/httpd-apreq/Changes,v
  retrieving revision 1.50
  retrieving revision 1.51
  diff -u -r1.50 -r1.51
  --- Changes	18 Apr 2003 15:58:13 -0000	1.50
  +++ Changes	30 Apr 2003 17:46:48 -0000	1.51
  @@ -2,6 +2,10 @@
   
   =over 4
   
  +=item 1.14 - April 30, 2003
  +
  +Add documentation for subclassing Apache::Request. [Steve Hay]
  +
   =item 1.13 - April 18, 2003
   
   Sync test suite uris with latest Apache::Test [Stas]
  
  
  
  1.23      +55 -0     httpd-apreq/Request/Request.pm
  
  Index: Request.pm
  ===================================================================
  RCS file: /home/cvs/httpd-apreq/Request/Request.pm,v
  retrieving revision 1.22
  retrieving revision 1.23
  diff -u -r1.22 -r1.23
  --- Request.pm	27 Feb 2003 22:21:40 -0000	1.22
  +++ Request.pm	30 Apr 2003 17:46:48 -0000	1.23
  @@ -240,6 +240,61 @@
   
   =back
   
  +=head1 SUBCLASSING Apache::Request
  +
  +The Apache::Request class cannot be subclassed directly because its constructor
  +method does not bless new objects into the invocant class. Instead, it always
  +blesses them into the Apache::Request class itself.
  +
  +However, there are two main ways around this.
  +
  +One way is to have a constructor method in your subclass that invokes the
  +superclass constructor method and then re-blesses the new object into itself
  +before returning it:
  +
  +	package MySubClass;
  +	use Apache::Request;
  +	our @ISA = qw(Apache::Request);
  +	sub new {
  +		my($class, @args) = @_;
  +		return bless $class->SUPER::new(@args), $class;
  +	}
  +
  +The other way is to aggregate and delegate: store an Apache::Request object in
  +each instance of your subclass, and delegate any Apache::Request methods that
  +you are not overriding to it:
  +
  +	package MySubClass;
  +	use Apache::Request;
  +	sub new {
  +		my($class, @args) = @_;
  +		return bless { r => Apache::Request->new(@args) }, $class;
  +	}
  +	sub AUTOLOAD {
  +		my $proto = shift;
  +		our $AUTOLOAD;
  +		my $name = $AUTOLOAD;
  +		$name =~ s/^.*:://;
  +		return $proto->$name(@_);
  +	}
  +
  +In fact, the aggregate/delegate solution is made easier by some magic in the
  +Apache::Request class. If the instances of your subclass are hash references
  +then you can actually inherit from Apache::Request as long as the
  +Apache::Request object is stored in an attribute called "r" or "_r". (The
  +Apache::Request class effectively does the delegation for you automagically, as
  +long as it knows where to find the Apache::Request object to delegate to.)
  +
  +Thus, the second example above can be simplified as:
  +
  +	package MySubClass;
  +	use Apache::Request;
  +	our @ISA = qw(Apache::Request);
  +	sub new {
  +		my($class, @args) = @_;
  +		return bless { r => Apache::Request->new(@args) }, $class;
  +	}
  +
   =head1 Apache::Upload METHODS
   
   =over 4