Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XML::Atom::Server(3)  User Contributed Perl Documentation XML::Atom::Server(3)

NAME
       XML::Atom::Server - A server for	the Atom API

SYNOPSIS
	   package My::Server;
	   use base qw(	XML::Atom::Server );
	   sub handle_request {
	       my $server = shift;
	       $server->authenticate or	return;
	       my $method = $server->request_method;
	       if ($method eq 'POST') {
		   return $server->new_post;
	       }
	       ...
	   }

	   my %Passwords;
	   sub password_for_user {
	       my $server = shift;
	       my($username) = @_;
	       $Passwords{$username};
	   }

	   sub new_post	{
	       my $server = shift;
	       my $entry = $server->atom_body or return;
	       ## $entry is an XML::Atom::Entry	object.
	       ## ... Save the new entry ...
	   }

	   package main;
	   my $server =	My::Server->new;
	   $server->run;

DESCRIPTION
       XML::Atom::Server provides a base class for Atom	API servers. It
       handles all core	server processing, both	the SOAP and REST formats of
       the protocol, and WSSE authentication. It can also run as either	a
       mod_perl	handler	or as part of a	CGI program.

       It does not provide functions specific to any particular
       implementation, such as posting an entry, retrieving a list of entries,
       deleting	an entry, etc.	Implementations	should subclass
       XML::Atom::Server, overriding the handle_request	method,	and handle all
       functions such as this themselves.

SUBCLASSING
   Request Handling
       Subclasses of XML::Atom::Server must override the handle_request	method
       to perform all request processing. The implementation must set all
       response	headers, including the response	code and any relevant HTTP
       headers,	and should return a scalar representing	the response body to
       be sent back to the client.

       For example:

	   sub handle_request {
	       my $server = shift;
	       my $method = $server->request_method;
	       if ($method eq 'POST') {
		   return $server->new_post;
	       }
	       ## ... handle GET, PUT, etc
	   }

	   sub new_post	{
	       my $server = shift;
	       my $entry = $server->atom_body or return;
	       my $id =	save_this_entry($entry);  ## Implementation-specific
	       $server->response_header(Location => $server->uri . '/entry_id='	. $id);
	       $server->response_code(201);
	       $server->response_content_type('application/x.atom+xml');
	       return serialize_entry($entry);	  ## Implementation-specific
	   }

   Authentication
       Servers that require authentication for posting or retrieving entries
       or feeds	should override	the password_for_user method. Given a username
       (from the WSSE header), password_for_user should	return that user's
       password	in plaintext. This will	then be	combined with the nonce	and
       the creation time to generate the digest, which will be compared	with
       the digest sent in the WSSE header. If the supplied username doesn't
       exist in	your user database or alike, just return "undef".

       For example:

	   my %Passwords = ( foo => 'bar' );   ## The password for "foo" is "bar".
	   sub password_for_user {
	       my $server = shift;
	       my($username) = @_;
	       $Passwords{$username};
	   }

METHODS
       XML::Atom::Server provides a variety of methods to be used by
       subclasses for retrieving headers, content, and other request
       information, and	for setting the	same on	the response.

   Client Request Parameters
       o   $server->uri

	   Returns the URI of the Atom server implementation.

       o   $server->request_method

	   Returns the name of the request method sent to the server from the
	   client (for example,	"GET", "POST", etc). Note that if the client
	   sent	the request in a SOAP envelope,	the method is obtained from
	   the SOAPAction HTTP header.

       o   $server->request_header($header)

	   Retrieves the value of the HTTP request header $header.

       o   $server->request_content

	   Returns a scalar containing the contents of a POST or PUT request
	   from	the client.

       o   $server->request_param($param)

	   XML::Atom::Server automatically parses the PATH_INFO	sent in	the
	   request and breaks it up into key-value pairs. This can be used to
	   pass	parameters.  For example, in the URI

	       http://localhost/atom-server/entry_id=1

	   the entry_id	parameter would	be set to 1.

	   request_param returns the value of the value	of the parameter
	   $param.

   Setting up the Response
       o   $server->response_header($header, $value)

	   Sets	the value of the HTTP response header $header to $value.

       o   $server->response_code([ $code ])

	   Returns the current response	code to	be sent	back to	the client,
	   and if $code	is given, sets the response code.

       o   $server->response_content_type([ $type ])

	   Returns the current Content-Type header to be sent back to the
	   client, and $type is	given, sets the	value for that header.

   Processing the Request
       o   $server->authenticate

	   Attempts to authenticate the	request	based on the authentication
	   information present in the request (currently just WSSE). This will
	   call	the password_for_user method in	the subclass to	obtain the
	   cleartext password for the username given in	the request.

       o   $server->atom_body

	   Returns an XML::Atom::Entry object containing the entry sent	in the
	   request.

USAGE
       Once you	have defined your server subclass, you can set it up either as
       a CGI program or	as a mod_perl handler.

       A simple	CGI program would look something like this:

	   #!/usr/bin/perl -w
	   use strict;

	   use My::Server;
	   my $server =	My::Server->new;
	   $server->run;

       A simple	mod_perl handler configuration would look something like this:

	   PerlModule My::Server
	   <Location /atom-server>
	       SetHandler perl-script
	       PerlHandler My::Server
	   </Location>

ERROR HANDLING
       If you wish to return an	error from handle_request, you can use the
       built-in	error method:

	   sub handle_request {
	       my $server = shift;
	       ...
	       return $server->error(500, "Something went wrong");
	   }

       This will be returned to	the client with	a response code	of 500 and an
       error string of "Something went wrong". Errors are automatically
       serialized into SOAP faults if the incoming request is enclosed in a
       SOAP envelope.

AUTHOR & COPYRIGHT
       Please see the XML::Atom	manpage	for author, copyright, and license
       information.

perl v5.32.0			  2017-05-12		  XML::Atom::Server(3)

NAME | SYNOPSIS | DESCRIPTION | SUBCLASSING | METHODS | USAGE | ERROR HANDLING | AUTHOR & COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::Atom::Server&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help