NAME
   AtomBus - An AtomPub server for messaging.

VERSION
   version 1.0404

SYNOPSIS
       use Dancer;
       use AtomBus;
       dance;

DESCRIPTION
   AtomBus is an AtomPub server that can be used for messaging. The idea is
   that atom feeds can correspond to conceptual queues or buses. AtomBus is
   built on top of the Dancer framework. It is also pubsubhubbub friendly.

   These examples assume that you have configured your web server to point
   HTTP requests starting with /atombus to your AtomBus server (see
   "DEPLOYMENT"). To publish an entry, make a HTTP POST request:

       $ curl -d '<entry> <title>allo</title> <content type="xhtml">
         <div xmlns="http://www.w3.org/1999/xhtml" >an important message</div>
         </content> </entry>' http://localhost/atombus/feeds/widgets

   That adds a new entry to a feed titled widgets. If that feed didn't
   exist before, it will be created for you. To retrieve the widgets feed,
   make a HTTP GET request:

       $ curl http://localhost/atombus/feeds/widgets

   Clients can request only entries that came after the last entry they
   processed. They can do this by providing the id of the last message as
   the start_after parameter:

       $ curl http://localhost/atombus/feeds/widgets?start_after=42

   Alternatively, you can provide a start_at param. This will retrieve
   entries starting with the given id:

       $ curl http://localhost/atombus/feeds/widgets?start_at=42

   HTTP ETags are also supported. The server responds with an ETag header
   for each request. The client can provide that ETag as the If-None-Match
   header. The following example will work the same as if the client
   provided a start_after parameter. Except that it will return an empty
   body and a 304 status if there are no new entries. This is the behavior
   that pubsubhubbub recommends
   <http://code.google.com/p/pubsubhubbub/wiki/PublisherEfficiency>.

       $ curl -H 'If-None-Match: "42"' http://localhost/atombus/feeds/widgets

   Note that the most messages you will get per request is determined by
   the page_size setting. If you do not specify a page_size setting, it
   defaults to 1000. This default may change in the future, so don't count
   on it.

   AtomBus is mostly a proper implementation of the AtomPub protocol and
   will validate 100% against <http://validator.w3.org/feed>. One point
   where it diverges from the AtomPub spec is that feed entries are
   returned in fifo order. This is because a message consumer will most
   likely want to consume messages in the order that they were published.
   In the future, a config setting may be available to reverse the order.

CONFIGURATION
   Configuration can be achieved via a config.yml file or via the set
   keyword. To use the config.yml approach, you will need to install YAML.
   See the Dancer documentation for more information. The only required
   config setting is the dsn.

   Example config.yml:

       # Dancer specific config settings
       logger: file
       log: errors

       atombus:
           page_size: 100
           db:
               dsn:  dbi:mysql:database=atombus
               user: joe
               pass: momma

   You can alternatively configure the server via the 'set' keyword in the
   source code. This approach does not require a config file.

       use Dancer;
       use AtomBus;

       # Dancer specific config settings
       set logger      => 'file';
       set log         => 'debug';
       set show_errors => 1;

       set atombus => {
           page_size => 100,
           db => {
               dsn => 'dbi:SQLite:dbname=/var/local/atombus/atombus.db',
           }
       };

       dance;

DATABASE
   AtomBus is backed by a database. The dsn in the config must point to a
   database which you have write privileges to. The tables will be created
   automagically for you if they don't already exist. Of course that
   requires create table privileges. All databases supported by DBIx::Class
   are supported, which are most major databases including postgresql,
   sqlite, mysql and oracle.

DEPLOYMENT
   Deployment is very flexible. It can be run on a web server via CGI or
   FastCGI. It can also be run on any Plack web server. See
   Dancer::Deployment for more details.

 FastCGI
   AtomBus can be run via FastCGI. This requires that you have the FCGI and
   Plack modules installed. Here is an example FastCGI script. It assumes
   your AtomBus server is in the file atombus.pl.

       #!/usr/bin/env perl
       use Dancer ':syntax';
       use Plack::Handler::FCGI;

       my $app = do "/path/to/atombus.pl";
       my $server = Plack::Handler::FCGI->new(nproc => 5, detach => 1);
       $server->run($app);

   Here is an example lighttpd config. It assumes you named the above file
   atombus.fcgi.

       fastcgi.server += (
           "/atombus" => ((
               "socket" => "/tmp/fcgi.sock",
               "check-local" => "disable",
               "bin-path" => "/path/to/atombus.fcgi",
           )),
       )

   Now AtomBus will be running via FastCGI under /atombus.

 Plack
   AtomBus can be run with any Plack web server. Just run:

       plackup atombus.pl

   You can change the Plack web server via the -s option to plackup.

MOTIVATION
   I like messaging systems because they make it so easy to create scalable
   applications. Existing message brokers are great for creating message
   queues. But once a consumer reads a message off of a queue, it is not
   available for other consumers. I needed a system to publish events such
   that multiple heterogeneous services could subscribe to them. So I
   really needed a message bus, not a message queue. I could for example
   have used something called topics in ActiveMQ, but I have found ActiveMQ
   to be broken in general. An instance I manage has to be restarted daily.
   AtomBus on the other hand will be extremely stable, because it is so
   simple. It is in essence just a simple interface to a database. As long
   as your database and web server are up, AtomBus will be there for you.
   And there are many ways to add redundancy to databases and web heads.
   Another advantage of using AtomBus is that Atom is a well known
   standard. Everyone already has a client for it, their browser. Aren't
   standards great! By the way, if you just need message queues, try
   POE::Component::MessageQueue. It rocks. If you need a message bus, give
   AtomBus a shot.

AUTHOR
   Naveed Massjouni <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2010 by Naveed Massjouni.

   This is free software; you can redistribute it and/or modify it under
   the same terms as the Perl 5 programming language system itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.