JBoss.orgCommunity Documentation

Chapter 3. Poorsmatic

3.1. Get the source
3.2. Poorsmatic application overview
3.2.1. Web
3.2.2. Database
3.2.3. 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.4.4. Transactions
3.5. Wrapping up

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

We will create an application called Poorsmatic, a "poor man's Prismatic". This is a truly awful content discovery service that merely returns URL's from Twitter that contain at least one occurrence of the search term used to find the tweets containing the URL's in the first place.

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

We made the application source available for you in the TorqueBox git repository in examples/poorsmatic/ directory. To get started you need to clone the repository.

$git clone git://github.com/torquebox/torquebox.git
Cloning into 'torquebox'...
remote: Counting objects: 77466, done.
remote: Compressing objects: 100% (26065/26065), done.
remote: Total 77466 (delta 37601), reused 76739 (delta 36971)
Receiving objects: 100% (77466/77466), 47.06 MiB | 2.48 MiB/s, done.
Resolving deltas: 100% (37601/37601), done

File location

When not said otherwise every file location used in this guide will be relative to the examples/poorsmatic/ directory located under the checkout directory.

The main goal of the application is to grab tweets from Twitter stream. We'll use a TwitterService implemented as TorqueBox service. The service itself will be instructed in which keywords we're interested via terms topic. Received tweets will be scanned for URL's and those URL's will be put into url's queue for processing. The URLScraper will be responsible for visiting all URL's from the urls queue and counting the words found in the <body/> tag on the page. Results will be put into database. There will be also a web interface for viewing the URL's and editing the terms.

We choose PostgreSQL mainly because it has support for transactions which will be used in our application.

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

$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........... 2.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 http://127.0.0.1:9990/management
14:35:02,073 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on http://127.0.0.1:9990
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 the torquebox deploy command:

$torquebox deploy
Deployed: poorsmatic-knob.yml
    into: /home/goldmann/work/torquebox-2.2.0/jboss/standalone/deployments

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

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

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

In our application we use Twitter to receive tweets from the stream filtered by some keywords. The best way to run something constantly is to implement it as a TorqueBox service. Below you can find a simple skeleton.


The code is pretty self-explaining. 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. 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 in TwitterService class. We need to do it in the mentioned before torquebox.rb deployment descriptor. You may also ask how do we inject the credentials required to connect to Twitter? Yes, you're right, deployment descriptor.


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

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

Messaging allows us to create loosely coupled applications. Using queues and topics aswell 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 - take a look at the messaging section of TorqueBox manual.

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


A new message processor will be created for each message that arrives to the queue. The message itself will be injected 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 thing to do is to simply get access to the service and execute an update method on it. Let's do it!


Each time a TermConsumer message processor is created TorqueBox will use its power to inject the TwitterService service into the consumer. Afterwards the terms will be injected into the on_message method and the update method will be executed on the service itself. The only thing that left now is to show the update method in TwitterService class.


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

Last thing left to do is to wire the message consumer with the queue or topic. We use the deployment descriptor. Here is how to do it:


You can ask yourself what 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 many messages arriving and needs more workers to process them.

You can find another message processor used to retrieve and parse web pages in url_scrapper.rb file. Since URLScrapper doesn't do anything fancy besides counting the words in <body> and saving the result in a database we'll not go into discussing it this time, sorry.

The last feature of TorqueBox used in the presented application are distributed transactions. Distributed transaction ensure the atomicity of the execution. They can span across the whole application. For example a transaction could be started in the web layer and end in database. This is exactly how we use it in Poorsmatic!


Look at the post '/terms' block. This code is executed when we try to save a new term using the web page. First - we create a Term object, then we start a transaction and try to save the object to the database. If the operation was successfull we send a list of the terms (see terms_changed method) as array to the /topic/terms topic.

The nice thing about transaction is that they're atomic. This means that if an error occurs in the transaction block, the transaction is rolled back and the state is restored. For example if an error occurs in our case during sending a message to the topic, the whole transaction is rolled back and the database state will be restored too!

You can find another usage of transaction in the delete '/term:id' block. It'll make sure that we'll notify the terms queue only after successful removal of the term from database.

Since distributed transactions is an advanced topic you can read about them in the TorqueBox manual. You'll find there more information about transactions itself or configuration options.

Congratulations! You know now many of TorqueBox features. There are still many to explore. To learn more about them just open the TorqueBox manual and use them.

Poorsmatic application was just a simple example. You can always go back to the source code and see again how it was done.