hemlock 配置记录(real-time web applications)

作者：敖士伟 ikmb@163.com

主要参见： http://hemlock-kills.com/learn

下面实践配置注意事项

平台：CentOS 5

所用软件：
jre1.6.0_05
flex_sdk_3.4
ruby1.9.1（就不需要rake了）
rubygems-1.3.3
环境变量（例）
/opt/rubygems-1.3.3/bin:/usr/lib/jre1.6.0_05/bin:/usr/opt/ruby191/bin:/root/flex_sdk_3.4/bin
以及JAVA＿HOME

 /etc/profile
export PATH=/root/flex_sdk_3.4/bin:$PATH
export PATH=/usr/opt/ruby191/bin:$PATH
export PATH=/usr/lib/jre1.6.0_05/bin:$PATH
export PATH=/opt/rubygems-1.3.3/bin:$PATH
export FLEX_SDK_HOME="/root/flex_sdk_3.4"

对HEMLOCK的修改：
1、去掉hemlock/Rakefile中的require 'ftools'
2、修改hemlock/src/com/mintdigital/drawingDemo/containers/DrawingDemoContainer.as中override protected function initialize():void{方法中include为绝对路径，如： include '/opt/hemlock/src/config/environment.as';

============

We will update this documentation regularly. It is not complete but you should have enough to get you started here. We just wanted to get the source code into your hands as soon as possible!

Getting Started

Hemlock is a framework for building real-time, multi-user web applications. It combines the speed and scalability of XMPP with the real-time connectivity and UI robustness of Flash. Read more about it on our blog.

Before you being developing with Hemlock, there are a few things you need to set up on your computer. Here, we'll walk you through those steps.

Adobe Flex

Hemlock relies on the Adobe Flex SDK. This is a free download from Adobe.com, and you can get it here.

The Flex SDK is bundled with:

• mxmlc: Command-line utility for compiling ActionScript into a SWF file.
• Flash Player: Stand-alone application for playing a SWF file outside of a browser.
• fdb: Command-line utility for tracking debug messages during SWF runtime.

After installation, you also need to set some environment variables (in your ~/.profile or equivalent in OS X, Linux, or Unix). Assuming that you installed at /Applications/Flex SDK 3, add this:

export PATH=/Applications/Flex/ SDK/ 3/bin:$PATH
export FLEX_SDK_HOME="/Applications/Flex/ SDK/ 3"

Update these to correspond to your particular installation path as needed.

ejabberd

Installing ejabberd

Hemlock uses ejabberd for XMPP. Dowload the free ejabberd installer here and run it. ejabberd will ask you for a virtual host; make sure you enter localhost here.

You will also need to add an alias for ejabberd to your profile or equivalent (OS X, Linux, Unix):

alias ejabberdctl="/Applications/ejabberd-2.0/bin/ejabberdctl"

Once again, update this to correspond to your particular installation path as needed.

From here on, you can type ejabberdctl in your command line to speak to ejabberd. To start ejabberd, just type this:

ejabberdctl start

There are also other commands for ejabberd, such as ejabberdctl stop, ejabberdctl restart, and ejabberdctl status. For more information, see the ejabberd reference documents.

Configuring ejabberd

Please ensure your computer has ports 5222 and 5280 open. If you're running OS X, these should be automatically open in 10.5 (Leopard); with older versions, you can configure under Firewall in System Preferences.

Next, we will disable secure data transfers in ejabberd for now. Open /Applications/ejabberd-2.0/conf/ejabberd.cfg in your text editor. Look for the 5222, ejabberd_c2s block in the “LISTENING PORTS” section, and comment out the line resembling:

{certfile, "/Applications/ejabberd-2.0/conf/server.pem"}, starttls,

You should also ensure that ejabberd.cfg lists localhost as a virtual host. To do this, check that ejabberd.cfg contains localhost in the “SERVED HOSTNAMES” section, and add localhost to hosts if necessary, like so:

{hosts, ["YOUR_COMPUTER_NAME.local", "localhost"]}.

A default ejabberd installation only allows one registration every 5 minutes. You will probably want to create accounts more often when you are testing. Therefore we will disable the registration time limit. To do this, find the section ACCESS RULES in your ejabberd.cfg and add the following to the end:

%% Disable registration time-limit
{registration_timeout, 1}.

Finally, restart ejabberd from command line to propagate the changes.

Setting up your ejabberd accounts

ejabberd should have created you an Admin account at installation. If not, follow the instructions here to create an admin ejabberd account.

You can login to the ejabberd web server with your admin account at

http://localhost:5280/admin

From here, you can create additional test accounts for your apps.

Ruby and Rake

Hemlock comes with a few scripts to streamline common tasks like compilation. To run these, you'll need to install:

• Ruby: download
• Rake: download

An example app

Hemlock ships with an example app called DrawingDemoContainer. With this app, multiple users can draw pictures together on the same canvas in real-time, using user interface elements that can be easily dropped into any Hemlock app.

Here's how to try it out:

1. Download Hemlock. The latest is available on Hemlock's download page on GitHub. Unarchive the downloaded file, and navigate into it via command line.
2. Prepare your ActionScript environment. Find the file config/environment.as-example, and save a copy of it as config/environment.as. Update your environment's SERVER and SOURCE_PATH values.
3. Compile the app. From within the Hemlock directory, run rake hemlock:build:drawingDemo. If you've followed the setup instructions, this should create a file at src/com/mintdigital/drawingDemo/containers/DrawingDemoContainer.swf.
4. Prepare the HTML for embedding. You'll find a template HTML file at public/index.html. Save a copy to your web server, or your local computer if you have web sharing enabled.
5. Embed the app. Move the .swf file to the same place as your HTML file. Then, update the HTML file's placeholders to point to the .swf file.
6. Start the Flash policy daemon. This allows Flash to communicate with the necessary XMPP port. Just run rake hemlock:start:policyd, which starts the daemon running in the background. This should run from the same domain as your HTML file (i.e., your web server or your local server).
7. Run the app! Navigate to the HTML file in your browser, and you should see the Flash-based sign-in form. Sign in, or if you don't have an account on this server yet, create one by entering a username and password, then clicking "Register". Create a room, then start drawing!

That's it—you're up and running with Hemlock!

Want to see what it's like with multiple people in the room? Just open another browser tab, open the app again, and sign in with a different account. Everything you draw in one window appears in the other!

Anatomy of a Hemlock app

A Hemlock app is based on two types of components, a HemlockContainer and some HemlockWidgets.

HemlockContainer

The HemlockContainer is the heart of the Hemlock app, and is the ActionScript compiler's starting point. The container is responsible for maintaining the app's models: it tracks the app's state, such as the list of users playing a game, and how many points each user has. The container also holds a collection of HemlockWidgets, described below.

HemlockWidget

While the container maintains the app's model data, the HemlockWidget maintains the app's views: creating the user interface and handling user input, such as chat messages and mouse clicks. The widgets packaged with Hemlock are designed to plug into any Hemlock app. For instance, the framework includes ChatroomWidget, which lets users send text-based messages to each other, and DrawingWidget, which lets users draw pictures on a single canvas in real-time. Both of these are demonstrated in the included DrawingDemoContainer.

Hemlock apps use Flash's built-in event system to communicate between a HemlockContainer and its HemlockWidgets. When the app receives data, it is propagated throughout the app like this:

1. Raw data reaches the app from the XMPP server. Hemlock turns this into a native ActionScript object, and notifies your app by dispatching an event on a HemlockDispatcher. The HemlockContainer should be listening to the HemlockDispatcher for events that the app is interested in. Typically, these include events related to session (dispatched when a user signs in or out) and presence (dispatched when a user enters or exits the app).
2. When the container observes an event that it was listening for, it handles the event first by updating its model data (e.g., its internal list of users present, number of points per user). Then, the app redispatches the same event on itself.
3. The container has a collection of HemlockWidgets. Each widget listens to the container for any subset of events that it's interested in. For instance, one widget might listen for chat events; another might listen for drawing events. Each widget then updates its own views according to data from the events.

By using this event flow, widgets and containers are loosely coupled—the container never directly tells a widget what to do. Instead, the container announces (by dispatching events on itself) that new data is available, and any listening widgets act on that data independently. As an app matures, this means that old widgets can be swapped out for new ones, and useful widgets can be easily reused in other containers.

To learn more about Hemlock's inner workings, take a look at our Code section.