I wish for a consistent API and documentation in the upcoming mod_perl 2.0
implementation. For example, right now, we have several different ways to
tweak outgoing response headers. Some headers have their own method
($r->content_type), while others are aggregated ($r->header_out). Some of
the ones that have their own accessor have slightly tweaked method names
($r->set_content_length). Worse, the documentation conflicts with the
implementation. perldoc Apache says "You should not define any
'Content-XXX' headers by calling [header_out], because these headers use
their own specific methods." However, there is no method content_length,
you either have to set it using header_out, or use Apache::File and get
set_content_length.
The origin of these inconsistencies has, I think, been the years-long
development of both mod_perl and Apache 1.x. Some headers may have their
own accessors because they need to tweak something in the Apache core when
they get set. Regardless, I propose a more consistent API for mod_perl
2.0. When setting an outbound header, I would prefer to use all method
calls. I would also be fine with using a generic method like
$r->header_out. However, I think that accessor method interface is
preferrable because it lets us plug in funky logic that may be needed when
a header is set. The header_out interface can have that too, but only if
it switches on the hash key, in which case it is just identical to but
slower than the accessor method interface.
That's my two cents. Since I'm bitching about it, I volunteer to help be
the interface and documentation police for 2.0
-jwb
