=head1 NAME

Uttu - web interface driver

=head1 SYNOPSIS

In httpd.conf:

  PerlModule Uttu
  PerlTransHandler Uttu
  <Location "/some/uri">
      UttuConf conf/uttu.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 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.

=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.

=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::mason> for more information on the Mason handler.  See
L<Uttu::Handler> for what a content handler should provide.

=item db_database, db_const_database

This is a string denoting the database, hostname, etc., hosting the
database used especially by the uri-to-filename mapping.  This is also the
default database other modules may use.

The C<$dsn> string used in the C<DBI-E<gt>connect> call is constructed from this.

 $dsn = "dbi:$global_dbi_driver:$global_db_database"

The default is none.

If multiple C<db_database> lines are present, Uttu will cycle through them
until it exhausts all available database definitions, or it finds one that
allows a connection.  This allows failover to alternate databases.

C<db_database> should allow modifications as well as read-only access.
Uttu itself only neads read access.  C<db_const_database> implies that the
database will not be modified.

=item db_driver, db_const_driver

This is the DBI driver to use.  C<DBD::$db_driver> must be loadable.

The default is C<undef>ined.

C<db_const_driver> may be used to define the driver used for read-only
access.

=item db_password, db_const_password

This is a single string which is the password to use when connecting to the
database.

The default is C<undef>ined.

C<db_const_password> is the password to use for read-only access.

=item db_password_file, db_const_password_file

This is the name of a file, relative to the server root if not an absolute
path, which contains the password on its first line.  The first line is
read in, C<chomp>'d, and then used to set C<db_password> above.  This is
useful if you want to keep the password out of the configuration file.

The default is C<undef>ined.

C<db_const_password_file> may be used to define C<db_const_password>.

=item db_username, db_const_username

This is a single string which is the username to use when connecting to the
database.

The default is C<undef>ined.

C<db_const_username> defines the username for read-only access.

=item db_uri_map_select_comp

This is the SQL statement for selecting the component that corresponds to a
uri.  Only one component should match.  There should only be one place
holder (C<?>) which is where the uri will be inserted.

The default is C<SELECT file FROM functions WHERE uri=?>.

=item db_uri_map_select_uri

This is the SQL statement for selecting a uri that corresponds to a
component.  Multiple uris may match.  There should only be one place holder
(C<?>) which is where the component name will be inserted.

The default is C<SELECT uri FROM functions WHERE file=?>.

=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 the C<init> function
returns a true value.

This is one way function sets can know how to interact with the framework,
or if they can work with it at all.

Be aware that function sets that share the same name but require different
frameworks will not be able to run on the same server.

=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>.

=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.

=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 map_uri

This is a mapping or 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.  A special
case is if a path at the beginning of a URI is mapped to a file.  This
allows the use of C<dhandler>s.

=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 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 file_to_uri

 <a href="<% $u->file_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 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, %options);

This will return a database handle (result of a C<DBI-E<gt>connect> call)
for the connection configured in the configuration file.

The call C<$u -E<gt> query_dbh("global_db")>, for example will first look for the following configuration items.

  [global]
    db_const_driver    (string)
    db_const_database  (list)
    db_const_username  (string)
    db_const_password  (string)
    db_const_option    (hash)

For those of these that it can't find, it will look for the following.

  [global]
    db_driver    (string)
    db_database  (list)
    db_username  (string)
    db_password  (string)
    db_option    (hash)

Currently, only the C<Write> option is supported.  If this option is true,
then the C<_const> part of the prefix will not be considered.  This is
useful for specifying a database for reading and another for writing, with
round robin access to either as desired.

This function expects the C<*_database_*> variable to be a list of suitable
strings.  If the string last used to make a connection does not return a
valid database handle, then it will go through the rest of the list in
order until either it returns to the most recently used C<database>
configuration or establishes a successful connection.

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

This function leaves caching of database connections to L<Apache::DBI|Apache::DBI>.

=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_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<modules> (the default),
then C<$comp> should be C<uttu/init> instead of C</modules/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 uri_to_file

 $component = $u -> uri_to_file($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.






=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

=head2 Handling Apache Restarts

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

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

=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.


=head1 SEE ALSO

L<AppConfig>,
L<Locale::Maketext>,
L<Uttu::Manual>.

=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 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.5 2002/03/20 17:53:30 jgsmith Exp $
