=head1 NAME

ORM - Object relational mapper для Perl, предназначен для хранения и поиска объектов
в базе данных.

=head1 SYNOPSIS

  use Music::Song;
  use Music::Performer;

  # Show number of songs performed by 'Gorillaz'
  print Music::Song->count( filter=>( Music::Song->M->performer->name eq 'Gorillaz' ) );

  # Find object corresponding to performer 'Gorillaz'
  $performer = Music::Performer->find
  (
      filter=>( Music::Performer->M->name eq 'Gorillaz' ),
  );

  # Add new song to our database
  $error = ORM::Error->new;
  $song  = Music::Song->new
  (
      error => $error,
      prop  =>
      {
          performer => $performer,
          year      => 2005,
          title     => "September's Gone",
          content   => "/home/user/music/Gorillaz/September's Gone.mp3",
      },
  );
  if( $error->fatal )
  {
      die $error->text;
  }
  else
  {
      print $song->title,"\n";
  }

=head1 DESCRIPTION

ORM is Perl library that implements object-relational mapping.
Its features are much similar to those of Java's Hibernate library,
but interface is much different and easier to use.

=head2 Преимущества использования ORM

=over

=item *
С помощью ORM Вы получаете доступ ко всем возможностям
SQL-сервера без использования SQL-запросов. SQL-запросы генерируются
с учетом особенностей конкретной СУБД. Это позволяет Вам быть
уверенными что Ваши приложения, написанные с использованием ORM
действительно работоспособны на всех поддерживаемых базах данных.

=item *
Блягодаря тому, что Вам не придется писать SQL-запросы, резко
уменьшается опасность взлома Вашей информационной системы
с использованием атак типа SQL-injection.

=item *
Вы легко можете реализовать балансировку нагрузки и повысить отказоустойчивость
Вашей информационной системы используя комбинацию драйверов ORM::Db::Replicated и
ORM::Db::Backup и реплицируемые (например, PostgreSQL) или кластерные (например,
MySQL Cluster) СУБД.

=back

=head2 Основные возможности

=over

=item * Поддержка наследования хранимых объектов

=item * Поддержка транзакций

=item * Отсутствие необходимости писать SQL-запросы

=item * Полноценный поиск объектов в БД с использованием обычных Perl-выражений

=item * Связи между объектами "Один ко многим" и "Многие ко многим"

=item * Эмуляция внешних ключей

=item * История изменений объектов

=item * Частично загруженные (lazy-loaded) объекты

=item * Статистические данные по объектам (с использованием GROUP BY)

=item * Использование объектов произвольных классов в качестве свойств

=item * Автоматические акессоры и мутаторы

=item * Кеширование объектов

=item * Выделеный слой кода для работы с БД

=back

Информация о добавлении новых возможностей в файле TODO.txt

=head2 Основные термины

=over 

=item Промежуточный (Intermediate) класс

это класс который не может иметь представителей.

=item Инициирующий (Initial) класс

это intermediate класс, унаследованный непосредственно
от ORM и являющйися базовым для всех классов объектной модели.

=item Первоначальный (Primary) класс

это класс унаследованный непосредственно от Initial класса.

=back

=head2 Инициирующий класс

Первым шагом в использовании ORM будет являтся создание инициирующего класса
объектной модели. Инициирующий класс путем задания параметров в методе _init
и путем переопределения методов класса ORM может устанавливать общее для всей
модели поведение.

Например, задать используемый размер кэша, установить соответствие имен
ORM-классов и таблиц БД или указать соответствие типов полей таблицы классам
соответствующих свойств объектов.

Для модели музыкальной коллекции это будет класс



Класс Music::ORM наследуется от ORM и будет являтся базовым
для всех классов объектной модели.

 Класс Music::Song - один из классов объектной модели музыкальной коллекции,
 наследуется от базового класса модели Music::ORM.
 Информацию о свойствах объектов этого класса и о связях с другими объектами
 ORM берет из базы данных, каждому классу в соответствие классу объектам класса соответствуют
 named 'Music_Song' you can change its suggested name by overriding method
 ORM->_guess_table_name() or by specifying 'table' argument in use clause.

=head2 Частичная загрузка (lazy_load)

=head1 Методы

=head2 _init

=over

=item history_class

Определяет класс, который будет использоваться для записи и хранения B<истории>
изменения объектов нашей модели. Подробности о классе C<Todo::History> ниже.

Если параметр не указан - история будет отключена для всей модели.

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

=item prefer_lazy_load

Отдавать предпочтение частичной загрузке объектов по умолчанию.
Подробней о частичной загрузке объектов смотрите в L<ORM(5)>.

=item emulate_foreign_keys

Параметр, позволяющий включить проверку целостности данных на уровне ORM
для баз данных, не поддерживающих внешние ключи.

=item default_cache_size

Задает размер кэша объектов.

ORM не использует общий кэш для всех объектов,
вместо этого кэш сопоставляется каждому B<первоначальному> классу
(классу, унаследованному непосредственно от инициирующего класса)
и используется для кэширования его представителей и представителей всех его потомков.

Даже если размер кэша установлен в 0, то объект уже загруженный в память
не будет повторно загружаться из базы. То есть:

  $a = Todo::Task->find_id( id=1 );
  $b = Todo::Task->find_id( id=1 );

обратиться к БД всего один раз а не два.
Кроме того $a и $b будут содержать один и тот же объект.

=item db

Используемый драйвер СУБД. Подробней читайте в L<ORM::Db(5)>.

=back

=head1 SEE ALSO

http://sourceforge.net/projects/perlorm

=head1 AUTHOR

Alexey V. Akimov

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2005 by Alexey V. Akimov

This library is free software; you can redistribute it and/or modify
it under the terms of LGPL licence.

=cut
