== How to get latest version ==

To get a copy of the current repository:

  darcs get http://jabber-rpc.rubyforge.org

If you don't have darcs, you can find it at
http://abridgegame.org/darcs, or just download the latest jabber-rpc
snapshot at http://jabber-rpc.rubyforge.org/jabber-rpc.tar.gz.


== Jabber-RPC ==

This is a means for an object to expose functionality to the outside
world, and for a client to access that functionality.  Other players
in this field you might know of are SOAP and XMLRPC over HTTP, and
CORBA.

Unlike CORBA, in Jabber-RPC conversation is not limited to a set of
trusted computers.

Unlike SOAP and XMLRPC over HTTP, the object exposing functionality
needs not be running on an Internet server, it can be anywhere (as
long as a connection can be made to a Jabber server), also inside a
LAN behind a firewall.  Communication can be asynchronous, both
parties can initiate it.

Being also used as a transport for instant messaging, Jabber has
potential as User to Application platform, a place where users and
applications (or shall we say `agents' at this point) share the same
space as peers.


== Status ==

Highly experimental, no installation procedure, you even have to hack
the sources to have the tests work.  Scary enough? :-)


== See it at work ==

For a simple test, register two Jabber IDs with a Jabber server, then
in the tests at the end of the rpc.rb file change the constants
AGENT_JID, AGENT_PWD, CLIENT_JID, CLIENT_PWD to match the IDs you
registered.  Then run:

  ruby rpc.rb

Have a look at the tests' source to see what's going on.  For a
juicier example, run:

  ruby todo_agent.rb -h

This is a little assistant which will happily record todo items for
anyone in the world, keeping a separate list for each requester.
Provide appropriate parameters for Jabber ID, password, and database
connection settings:

  ruby todo_agent.rb --jid "bot@localhost/Todo" --password "bot"


== Dependencies ==

jabber4r (http://rubyforge.org/projects/jabber4r/)


== Quick RPC tutorial ==

To expose an object, assuming "bot@localhost" is a valid Jabber ID and
its password is "bot":

  require "jabber/rpc"

  class TestAgent < Jabber::RPC::BasicAgent
    def exposed_commands
      ["alive?"]
    end

    def alive?
      true
    end
  end

  agent = TestAgent.new("bot@localhost/TestAgent", "bot")
  agent.connect

To talk to an agent from an application, assuming "user@localhost" is
a valid Jabber ID and its password is "user":

  session = Jabber::Session.bind("user@localhost/Ruby", "user")
  agent = Jabber::RPC::Client.new(session, "bot@localhost/TestAgent").proxy3
  agent.alive?  #=>  true


== License ==

Same as Ruby


== Author ==

Massimiliano Mirra, mmirra <at> sanniolug <dot> org

Several snippets included from xmlprc4r module for Ruby by Micheal
Neumann and jabber4r by Rich Kilmer.


== More information ==

* http://www.openp2p.com/pub/a/p2p/2002/01/11/jabber_bots.html

"Is Jabber's Chatbot the Command Line of the Future?"  An article on
Jabber bots.

* http://www.jabber.com/media/Jabber_Messaging_Web_Services.pdf

Overview of Jabber as middleware for remote services

* http://www.newsforge.com/article.pl?sid=04/11/23/1546233

General introduction to Jabber and XMPP, mostly from the user
perspective

* http://www.infoworld.com/articles/pl/xml/02/09/30/020930plentim.html

General article on instant messaging in the enterprise, the
interesting part is the "Web Services, Jabber-style" box at the
end

* http://jabberzilla.jabberstudio.org/wifm/imandmore.shtml

* http://jabberzilla.jabberstudio.org/wifm/speed.shtml

A couple of pages that whetted my appetite

* http://www.jabber.org/jeps/jep-0009.html

Official specs for Jabber-RPC

* http://www.oreilly.com/catalog/jabber/chapter/ch05.html

Sample chapter from "Programming Jabber": "Jabber Technology Basics"


== To do ==

Possibly relocate the server/agent class as XMLRPC::JabberServer,
together with Server, CGIServer, WEBrickServlet etc.

Bring on par with XMLRPC::Server: add multicall, introspection and
asynchronous calls.

Reintegrate User To Application layer to translate user commands into
RPCs and responses into user readable results.

Make my mind up on Server (consistent with names in XMLRPC module)
vs. Agent (cooler :-)).
