local-lib5/man/man3/XML::Atom::Server.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "XML::Atom::Server 3"
 127 .TH XML::Atom::Server 3 "2009-04-24" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 XML::Atom::Server \- A server for the Atom API
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 11
 137 \&    package My::Server;
 138 \&    use base qw( XML::Atom::Server );
 139 \&    sub handle_request {
 140 \&        my $server = shift;
 141 \&        $server\->authenticate or return;
 142 \&        my $method = $server\->request_method;
 143 \&        if ($method eq \*(AqPOST\*(Aq) {
 144 \&            return $server\->new_post;
 145 \&        }
 146 \&        ...
 147 \&    }
 148 \&
 149 \&    my %Passwords;
 150 \&    sub password_for_user {
 151 \&        my $server = shift;
 152 \&        my($username) = @_;
 153 \&        $Passwords{$username};
 154 \&    }
 155 \&
 156 \&    sub new_post {
 157 \&        my $server = shift;
 158 \&        my $entry = $server\->atom_body or return;
 159 \&        ## $entry is an XML::Atom::Entry object.
 160 \&        ## ... Save the new entry ...
 161 \&    }
 162 \&
 163 \&    package main;
 164 \&    my $server = My::Server\->new;
 165 \&    $server\->run;
 166 .Ve
 167 .SH "DESCRIPTION"
 168 .IX Header "DESCRIPTION"
 169 \&\fIXML::Atom::Server\fR provides a base class for Atom \s-1API\s0 servers. It handles
 170 all core server processing, both the \s-1SOAP\s0 and \s-1REST\s0 formats of the protocol,
 171 and \s-1WSSE\s0 authentication. It can also run as either a mod_perl handler or as
 172 part of a \s-1CGI\s0 program.
 173 .PP
 174 It does not provide functions specific to any particular implementation,
 175 such as posting an entry, retrieving a list of entries, deleting an entry, etc.
 176 Implementations should subclass \fIXML::Atom::Server\fR, overriding the
 177 \&\fIhandle_request\fR method, and handle all functions such as this themselves.
 178 .SH "SUBCLASSING"
 179 .IX Header "SUBCLASSING"
 180 .SS "Request Handling"
 181 .IX Subsection "Request Handling"
 182 Subclasses of \fIXML::Atom::Server\fR must override the \fIhandle_request\fR
 183 method to perform all request processing. The implementation must set all
 184 response headers, including the response code and any relevant \s-1HTTP\s0 headers,
 185 and should return a scalar representing the response body to be sent back
 186 to the client.
 187 .PP
 188 For example:
 189 .PP
 190 .Vb 8
 191 \&    sub handle_request {
 192 \&        my $server = shift;
 193 \&        my $method = $server\->request_method;
 194 \&        if ($method eq \*(AqPOST\*(Aq) {
 195 \&            return $server\->new_post;
 196 \&        }
 197 \&        ## ... handle GET, PUT, etc
 198 \&    }
 199 \&
 200 \&    sub new_post {
 201 \&        my $server = shift;
 202 \&        my $entry = $server\->atom_body or return;
 203 \&        my $id = save_this_entry($entry);  ## Implementation\-specific
 204 \&        $server\->response_header(Location => $server\->uri . \*(Aq/entry_id=\*(Aq . $id);
 205 \&        $server\->response_code(201);
 206 \&        $server\->response_content_type(\*(Aqapplication/x.atom+xml\*(Aq);
 207 \&        return serialize_entry($entry);    ## Implementation\-specific
 208 \&    }
 209 .Ve
 210 .SS "Authentication"
 211 .IX Subsection "Authentication"
 212 Servers that require authentication for posting or retrieving entries or
 213 feeds should override the \fIpassword_for_user\fR method. Given a username
 214 (from the \s-1WSSE\s0 header), \fIpassword_for_user\fR should return that user's
 215 password in plaintext. This will then be combined with the nonce and the
 216 creation time to generate the digest, which will be compared with the
 217 digest sent in the \s-1WSSE\s0 header. If the supplied username doesn't exist in
 218 your user database or alike, just return \f(CW\*(C`undef\*(C'\fR.
 219 .PP
 220 For example:
 221 .PP
 222 .Vb 6
 223 \&    my %Passwords = ( foo => \*(Aqbar\*(Aq );   ## The password for "foo" is "bar".
 224 \&    sub password_for_user {
 225 \&        my $server = shift;
 226 \&        my($username) = @_;
 227 \&        $Passwords{$username};
 228 \&    }
 229 .Ve
 230 .SH "METHODS"
 231 .IX Header "METHODS"
 232 \&\fIXML::Atom::Server\fR provides a variety of methods to be used by subclasses
 233 for retrieving headers, content, and other request information, and for
 234 setting the same on the response.
 235 .SS "Client Request Parameters"
 236 .IX Subsection "Client Request Parameters"
 237 .IP "\(bu" 4
 238 \&\f(CW$server\fR\->uri
 239 .Sp
 240 Returns the \s-1URI\s0 of the Atom server implementation.
 241 .IP "\(bu" 4
 242 \&\f(CW$server\fR\->request_method
 243 .Sp
 244 Returns the name of the request method sent to the server from the client
 245 (for example, \f(CW\*(C`GET\*(C'\fR, \f(CW\*(C`POST\*(C'\fR, etc). Note that if the client sent the
 246 request in a \s-1SOAP\s0 envelope, the method is obtained from the \fISOAPAction\fR
 247 \&\s-1HTTP\s0 header.
 248 .IP "\(bu" 4
 249 \&\f(CW$server\fR\->request_header($header)
 250 .Sp
 251 Retrieves the value of the \s-1HTTP\s0 request header \fI\f(CI$header\fI\fR.
 252 .IP "\(bu" 4
 253 \&\f(CW$server\fR\->request_content
 254 .Sp
 255 Returns a scalar containing the contents of a \s-1POST\s0 or \s-1PUT\s0 request from the
 256 client.
 257 .IP "\(bu" 4
 258 \&\f(CW$server\fR\->request_param($param)
 259 .Sp
 260 \&\fIXML::Atom::Server\fR automatically parses the \s-1PATH_INFO\s0 sent in the request
 261 and breaks it up into key-value pairs. This can be used to pass parameters.
 262 For example, in the \s-1URI\s0
 263 .Sp
 264 .Vb 1
 265 \&    http://localhost/atom\-server/entry_id=1
 266 .Ve
 267 .Sp
 268 the \fIentry_id\fR parameter would be set to \f(CW1\fR.
 269 .Sp
 270 \&\fIrequest_param\fR returns the value of the value of the parameter \fI\f(CI$param\fI\fR.
 271 .SS "Setting up the Response"
 272 .IX Subsection "Setting up the Response"
 273 .IP "\(bu" 4
 274 \&\f(CW$server\fR\->response_header($header, \f(CW$value\fR)
 275 .Sp
 276 Sets the value of the \s-1HTTP\s0 response header \fI\f(CI$header\fI\fR to \fI\f(CI$value\fI\fR.
 277 .IP "\(bu" 4
 278 \&\f(CW$server\fR\->response_code([ \f(CW$code\fR ])
 279 .Sp
 280 Returns the current response code to be sent back to the client, and if
 281 \&\fI\f(CI$code\fI\fR is given, sets the response code.
 282 .IP "\(bu" 4
 283 \&\f(CW$server\fR\->response_content_type([ \f(CW$type\fR ])
 284 .Sp
 285 Returns the current \fIContent-Type\fR header to be sent back to the client, and
 286 \&\fI\f(CI$type\fI\fR is given, sets the value for that header.
 287 .SS "Processing the Request"
 288 .IX Subsection "Processing the Request"
 289 .IP "\(bu" 4
 290 \&\f(CW$server\fR\->authenticate
 291 .Sp
 292 Attempts to authenticate the request based on the authentication
 293 information present in the request (currently just \s-1WSSE\s0). This will call
 294 the \fIpassword_for_user\fR method in the subclass to obtain the cleartext
 295 password for the username given in the request.
 296 .IP "\(bu" 4
 297 \&\f(CW$server\fR\->atom_body
 298 .Sp
 299 Returns an \fIXML::Atom::Entry\fR object containing the entry sent in the
 300 request.
 301 .SH "USAGE"
 302 .IX Header "USAGE"
 303 Once you have defined your server subclass, you can set it up either as a
 304 \&\s-1CGI\s0 program or as a mod_perl handler.
 305 .PP
 306 A simple \s-1CGI\s0 program would look something like this:
 307 .PP
 308 .Vb 2
 309 \&    #!/usr/bin/perl \-w
 310 \&    use strict;
 311 \&
 312 \&    use My::Server;
 313 \&    my $server = My::Server\->new;
 314 \&    $server\->run;
 315 .Ve
 316 .PP
 317 A simple mod_perl handler configuration would look something like this:
 318 .PP
 319 .Vb 5
 320 \&    PerlModule My::Server
 321 \&    <Location /atom\-server>
 322 \&        SetHandler perl\-script
 323 \&        PerlHandler My::Server
 324 \&    </Location>
 325 .Ve
 326 .SH "ERROR HANDLING"
 327 .IX Header "ERROR HANDLING"
 328 If you wish to return an error from \fIhandle_request\fR, you can use the
 329 built-in \fIerror\fR method:
 330 .PP
 331 .Vb 5
 332 \&    sub handle_request {
 333 \&        my $server = shift;
 334 \&        ...
 335 \&        return $server\->error(500, "Something went wrong");
 336 \&    }
 337 .Ve
 338 .PP
 339 This will be returned to the client with a response code of 500 and an
 340 error string of \f(CW\*(C`Something went wrong\*(C'\fR. Errors are automatically
 341 serialized into \s-1SOAP\s0 faults if the incoming request is enclosed in a \s-1SOAP\s0
 342 envelope.
 343 .SH "AUTHOR & COPYRIGHT"
 344 .IX Header "AUTHOR & COPYRIGHT"
 345 Please see the \fIXML::Atom\fR manpage for author, copyright, and license
 346 information.