=head1 NAME

HTTP::Server::VirtualHost - base-class for virtual host definitions

=head1 INHERITANCE

 HTTP::Server::VirtualHost is extended by
   HTTP::Server::VirtualHost::LocalHost

=head1 SYNOPSIS

 use HTTP::Server::Multiplex;

 my $vhost  = HTTP::Server::VirtualHost->new(@vhost_opts);
 my $daemon = HTTP::Server::Multiplex->new
   ( @other_options
   , vhosts => $vhost
   );

 # or
 my $daemon = HTTP::Server::Multiplex->new(@other_opts);
 $daemon->addVirtualHost($vhost);
 $daemon->addVirtualHost(@vhost2_opts);

 # create object which extends HTTP::Server::VirtualHost
 my $myvhost = MyVHost->new(...);
 $daemon->addVirtualHost($myvhost);

=head1 DESCRIPTION

These virtual host definitions are used by L<HTTP::Server::Multiplex|HTTP::Server::Multiplex>, to
implement (server) name based data seperation.  Its features resemble those
of Apache virtual hosts.

Each virtual host usually has to L<HTTP::Server::Directory|HTTP::Server::Directory> slaves: one
which describes the permissions for user directories (url paths in the
form C< /~user/ >) and one for data outside the user space.

=head1 METHODS

=head2 Constructors

You may avoid the creation of extension classes for each virtual host,
by using these options.

HTTP::Server::VirtualHost-E<gt>B<new>(OPTIONS|HASH-of-OPTIONS)

=over 4

 Option        --Default
 aliases         []
 directories     <see text>
 directory_list  <false>
 documents       <undef>
 handlers        {}
 index_file      ['index.html', 'index.htm']
 name            <required>
 rewrite         <undef>
 user_dirs       <see text>

. aliases => HOSTNAME|ARRAY-of-HOSTNAMES

. directories => OBJECT|HASH|ARRAY

=over 4

Pass one or more L<HTTP::Server::Directory|HTTP::Server::Directory> OBJECTS, or HASHes which will
be used to initialize them.  If no information is provided, then only C<<
/~user >> urls and scripts can be used.

=back

. directory_list => BOOLEAN

=over 4

Enables the display of a directory, when it does not contain one of the
C<index_file> prepared defaults.

=back

. documents => DIRECTORY

=over 4

An absolute DIRECTORY for the location of the source files.  Creates the
most free L<HTTP::Server::Directory|HTTP::Server::Directory> object.  If you need things like
access restrictions, then do not use this option but the C<directories>
option.

=back

. handlers => HASH

=over 4

The keys are path names, part of the request URIs.  The values are
CODE-references, called when that URI is addressed.  The access rules
are taken from the directory definition which is selected by the path,
for that's all.

The handlers are called with a the connection (L<HTTP::Server::Connection|HTTP::Server::Connection>),
request (HTTP::Request), uri object (URI).

=back

. index_file => STRING|ARRAY

=over 4

When a directory is addressed, it is scanned whether one of these files
exist.  If so, the content will be shown.

=back

. name => HOSTNAME

. rewrite => CODE

=over 4

See L<rewrite()|HTTP::Server::VirtualHost/"Basic daemon actions">.

=back

. user_dirs => undef|OBJECT|HASH

=over 4

If not specified, a L<HTTP::Server::Directory::UserDirs|HTTP::Server::Directory::UserDirs> is created for
you, with standard Apache behavior.  You may provide your own OBJECT or
a HASH which contains the parameters to create it.  When you explicitly
specify an C<undef> value, then user directories will not be allowed.

=back

=back

=head2 Attributes

$obj-E<gt>B<aliases>

=over 4

Returns a list of all aliases (alternative names) for this server.

=back

$obj-E<gt>B<name>

=over 4

Returns the primary name for this server.

=back

=head2 Handler

$obj-E<gt>B<handleRequest>(CONNECTION, REQUEST)

=over 4

=back

$obj-E<gt>B<requestForMe>(URI)

=over 4

Re-check whether a request is really for this virtual host.

=back

$obj-E<gt>B<showDirectory>(CONNECTION, REQUEST, PATH, LIST)

=over 4

Overrule this method with the way you would like to display an
automatically generated directory index.

=back

=head2 Basic daemon actions

$obj-E<gt>B<allow>(CLIENT, SESSION, REQUEST, URI)

=over 4

BE WARNED that the URI is the rewrite of the REQUEST uri, and therefore
you should use that URI.  The SESSION represents a user.

See L</Allow access>.

=back

$obj-E<gt>B<rewrite>(URI)

=over 4

Returns an URI object as result, which may be the original in case of
no rewrite was needed.  See L</URI Rewrite>.

=back

=head2 Directories

$obj-E<gt>B<addDirectory>(OBJECT|OPTIONS)

=over 4

Either pass a L<HTTP::Server::Directory|HTTP::Server::Directory> OBJECT or the OPTIONS to create
the object.

=back

$obj-E<gt>B<directoryOf>(PATH)

=over 4

Find the best matching L<HTTP::Server::Directory|HTTP::Server::Directory> object.

=back

$obj-E<gt>B<filename>(URI)

=over 4

Translate the URI into a filename, without checking for existence.  Returns
<undef> is not possible.

=back

=head2 Access permissions

=head1 DETAILS

=head2 URI Rewrite

For each request, the L<rewrite()|HTTP::Server::VirtualHost/"Basic daemon actions"> method is called to see whether a
rewrite of the URI is required.  The method must return the original URI
object (the only parameter) or a new URI object.

example: rewrite URI

  package My::Virtual::Host;
  use base 'HTTP::Server::VirtualHost';

  my %lookup =
    ( '/'     => '/index-en.html'
    , '/news' => 'http://news.example.org/index.html'
    );

  sub rewrite($)
  {  my ($self, $uri) = @_;

     # with lookup table
     $uri = URI->new_abs($lookup{$uri->path}, $uri)
         if exists $lookup{$uri->path};

     # whole directory trees
     $uri = URI->new_abs('/somewhere/else'.$1, $uri)
         if $uri->path =~ m!^/some/dir(/.*|$)!;
     
     # maybe more work in the base class
     $uri->SUPER::rewrite($uri);
  }

=head1 SEE ALSO

This module is part of HTTP-Server-Multiplex distribution version 0.10,
built on September 10, 2008. Website: F<http://perl.overmeer.net/httpd-multiplex/>

=head1 LICENSE

Copyrights 2008 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>

