package Eve::HttpResource::Graph;
use parent qw(Eve::HttpResource);
use strict;
use warnings;
use Eve::Exception;
=head1 NAME
B<Eve::HttpResource::Graph> - a base class for the Graph API
node HTTP resources.
=head1 SYNOPSIS
package Eve::HttpResource::SomeGraphResource;
use parent qw(Eve::HttpResource::Graph);
sub _read {
# some object's hash is returned here
}
sub _get_connections {
# some connections hash is returned here
}
sub _get_fields {
# some object fields hash is returned here
}
sub _get_type {
# a required type string is returned here
}
1;
=head1 DESCRIPTION
B<Eve::HttpResource::Graph> is an HTTP resource based class
providing an automation of the Facebook like Graph API node/connection
functionality.
Methods C<_read()>, C<_publish()>, C<_remove()>,
C<_get_connections()>, C<_get_fields()>, C<_get_type()>,
C<_get_actions()> and C<_get_id_alias_hash()> could be overriden by
the class derivatives. When not overriden these methods except
C<_get_connections()> and C<_get_fields> throw the exception
C<Eve::Exception::Http::405MethodNotAllowed>. C<_get_type> throws a
C<Eve::Error::NotImplemented> exception which means it must be
overridden to be used. Inside the described above methods class
attributes C<_request>, C<_response>, C<_session>, C<_event_map> and
C<_dispatcher> can be found.
All methods are passed the list of named matched URI parameters as
arguments. The following example illustrates the usage of named
arguments in a resource that is bound to the
C<http://example.com/:named/:another> pattern URI:
my ($self, %arg_hash) = @_;
Eve::Support::arguments(\%arg_hash, my ($named, $another));
If the C<metadata> query string parameter is specified then the
C<metadata> section is added to the result. This section always
contains the object's type returned by the C<_get_type> method, and if
present, the object's connections returned by the
C<_get_connections()> method, the object's fields returned by the
C<_get_fields> method and the object's actions returned by the
C<_get_actions()> method.
If the request method is C<POST> and the query string is supplied with
C<method=delete> then it behaves just like the C<DELETE> method is
requested. If other value is passed to the C<method> then the
exception C<Eve::Exception::Http::400BadRequest> is thrown.
If C<Eve::Exception::Privilege> is thrown in the user code the
exception C<Eve::Exception::Http::403Forbidden> is rethrown.
Note that the resource must be bound with the C<id> placeholder. The
C<_id> attribute is representing it. If C<_get_id_alias_hash()> is
redefined you can use ID aliases in URI according to the hash keys.
Object deletion requests must use the deleted object's node URI. In
case a connection with no public ID is deleted, the request must use
the respective object connection URI.
=head3 Constructor arguments
=over 4
=item C<request>
an HTTP request object
=item C<response>
an HTTP response object
=item C<session_constructor>
a reference to a subroutine accepting the session C<id> argument and
returning a session object
=item C<dispatcher>
an HTTP dispatcher object
=item C<json>
a JSON encoder object.
=back
=head1 METHODS
=head2 B<init()>
=cut
sub init {
my ($self, %arg_hash) = @_;
my $arg_hash = Eve::Support::arguments(\%arg_hash, my $json);
$self->{'_json'} = $json;
$self->{'_id'} = undef;
$self->SUPER::init(%{$arg_hash});
return;
}
=head2 B<_read()>
This method is called when the graph node or connection is requested
with the GET method.
=head3 Returns
It is expected to return a data hash reference
that will be automatically converted to a required textual
representation and returned to the client
=head3 Throws
=over 4
=item C<Eve::Exception::Http::405MethodNotAllowed>
When a method is used without being overridden in a descendant class.
=back
=cut
sub _read {
Eve::Exception::Http::405MethodNotAllowed->throw(
message => 'Method is not implemented.');
return;
}
=head2 B<_publish()>
This method is called when the graph node or connection is requested
with the POST method.
=head3 Returns
It is expected to return a data hash reference
that will be automatically converted to a required textual
representation and returned to the client
=head3 Throws
=over 4
=item C<Eve::Exception::Http::405MethodNotAllowed>
When a method is used without being overridden in a descendant class.
=back
=cut
sub _publish {
Eve::Exception::Http::405MethodNotAllowed->throw(
message => 'Method is not implemented.');
return;
}
=head2 B<_remove()>
This method is called when the graph node or connection is requested
with the DELETE method or when the POST method is used in conjunction
with a C<method=delete> query string parameter..
=head3 Returns
It is expected to return a data hash reference
that will be automatically converted to a required textual
representation and returned to the client
=head3 Throws
=over 4
=item C<Eve::Exception::Http::405MethodNotAllowed>
When a method is used without being overridden in a descendant class.
=back
=cut
sub _remove {
Eve::Exception::Http::405MethodNotAllowed->throw(
message => 'Method is not implemented.');
return;
}
=head2 B<_get_connections()>
This method is called when the C<metadata> parameter is recieved in
the request. Overriding this method is optional.
=head3 Returns
It is expected to return a connection hash reference
that will be automatically converted to a required textual
representation and returned to the client.
=cut
sub _get_connections {
return (undef);
}
=head2 B<_get_fields()>
This method is called when the C<metadata> parameter is recieved in
the request. Overriding this method is optional.
=head3 Returns
It is expected to return a fields hash reference that will be
automatically converted to a required textual representation and
returned to the client.
=cut
sub _get_fields {
return (undef);
}
=head2 B<_get_actions()>
This method is called when the C<metadata> parameter is recieved in
the request. Overriding this method is optional.
=head3 Returns
It is expected to return an actions hash reference with action keys as
keys and action names as values that will be automatically converted
to a required textual representation and returned to the client.
=cut
sub _get_actions {
return (undef);
}
=head2 B<_get_type()>
This method is called when the C<metadata> parameter is recieved in
the request.
=head3 Returns
It is expected to return a type string that will be automatically
converted to a required textual representation and returned to the
client.
=head3 Throws
=over 4
=item C<Eve::Error::NotImplemented>
When a method is used without being overridden in a descendant class.
=back
=cut
sub _get_type {
Eve::Error::NotImplemented->throw(
message => 'The _get_type method must be implemented.');
return;
}
=head2 B<_get_alias_hash()>
This method is called when the graph HTTP resource processes the
pattern placeholder matches from a request URI. A hash of aliases for
an id can be specified in this method. For example, if an id in the
URI is specified as an C<alias> keyword, it can be replaced with a
real identifier by returning this hash reference:
return {'alias' => $some_service->get_parameter(name => 'id')};
=head3 Returns
It is expected to return a reference to a hash of aliases for an
identifier.
=head3 Throws
=over 4
=item C<Eve::Error::NotImplemented>
When a method is used without being overridden in a descendant class.
=back
=cut
sub _get_id_alias_hash {
return {};
}
sub _get {
my ($self, %matches_hash) = @_;
eval {
$self->_build_response(
result_callback => sub { $self->_read(%matches_hash); },
matches_hash => \%matches_hash);
};
$self->_process_exceptions();
return;
}
sub _post {
my ($self, %matches_hash) = @_;
my $method = $self->_request->get_uri()->
get_query_parameter(name => 'method');
eval {
if (defined $method) {
if ($method eq 'delete') {
$self->_delete(%matches_hash);
} else {
Eve::Exception::Http::400BadRequest->throw(
message => 'Unsupported pseudo method "'.$method.
'" for POST.');
}
} else {
$self->_build_response(
result_callback => sub { $self->_publish(%matches_hash); },
matches_hash => \%matches_hash);
}
};
$self->_process_exceptions();
return;
}
sub _delete {
my ($self, %matches_hash) = @_;
eval {
$self->_build_response(
result_callback => sub { $self->_remove(%matches_hash); },
matches_hash => \%matches_hash);
};
$self->_process_exceptions();
return;
}
sub _get_metadata {
my ($self, %matches_hash) = @_;
my $connections = $self->_get_connections(%matches_hash);
my $metadata = {
defined $connections ? ('connections' => $connections) : ()};
return $metadata;
}
sub _build_response {
my ($self, %arg_hash) = @_;
Eve::Support::arguments(
\%arg_hash, my ($result_callback, $matches_hash));
if (not exists $matches_hash->{'id'}) {
Eve::Error::Value->throw(
message => 'No identifier has been matched in the URI.');
} else {
if (exists $self->_get_id_alias_hash()->{$matches_hash->{'id'}}) {
$self->_id = $self->_get_id_alias_hash()->{$matches_hash->{'id'}};
} else {
$self->_id = $matches_hash->{'id'};
if ($self->_id =~ /\D/) {
Eve::Exception::Http::400BadRequest->throw(
message => 'The identifier must be a number or an allowed '.
'alias, got "'.$self->_id.'".');
}
}
};
my $result = $result_callback->();
my $metadata;
if ($self->_request->get_uri()->get_query_parameter(name => 'metadata')) {
$metadata = $self->_get_metadata(%{$matches_hash});
}
$self->_set_response(
code => 200,
reference => Eve::Support::indexed_hash(
%{$result},
defined $metadata ? ('metadata' => $metadata) : ()));
return;
}
sub _process_exceptions {
my $self = shift;
my ($e, $code, $type);
if ($e = Eve::Exception::Http::400BadRequest->caught()) {
($code, $type) = (400, 'Request');
} elsif ($e = Eve::Exception::Http::401Unauthorized->caught()) {
($code, $type) = (401, 'Authorization');
} elsif ($e = Eve::Exception::Http::405MethodNotAllowed->caught()) {
($code, $type) = (405, 'Request');
} elsif ($e = Eve::Exception::Data->caught()) {
($code, $type) = (400, 'Data');
} elsif ($e = Eve::Exception::Privilege->caught()) {
#print STDERR "HttpResource::Graph::process_exceptions: caught privilege exception!\n";
($code, $type) = (403, 'Privilege');
} elsif ($e = Exception::Class::Base->caught()) {
$e->rethrow();
}
if (defined $e) {
$self->_set_response(
code => $code,
reference => {
'error' => Eve::Support::indexed_hash(
'type' => $type,
'message' => $e->message)});
}
return;
}
sub _set_response {
my ($self, %arg_hash) = @_;
Eve::Support::arguments(\%arg_hash, my ($code, $reference));
$self->_response->set_status(code => $code);
$self->_response->set_header(
name => 'Content-Type', value => 'text/javascript');
$self->_response->set_body(
text => $self->_json->encode(reference => $reference));
return;
}
=head1 SEE ALSO
=over 4
=item L<Eve::HttpResource>
=item L<Eve::Exception>
=back
=head1 LICENSE AND COPYRIGHT
Copyright 2012 Igor Zinovyev.
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
=head1 AUTHOR
=over 4
=item L<Sergey Konoplev|mailto:gray.ru@gmail.com>
=back
=cut
1;
