pub/Impl: Lib/IMPL/Web/Application/RestResource.pm comparison

comparison Lib/IMPL/Web/Application/RestResource.pm @ 202:5146e17a7b76

IMPL::Web::Application::RestResource fixes, documentation

author	sergey
date	Wed, 25 Apr 2012 02:49:23 +0400
parents	0c018a247c8a
children	292226770180

comparison

equal deleted inserted replaced

-:0c018a247c8a
+:5146e17a7b76
 package IMPL::Web::Application::RestResource;
 use strict;
-use IMPL::lang qw(:declare :constants is);
+use IMPL::lang qw(:declare :constants is :hash);
 use IMPL::Exception();
 use IMPL::declare {
 	require => {
 		ForbiddenException => 'IMPL::Web::ForbiddenException',
 		NotFoundException => 'IMPL::Web::NotFoundException',
 		InvalidOpException => '-IMPL::InvalidOperationException',
 		ArgumentException => '-IMPL::InvalidArgumentException',
 		TTransform => '-IMPL::Transform',
 		TResolve => '-IMPL::Config::Resolve',
-		CustomResource => 'IMPL::Web::Application::CustomResource'
+		CustomResource => 'IMPL::Web::Application::RestCustomResource'
 	},
 	base => {
 		'IMPL::Web::Application::RestCustomResource' => '@_'
 	}
 };
 	my ($this) = @_;
 	die ArgumentException->new("target") unless $this->target;
 	$this->final($this->childRegex ? 0 : 1);
+	$this->methods({}) unless $this->methods;
 	if ($this->enableForms) {
 $this->methods->{create} = {
-	get => \&_ParentGet,
+	get => $this->get,
-	post => \&_ParentPost,
+	post => $this->post,
 	final => 1 # this resource doesn't have any children
-};
+} if $this->post;
 $this->methods->{edit} = {
-	get => \&_ParentGet,
+	get => $this->get,
-	post => \&_ParentPut,
+	post => $this->put,
 	final => 1 # this resource doesn't have any children
-};
+} if $this->put;
 $this->methods->{delete} {
-	get => \&_ParentGet,
+	get => $this->get,
-	post => \&_ParentDelete
+	post => $this->delete,
 	final => 1 # this resource doesn't have any children
-}
+} if $this->delete;
 	}
 }
-sub _ParentGet {
+# создает дочерний ресурс из описания, однако все методы созданного
-	my ($this,$action) = @_;
+# ресурса переадресуются к его родителю, это нужно, чтобы публиковать
-	return $this->parent->GetImpl($action);
+# методы и свойства объекта
-}
+sub _CreateSubResource {
+	my ($this,$resource,$id) = @_;
-sub _ParentPut {
-my ($this,$action) = @_;
+	my %methods = map {
-return $this->parent->PutImpl($action);
+my $method = $resource->{$_};
-}
+$_ => sub {
+my ($this,$action) = @_;
-sub _ParentPost {
+return $this->parent->InvokeMember($method,$action);
-my ($this,$action) = @_;
+};
-return $this->parent->PostImpl($action);
+} grep $resource->{$_}, qw(get post put delete);
-}
+return CustomResource->new(
-sub _ParentDelete {
+%methods,
-my ($this,$action) = @_;
+final => $resource->{final},
-return $this->parent->DeleteImpl($action);
+parent => $this,
+id => $id,
+contract => $this->contract
+);
 }
 sub FetchChildResource {
 	my ($this,$id,$action) = @_;
 		my $method = $this->index;
 		die ForbiddenException->new() unless $method;
 		$res = $this->InvokeMember($method,$action);
-	} elsif (my $resource = $this->methods->{$id}) {
+	} elsif ($this->methods and my $resource = $this->methods->{$id}) {
-		return CustomResource->new(
-get => $resource->{get},
+		return $this->_CreateSubResource($resource,$id);
-post => $resource->{post},
-put => $resource->{put},
+	} elsif ($rx and $id =~ m/^$rx$/ and my $method = $this->fetch) {
-delete => $resource->{delete},
-parent => $this,
+		$method = {
-id => $id,
+			method => $method,
-target => $this->target
+			parameters => 'id'
-		);
+		} unless ref $method;
-	} elsif ($rx and $id =~ m/^$rx$/ and $method = $this->fetch) {
 		$res = $this->InvokeMember($method,$action, { id => $id } );
-	} else {
-		die ForbiddenException->new();
 	}
 die NotFoundException->new() unless defined $res;
 return $this->contract->Transform($res, {parent => $this, id => $id} );
+}
+sub InvokeMember {
+my ($this,$method,$action,$predefined) = @_;
+die ArgumentException->new("method","No method information provided") unless $method;
+#normalize method info
+if (not ref $method) {
+$method = {
+method => $method
+};
+}
+if (ref $method eq 'HASH') {
+my $member = $method->{method} or die InvalidOpException->new("A member name isn't specified");
+$member = $member->Invoke($this) if eval { $member->isa(TResolve) };
+my @args;
+if (my $params = $method->{parameters}) {
+if (ref $params eq 'HASH') {
+@args = map {
+$_,
+$this->MakeParameter($params->{$_},$action,$predefined)
+} keys %$params;
+} elsif (ref $params eq 'ARRAY') {
+@args = map $this->MakeParameter($_,$action,$predefined), @$params;
+} else {
+@args = ($this->MakeParameter($params,$action,$predefined));
+}
+}
+return $this->target->$member(@args);
+} elsif (ref $method eq TResolve) {
+return $method->Invoke($this);
+} elsif (ref $method eq 'CODE') {
+return $method->($this,$action);
+} else {
+die InvalidOpException->new("Unsupported type of the method information", ref $method);
+}
+}
+sub MakeParameter {
+my ($this,$param,$action,$predefined) = @_;
+my $params = hashApply(
+	    {
+	    	id => $this->id,
+	    	action => $action,
+	    	query => $action->query
+	    },
+	    $predefined || {}
+	);
+if ($param) {
+if (is $param, TTransform ) {
+return $param->Transform($action->query);
+} elsif ($param and not ref $param) {
+return $params->{$param} || $action->query->param($param);
+} else {
+die InvalidOpException->new("Unsupported parameter mapping", $param);
+}
+} else {
+return undef;
+}
 }
 1;
 __END__
 				method => 'Vote',
 				parameters => [qw(id rating comment)]
 			}
 		}
 	}
-	list => 'search',
+	index => {
+		method => 'search',
+		paremeters => [qw(filter page limit)]
+	},
 	fetch => 'GetItemById'
 }
 );
 =end code
 =head1 DESCRIPTION
 Каждый ресурс представляет собой коллекцию и реализует методы C<HTTP> C<GET,POST,PUT,DELETE>.
-Ресурсы выстраиваются в иерархию, на основе пути. Поиск конечного реурса происходит последовательным
+Вызов каждого из этих методов позволяет выполнить одну из операций над ресурсом, однако
-вызовом метода GET с именем очередного ресурса.
+операций может быть больше, для этого создаются дочерние ресурсы (каждый из которых также
+может иметь четыре метода C<GET,POST,PUT,DELETE>), однако обращения к методам у дочерних
+ресурсов отображаются в вызовы методов у родительского ресурса.
+Такой подход позволяет расширить функциональность не изменяя стандарт C<HTTP>, а также обойти
+ограничения браузеров на методы C<PUT,DELETE>.
+Данный тип ресутсов расчитан на использование с конфигурацией, которую можно будет
+сохранить или прочитать, например, из файла. Для этого у ресурса есть ряд настроек,
+которые позволяют в простой форме задать отображения между C<HTTP> методами и методами
+объекта представленного данным ресурсом.
 =head2 HTTP METHODS
 =head3 C<GET>
-Возвращает коллекцию дочерних ресурсов.
+Возвращает данные из текущего ресурса. Обращение к данному методу не должно вносить
+изменений в ресурсы.
-=head3 C<GET {id}>
+=head3 C<PUT>
-Возвращает дочерний объект с идентификатором C<id>
+Обновляет ресурс. Повторное обращение к данному методу должно приводить к одному и
-=head3 C<GET {method}>
+томуже результату.
-Вызывает метод C<method> и возвращает его результаты. При публикации методов доступных
+=head3 C<DELETE>
-через C<GET> данные методы не должны вносить изменений в предметную область.
+Удаляет ресурс.
-=head3 C<PUT {id}>
-Обновляет дочерний ресурс с указанным идентификатором.
-=head3 C<DELETE {id}>
-Удаляет дочерний ресурс с указанным идентификатором.
 =head3 C<POST>
-Добавляет новый дочерний ресурс в коллекцию.
+Данный метод может вести себя как угодно, однако обычно он используется для добавления
+нового дочернего ресурса в коллекцию,также может использоваться для вызова метода, в случае
-=head3 C<POST {method}>
+если происходит публикация методов в качестве дочерних ресурсов.
-Вызывает метод C<method>.
-=head2 HTTP METHOD MAPPING
-=head3 C<POST {method}>
-Вызывает метод C<method>, в отличии от C<GET> методы опубликованные через C<POST> могут вносить
-изменения в объекты.
 =head1 BROWSER COMPATIBILITY
 Однако существует проблема с браузерами, поскольку тег C<< <form> >> реализет только методы
 C<GET,POST>. Для решения данной проблемы используется режим совместимости C<enableForms>. В
 случае когда данный режим активен, автоматически публикуются дочерние ресурсы C<create,edit,delete>.
-=head2 C<GET create>
+Данные ресуры пбликуются как методы, что означает то, что обращения к ним будут превращены в
+выполнения соответсвующих методов на родительском объекте.
-Возвращает C<target>.
+=head2 C<create>
-=head2 C<POST create>
+По сути данные ресурс не является необходимостью, однако создается для целостности модели.
-Вызывает метод C<PostImpl> передавая ему свои параметры.
+=head3 C<GET>
-=head2 C<GET edit>
+Передает управление методу C<get>
-Возвращает C<target>.
+=head3 C<POST>
-=head2 C<POST edit>
+Передает управление методу C<post>
-Вызывает метод C<$this->parent->PutImpl($this->id)> передавая ему свои параметры.
+=head2 C<edit>
-=head2 C<GET delete>.
+=head3 C<GET>
-Возвращает C<target>.
+Передает управление методу C<get>
-=head2 C<POST delete>.
+=head3 C<POST>
-Вызывает метод C<$this->parent->DeleteImpl($this->id)> передавая ему свои параметры.
+Передает управление методу C<put>, как если бы он был выполнен непосредственно у
+родительского ресурса.
+=head2 C<delete>
+=head3 C<GET>
+Передает управление методу C<get>
+=head3 C<POST>
+Передает управление методу C<delete>, , как если бы он был выполнен непосредственно у
+родительского ресурса.
+=head1 METHOD DEFINITIONS
+Все методы ресурсов данного типа задаются описаниями, хранящимися в соответствующих
+свойствах. Когда наступает необходимость вызова соответствующего метода, его описание
+бедется из свойства и передается методу C<InvokeMember>, который и производит вызов.
+=head2 C<HASH>
+Содержит в себе описание метода, который нужно вызвать, а также его параметры.
+=over
+=item C<method>
+Имя метода который будет вызван.
+=item C<paremeters>
+Описание параметров метода, может быть либо массивом, либо хешем, либо простым
+значением.
+=over
+=item C<ARRAY>
+Метод получает список параметров, каждый элемент данного массива будет превращен
+в параметр при помощи метода C<MakeParameter>
+=item C<HASH>
+Метод получает список параметров, который состоит пар ключ-значение, каждое значение
+данного хеша будет превращено в зачение параметра метода при помощи метода C<MakeParameter>.
+Ключи хеша изменениям не подвергаются.
+=item Простое значение
+Метод получает одно значение, которое будет получено из текущего при помощи C<MakeParameter>.
+=back
+=back
+=head2 C<CODE>
+Если в описании метода находится ссылка на функцию, то эта функция будет вызвана с параметрами.
+Данный вариант полезен когда ресурсы создаются програмно обычного механизма описаний не достаточно
+для реализации требуемого функционала.
+=over
+=item C<$resource>
+Текущий ресурс у которого производится вызов метода.
+=item C<$action>
+Текущий запрос C<IMPL::Web::Application::Action>.
+=back
+=head2 Простое значение
+Интерпретируется как имя метода у объекта данных текущего ресурса.
 =head1 MEMBERS
 =head2 C<[get]id>
 Идентификатор текущего ресурса.
 =head2 C<[get]target>
-Объект (также может быть и класс), обеспечивающий функционал ресурса.
+Объект данных (может быть и класс, поскольку у него будут только вызываться
+методы), обеспечивающий функционал ресурса.
 =head2 C<[get]parent>
 Родительский ресурс, в котором находится текущий ресурс. Может быть C<undef>,
 если текущий ресурс является корнем.
 Содержит описание метода для получения дочернего объекта. Если данный метод
 отсутствует, то дочерние ресурсы не получится адресовать относительно данного.
 По умолчанию получает идентификатор дочернего ресурса первым параметром.
-=head2 C<[get]list>
+=head2 C<[get]index>
 Описание метода для получения списка дочерних объектов. По умолчанию не
 получает параметров.
-=head2 C<[get]insert>
+=head2 C<[get]post>
 Описание метода для добавление дочернего ресурса. По умолчанию получает
 объект C<CGI> описывабщий текущий запрос первым параметром.
-=head2 C<[get]update>
+=head2 C<[get]put>
 Описание метода для обновления дочернего ресурса. По умолчанию получает
-идентификатор дочернего ресурса и объект C<CGI> текущего запроса.
+объект C<CGI> текущего запроса.
 =head2 C<[get]delete>
-Описание метода для удаления дочернего ресурса. По умолчанию получает
+Описание метода для удаления дочернего ресурса. По умолчанию не получает
-идентификатор дочернего ресурса.
+параметров.
-=head2 C<GetImpl($child,$action)>
+=head2 C<GetImpl($action)>
 =over
-=item C<$child>
-Идентификатор дочернего ресутсра
 =item C<$action>
 Текущий запрос C<IMPL::Web::Application::Action>.
 =back
 Переадресует запрос нужному методу внутреннего объекта C<target> при
 помощи C<InvokeMember>.
-=head2 C<PutImpl($child,$action)>
+=head2 C<PutImpl($action)>
 =over
-=item C<$child>
-Идентификатор дочернего ресутсра
 =item C<$action>
 Текущий запрос C<IMPL::Web::Application::Action>.
 =back
 Переадресует запрос нужному методу внутреннего объекта C<target> при
 помощи C<InvokeMember>.
-=head2 C<PostImpl($child,$action)>
+=head2 C<PostImpl($action)>
 =over
-=item C<$child>
-Идентификатор дочернего ресутсра
 =item C<$action>
 Текущий запрос C<IMPL::Web::Application::Action>.
 =back
 Переадресует запрос нужному методу внутреннего объекта C<target> при
 помощи C<InvokeMember>.
-=head2 C<DeleteImpl($child,$action)>
+=head2 C<DeleteImpl($action)>
 =over
-=item C<$child>
-Идентификатор дочернего ресутсра
 =item C<$action>
 Текущий запрос C<IMPL::Web::Application::Action>.
 =back
 Переадресует запрос нужному методу внутреннего объекта C<target> при
 помощи C<InvokeMember>.
-=head2 C<InvokeMember($memberInfo,$child,$action)>
+=head2 C<InvokeMember($memberInfo,$action,$params)>
 =over
 =item C<$memberInfo>
 Описание члена внутреннего объекта C<target>, который нужно вызвать.
-=item C<$child>
-Идентификатор дочернего ресутсра
 =item C<$action>
 Текущий запрос C<IMPL::Web::Application::Action>.
+=item C<$params>
+Ссылка на хеш с предопределенными параметрами.
 =back
 Вызывает метод внутреннего объекта C<target>, предварительно подготовив
 параметры на основе описания C<$memberInfo> и при помощи С<MakeParameter()>.
-=head2 C<MakeParameter($paramDef,$child,$action)>
+=head2 C<MakeParameter($paramDef,$action)>
 =over
 =item C<$paramDef>
 =over
 =item C<id>
-Идентификатор дочернего ресурса
+Идентификатор ресурса
 =item C<query>
 Объект C<CGI> текущего запроса
 =back
 Если описание параметра - объект C<IMPL::Transform>, то будет выполнено это преобразование над C<CGI>
 объектом текущего запроса C<< $paramDef->Transform($action->query) >>.
+=item C<$action>
+Текущий запрос
 =back
 =cut

Mercurial > pub > Impl

comparison Lib/IMPL/Web/Application/RestResource.pm @ 202:5146e17a7b76