=head1 NAME

Uttu - web interface driver

=head1 SYNOPSIS

In httpd.conf:

  PerlModule Uttu
  PerlTransHandler Uttu
  <Location "/some/uri">
      UttuDefine variable value
      UttuConf conf/uttu.conf conf/my.conf
  </Location>

=head1 DESCRIPTION

Uttu is a web interface driver that works with a framework and function sets
to build an application.  Support is provided for building the
infrastructure for a site -- no demands are made for doing sessions in a
particular way, or authenticating against a particular database.  The
actual specifics are defined by the framework.  This allows you to create
your own flavor of Uttu, if you desire, without having to muck around in the
Uttu module.  Think of LPC and LPMuds with their driver and mudlib.

Uttu itself sets up a particular environment in which a content handler
such as L<HTML::Mason|HTML::Mason> handles requests.  Thus, the full
capabilities of the content handler are available.  In addition, the global
$u variable is available at all times (in Mason - methods of access may
vary with the content handler environment).  This is a Uttu object that
contains the current configuration as well as notes for the current
request.

The content handler as well as other aspects of the request handling
are configured with a configuration file specified by the C<UttuConf> Apache
configuration directive.  The framework and function sets may all define
variables for the configuration file.

=head1 APACHE DIRECTIVES

=head2 UttuConf

 UttuConf configuration/file

This will read in the specified file(s) and set up the content handler
object.  If the file is given with a relative path, it is understood to be
relative to the current server root.  Files are read in the order they are
listed.

=head2 UttuDefine

 UttuDefine variable value

This will set the particular variable to have the specified value for use
in the configuration files.  This allows such things as general
configuration files that change with a username, for example, that is
defined in the httpd.conf file.

Values are scalars.

=head2 UttuDefineList

  UttuDefineList variable value1 value2 ...

This will set the particular variable to have the specified list of values
for use in the configuration files.

Multiple uses of UttuDefineList with the same variable name will merge values.

=head2 UttuDefineMap

  UttuDefineMap variable key value

This will set the particular variable to have the specified mapping of keys
and values for use in the configuration files.

Multiple uses of UttuDefineMap with the same variable name will merge values.

=head1 CONFIGURATION

The configuration file is read using L<AppConfig|AppConfig>.  See
L<AppConfig> for file format details.  This file is broken into sections,
each module or function set having its own section.  See the individual
documentation for each module, framework, or function set for the variables
defined by that module.

=head2 [global] variables

Global configuration variables directly affect how Uttu handles requests
before handing off to the content handler.  Some of these configuration
variables may be used by function sets as defaults, for example, the
database connection parameters.

Specifying the [global] section is optional (though may be required if
using sections in the configuration file).  If not using a [global]
section, prepend <global_> to the variable names listed here, as has been
done when referencing them as variables for substitutions (e.g.,
C<$global_content_handler>).

=over 4

=item content_handler

This is the content handler to use when processing pages.  For example,
C<mason> is included with the standard Uttu distribution and creates an
C<HTML::Mason::ApacheHandler> object to handle pages. See L<Uttu::Handler>
for what a content handler should provide.

Uttu comes with support for AxKit (C<axkit>), HTML::Mason (C<mason>),
and the Template Toolkit (C<template>).  See the documentation for
C<Uttu::Handler::$global_content_handler> for configuration information.

=item db_uri_map_table

This is the table in which the uri-to-filename mapping resides.

The default value is `functions'.

=item db_uri_map_field_file

This is the name of the field containing the component (or file) name.

The default value is `file'.

=item db_uri_map_field_uri

This is the name of the field containing the uri relative to the site root
(the <Location> directive, for example).

The default value is `uri'.

=item db_uri_map_where

  db_uri_map_where +{ uid => $u->note("uid") }

This should be a snippet of code returning a hash or array reference
defining additional terms for the where clause used in selecting entries
from the uri-to-filename mapping.  C<$u> is provided and is a reference to
the current Uttu object.

See L<DBIx::Abstract> for how to construct a where clause as a hash or
array reference.

The default is C<undef>ined.

=item framework

This is the framework to use.  This is not a required variable, but it can
be useful to know during configuration which framework is being used.

The value is valid if and only if the module
C<Uttu::Framework::$global_framework> is loadable and its C<init> function
returns a true value.

A framework can set certain default values for configuration variables.
For example, the C<Uttu::Framework::Uttu> framework sets the
C<content_handler> to C<mason>.

=item function_set_base

Most content handlers have directories under which the files should
reside.  For example, with HTML::Mason, there are component roots.  This is
the directory under those directories in which the web pages for function
sets are installed.  If multiple root directories are configured, then this
is appended to all of them when looking for a page in a function set.

The default is C<sets>.  Be careful changing this.
L<Uttu::MakeMaker|Uttu::MakeMaker> expects this to be C<sets> (for now).

=item handle

This is a list of file extensions that Uttu should handle.  Otherwise, it
will decline to rewrite the URL to point to the component (but see L</translate_uri>).

=item hostname

This is the hostname of the server.  This is useful if the virtual server
answers on several hostnames but the configuration is only stored with one
of them.  Use this if there are problems with some hostnames but not others
and they are all configured with one virtual server directive.

=item index

This is the name of the directory index.  This is added to the end of the
URI if the URI is for a directory (ends in a slash - C</>).

Default is C<index.html>.

=item internationalization

This may also be referred to as C<i18n>.

If this is true, general support for internationalization is enabled.

If this is true and L<Locale::Maketext|Locale::Maketext> is not loadable,
it will revert to false.

See L<Uttu::L10N> for more information on internationalization.

The default is false.

=item lib

This is an additional directory to add to C<@INC> when looking for Perl
modules, especially during configuration.  These directories are also added
to C<@INC> for each request.

=item map_uri

This is a mapping of URIs to filenames that overrides the database.  This
is also useful if the database is not setup yet, but the base modules are
installed.  See the documentation for the base module set for the
configuration information to map URIs to filenames so documentation can be
read.

This variable can appear multiple times, once per URI-to-filename mapping.
The format is as follows:

 map_uri /some/uri = /some/file

Only URIs that are in the mapping will be visible to the client.  See the
content handler documentation for exceptions (such as C<dhandlers> and
L<Uttu::Handler::mason|Uttu::Handler::mason>).

=item port

This sets the port at which the virtual server is listening.  This does not
affect Apache, but informs Uttu of which port it should expect the
connection to appear to be on.  Use this if the port at request time is
different than that set in the virtual host configuration directive.

=item resources

This allows resource configuration to be done via an XML file. See 
L<Uttu::Resource> for more information on the XML schema.  This 
requires L<XML::XPath|XML::XPath> and some of the 
L<ResourcePool|ResourcePool> modules, which will not be loaded 
unless this variable is set.

=item translate_uri

This is a list of file extensions that Uttu should not handle yet map the
uri to a filename.  Uttu will handle uri-to-filename translation but not
set the content handler.  This is useful for graphic images that are
distributed with a framework or function set.

=item uri_mapping

If this is true, then the URI will be mapped to a component using the
C<map_uri> information from the configuration file as well as the
URI-to-filename database mapping, if available.  If this is false, then the
components referred to by the URIs are expected to be in the document root
under the location where the configuration is read.

The default is false.

=item uri_map_namespace

This is the Cache::Cache namespace to use for the uri-to-filename map cache.

The default is C<$framework:global_uri_map>.

=item uri_map_expiration

This is the default expiration time for items in the cache.

The default is C<never>.

=item uri_map_auto_purge_interval

This is how often items are checked for expiration.

The default is C<never>.

=item uri_map_size_limit

This is the maximum size of the cache.  If items are added to the cache,
old items are removed.  This may be specified as a number followed by the
letters k, g, or m (e.g., 10 M).

The default is C<NO_MAX_SIZE>.

=item uri_map_sharedmemory

If this is true, then Cache::Cache will be directed to use shared memory.
If this fails, the cache will not be used.  It will not fall back to a
non-shared memory cache.

The default is not to use shared memory.

=back 4

=head1 UTTU METHODS

The following methods and functions are defined by this module and are
available either via the C<$u> global variable (in Mason components) or
the C<Uttu> package.

=over 4

=item clear_components

  $u -> clear_components($key)

This will clear the list of components associated with C<$key>.  This will
only be for the current request.

=item comp_to_rel_uri

 <a href="<% $u -> comp_to_rel_uri($comp) %>">Link Text</a>

This will translate the filename to the URI corresponding to that file.  The URI that matches the current URI closest will be
returned if more than one URI matches the file.  C<$function_set_base> should already be removed from the filename.

This is just like C<comp_to_uri> except the returned URI is relative to the current URI.

=item comp_to_uri

 <a href="<% $u->comp_to_uri($comp) %>">Link Text</a>

This will translate the filename to the URI corresponding to that file.
The URI that matches the current URI closest will be returned if more than
one URI matches the file.  C<$function_set_base> should already be removed
from the filename.

=item config

This method returns the current C<AppConfig> object.

  my $c = Uttu -> config;
or
  my $c = $u -> config;

=item define

This defines configuration variables.  If no configuration file is being
read, then these are cached for later use.  Otherwise, they are added only
to the configuration currently being read. 

The arguments are almost identical to the C<define> function in
L<AppConfig|AppConfig>.  C<Uttu-E<gt>define> expects an even number of
arguments (basically a hash).

=item note

This is a handy way to track information during a request.  The notes are
cleared at the end of each request.

Called with one argument retrieves the note.  Called with two arguments
sets the note.

 my $context = $u -> note('context');
 $u -> note('context', new My::Context ( session => $u->note('session') ));

=item query_cache

  $cache = $u -> query_cache($config_prefix);

This will return a Cache::Cache object configured by the configuration file.

The call C<$u -E<gt> query_cache("global_uri_map")>, for example will use
the following configuration items.

 [global]
   uri_map_namespace            (string)
   uri_map_expiration           (string)
   uri_map_auto_purge_interval  (string)
   uri_map_size_limit           (string)
   uri_map_sharedmemory         (boolean)

It will return C<undef> if it can not create the cache.

=item query_dbh

  $dbh = $u -> query_dbh($config_prefix);

This will return a database handle previously configured in the C<resources> configuration file.

It will return C<undef> if it can not establish a connection.

This function leaves caching of database connections to L<ResourcePool|ResourcePool>.

The database handle will be freed at the end of the current Apache request handling phase.

=item query_components

 Uttu -> query_components($key);

Returns a list of Mason components or web pages (if the content handler is
not HTML::Mason, then these should be considered strings specifying pages
or other functions to be called -- basically, the meaning of the return
value is framework-defined).  These should be called in the order
returned.  The key ($key) is framework-defined.

=item register_component

 Uttu -> register_component($key, $priority, $comp);

This method registers a component in a list named by $key.  The priority
gives a relative ordering in which to call the components.  The significant
values of $key are defined by the framework.

The component C<$comp> should be relative to the C<$function_set_base>.
For example, if C<$function_set_base> is set to C<sets> (the default),
then C<$comp> should be C<uttu/init> instead of C</sets/uttu/init>.

Calling C<register_component> during server startup will register the
component for all requests.  Otherwise, it will be removed from the list at
the end of the current request.

=item resource

 $pool = Uttu -> resource($key);
 $handle = $pool -> get();
  
 # do stuff
  
 $pool -> free($handle)
 # or (if an error)
 $pool -> fail($handle)

This method will return the L<ResourcePool::LoadBalancer|ResourcePool::LoadBalancer> 
object managing the specified resource.

=item uri_to_comp

 $component = $u -> uri_to_comp($uri);

This will return the file the given URI maps to.  This does not take
into consideration internationalization.

=back 4

=head1 URI MAPPING

Uttu looks in two places for the URI to component mapping information:
internal cache, external database.  The configuration file is used to 
provide a minimal mapping in case the database is not available.

The content handler is used to find the file in the filesystem 
after the URI has been mapped to a filename.  That is, the content 
handler may use a series of directories as a path to find the file.

=head1 INTERNATIONALIZATION

Uttu has minimal support for internationalization.  The reason for this is
that there are already good ways to handle language choice without
rewritting it all in Perl again.

Uttu lets Apache handle the choice of which file to serve after it has
translated the URI to a filename.  This is subject to change since it
doesn't handle well the case of HTML::Mason with different component roots
where one component root has working files masking some of the files in a
more general or production component root.

Uttu uses L<Locale::Maketext|Locale::Maketext> as the basis for its
language translation services.

If internationalization is enabled, Uttu will search through several Perl
modules, using the first one it finds.  These are, in order of preference
and following the suggested C<@ISA> chain,

 Uttu::Framework::$framework::L10N::Local::$function_set,
 Uttu::Framework::$framework::L10N::$function_set,
 Uttu::Framework::$framework::L10N::Local,
 Uttu::Framework::$framework::L10N,
 Uttu::L10N.

=head1 BUGS

Please report bugs to either the request tracker for CPAN 
(L<http://rt.cpan.org/|http://rt.cpan.org/>) or on the SourceForge project
(http://sourceforge.net/projects/gestinanna/|http://sourceforge.net/projects/gestinanna/>).

=head2 Handling Apache Restarts

This isn't so much a bug as a situation with an ugly workaround.
Before 0.03, Uttu would delete all Uttu:: modules from %INC when loaded.
Otherwise, certain Uttu:: modules would not be loaded into the symbol tables
by Perl during an Apache restart.

This appears to not be a problem on FreeBSD 4.6 using Perl 5.6.1 and 
mod_perl 1.27, so the munging of %INC has been removed.  If you 
experience problems, let me know (or better yet, send a patch that 
fixes them).

So Uttu can handle an Apache restart but it just isn't always 
graceful about doing so.

This may be related to the next bug.

=head2 Apache::Status, Symbol Tables, and Solaris

This bug hasn't shown up on FreeBSD 4.4 and Perl 5.6.1, but with Solaris
2.7 and Perl 5.6.1, trying to dump the symbol table with Apache::Status
results in a core dump if this module is loaded.

=head2 Internationalization and mod_negotiation

mod_negotiation doesn't get to see the directory in which the component or
file resides until after Uttu has done the uri-to-filename conversion.

=head2 Apache must start in /

Apache must be started while in the root (/) directory.  Otherwise, 
Uttu may be unable to find certain modules or files.  This doesn't 
show up when running the tests.  This may be fixed already.  This 
notice will be removed in a future release when it has been more 
thoroughly tested.

=head1 SEE ALSO

L<AppConfig>,
L<DBIx::Abstract>,
L<Locale::Maketext>,
L<ResourcePool>,
L<Uttu::Manual>,
L<Uttu.TAMU.Edu website|http://uttu.tamu.edu/>.

=head1 WHY UTTU?

Uttu is the Sumerian goddess of the weaving arts and is closely associated
with spiders.  While the Uttu module is not acting as a spider, it does
weave a web.

=head1 AUTHOR

James G. Smith <jsmith@cpan.org>

=head1 COPYRIGHT

Copyright (C) 2002-2003 Texas A&M University.  All Rights Reserved.

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

$Id: Uttu.pod,v 1.14 2003/04/16 19:43:22 jgsmith Exp $