Cosmopolite

Client/server publish/subscribe and key/value storage for AppEngine

Cosmopolite Tutorial

AppEngine prerequisites

  1. Download and install the Python AppEngine SDK

Server-side setup

  1. Create an application in your SDK client
  2. Download cosmopolite via the links at left. Unpack it into a "cosmopolite" subdirectory of your local application
  3. Create an app.yaml file for your application.
  4. Add a cosmopolite include to your app.yaml file: 
    includes:
- cosmopolite
  5. Start the application in your SDK client

Test cosmopolite

  1. Access your local cosmopolite debug page (replace port if necessary): http://localhost:8080/cosmopolite/static/debug.html
  2. Subscribe to a subject "testsubject"
  3. Send a message to that subject; it should appear in the message list below

Create a test page

  1. Create a test.html page at the top level of your application: 
    <html>
  <head>
    <script src="/cosmopolite/static/cosmopolite.js" charset="UTF-8"></script>
  </head>
  <body>
    <script>
// Subsequent script examples go here
    </script>
  </body>
</html>
  2. Add a mapping to app.yaml: 
    handlers:
- url: /test.html
  static_files: test.html
  upload: test.html
  3. Have it create a cosmopolite instance and send a message to it: 
    var cosmo = new Cosmopolite();
cosmo.sendMessage('testsubject', 'test message');
  4. Keep the debug page (from above) up and subscribed (to "testsubject") in one browser tab
  5. Load your test page in an incognito window (right click/control-click, Open Link in Incognito Window)
  6. The debug page should show the message from the test page
  7. You've written code that uses cosmopolite!

Time out for concepts

  1. Subject: a topic that clients that publish and subscribe to, e.g. "books"
  2. Message: a single chunk of data transmitted to a single subject, e.g. "I love books!"
  3. Key: an optional string associated with a message, that can be used to look up the last message with a given key, e.g. "title" (key) = "A place to talk about books" (message)
  4. Client: an instance of Cosmopolite() in a browser
  5. Profile: a collection of clients that all speak as the same user (and so should appear the same to subscribers)

Subscribe to a subject

  1. Change your test script: 
    var callbacks = {
  onMessage: function(msg) {
    alert(msg['message']);
  },
};
var cosmo = new Cosmopolite(callbacks);
cosmo.subscribe('testsubject');
  2. Load (or re-load) the test page (still in an incognito window)
  3. Use the debug interface to send a message to testsubject
  4. Your test page should generate an alert popup