fix documentation errors
[chaz/p5-HTTP-AnyUA] / lib / HTTP / AnyUA / Backend.pm
1 package HTTP::AnyUA::Backend;
2 # ABSTRACT: A base class for HTTP::AnyUA backends
3
4 =head1 SYNOPSIS
5
6 package HTTP::AnyUA::Backend::MyUserAgent;
7
8 use parent 'HTTP::AnyUA::Backend';
9
10 sub response_is_future { 0 }
11
12 sub request {
13 my ($self, $method, $url, $args) = @_;
14
15 my $ua = $self->ua;
16
17 # Here is where you transform the arguments into a request that $ua
18 # understands, make the request against $ua and get a response, and
19 # transform the response to the expected hashref form.
20
21 my $resp = $ua->make_request();
22
23 return $resp;
24 }
25
26 ### Non-blocking user agents are expected to return Future objects:
27
28 use Future;
29
30 sub response_is_future { 1 }
31
32 sub request {
33 my ($self, $method, $url, $args) = @_;
34
35 my $ua = $self->ua;
36
37 my $future = Future->new;
38
39 # Again, this example glosses over transforming the request and response
40 # to and from the actual user agent, but such details are the whole
41 # point of a backend.
42
43 $ua->nonblocking_callback(sub {
44 my $resp = shift;
45
46 if ($resp->{success}) {
47 $future->done($resp);
48 }
49 else {
50 $future->fail($resp);
51 }
52 });
53
54 return $future;
55 }
56
57 =head1 DESCRIPTION
58
59 This module provides an interface for an L<HTTP::AnyUA> "backend," which is an adapter that adds
60 support for using a type of user agent with L<HTTP::AnyUA>.
61
62 This class should not be instantiated directly, but it may be convenient for backend implementations
63 to subclass it.
64
65 At its core, a backend simply takes a set of standard arguments that represent an HTTP request,
66 transforms that request into a form understood by an underlying user agent, calls upon the user
67 agent to make the request and get a response, and then transforms that response into a standard
68 form. The standard forms for the request and response are based on L<HTTP::Tiny>'s arguments and
69 return value to and from its L<request|HTTP::Tiny/request> method.
70
71 =head1 SEE ALSO
72
73 =for :list
74 * L<HTTP::AnyUA/The Request> - Explanation of the request arguments
75 * L<HTTP::AnyUA/The Response> - Explanation of the response
76
77 =cut
78
79 use warnings;
80 use strict;
81
82 our $VERSION = '9999.999'; # VERSION
83
84
85 =method new
86
87 $backend = HTTP::AnyUA::Backend::MyUserAgent->new($my_user_agent);
88
89 Construct a new backend.
90
91 =cut
92
93 sub new {
94 my $class = shift;
95 my $ua = shift or die 'User agent is required';
96 bless {ua => $ua}, $class;
97 }
98
99 =method request
100
101 $response = $backend->request($method => $url, \%options);
102
103 Make a request, get a response.
104
105 This must be overridden by implementations.
106
107 =cut
108
109 sub request {
110 die 'Not yet implemented';
111 }
112
113 =attr ua
114
115 Get the user agent that was passed to L</new>.
116
117 =cut
118
119 sub ua { shift->{ua} }
120
121 =attr response_is_future
122
123 Get whether or not responses are L<Future> objects. Default is false.
124
125 This may be overridden by implementations.
126
127 =cut
128
129 sub response_is_future { 0 }
130
131 1;
This page took 0.036431 seconds and 4 git commands to generate.