Apache::Wombat::Connector - Apache/mod_perl connector

- NAME
- SYNOPSIS
- DESCRIPTION
- CONSTRUCTOR
- ACCESSOR METHODS
- PUBLIC METHODS
- LIFECYCLE METHODS
- SEE ALSO
- AUTHOR

# NAME

Apache::Wombat::Connector - Apache/mod_perl connector

# SYNOPSIS

      # My/Handler.pm

      my $connector = Apache::Wombat::Connector->new();
      $connector->setName('Apache connector');
      $connector->setScheme('http');
      $connector->setSecure(undef)

      # ... create a Service as $service
      # calls $connector->setContainer() internally
      $service->addConnector($connector);

      sub child_init_handler {
          my $r = shift;
          $connector->start();
          return Apache::Constants::OK;
      }

      sub handler {
          my $r = shift;
          $connector->process($r);
          return $r->status();
      }

      sub child_exit_handler {
          my $r = shift;
          $connector->stop();
          return Apache::Constants::OK;
      }

      # httpd.conf:
      <Location />
        SetHandler perl-script
        PerlChildInitHandler My::Handler::child_init_handler
        PerlHandler          My::Handler::handler
        PerlChildExitHandler My::Handler::child_exit_handler
      </Location>

# DESCRIPTION

This Connector receives requests from and returns responses to an Apache web server within which Wombat is embedded. It does not listen on a socket but rather provides a `process()` entry point with which it receives and returns an Apache instance. It provides HttpRequest and HttpResponse implementations that delegate many fields and methods to an underlying Apache::Request instance.

ApacheConnector assumes an Apache 1 & mod_perl 1 single-threaded multi-process environment. It's unknown whether it will work in any other environment.

Requires mod_perl to be compiled with at least one of the following options:

      DYNAMIC=1
      PERL_TABLE_API=1
      EVERYTHING=1

# CONSTRUCTOR

`new()`
  Create and return an instance, initializing fields to default values.

# ACCESSOR METHODS

`getContainer()`
  Return the Container used for processing Requests received by this Connector.

`setContainer($container)`
  Set the Container used for processing Requests received by this Connector.

  Parameters:

  $container
    the Wombat::Container used for processing Requests

`getName()`
  Return the display name of this Connector.

`getScheme()`
  Return the scheme that will be assigned to Requests recieved through this Connector. Default value is http.

`setScheme($scheme)`
  Set the scheme that will be assigned to Requests received through this Connector.

  Parameters:

  $scheme
    the scheme

`getSecure()`
  Return the secure connection flag that will be assigned to Requests received through this Connector. Default value is false.

`setSecure($secure)`
  Set the secure connection flag that will be assigned to Requests received through this Connector.

  Parameters:

  $secure
    the boolean secure connection flag

# PUBLIC METHODS

`await()`
  Begin listening for requests. Returns immediately since Apache itself listens for requests.

`createRequest()`
  Create and return a Apache::Wombat::Request instance.

`createResponse()`
  Create and return a Apache::Wombat::Response instance.

`process($r)`
  Process the given Apache request record (converting it to an instance of Apache::Request in the process), generating and sending a response. This method is meant to be called during the content handling phase by a PerlHandler subroutine; after calling this method, the handler should examine the Apache request's status code and return an appropriate value.

  Parameters:

  $r
    the Apache instance

# LIFECYCLE METHODS

`start()`
  Prepare for active use of this component. This method should be called before any of the public methods of the component are utilized.

  Throws:

  Wombat::LifecycleException
    if the component has already been started

`stop()`
  Gracefully terminate active use of this component. Once this method has been called, no public methods of the component should be utilized.

  Throws:

  Wombat::LifecycleException
    if the component is not started

# SEE ALSO

mod_perl, Apache, the Apache::Request manpage, the Wombat::Container manpage, the Apache::Wombat::Request manpage, the Apache::Wombat::Response manpage, the Wombat::Exception manpage

# AUTHOR

Brian Moseley, bcm@maz.org