1XML::Atom::Server(3pm)User Contributed Perl DocumentationXML::Atom::Server(3pm)
2
6 XML::Atom::Server - A server for the Atom API
7
9 package My::Server;
10 use base qw( XML::Atom::Server );
11 sub handle_request {
12 my $server = shift;
13 $server->authenticate or return;
14 my $method = $server->request_method;
15 if ($method eq 'POST') {
16 return $server->new_post;
17 }
18 ...
19 }
20 my %Passwords;
22 sub password_for_user {
23 my $server = shift;
24 my($username) = @_;
25 $Passwords{$username};
26 }
27 sub new_post {
29 my $server = shift;
30 my $entry = $server->atom_body or return;
31 ## $entry is an XML::Atom::Entry object.
32 ## ... Save the new entry ...
33 }
34 package main;
36 my $server = My::Server->new;
37 $server->run;
38
40 XML::Atom::Server provides a base class for Atom API servers. It
41 handles all core server processing, both the SOAP and REST formats of
42 the protocol, and WSSE authentication. It can also run as either a
43 mod_perl handler or as part of a CGI program.
44 It does not provide functions specific to any particular
46 implementation, such as posting an entry, retrieving a list of entries,
47 deleting an entry, etc. Implementations should subclass
48 XML::Atom::Server, overriding the handle_request method, and handle all
49 functions such as this themselves.
50
52 Request Handling
53 Subclasses of XML::Atom::Server must override the handle_request method
54 to perform all request processing. The implementation must set all
55 response headers, including the response code and any relevant HTTP
56 headers, and should return a scalar representing the response body to
57 be sent back to the client.
58 For example:
60 sub handle_request {
62 my $server = shift;
63 my $method = $server->request_method;
64 if ($method eq 'POST') {
65 return $server->new_post;
66 }
67 ## ... handle GET, PUT, etc
68 }
69 sub new_post {
71 my $server = shift;
72 my $entry = $server->atom_body or return;
73 my $id = save_this_entry($entry); ## Implementation-specific
74 $server->response_header(Location => $server->uri . '/entry_id=' . $id);
75 $server->response_code(201);
76 $server->response_content_type('application/x.atom+xml');
77 return serialize_entry($entry); ## Implementation-specific
78 }
79 Authentication
81 Servers that require authentication for posting or retrieving entries
82 or feeds should override the password_for_user method. Given a username
83 (from the WSSE header), password_for_user should return that user's
84 password in plaintext. This will then be combined with the nonce and
85 the creation time to generate the digest, which will be compared with
86 the digest sent in the WSSE header. If the supplied username doesn't
87 exist in your user database or alike, just return "undef".
88 For example:
90 my %Passwords = ( foo => 'bar' ); ## The password for "foo" is "bar".
92 sub password_for_user {
93 my $server = shift;
94 my($username) = @_;
95 $Passwords{$username};
96 }
97
99 XML::Atom::Server provides a variety of methods to be used by
100 subclasses for retrieving headers, content, and other request
101 information, and for setting the same on the response.
102 Client Request Parameters
104 • $server->uri
105 Returns the URI of the Atom server implementation.
107 • $server->request_method
109 Returns the name of the request method sent to the server from the
111 client (for example, "GET", "POST", etc). Note that if the client
112 sent the request in a SOAP envelope, the method is obtained from
113 the SOAPAction HTTP header.
114 • $server->request_header($header)
116 Retrieves the value of the HTTP request header $header.
118 • $server->request_content
120 Returns a scalar containing the contents of a POST or PUT request
122 from the client.
123 • $server->request_param($param)
125 XML::Atom::Server automatically parses the PATH_INFO sent in the
127 request and breaks it up into key-value pairs. This can be used to
128 pass parameters. For example, in the URI
129 http://localhost/atom-server/entry_id=1
131 the entry_id parameter would be set to 1.
133 request_param returns the value of the value of the parameter
135 $param.
136 Setting up the Response
138 • $server->response_header($header, $value)
139 Sets the value of the HTTP response header $header to $value.
141 • $server->response_code([ $code ])
143 Returns the current response code to be sent back to the client,
145 and if $code is given, sets the response code.
146 • $server->response_content_type([ $type ])
148 Returns the current Content-Type header to be sent back to the
150 client, and $type is given, sets the value for that header.
151 Processing the Request
153 • $server->authenticate
154 Attempts to authenticate the request based on the authentication
156 information present in the request (currently just WSSE). This will
157 call the password_for_user method in the subclass to obtain the
158 cleartext password for the username given in the request.
159 • $server->atom_body
161 Returns an XML::Atom::Entry object containing the entry sent in the
163 request.
164
166 Once you have defined your server subclass, you can set it up either as
167 a CGI program or as a mod_perl handler.
168 A simple CGI program would look something like this:
170 #!/usr/bin/perl -w
172 use strict;
173 use My::Server;
175 my $server = My::Server->new;
176 $server->run;
177 A simple mod_perl handler configuration would look something like this:
179 PerlModule My::Server
181 <Location /atom-server>
182 SetHandler perl-script
183 PerlHandler My::Server
184 </Location>
185
187 If you wish to return an error from handle_request, you can use the
188 built-in error method:
189 sub handle_request {
191 my $server = shift;
192 ...
193 return $server->error(500, "Something went wrong");
194 }
195 This will be returned to the client with a response code of 500 and an
197 error string of "Something went wrong". Errors are automatically
198 serialized into SOAP faults if the incoming request is enclosed in a
199 SOAP envelope.
200
202 Please see the XML::Atom manpage for author, copyright, and license
203 information.
204perl v5.38.0 2023-07-21 XML::Atom::Server(3pm)