Sophisticated Asterisk Development with Adhearsion
Pages: 1, 2, 3, 4

Distributing and Reusing Code

Because an Adhearsion application resides within a single folder, completely copying the VoIP application is as simple as zipping the files. For one of the first times in the Asterisk community users can easily exchange and build upon another's successful application. In fact, open sourcing individual Adhearsion applications is greatly encouraged.

Additionally, on a more localized level, users can reuse Adhearsion framework extensions, called helpers, or roll their own. Helpers range from entire sub-frameworks like the Micromenus framework for integrating with on-phone microbrowsers to adding a trivial new dial plan method which returns a random quote by Oscar Wilde.

Below is a simple Adhearsion helper written in Ruby. It creates a new method that will exist across the entire framework, including the dial plan. For simplicity's sake, the method downloads an XML document at a specified HTTP URL and converts it to a Ruby Hash object (Ruby's associative array type).

def remote_parse url
  Hash.from_xml open(url).read
end

Note that these three lines can work as the entire contents of a helper file. When Adhearsion boots, it executes the script in a way which makes any methods or classes defined available anywhere in the system.

For some issues, particularly ones of scaling Adhearsion, it may be necessary to profile out bottlenecks to the king of efficiency: C. Below is an example Adhearsion helper, which returns the factorial of a number given:

int fast_factorial(int input) {
  int fact = 1, count = 1;
  while(count <= input) {
    fact *= count++;
  }
  return fact;
}

Again, the code here can exist as the entire contents of a helper file. In this case, because it is written in C, it should have the name factorial.alien.c. This tells Adhearsion to invoke its algorithm to read the file, add in the standard C and Ruby language development headers, compile it, cache the shared object, load it into the interpreter, and then wrap the C method in a Ruby equivalent. This is an example dial plan that simply speaks back the factorial of six using this C helper.

fast_test {
  num = fast_factorial 6
  play num
}

Note that the C method becomes a first-class Ruby method. Ruby number objects passed to the method are converted to C's "int" primitive and the return value is converted back to a Ruby number object.

Helpers promise robust albeit simple extensibility to a VoIP engineer's toolbox but, best of all, useful helpers can be traded and benefit the entire community.

Integrate with Your Desk Phone Using Micromenus

With increasing competition between modern IP-enabled desk phone manufacturers, the microbrowser feature has snuck in relatively unnoticed and underused. The principle is simple: physical desk phones construct interactive menus on a phone by pulling XML over HTTP or the like. Contending interests, however, lead this technology amiss—every vendor's XML differs, microbrowsers are often quirky, and available features vary vastly.

The Micromenus framework exists as an Adhearsion helper and aims to abstract the differences between vendors' phones. For this very particular development domain (i.e., creating menus), Micromenus uses a very simple Ruby-based "Domain Specific Language" to program logic cleanly and independent of any phone brands.

This is a simple example Micromenu:

image 'company-logo'
item "Call an Employee" do
  # Creates a list of employees as callable links from a database.
  Employee.find(:all).each do |someone|
    # Simply select someone to call that person on your phone.
    call someone.extension, someone.full_name
  end
end
item "Weather Information" do
  call "Hear the weather report" do
    play weather_report("Portland, OR")
  end
  item "Current: " + weather("Portland, OR")[:current][:temp]
end
item "System Uptime: " + `uptime`

A list item displays in two ways. If given only a text String, Micromenus renders only a text element. If the arguments contain a do/end block of nested information, that text becomes a link to a sub-page rendering that nested content.

A call item also has two uses, each producing a link that, when selected, initiates a call. When call receives no do/end block, it simulates physically dialing the number given as the first argument. When a do/end block exists and all calls route through Adhearsion, selecting that item executes the dial plan functionality within the block. This is a great example of how handling the dial plans and on-screen Microbrowsers within the same framework pays off well.

From this example we can see a few other neat things about Micromenus:

• Micromenus supports sending images. If the requesting phone does not support images, the response will have no mention of them.

• All Adhearsion helpers work here too. We use the weather helper in this example.

• The Micromenus sub-framework can use Adhearsion's database integration.
• Ruby can execute a command inside backticks and return the result as a String. We report the uptime here with it.

The example above of course assumes you have configured your application's database integration properly and have an Employee class mapping to a table with an extension and full_name column.

Because Micromenus simply renders varying responses over HTTP, a normal web browser can make a request to the Micromenus server too. For these more high-tech endpoints, Micromenus renders an attractive interface with Ajax loading, DHTML effects, and draggable windows.

In the interest of "adhering" people together, Micromenus exists as another option to make your Adhearsion VoIP applications more robust.

Integrating with a Web Application

Though Adhearsion by design can integrate with virtually any application, including PHP or Java Servlets, Ruby on Rails makes for a particularly powerful partner. Rails is a web development framework getting a lot of press lately for all the right reasons. Its developers use Ruby to its full potential, showing how meta-programming really does eliminate unnecessary developer work. Rails' remarkable code clarity and application of the Don't Repeat Yourself (DRY) principle served as a strong inspiration to the inception of Adhearsion as it exists today.

Starting with Adhearsion version 0.8.0, Adhearsion's application directory drops in place on top of an existing Rails application, sharing data automatically. If you have needs to develop a complex web interface to VoIP functionality, consider this deadly duo.

Using Java

Eyebrows around the world raised when Sun announced itshiring of the two core developers of the JRuby interpreter project, Charles Nutter and Thomas Enebo, in September 2006. JRuby is a Ruby interpreter written in Java instead of C. Because JRuby can compile parts of a Ruby application to Java bytecode, JRuby is actually outperforming the C implementation of Ruby 1.8 in many different benchmarks and promises to outperform Ruby 1.8 in all cases in the near future.

A Ruby application running in JRuby has the full benefit of not only Ruby libraries but any Java library as well. Running Adhearsion in JRuby brings the dumbfounding assortment of third-party Java libraries to PBX dial plan writing. If your corporate environment requires tight integration with other Java technologies, embedding Adhearsion in a J2EE stack may offer the flexibility needed.

Additional Information

• For more information about the fast-moving Adhearsion community, including complete walkthroughs, see Adhearsion's official web site at http://adhearsion.com.
• Adhearsion's official blog at http://blog.adhearsion.com.
• The web site of Adhearsion's parent consulting company http://codemecca.com. Codemecca is the official maintainer of Adhearsion and provides Adhearsion consulting. Codemecca specializes in using Adhearsion to rapidly build complex, next-generation phone systems and leveraging VoIP effectively in a new or existing product. If you have sophisticated plans with VoIP using Asterisk, consider using this powerful, new technology with Codemecca's assistance.

Jay Phillips is an innovator in the spaces where sophisticated VoIP development falls apart and where Ruby rocks. As the creator of Adhearsion and its parent company Codemecca, Jay brings new possibilities to these two technologies through his work on the open-source Adhearsion framework and its parent company Codemecca.

---

Return to Emerging Telephony.