HTTP::Response - Class encapsulating HTTP Responses

SYNOPSIS

        require HTTP::Response;

DESCRIPTION

       The HTTP::Response class encapsulate HTTP style responses.
       A response consist of a response line, some headers, and a
       (potential empty) content. Note that the LWP library will
       use HTTP style responses also for non-HTTP protocol
       schemes.

       Instances of this class are usually created and returned
       by the request() method of an LWP::UserAgent object:

        #...
        $response = $ua->request($request)
        if ($response->is_success) {
            print $response->content;
        } else {
            print $response->error_as_HTML;
        }

       HTTP::Response is a subclass of HTTP::Message and
       therefore inherits its methods.  The inherited methods
       often used are header(), push_header(), remove_header(),
       headers_as_string(), and content().  The header
       convenience methods are also available.  See the
       HTTP::Message manpage for details.

       The following additional methods are available:

       $r = HTTP::Response->new($rc, [$msg, [$header,
           [$content]]])
           Constructs a new HTTP::Response object describing a
           response with response code $rc and optional message
           $msg.  The message is a short human readable single
           line string that explains the response code.

       $r->code([$code])

       $r->message([$message])

       $r->request([$request])

       $r->previous([$previousResponse])
           These methods provide public access to the member
           variables.  The first two containing respectively the
           response code and the message of the response.

           The request attribute is a reference the request that
           because there might have been redirects and
           authorization retries in between.

           The previous attribute is used to link together chains
           of responses.  You get chains of responses if the
           first response is redirect or unauthorized.

       $r->status_line
           Returns the string "<code> <message>".  If the message
           attribute is not set then the official name of <code>
           (see the HTTP::Status manpage) is substituted.

       $r->base
           Returns the base URL for this response.  The return
           value will be a reference to a URI::URL object.

           The base URL is obtained from one the following
           sources (in priority order):

       1.      Embedded in the document content, for instance
               <BASE HREF="..."> in HTML documents.

       2.      A "Content-Base:" or a "Content-Location:" header
               in the response.

               For backwards compatability with older HTTP
               implementations we will also look for the "Base:"
               header.

       3.      The URL used to request this response. This might
               not be the original URL that was passed to
               $ua->request() method, because we might have
               received some redirect responses first.

               When the LWP protocol modules produce the
               HTTP::Response object, then any base URL embedded
               in the document (step 1) will already have
               initialized the "Content-Base:" header. This means
               that this method only perform the last 2 steps
               (the content is not always available either).

       $r->as_string
           Method returning a textual representation of the
           response.  Mainly useful for debugging purposes. It
           takes no arguments.

       $r->is_info

       $r->is_success

       $r->is_redirect

           These methods indicate if the response was
           informational, sucessful, a redirection, or an error.

       $r->error_as_HTML()
           Return a string containing a complete HTML document
           indicating what error occurred.  This method should
           only be called when $r->is_error is TRUE.

       $r->current_age
           This function will calculate the "current age" of the
           response as specified by <draft-ietf-http-v11-spec-07>
           section 13.2.3.  The age of a response is the time
           since it was sent by the origin server.  The returned
           value is a number representing the age in seconds.

       $r->freshness_lifetime
           This function will calculate the "freshness lifetime"
           of the response as specified by <draft-ietf-http-
           v11-spec-07> section 13.2.4.  The "freshness lifetime"
           is the length of time between the generation of a
           response and its expiration time.  The returned value
           is a number representing the freshness lifetime in
           seconds.

           If the response does not contain an "Expires" or a
           "Cache-Control" header, then this function will apply
           some simple heuristic based on 'Last-Modified' to
           determine a suitable lifetime.

       $r->is_fresh
           Returns TRUE if the response is fresh, based on the
           values of freshness_lifetime() and current_age().  If
           the response is not longer fresh, then it has to be
           refetched or revalidated by the origin server.

       $r->fresh_until
           Returns the time when this entiy is no longer fresh.

COPYRIGHT

       Copyright 1995-1997 Gisle Aas.

       This library is free software; you can redistribute it
       and/or modify it under the same terms as Perl itself.