package MPMinus::Manual; # $Id: Manual.pod 136 2013-05-17 09:34:11Z minus $

=pod

On future: encoding utf-8

=encoding windows-1251

=head1 NAME

MPMinus::Manual - What is MPMinus, and how do I use it?

=head1 VERSION

version 1.13

=head1 TERMS

=over 8

=item B<Apache>

WEB-сервер Apache. Этот WEB-сервер является единственным сервером, поддерживающим MPMinus. MPMinus 
разработан на основе моделя mod_perl2, как модуль Apache.

=back

=head1 DESCRIPTION

MPMinus (MPM) - mod_perl2 Web Application Framework

MPMinus - Фреймворк для разработки сайтов с высокой нагрузкой.
MPMinus рассчитан для специалистов, работающих со связкой технологий Apache + mod_perl2.
Большинство базовых технологий, использующиеся в работе этой связки, этим документом не рассматриваются.
Для получения более подробной информации о вопросах связанных с mod_perl2, Apache и Perl, обращайтесь
к соответствующим справочным руководствам этих технологий. В задачи этого пособия входит подробное 
описание работы MPMinus.

=head2 CATALYST AND MPMINUS

Иногда разработчики приводят аналогию MPMinus с системой Catalyst. Такая аналогия может быть спорной,
т.к. это абсолютно две разные системы. Система Catalyst это система которая призвана объединить 
компоненты Model, View и Controller в одно целое; когда как система MPMinus объеденят лишь методы доступа
к объектам уровней Model, View и Controller.

Но сразу хотелось бы оговориться, что большая часть идей принятых разработчиками Catalyst, приянто и 
проектом MPMinus, что позволяет говорить о развитии проектов в одном направлении.

=head1 CONFIGURATION

Конфигурационные параметры инициализируются в проектом модуле ModPerl::MySite::Handlers с помощью 
принудительного вызова:

    sub handler {
        my $r = shift;
        my $m = MPMinus->m;
        $m->conf_init($r, __PACKAGE__);
        
        ...
        
        my $project = $m->conf('project');
        
        ...    
    }

Для доступа к данным конфигурации (переменным величинам) существует ряд методов:

    $m->conf('NAME') - Получение значение переменной NAME из хэша конфигурации
    
    my $cfg = $m->get('conf') - Получение ссылки на хэш конфигурации

При работе с проектами следует различать уровни установки тех или иных переменных.

Более подробную информацию см. L<MPMinus::Configuration>

=head2 APACHE LEVEL

Уровень процессов Apache (httpd).

Переменные этого уровня являются общими переменными для всех проектов MPMinus.
К таким переменным следует относить: неизменяемые пользователем значения, установленные в 
конфигурационных файлах Apache: *.conf. Доступ к этим переменным можно получить с помощью
методов mod_perl. См. L<http://perl.apache.org/docs/index.html>

=head2 REQUEST LEVEL

Переменные этого уровня изменяются при каждом клиентском запросе, эти переменые конструируются на
лету, к ним относятся, в частности, значения переменной среды окружения $ENV.

=over 8

=item B<sid>

16-ти значное 16-тиричное число, идентификатор запроса (MPMinus-сессии)

=item B<hitime>

Дата и время в милисекундах момента запроса

=item B<package>

Пара значений: имя пакета и количество инициированных запросов на данный процесс Apache

=item B<project>

Имя проекта НЕ в стандарте UNIX (с учетом регистра)

=item B<prefix>

Имя проекта в стандарте UNIX (как результат выражения lc(project)). Это значение
используется как префикс проекта для нужд генерации файлов, каталогов и другой статической
информации.

=item B<request_uri>

Строка запроса, URI

=item B<request_method>

Метод запроса

=item B<remote_user>

Логин пользователя (HTTP)

=item B<remote_addr>

IP адрес пользователя (HTTP)

=item B<http_host>

Доменное имя сайта к которому осуществляется обращение.
Для нестандартных портов строится как: server_name[:server_port]

=item B<server_admin>

Адрес e-mail администратора проекта, maintainer

=item B<server_name>

Доменное имя сайта (виртуального хоста), заданное директивой ServerName

=item B<server_port>

Номер используемого порта (виртуального хоста)

=item B<document_root>

Корневая папка проекта доступная из вне (абсолютный базовый путь).
Используется разработчиком проектов как базовый путь до корня сайта проекта.

=item B<modperl_root>

Абсолютный базовый путь до корня проекта. Этот путь используется для 
системных нужд и применяется для генерирования системных папок и файлов 
для использования по умолчанию. Полезно использовать для объединения всех
сайтов основанных на MPMinus по части логов и конфигураций. 

Этот путь может определять то, где могут храниться данные доступные ВСЕМ проектам MPMinus
поэтому рациональность использования должна быть определена быть определена приватностью проекта.

Для "конкретных" данных проекта следует использовать document_root (shtml, cache и т.д.) когда как
modperl_root отлично подйдет для папки логов, баз данных, баз сессий и прочей статической информации.

=back

=head2 PROJECT LEVEL

Уровень проекта.

Переменные этого уровня едины для всех экземпляров конкретного проекта.

=over 8

=item B<dir_conf>

Директория конфигурации (conf)

=item B<dir_cache>

Директория кэша (cache)

=item B<dir_logs>

Директория логов проекта (log)

=item B<dir_db>

Директория локальных БД (db)

=item B<dir_shtml>

Директория шаблонов SSI (shtml)

=item B<fileconf>

Путь к файлу конфигурации <prefix>.conf

=item B<file_error>

Имя файла лога ошибок (только имя): mpminus-<prefix>_error.log

=item B<file_debug>

Имя файла лога сообщений отладки (только имя): mpminus-<prefix>_debug.log

=item B<logdir>

Путь до каталога логов (абсолютный путь)

=item B<confdir>

Путь до каталога конфигурации (абсолютный путь)

=item B<errorlog>

Путь до файла лога ошибок (абсолютный путь)

=item B<debuglog>

Путь до файла лога сообщений отладки (абсолютный путь)

=item B<url>

Адрес сайта проекта HTTP для нужд редиректов и внутренних абсолютных ссылок (URL)

=item B<urls>

Адрес сайта проекта HTTPS для нужд редиректов и внутренних абсолютных ссылок (URL)

=item B<url_shtml>

Конечный URL (HTTP) до шаблонов SSI (файлов shtml)

=item B<urls_shtml>

Конечный URL (HTTPS) до шаблонов SSI (файлов shtml)

=item B<configloadstatus>

Статус чтения файла <prefix>.conf (0 - не прочтено /1 - прочтено)

=item B<locked_keys>

Список (ссылка на массив) защищенных ключей конфигурации

=back
    
Флаги (0 - выключено / 1 - включено):

=over 8

=item B<_debug_>

Флаг отладки 

=item B<_syslog_>

Флаг использования системного лога в качестве стандартного лога ошибок и отладки

=item B<_sendmail_>

Флаг разрешения отправки e-mail

=item B<_errorsendmail_>

Флаг разрешения отправки e-mail по факту ошибок (exception)

=back

Особые переменные (extended). Эти переменные могут быть определены в конфигурационном файле виртуального
хоста, или же в файле конфигурации проекта fileconf (например, <prefix>.conf)

=over 8

=item B<content_type>

MIME тип содержимого, Content-Type по умолчанию

=item B<smtp_host>

IP адрес или доменное имя SMTP сервера

=item B<smtp_user>

Логин (если требуется авторизация SMTP)

=item B<smtp_password>

Пароль (если требуется авторизация SMTP)

=item B<db_driver>

Имя драйвера, например: CSV, DBM, ExampleP, File, Gofer, ODBC, Oracle, Pg, Proxy, SQLite, Sponge, mysql

=item B<db_dsn>

DSN соединения, например: DBI:Oracle:MYSID

=item B<db_host>

IP адрес или доменное имя базы данных

=item B<db_name>

Имя базы данных (или SID)

=item B<db_port>

Порт БД, если он не стандартный

=item B<db_user>

Логин пользователя базы данных

=item B<db_password>

Пароль пользователя базы данных

=item B<db_timeout_connect>

Время, в секундах, определяющее таймаут на соединение

=item B<db_timeout_request>

Время, в секундах, определяющее таймаут на запрос

=item B<db_mysql_host>

IP адрес или доменное имя базы данных MySQL

=item B<db_mysql_name>

Имя базы данных MySQL

=item B<db_mysql_user>

Логин пользователя базы данных MySQL

=item B<db_mysql_password>

Пароль пользователя базы данных MySQL

=item B<db_oracle_host>

IP адрес или доменное имя базы данных Oracle

=item B<db_oracle_name>

Имя базы данных Oracle

=item B<db_oracle_user>

Логин пользователя базы данных Oracle

=item B<db_oracle_password>

Пароль пользователя базы данных Oracle

=back

=head2 MSO CONFIGURATION (MULTISTORE)

Для конфигурирования MultiStore соединений, используется конструкция в файле конфигурации fileconf
имеющая вид, примерно следующий:

    <store foo>
        dsn   DBI:mysql:database=TEST;host=192.168.1.1
        user  login
        pass  password
        <Attr>
            mysql_enable_utf8 1
            RaiseError        0
            PrintError        0
        </Attr>
    </store>
    <store bar>
        dsn   DBI:Oracle:FOOSID
        user  login
        pass  password
        <Attr>
            RaiseError        0
            PrintError        0
        </Attr>
    </store>
    <store baz>
        dsn   DBI:Oracle:BARSID
        user  login
        pass  password
        <Attr>
            RaiseError        0
            PrintError        0
        </Attr>
    </store>

Данный пример может располагаться как в фале конфигурации fileconf так и в любом другом 
зависимом файле, например, conf/mso.conf

Методы доступа к этим данным конфигурации приведены на странице описания L<MPMinus::Store::MultiStore/EXAMPLE>

=head1 API: INTERFACE AND METHODS

Основной принцип MPMinus - предоставление API! Именно API позволяет модифицировать код MPMinus независимо
от кода Ваших проектов. 

Взаимодействие с API выполняется в два этапа. Первый - момент компилляции; второй - момент выполнения.
На момент компилляции происходит объединение всех ващих классов с классами ядра MPMinus. На момент выполнения
вызываются те или иные методы MPMinus.

Все методы MPMinus условно делятся на классы: основные методы, методы MVC SKEL Transaction и утилитарные методы.

=head2 MAIN METHODS

Основные методы MPMinus позволяют получить доступ к основным инструментам ядра MPMinus - подключенным 
объектам ядра MPMinus.

=over 8

=item B<conf, config, get_conf, get_config>

See L<MPMinus>

=item B<conf_init>

See L<MPMinus::Configuration>

=item B<disp, dispatcher>

See L<MPMinus>

=item B<drec, drecord, record>

See L<MPMinus>

=item B<get, get_node>

See L<MPMinus>

=item B<m, glob>

See L<MPMinus>

=item B<multistore>

See L<MPMinus>

=item B<mysql>

See L<MPMinus>

=item B<namespace>

See L<MPMinus>

=item B<oracle>

See L<MPMinus>

=item B<r, req>

See L<MPMinus>

=item B<set, set_node>

See L<MPMinus>

=item B<set_conf, set_config>

See L<MPMinus>

=back

=head2 MVC SKEL TRANSACTION METHODS

Методы MVC SKEL Transaction используются в случае когда поверх базовых хендлеров происходит 
расширенная диспетчеризация с использованием механизма MVC SKEL. Более подробную информацию см. 
L<MPMinus::Transaction>

=over 8

=item B<ActionTransaction>

See L<MPMinus::Transaction>

=item B<ActionExecute>

See L<MPMinus::Transaction>

=item B<ActionCheck>

See L<MPMinus::Transaction>

=item B<getActionRecord>

See L<MPMinus::Transaction>

=back

=head2 UTILYTARY METHODS

Утилитарнные методы призваны обеспечить доступ к механизмам логирования, отладки, отправки писем,
обработки исключений и т.п.

=over 8

=item B<debug>

See L<MPMinus::Util>

=item B<exception>

See L<MPMinus::Util>

=item B<log>

See L<MPMinus::Util>

=item B<log_*>

See L<MPMinus::Util>

=item B<sendmail, send_mail>

See L<MPMinus::Util>

=item B<syslog>

See L<MPMinus::Util>

=back

=head1 HANDLERS

    !!! Тут описываем хэндлеры, принцип построения класса !!!

=head2 HANDLER'S TYPES

    !!! Типы !!! см. соотв. секцию конфигурации mod_perl2 !!!

    тип хэндлера modperl вместо стандартного (perl-script)

    Если используется $r->handler('modperl') то нужно устанавливать опции:
    PerlOptions +GlobalRequest
    PerlOptions +SetupEnv
    
    Подробнее см. http://perl.apache.org/docs/2.0/user/config/config.html#C_SetHandler_

=head2 FILTERS

    !!! Тут описываем фильтры !!!

    sub handler {
        ...
        $r->add_output_filter(\&OutputFilterHandler); # Устанавливаем хэндлер OutputFilter
        $r->add_input_filter(\&InputFilterHandler);   # Устанавливаем хэндлер InputFilter
        ...
    }

=head1 DISPATCHING

Диспетчеризация обеспечивает URL-to-Action механизм обработки клиентских запросов.
Механизм основан на том факте, что в зависимости от переданного URL выполняется то или иное действие
на стороне MPMinus. На текущий момент использует URL(URI) диспетчеризация. Сам URI Диспетчер 
обеспечивает диспетчеризацию запросов клиента исходя из ряда типов диспетчеризации: 

Location, Regexp, LocArr и MixArr.

Каждый из этих типов служит для диспетчеризации различных запросов исходя из текущих требований
разрабатываемого сайта. Подробнее о различиях типов диспетчеризации см. ниже.

Настройка диспетчеризации выполняется в двух местых: в конфигурационном файле проекта и непосредственно 
в модуле обработчиков (хэндлеров) ожидаемых действий.

=over 8

=item B<Location>

Эта диспетчеризация выражается в прямом сопоставлении - "Запрошеный URI" == "Значение".

Например: "/" == "/"

Для включения в работу такой диспетчеризации следует сделать следующие изменения
в конфигурации Apache:

    <Location ~ ^/$>
        PerlInitHandler  ModPerl::MySite::Handlers
    </Location>

И, соответственно, в модуле ModPerl::MySite::Root:

    sub record {
        (
            -uri => '/',
            ...
        )
    }

Диспетчеризация Location наиболее проста в обработке и является эталоном производительности.
Этот тип диспетчеризации подходит для большинства сайтов, разрабатывающихся с использованием 
MPMinus. 

=item B<Regexp>

Эта диспетчеризация выражается в сопоставлении - "Запрошеный URI" =~ "Regexp".

Например: "/0123456789abcdef" =~ /^\/[a-zA-Z0-9]{16}\/?$/

Для включения в работу такой диспетчеризации следует сделать следующие изменения
в конфигурации Apache:

    <Location ~ ^\/[a-zA-Z0-9]{16}\/?$>
        PerlInitHandler  ModPerl::MySite::Handlers
    </Location>

И, соответственно, в модуле ModPerl::MySite::Root:

    sub record {
        (
            -uri => ['REGEXP', 'root.mpm', qr/^\/[a-zA-Z0-9]{16}\/?$/],
            ...
        )
    }

Где REGEXP - Ключ типа диспетчеризации. Ключи типов диспетчеризации регистронезависимы.

=item B<LocArr>

Эта диспетчеризация выражается в обратном сопоставлении характерном для нескольких вариантов URI из 
списка, как - "Запрошеный URI" == "Одно из значений списка".

Например: "/" == ("/","/root.mpm","/index.mpm")[0]

Для включения в работу такой диспетчеризации следует сделать следующие изменения
в конфигурации Apache:

    <Location ~ \.[mM][pP][mM]$>
        PerlInitHandler  ModPerl::MySite::Handlers
    </Location>						
    <Location ~ ^/$>
        PerlInitHandler  ModPerl::MySite::Handlers
    </Location>

И, соответственно, в модуле ModPerl::MySite::Root:

    sub record {
        (
            -uri => ['LOCARR', 'root.mpm', ['/','/root.mpm','/index.mpm']],
            ...
        )
    }

=item B<MixArr>

Эта смешанная диспетчеризация, выражается в обратном сопоставлении - "Запрошеные URI" = "Обработчик"
или "(Запрошеные URI) =~ Regexp".

Например: "/" (==,=~) ("/",qr/^\/(root|index)\.mpm$/)

Для включения в работу такой диспетчеризации следует сделать следующие изменения
в конфигурации Apache:

    <Location ~ \.[mM][pP][mM]$>
        PerlInitHandler  ModPerl::MySite::Handlers
    </Location>						
    <Location ~ ^/$>
        PerlInitHandler  ModPerl::MySite::Handlers
    </Location>

И, соответственно, в модуле ModPerl::MySite::Root:

    sub record {
        (
            -uri => ['MIXARR', 'root.mpm', ['/',qr/^\/(root|index)\.mpm$/]],
            ...
        )
    }

=back

=head1 MVC

Шаблон проектирования MVC как частный случай в практике разработки WEB пприложений можно описать 
триадой терминов.

=over 8

=item B<Model>

Чтение и изменение непосредственно данных. Предоставляется посредством использования DBI, SOAP, LDAP
и других систем и подходов.

See L<MPMinus::Store::MultiStore>, L<MPMinus::Store::MySQL>, L<MPMinus::Store::Oracle>, 
L<MPMinus::Store::DBI>

=item B<View>

Предоставление данных пользователю. Осуществляется посредством шаблонизации с помощью таких модулей 
как L<TemplateM>, L<Template::Toolkit>, L<Mason>, L<HTML::Template> и других

=item B<Controller>

Контроль всего этапа запроса, проверка параметров, диспетчеризация действий, управление потоком. 
В этом заключается весь MPMinus.

=back

Более подробную информацию о MVC, а вернее сказать шаблона проектирования, читайте в соответствующей 
документации. Здесь же следует расскзать о различиях подхода классического MVC и "MVC SKEL".

=head2 CLASSIC MVC

Классический MVC в контексте использования MPMinus можно охарактеризовать диспетчеризацией. См. 
L</DISPATCHING>. Когда приходит запрос в виде URL то первым делом происходит отработка хендлеров
по правилам диспетчеризации. Этот подход рационально использовать на сервис ориентированных системах,
например, в системах запрос-ответ где в качестве запросы принимается условно "просьба предоставить контент"
а в качестве ответа возвращается условно "Примите запрошенный контент".

    !!! Тут описываем стандартынй механизм запрос - ответ на примере pay.allo или kernel !!!

=head2 MVC SKEL

    !!! Тут описываем Transaction модель на примере AAA или аналога типа Root !!!

=head1 THANKS

Thanks to Dmitry Klimov for technical translating C<http://fla-master.com>.

=head1 AUTHOR

Serz Minus (Lepenkov Sergey) L<http://serzik.ru> E<lt>minus@mail333.comE<gt>

=head1 COPYRIGHT

Copyright (C) 1998-2013 D&D Corporation. All Rights Reserved

=head1 LICENSE

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

See C<LICENSE> file

=cut

__END__
