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, Apache::Request, Wombat::Container, Apache::Wombat::Request, Apache::Wombat::Response, Wombat::Exception

AUTHOR

Brian Moseley, bcm@maz.org