JBoss.orgCommunity Documentation

Chapter 3. Poorsmatic

3.1. Get the source
3.2. Poorsmatic application overview
3.2.1. Web
3.2.2. Configuration
3.3. Launch the application
3.4. Basic TorqueBox features
3.4.1. Deployment descriptor
3.4.2. Service
3.4.3. Messaging
3.5. Wrapping up

This chapter shows you how to build a simple web application based on Sinatra. Although the application itself is very small, it uses most of the features of TorqueBox.

We will create an application called Poorsmatic, a "poor man's Prismatic". This is a truly awful content discovery service that searches twitter using given terms, then extracts URLs from matching tweets and counts the occurrence of the search terms in the content from each URL.

If you don't get it - don't worry - everything will be clear later.

The source for our example application is available in the examples/poorsmatic/ directory of the TorqueBox source zip. To get started you need to download and unzip the source zip file.

$ wget http://torquebox.org/release/org/torquebox/torquebox-dist/3.2.0/torquebox-dist-3.2.0-src.zip
unzip torquebox-dist-3.2.0-src.zip

Our main data source for the application are tweets from the Twitter stream. We'll use a TorqueBox service (TwitterService) to do that. The service itself will be notified about which keywords we're interested via the terms topic. Received tweets will be scanned for URLs and those URLs will be put on to urls queue for processing. The URLScraper will be responsible for visiting each URL from the urls queue and counting the matching search terms found in the <body/> tag on the page. The resulting URLs and counts will be stored in the database. The final piece is a web interface for viewing the URLs and editing the search terms.

The object-relational mapper we've chosen is DataMapper. To see the DataMapper configuration details, look in torquebox_init.rb. Our models are defined in the models/ directory.

In this quick overview of the app we will not go into the full details of the models - feel free to peruse that code at your leisure.

It's time to launch the application for the first time. First, we need to start TorqueBox by executing torquebox run. The output should be similar to:

$torquebox run
14:34:42,734 INFO  [org.torquebox.jobs.as] Initializing TorqueBox Jobs Subsystem
14:34:42,735 INFO  [org.torquebox.services.as] Initializing TorqueBox Services Subsystem
14:34:42,738 INFO  [org.torquebox.core.as] Initializing TorqueBox Core Subsystem
14:34:42,740 INFO  [org.torquebox.security.as] Initializing TorqueBox Auth Subsystem
14:34:42,740 INFO  [org.torquebox.web.as] Initializing TorqueBox Web Subsystem
14:34:42,733 INFO  [org.torquebox.cdi.as] Initializing TorqueBox CDI Subsystem
14:34:42,792 INFO  [org.torquebox.stomp.as] Initializing TorqueBox STOMP Subsystem
14:34:42,791 INFO  [org.projectodd.polyglot.stomp.as] Initializing Polyglot STOMP Subsystem
14:34:42,807 INFO  [org.projectodd.polyglot.hasingleton.as] Initializing HA-Singleton Subsystem
14:34:42,808 INFO  [org.projectodd.polyglot.cache.as] Initializing Polyglot Cache Subsystem
14:34:42,854 INFO  [org.torquebox.core.as] Welcome to TorqueBox AS - http://torquebox.org/
14:34:42,855 INFO  [org.torquebox.core.as]   version........... 3.2.0
14:34:42,856 INFO  [org.torquebox.core.as]   build............. 74
14:34:42,857 INFO  [org.torquebox.core.as]   revision.......... 530d7d30a5ba5ca953eba21b2aa6df1bf4022649
14:35:02,072 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015961: Http management interface listening on
14:35:02,073 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on
14:35:02,073 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss AS 7.1.x.incremental.129 "Arges" started in 21875ms - Started 281 of 400 services (118 services are passive or on-demand)

Now we're ready to deploy the application. To do so go to the examples/poorsmatic/ directory and execute torquebox deploy:

$torquebox deploy
Deployed: poorsmatic-knob.yml
    into: /Users/someone/torquebox-3.2.0/jboss/standalone/deployments

You can now reach your application at http://localhost:8080/poorsmatic/. If you see "Hello from Poorsmatic!", it means that everything worked perfectly!

Congratulations! You now have a running web application. In the next few steps we will discuss the TorqueBox features we used to build it.

In this section we'll discuss the basic TorqueBox features which made it possible to build this application.

In our application we filter the Twitter stream with a set of keywords. The best way in TorqueBox to run something that needs a constant connection is to implement it as a TorqueBox service. Below you can find a simple skeleton service.

The code is fairly self-explanatory. The only thing you need to keep in mind is that the start method is executed when you deploy the service. Similarly the stop method is executed when you undeploy the service. It's as simple as that.

In our application we'll use the twitter4j4r Twitter client (please don't ask about the name).

Now we need to inform TorqueBox that we want to deploy a service implemented by TwitterService class. We do so in our deployment descriptor (torquebox.rb). You might also ask how we inject the credentials required to connect to Twitter? Yes, you're right, the deployment descriptor.

Before you deploy the application make sure you use the correct credentials. You can generate them on the
Twitter apps page. Just create a new application and you're ready to rock.

You may wonder how we update the keyword list we want to watch on Twitter? We'll use the messaging features of TorqueBox.

Messaging allows us to create loosely coupled applications. Using queues and topics as well as message producers and consumers is very easy, so let's start right away! If you're new to the messaging terms, don't fear - just take a look at the messaging section of the TorqueBox manual.

It's pretty easy to consume a message from a queue or topic. You use message processors.

A new message processor instance will be created for each message that arrives to the queue. The message itself will be passed to the on_message method. You can do whatever you want with it afterwards. In our case we want to update the keywords in the twitter service. The easiest way to do that is to get access to the service and execute an update method on it. Let's do it!

Each time a TermConsumer message processor instance is created, TorqueBox will inject the TwitterService service into the processor. Then terms will be passed to the on_message method and the update method will be executed on the service itself. The only thing left now is to show the update method in the TwitterService class.

Execution of this method will update the terms list. Additionally the Twitter client will be restarted to watch for the new keywords.

The last task left with setting up this processor is to wire the message consumer to the queue or topic. We use the deployment descriptor. Here's how:

You may ask yourself what the concurrency parameter means. This tells TorqueBox how many message processors of the selected type should be connected to the selected queue. This is very handy if you expect to have messages arriving faster than you can process them.

You can find another message processor that is used to retrieve and parse web pages in url_scrapper.rb. Since URLScrapper doesn't do anything fancy other than counting the words in <body> and saving the result to the database, we won't go into its details.

Congratulations! You now know a little about a few of the features of TorqueBox. There are still many to explore. To learn more about them, take a look at the TorqueBox manual.

The Poorsmatic application was just a simple example. Feel free to go through the source code to in detail how it was done.