Karotz can connect to the internet and you can deploy applications on it. It’s a tiny multitalent, speaks, blinks, turns his ears, takes photos and plays musik. The really cool stuff about all this, is that you can also access it via a REST-api.

I was a little disturbed by the bad documentation of the api, but since Karotz has had a pretty shaken history, I was willing to see over it. Nevertheless I had a really hard time figuring out how to use the API, especially the interactiveMode sessions, which are crucial for interacting with Karotz. That’s why I wanted to give you a short HOW-TO wrapup on it.

Basic Setup

First of all you need to have a Karotz up and running, like it’s described in the handbook. Register yourself at karotz.com and click on the lab button at the bottom of the page. Once you registered yourself for all the developer stuff, you need to register a new application for yourself in order to get access to the credentials needed to talk to Karotz.

In order to get your own application, you need to create a descriptor.xml and package it as a zip-file and then load it up to the appstore and then deploy it to your bunny. Here is an example, which exposes the install-id of your application, which you need to accesss your Karotz:

<descriptor>
  <version>0.0.1</version>
  <accesses>
    <access>tts</access>
    <access>ears</access>
    <access>led</access>
    <access>multimedia</access>
  </accesses>
  <deployment>external</deployment>
  <parameters>
    <parameter key="showInstallUuid" value="true"/>
  </parameters>
</descriptor>

Have a look at this Christops Blog if you don’t get it working for yourself.

Using the Gem

There are already some code-examples on the developer-pages on how to get an interactive_id for your Karotz and some code has been released for Ruby as ruby-karotz here and here none of them exposing a nice API or describing the process of how to get all the peaces of the puzzle together. That’s why I am currently writing this…

So here is an example of how to interact with the karotz gem:

Karotz::Configuration.configure do |config|
  config.install_id = ENV['KAROTZ_INSTALL_ID']
  config.api_key    = ENV['KAROTZ_API_KEY']
  config.secret     = ENV['KAROTZ_SECRET']
end
 
Karotz::Client.session do |karotz|
  karotz.ears
  karotz.led
  karotz.say
  karotz.play
end

This will rotate Karotz ears, blink the LED, say ‘test’ and let it play the A-TEAM theme!

FTW!

Ternary Operator

I am using the Ternary Operator quite a lot, because it keeps the code concise and often times more readable then long if-else statements. One thing that I discovered just recently is the following:

val = something ? 'this' : 'that'

If you look closely, you will see that there is not a comparison == but an assignment = operator present. The interesting fact though is where Ruby puts parenthesis in this code:

val = (something ? 'this' : 'that')

Makes a lot of sense, but is not obvious, especially if you are debugging some library code.

Another cool thing that you can do with the operator is nesting:

val == 0 ? 'zero' : val == 1 ? 'one' : 'other'
# is interpreted as
(val == 0 ? 'zero' : (val == 1 ? 'one' : 'other'))

But most of the times you are better of with Switch Cases.

Switch Case

There are some pretty cool features in the Ruby Switch Case. You can switch by class if you like:

case "some string"
when Integer
  puts "i am an int"
when String
  puts "i am a string"
else
  puts "dunno"
end

This works, because Ruby uses the === method to compare in a when block. So the when code above evaluates to:

String === "some string"

The cool thing is that you can implement the === method yourself and add some Ruby magic to the Switch Case.

But be aware of some stuff that might bite you while using Switch Cases! You should know that Ruby allows multiple arguments in a when block:

case val
when 5, 7
  puts "good numbers"
else puts "bad numbers"
end

It’s also important to know that you need to add a newline before writing your block code. It’s also possible to write oneliners by using a semicolon or the then keyword, otherwise the following code will be interpreted as belonging to the when condition:

case val
when 5, 7; puts "good numbers"
when 0 then puts "empty"
when 1, puts "syntax error"
else puts "bad numbers"
end

Older versions of Ruby also supported a syntax with a : at the end instead of a ;, wich looks kind of strange:

case val
when :number: puts "numbers"
else puts "not a numbers"
end

Missing something

Since the Ruby parser allows a lot of flexibility, it’s possible to implement stuff which does not make sense at all. For example this statement which misses the if at the beginning of the condition:

def test_failing
  else puts "invalid"
  end
end

Evaluating this method will fail (or even kill the ruby process):

warning: else without rescue is useless
syntax error, unexpected keyword_end, expecting $end

One thing that happens to me quite often, is that there are implicit things going on if you forget to add commas in your code, while I am not sure how and why they work:

puts "what" "the" "fuck" # => "whatthefuck"
puts String Integer # => Integer

Everything is a Method

Well not everything in Ruby is implemented as a method, but there a lot of things that you can at least use like methods. Did you know for example, that you can call the accessibility modifiers in Ruby like methods? This is pretty handy if you want to mark only some methods:

def my_method; end
private :my_method

It’s also quite important to know that method objects provide a lot of interesting information. Especially if you are doing some serious debugging with a lot of inheritance and Ruby magic involved:

"".method(:class).owner # => Kernel
class A
  def b;end
end
# works only in 1.9
A.new.method(:b).source_location # => ["...test.rb", 3]

When talking about methods, it’s worth knowing the keywords that are used in Ruby and in which context they can be used. A good example for this is the * character, which can be used quite differently:

# as a simple method
1 * 2
# for varargs in method signatures
def method_name(*args)
# for unsplatting arrays
some_method_that_has_three_args(*[1, 2, 3])

You should also be aware that some operators behave different from others:

def some_array
  @some_array ||= []
end
 
def doit
  some_array << [3,4] # ok
  some_array += [6,7] # raises undefined method `+' for nil:NilClass
end

Predefined Variables

In analogy to Pearl, Ruby provides a bunch of Predefined Variables that are worth knowing. A lot of them contain information about the current environment, code or execution context.

There are f.e. some extra variables for matching groups in Rubys regular expressions:

"hey_you" =~ /(.*)_(.*)/
$1 # => hey
$2 # => you
$0 # => .../test.rb

Unfortunately $0 has nothing to do with match groups, but is the name of the current executed program…

Naming Best Practices

When working with Ruby you get used to some best practices when it comes to names. This is important, because several thing are evaluated differently depending on up- and downcase:

CONSTANTS_ARE_UPPER_SNAKE_CASE
ClassesAreCamelCase
Modules::Should::Map::To::Folder::Structure

So it is quite surprising that Ruby comes with an Array() method which transforms everything it gets into an array unless it’s already an array:

Array("string") # => ["string"]
Array(["string"]) # => ["string"]

It’s also worth having a deep look into the Ruby documentation about Arrays and the Enumerable Module, because they provide a bunch of really cool helpers that can save you an everage developers lifetime if you know them by heart.

For some more cool Ruby tricks have a look at this Rubyinside post.

If you feel like sharing some more Ruby wisdom feel free to post a comment or contribute some sugar!

So, while sitting on my couch, I created a new resource for documentation of my pet project the asin gem, which you can find on heroku:

If you have any additions or questions feel free to fork the project or open up an issue on github.

Full Stack Background Processes

If you want to run a resque worker and a clockwork process within your web-app, this becomes a costly thing, even if those are just running some minor jobs in the night, because you need to pay for 2 additional dynos.
You could achieve this through defining multiple processes in your Procfile:

# Procfile
web: bundle exec rails server thin -p $PORT
worker: QUEUE=* bundle exec rake environment resque:work
clock: bundle exec clockwork app/clock.rb

heroku scale worker=1 clock=1

Sharing Addon Connections

As Heroku officially announced in their latest newsletter, it’s possible to share connections between multiple apps. In my case, this would be a connection to a redis key-value store, that is provided by Redistogo. It’s as simple as copying the environment configuration for the addon over to the second app:

heroku config | grep DATABASE_URL  --app sushi
=> DATABASE_URL   => postgres://lswlm...
 
heroku config:add DATABASE_URL=postgres://lswlm... --app sushi-analytics
=> Adding config vars: DATABASE_URL => postgres://lswlm...m/ldfoiusfsf
=> Restarting app... done, v74.

Going Freemium

So the solution for getting back to a free worker setup is combining 3 Heroku apps and a shared Redis connection through Redistogo:

heroku apps:create freemium-web --stack cedar --remote heroku
git push heroku master
 
heroku apps:create freemium-worker --stack cedar --remote worker
git push worker master
 
heroku apps:create freemium-clock --stack cedar --remote clock
git push clock master
 
heroku scale web=1 --app=freemium-web
heroku scale web=0 worker=1 --app=freemium-worker
heroku scale web=0 clock=1 --app=freemium-clock
 
heroku addons:add redistogo:nano --app=freemium-web
 
heroku config:add `heroku config -s --app=freemium-web|grep redis` --app=freemium-worker
heroku config:add `heroku config -s --app=freemium-web|grep redis` --app=freemium-clock

I created an example project running a Rails 3 application with a mounted Resque web, a Resque worker and a clock process with Clockwork.

Even simpler

If you are just looking for a simple solution of running a background process have a look at crony, a bootstrap project using rufus-scheduler.

Migrating From Bamboo to Cedar

Before migrating to Bamboo, you should make sure your app runs on Ruby 1.9.2. If your app is not already deployed successfully to bamboo-mri-1.9.2, you should do that first, and then come back and try Cedar.

Once you’re sure your app is fully compatible with Ruby 1.9.2, create an app on the Cedar stack and push to it. Currently, stack:migrate does not work for moving apps to Cedar.

Since there seem to be no blogposts of how to do all the stuff with an existing application I will try to cover everything that I did to do the migration manually in this article.

Cedar is different

If you are looking at the new stack you will notice that a lot has changed with Cedar. Most of the Heroku CLI has changed to reflect the new possibilites that come with the Cedar stack. Since Cedar introduces a new way of handling processes on Heroku, most of the commands are now streamlined with this:

# old
heroku console
heroku rake db:migrate
# new 
heroku run console
heroku run rake db:migrate
 
# have a look at running processes
heroku ps
 
# look at logs of different processes and tail the output
heroku logs --ps web -t

Preparing the Migration

I started by cloning my current app from Heroku into another directory and creating a new Cedar app on Heroku:

git clone git@heroku.com:hamburg-on-ruby.git legacy
cd legacy
heroku create --stack cedar

Adapting Cedar changes

The docs for creating a Rails 3 app on Cedar reflect some of the changes that have been introduced with Cedar.

One of those is that PostgreSQL is now recommended for local development and you need to have the pg-gem in your Gemfile. Otherwise you will get errors while running rake commands:

heroku run rake db:migrate
 
  Running rake db:migrate attached to terminal... up, run.1
  (in /app)
  rake aborted!
  no such file to load -- pg

Since I developed my app with SQLite3 and I don’t want to learn, install and manage ANOTHER Database I split up the database stuff for development, test and production:

# Gemfile
group :production do
  gem "pg"
end
 
group :development, :test do
  gem "sqlite3-ruby", :require => "sqlite3"
end

and exclude production dependencies from my local environment:

# put this into your .profile
alias bd="bundle --without=production"

It’s also recommended to serve Rails through thin webserver and manage the application with the Procfile manager foreman:

# Gemfile
gem "foreman"
gem "thin"

# Procfile
web: bundle exec rails server thin -p $PORT

foreman start

After going through those chages you should be able to see your application on localhost:

open http://localhost:5000

The migration process

If the application is running on your development machine you can start the core migration process by putting your legacy application into maintenance mode, so that no database changes will be made:

heroku maintenance:on
# stop worker, crons or whatever might be changing the db

Database Migration

After you completely halted everything on your dyno, you can start dumping the database to your development machine (I thought it would be neat to do a direct migration from the legacy database to the new Cedar database, but I did not get it working). You need to install the taps-gem in order to do any dumping. Taps will dump the database into your development database unless you provide an connection string to another database:

# use sqlite for dumping and do it into a separate file
heroku db:pull sqlite://dump.db
 
# mv the file to your Cedar application and push it
heroku db:push sqlite://dump.db

Config variables

If you have custom config variables in your application it’s pretty easy to move them into the new environment:

# list all config values of the legacy app in console format
heroku config -s
 
# replace the newlines with whitespaces and
# append all the configuration variables of 
# your new Cedar app at the end or remove the
# ones that you do not want to migrate!
 
# add the list of values to your Cedar app
heroku config:add KEY=VALUE KEY2=VALUE2 [...]

Installing addons

It’s also most likely that you want to use the same addons than in your legacy application:

# list your addons in the legacy app
heroku addons
 
# install all addons separately in the Cedar app
heroku addons:add apigee:basic
heroku addons:add cron:daily
[...]

Sendgrid

If you are using the Sendgrid Addon you should be aware that the automatic configuration is not working anymore the Cedar Stack! You need to configure it in your app:

  # config/environments/production.rb
  config.action_mailer.raise_delivery_errors = true
  config.action_mailer.smtp_settings = {
    :address        => "smtp.sendgrid.net",
    :port           => "25",
    :authentication => :plain,
    :user_name      => ENV['SENDGRID_USERNAME'],
    :password       => ENV['SENDGRID_PASSWORD'],
    :domain         => ENV['SENDGRID_DOMAIN']
  }

Switching domains

Before you do the last step, you should have a look if everything is up and running:

heroku open

If everything is fine, you can move all the domains from the legacy application to your new and shiny Cedar Stack application:

# list domains in legacy app
heroku domains
 
# and remove them
heroku domains:remove hamburg.onruby.de
heroku domains:remove onruby.de
[...]
 
# re-add them to Cedar application
heroku domains:add hamburg.onruby.de
heroku domains:add onruby.de
[...]

Looking at the result is quite disappointing, because nothing has changed for the user, but everything is new and shiny from the inside!

If you have any other pointers of what you need to do for migrating your application please feel free to add a comment!

I am very interested in doing mobile development as a hobby. I started iOS development about a year ago but i stopped after publishing my first iPhone app dzone mobile because i thought that all those AppStore™ and iTunes Connect™ stuff was a pain in the ass and distracting me from beeing productive.

So I began developing this same app for the Android platform, in order to get a feeling for it. I’ve been doing Java for about 7 years now, so developing on Android should be rather familiar to me instead of learning all this verbose Objective-C nerdy pointer stuff. I am very well known to Eclipse, so working with the Android Plugin should be easy, right?

I started the app in November of 2010, when I had some spare time between jobs, but somehow I stopped in the middle of the project and just recently started all over. I was wandering why I had not worked on the app for about half a year?

The answer is simple: Developing ANDROID sucks!

Eclipse

I stopped working with Java in the middle of last year, switching to Ruby development with TextMate and MacVim. Coming back to Eclipse is like getting hit by a truck! This IDE is so overwhelming, but instead of giving you what you need it hides the most common features, so that you have to search for it on stackoverflow.

Is it really necessary for me to do Open-Clean-Refresh-Close-Open-Refresh cycles on my project to let Eclipse realize that everything is fine besides Eclipse itself?

Why do people, building Eclipse plugins, make the same errors again and again? Swallow errors, so that you need to have the Error Log View open all the time? Show build failures without any hints? Are you serious about that LogCat stuff? WTF?

I am using the debugger all the time when I am new to some Framework in order to better understand what is going on. But this is not very usefull unless you can see the source code of where you currently are… Guess what, it’s reeeeally hard to get it going!

Emulator

The android Emulator is really slow on the Mac. I don’t know if it’s much faster on other systems, but i think it sucks. The startup time takes even more than eclipse, you need to fiddle around with runtime settings in order to adjust it to your needs and why is it so difficult to put all the options you have in the menu bar instead of hiding it somewhere in the function keys?

But the best thing is, that the emulator is just not working right in the beginning.

It does not properly respond to mouse gestures or the keyboard and ah yeah, I forgott, it’s ugly:

Desing-Flaws

Developing for iOS is a tough choice if one is coming from a language like Java that has a decent Runtime with garbage collection. I spent most of my development time with allocation/deallocation problems. This is something you really need to get into if you want to have fun working with Objective-C even though they just released ARC (automatic reference counting) on iOS 5.
Besides that, I really think that iOS does a better job in designing an architecture that is developer friendly.

The thing that I just can’t get over on Android devices is that the application (the activity to be precise) is going to be reloaded if you rotate your device and you need to take care of a lot of things in order to let your app respond to that interaction. Just have a look at your future self …

It’s really sad to me, that the Android designers decided to repeat the bad design decisions that had been established in Java Enterprise™ all over again! It took the Java community about a decade to step back and come to frameworks where developer productivity is THE thing to focus on. All the rookies that start their “Java career” with android will be doomed to go through this same process again! Poor bastards…

XML

Finally! Let’s define everything in XML! I am getting bored at bashing on XML…

dzone_android±master✓$ find . -name "*.xml"
./AndroidManifest.xml
./res/layout/details.xml
./res/menu/options.xml
./res/values/strings.xml
./res/xml/preferences.xml

iOS is also using XML for their interfaces, but they hide all that shit behind a really decent InterfaceBuilder!

The Builder and XML Tools in the Eclipse Plugin are so ugly that i rather write the whole shit by hand, bitches!

Tight coupling

Why, for gods sake, did they come up with the idea to use inheritance for everything in Android? It’s even worse than in J2EE because you are not bound to Interfaces but Classes! Hello dear Android designers, there is no such thing as Mixins or Multi-Inheritance in Java?! How am I supposed to write clean code with that? Answer: You are not going to write clean code anyway, because you have to do premature optimization on your code so that it can run on all the shitty Android devices! YEAH!

Just forget everything you learned form state of the art frameworks like MVC or DI. It’s just not possible! BY DESIGN!

Just put state, lifecycle, business and view logic in one class; also helps reducing your package size, hooray!

Checked Exceptions

Do we really need more Checked Exceptions? Really?

Testing

Writing tests for iOS was nearly impossible at the time I was doing it. Even the guys at the Cocoaheads Hamburg did not know how to get it running. But this situation has improved over the last months. Special thanks to XING for doing a lot of research there and presenting it on the Usergroup!

I thought that testing for Android would be really cool, because the Java community has a really strong background on TDD and Testing is even a Topic on the Dev Guide, even though it is the LAST one…

Let me make it clear to you: Testing Android sucks!

Because of all the tight coupling and multithreaded environment it is nearly impossible to test something. Even simple tasks like testing your Utility-Methods needs to be done in the Emulator! Just have a look at this multiscreen setup guide of how to get it running with JUnit (Hello?! JUnit 3 is deprecated for YEARS!).

Despite all this crap, I finally did it! So please test my dzone application, because I do not own an Android phone myself…

Nevertheless, I am proud to announce, that, thx to Rehanift’s fork, ASIN now support AWS cart operations:

  #just require
  require 'asin'
 
  # create an ASIN client
  client = ASIN.client
 
  # create a cart with an item
  cart = client.create_cart({:asin => '1430218150', :quantity => 1})
  cart.items
  => [<#Hashie::Mash ASIN="1430218150" CartItemId="U3G241HVLLB8N6" ... >]
 
  # get an already existing cart from a CartId and HMAC
  cart = client.get_cart('176-9182855-2326919', 'KgeVCA0YJTbuN/7Ibakrk/KnHWA=')
  cart.empty?
  => false
 
  # clear everything from the cart
  cart = client.clear_cart(cart)
  cart.empty?
  => true
 
  # add items to the cart
  cart = client.add_items(cart, {:asin => '1430216263', :quantity => 2})
  cart.empty?
  => false
 
  # update items in the cart
  cart = client.update_items(cart, {:cart_item_id => cart.items.first.CartItemId, :action => :SaveForLater}, {:cart_item_id => cart.items.first.CartItemId, :quantity => 7})
  cart.saved_items
  => [<#Hashie::Mash ASIN="1430218150" CartItemId="U3G241HVLLB8N6" ... >]

You can use the latest source from GitHub development branch or download the beta version of the gem from RubyGems. No easter eggs included

Happy shopping(cart)!

Enabling Rubygems

Since Ruby 1.9 Rubygems is bundled with every Ruby distribution. If you are using RVM you get Rubygems with the older versions too. Setting the RUBYOPT environment variable will enforce it even for 1.8 versions:

# no need for 'require "rubygems"' in your code
export RUBYOPT=rubygems

The Gem command

Since the merge of Gemcutter and Rubygems there have been a lot of improvements to the gem shell command. Sharing your code is now as easy as:

# create a gem from your local source configured in your gemspec
gem build your.gemspec
# upload the created gem 
gem push your-0.0.1.gem

There are some more new commands that handle the Rubygems API communication, which are very well documented on RubyGems.org.
It is also worth taking some time to get an overview of the old command reference. Commands like which or cleanup come in handy if you know them!

I use RVM and Gemsets extensively and I do not want to have all that duplicated RDoc and RI on disc (I’d rather search the web instead of using local generated doc), so I changed my .gemrc file to skip generating the doc on gem install:

# .gemrc
--- 
:update_sources: true
:sources: 
- http://gems.rubyforge.org/
- http://gems.github.com
gem: --no-ri --no-rdoc
:verbose: true
:bulk_threshold: 1000
:backtrace: false
:benchmark: false

Building a Gem

Jeweler is a great tool for scaffolding and releasing new Gems. If you don’t care about getting to know the basics, just move right over to their documentation. The problem is, that it makes things more complicated than they really are…

Naming and Versioning

There are some simple rules when it comes to naming:

1. Use lowercase letters only! Users of case insensitive file systems will be thankfull.
2. Use ASCII characters only! You know, those US guys just don’t know there is UTF-8.
3. Use _ underscores for parts of the name and – dashes for extensions of existing Gems.
4. Name your Gem like the file to require in your code. If not, put a big, fat warning in your documentation!

Choose the Gem name with care, because you know: naming is everything!

It became popular lately to start the development cycle with a version 0.0.1 instead of 1.0.0. I think this is just a matter of taste. More importantly you should handle your MAJOR.MINOR.FIX versions carefully. Increment your FIX version on bugfixes or additions to the API that won’t brake any existing code. Increment your MINOR version if you added features with an noticable impact to the API or it’s usage. Push a new MAJOR version if you changed your API completely or if you want to emphasize that the latest version is a major improvement or a new stable release. In an ideal world all those decisions and changes are documented in a CHANGELOG file.

In addition to these rules, Rubygems provides a mechanism to roll out beta versions of a Gem. In order to do this, just append a .beta etc. to the end of your version. These Gems can then be installed with the –pre flag:

gem install rails --pre # might install rails 3.1.0.beta some day

The Gemspec

One thing that is essential for creating a Gem is the .gemspec file. Put one in the root of your project folder and name it alike. The .gemspec file contains plain old Ruby and simply specifies all important attributes for your Gem. For an example, have a look at the gem_best_practice.gemspec:

# coding: utf-8
lib = File.expand_path('../lib/', __FILE__)
$:.unshift lib unless $:.include?(lib)
 
require 'gem_best_practice'
 
spec = Gem::Specification.new do |s|
  s.name = s.rubyforge_project = 'gem_best_practice'
  s.version = GemBestPractice::VERSION
 
  s.author = 'Peter Schröder'
  s.description = 'A Gem that shows best practice for Gem creation.'
  s.email = 'phoetmail@googlemail.com'
  s.homepage = 'http://github.com/phoet/gem_best_practice'
  s.summary = 'If you ever wondered how to create a Gem and what best practice should be applied, this project is for you.'
 
  s.has_rdoc = true
  s.rdoc_options = ['-a', '--inline-source', '--charset=UTF-8']
 
  s.files = Dir.glob('lib/**/*.rb') + Dir.glob('bin/*') + %w(README.rdoc)
  s.test_files = Dir.glob('test/**/*.rb')
 
  s.executables = %w(gbp)
  s.default_executable = 'gbp'
 
  s.add_dependency("erubis", "~> 2.6.0")
end

After the .gemspec file is done, the Gem may be built via the gem command:

gem build your.gemspec

Or with a custom Rake task:

spec = eval(File.new("your.gemspec").readlines.join("\n"))
Rake::GemPackageTask.new(spec) do |pkg|
  pkg.need_zip = true
  pkg.need_tar = true
end

Folder Structure

Ruby is an open language with very little restrictions. You can place your code anywhere, but there are some guidelines of how code should be structured so that nobody has to mess with the $LOAD_PATH in order to use it. This is an example of standard Gem folders:

gem_best_practice/
├── bin
├── example
├── lib
└── test

Your actual Ruby code should go under lib and subfolders. It’s a best practice to put just one file there and the other stuff right into another subfolder in order do avoid name clashes or the like. Extensions to the standard Ruby libraries should be separated out, so that they are easier to spot:

├── lib
│   ├── gem_best_practice
│   │   ├── core_ext
│   │   │   └── kernel.rb
│   │   ├── core_ext.rb
│   │   └── gbp.rb
│   └── gem_best_practice.rb

All the tests should go into the test folder ( spec / feature folder respectively). Make sure the Gem is well tested, otherwise chances are nobody will use the it nor contribute to the codebase. As an awesome Ruby developer, one would add some (working) examples in the example folder to demonstrate the API of your Gem in action. Additional executables for your Gem should be put into bin and don’t forget to add a proper shebang:

#!/usr/bin/env ruby

Dependencies

There are a lot of great libraries available for Ruby nowadays and one would be a fool not to use them. That’s why most of the Gems depend on other libraries. Different Gems may share common dependencies, so it’s elementary for a good Gem to be as loose about the own dependencies as possible to reduce versioning conflicts. Tools like Bundler do a great job on resolving those conflicts and they depend on the versions that are wired in the .gemspec file of a Gem. You can easily tell Bundler to use your .gemspec the main configuration source for your gems. A tradeoff between hard wiring Gem versions and providing no version restrictions at all, is to use the ~> range operator, that will allow newer dependency versions within the same MINOR version:

  s.add_dependency("erubis", "~> 2.6.0") # >= 2.6.0 and < 2.7.0

There is still one problem left. It’s currently not possible to define optional dependencies in your .gemspec file. This is a big problem for libraries that implement some kind of adapter pattern (Have a look at HTTPI which provides an interface to different HTTP libraries) and don’t want to force the user to install all underlying implementations (This is also a problem for bundler).

Until this problem is fixed in Rubygems, a simple approach to this problem is to programmatically rescue from LoadErrors:

# require optional dependency
begin
  require 'ap'
rescue LoadError
  puts "awesome_print would be awesome, please 'gem install awesome_print'"
end

Documentation and Examples

An awesome Gem deserves a decent documentation. If you are too lazy to document your code, you should at least bundle a README file with your source. GitHub does a great job at pushing a project to provide a README (rdoc/textile/markdown/…), because this file will be prominently rendered on the projects start page. The README should at least include installation instructions and basic usage examples.

Using YARD / RDoc in the source code is another great way to help others understand the code, provide bugfixes or extend existing functionality. Even for yourself, having a good inline documentiont will save time when returning to a piece of code you did not had your hands on for month.

Generating the documentation can easily be done with Rake:

Rake::RDocTask.new(:rdoc_dev) do |rd|
  rd.rdoc_files.include("lib/**/*.rb", "README.rdoc")
  rd.options + ['-a', '--inline-source', '--charset=UTF-8']
end

If the project is hosted on GitHub, rdoc.info may generate the documentation automatically from the source-repository. GitHub also provides a service-hook so that the documentation is updated on every push! A .document file in the project will give rdoc.info the right pointers which files to include in your docs:

lib/*.rb
README.rdoc

Depending on the project, it might be a good idea to include some usage examples with the code. This might be the case if one can not put all the necessary information in the inline comments or the README file. Bye the way, (especially behavior driven) tests serve very well as executable examples.

Another thing that is overlooked quite often is the documentation of Ruby runtime compatibility. Does the Gem work with MRI 1.8 / 1.9 / JRuby / REE / … ? Since RVM is a defacto standard in the Ruby environment, there is no good reason not to test at least Ruby 1.8.7 and 1.9.2.

And then?

After finishing the work on the first version of a Gem and pushing it to Rubygems, what comes next?

If you are just interested in the acceptence of the Gem you can have a look at the Rubygems user profile or individual Gem stats.

A good way to help the Gem gain acceptance is to make it OpenSource via GitHub or RubyForge.

It’s not easy to reach a wide range of users, but if you want to promote your Gem over the interwebs there are a lot of services like DZone or Forrst that allow you to post something about the Gem or to link to articles on your blog or Twitter posts. Another great resource for Ruby developers to discover new Gems is The Ruby Toolbox.

The Gem Best Practice Gem

I am currently putting all those Guidelines above into a Gem Best Practice Gem Project on GitHub which is inspired by bundler’s bundle gem command.

More best practice, less fail!

About a week ago rubiii has released the first beta of Savon 0.8. A lot of bugfixes, improvement and API changes have been addressed in the latest version. If you want to get used to the new API a good starting point is the Savon Guide.

One thing that should be noted right away, is that Savon 0.8 is not downwards compatible. Most code parts have been rewritten and Savon now offers an improved error handling, support for local wsdl documents and more flexibility on request methods. See the changelog for more information.

Shootout update

I have updated the examples used for the shootout to reflect the latest changes for Savon 0.8.beta3, Handsoap 1.1.7 and SOAP4R. I restructured the examples, removed dead services and added Bundler for gem dependencies. The examples run on MRI 1.8.7 and JRuby 1.5.2.

More Savon infrastructure

Some effort has been taken to make the day to day work with Savon even more pleasant. If you are working with RSpec, you can now test using Savon Spec.

If you are used to work with ActiveRecord models Savon Model will help integrating SOAP into your Rails projects.

SOAP without fail!

If your app is hosted on Heroku you wonder weather wkhtmltopdf is available so that you can use one of these awesome libraries. Searching the Heroku docs, you will probably come to same conclusion: nothing on there!

You’re correct that there’s no official documentation. Most of our customers seem to be using wkhtmltopdf, generally with pdfkit. I do hope to document this usage soon.

http://github.com/jdpace/PDFKit
http://code.google.com/p/wkhtmltopdf/

If you want us to offer a Prince add-on, I encourage you to write them inviting them to check out our Add-on Provider Programme: http://addons.heroku.com/provider

Of course, you can always purchase your own license and run it on EC2 or another server of your choosing.

PrinceXML

One of the libraries that were used at my last job was PrinceXML, which did a great jog generating PDFs from HTML pages. It supports most of the HTML and CSS stuff, passing the ACID2 test. PrinceXML has some additional CSS attributes that enable you to configure additional PDF specific layout settings.

DocRaptor

Since PrinceXML is a commercial product, Heroku won’t support it and I did not find anything on the web, that would offer PDF generation as a service. Asking the PrinceXML Forum I found out about DocRaptor. These guys provide a service to convert HTML to XLS or PDF over a webservice interface, extactly what I was looking for. As an additional bonus, they just implemented a gem for supporting the Heroku Add-on interface. Mail to Expected Behavior Support if you want to participate in the private beta.

Improvements

DocRaptor offers a great service, but they are still in early development. There were some Issues that were resolved recently. If you are a user of PrinceXML you probably know the –baseurl option that allows usage of relative paths for images and stylesheets. DocRaptor adds support for command line options just yet. The feature for generating a PDF from a given URL is even better!

Using DocRaptor from Rails

The latest DocRaptor documentation for the Heroku Add-on is decent and it provides some nice examples.

PDF from raw HTML

Here is what I did to get it running on my Rails 3 project:

# Gemfile
gem "doc_raptor", "0.1.1"
 
# mime_types.rb
Mime::Type.register_alias "application/pdf", :pdf
 
# your_controller.rb
def your_pdf_action
  respond_to do |format|
    format.pdf do
      data = DocRaptor.create(:name => 'DocRaptor.pdf', :document_content => render_to_string, :document_type => "pdf", :prince_options => {:baseurl => 'http://nofail.de'})
      send_data data, :type => 'application/pdf', :filename => 'DocRaptor.pdf'
    end
  end
end

If you registered the pdf mime-type you will have to provide an additional layout for this. I added some PrinceXML specific parameters to the styles to make it a fullscreen PDF. One thing that is essential for making the stylesheets work is the media => ‘screen, print’ settings:

// application.pdf.haml
= stylesheet_link_tag 'style', :media => 'screen, print'
// you can provide a base tag for images and stylesheets
// %base{:url=>'http://blog.nofail.de'}
 
%style
  @page { size: A4 }
  @page { margin: 0px }
  @page { border: none }
  @page { padding: 0px }
  @page { prince-shrink-to-fit: auto }

PDFs from an URL

The simplest solution for generating a PDF is to send an url to the service, so you can re-use all your view logic:

data = DocRaptor.create(:name => "DocRaptor.pdf", :document_url => "http://blog.nofail.de", :document_type => "pdf")
send_data data, :type => 'application/pdf', :filename => "DocRaptor.pdf"

One caveat though, you got to have at least two dynos to serve the additional request from DocRaptor!

See a working example on my homepage.

Generating PDF form HTML without the hassle, thanks to DocRaptor!

Homebrew

Homebrew is a Ruby based packaging tool for Mac and once you start using it, you immediately hate yourself for having wasted time on MacPorts…

“Homebrew is the easiest and most flexible way to install the UNIX tools Apple didn’t include with OS X.”

This quote is from the official website and I guess they are absolutely right!

Formula

Homebrew is build around formulas. They describe how a package should be loaded from the web and installed on your system. It also cares about package dependencies, paths and all the other ugly stuff:

require 'formula'
 
class Wget < Formula
  homepage 'http://www.gnu.org/wget/'
  url 'http://ftp.gnu.org/wget-1.12.tar.gz'
  md5 '308a5476fc096a8a525d07279a6f6aa3'
 
  def install
    system "./configure --prefix=#{prefix}"
    system 'make install'
  end
end

You can easily install packages from the shell with brew:

brew install wget

Homebrew puts all the packages into ‘/usr/local’, so that it won’t interfer with other components of your system. To get your packages working, you need to include it into your $PATH. If you have any problems running something, Homebrew comes with the doctor command, that scans for problems in your setup!

Installation

Just download Homebrew to your system and update once a while:

# install homebrew via curl
sudo mkdir -p /usr/local && sudo chown -R $USER /usr/local && curl -Lsf http://bit.ly/9H4NXH | tar xvz -C/usr/local --strip 1
 
# update homebrew
brew update

Git, MySQL, Sphinx and more

What else do you need? Just search for it or get more infos with info!

These are the packages that I needed for development:

# install mysql and set it up
brew install mysql
mysql_install_db
# add mysqld as launch agent
cp /usr/local/Cellar/mysql/#{MYSQL_VERSION}/com.mysql.mysqld.plist ~/Library/LaunchAgents
launchctl load -w ~/Library/LaunchAgents/com.mysql.mysqld.plist
 
# install git
brew install git git-flow
 
# add git bash completion (find path to your git with 'brew info git')
ln -s /usr/local/Cellar/git/#{GIT_VERSION}/etc/bash_completion.d/git-completion.bash ~/.git-completion.bash
source .git-completion.bash
 
# install sphinx search-deamon
brew install sphinx
 
# aspell with all spellings
brew install aspell --all
 
# libxml and imagemagick for sprites
brew install libxml2 imagemagick

RVM the Ruby Version Manager

RVM is a command line tool for managing your local Ruby environments, you can get some more information on the RVM homepage and in earlier articles.

Quick start with installing RVM to your machine:

# install rvm via curl !!! FOLLOW RVM INSTRUCTIONS !!!
bash < <( curl http://rvm.beginrescueend.com/releases/rvm-install-head )
 
# download and compile latest 1.8.7
rvm install 1.8.7
 
# create a .rvmrc file in your app's base directory
echo "rvm use 1.8.7@#{YOUR_APP} --create" > #{YOUR_APP}/.rvmrc
# execute it by cd-ing to your app's directory
cd #{YOUR_APP}

Now you can work on your app with a custom gem environment. Unless you are using Bundler, this is probably what you want for installing and removing gems painlessly.

Cucumber with Celerity

Behavior driven development with Cucumber works nicely with Celerity, a JRuby implementation of a headless browser using HtmlUnit and it’s companion a Ruby wrapper called Culerity. Culerity has recently been updated with some configuration points for registering your local JRuby environment:

# jruby config für culerity (from http://rvm.beginrescueend.com/integration/culerity/)
rvm install jruby
rvm use jruby@celerity --create
gem install celerity
rvm wrapper jruby@celerity celerity jruby
# add to .profile
export JRUBY_INVOCATION="$(readlink "$(which celerity_jruby)")"

If you are experiencing any weird Broken Pipe errors (like me), have a look at this issue.

This is just an example of how you can setup your Rails development environment. Comments on this topic are appreciated!

The biggest problem with getting started was that I had no idea what application I could write for that device that could become somewhat usable. As I am a passionate tech reader, I consume a lot of articles posted on DZone. Usually I use a feed reader like NetNewsWire for that, which works very well for my MacBook but is nearly useless on the iPhone, because the DZone site is not very mobile friendly…

Problems

Since there was no DZone iPhone application on the marked I started working on it. Parsing DZone feeds was easy, even though the buildin XML support on iOS sucks. There were some nice libraries that made my life easier.

No deeplink

The DZone RSS feed does not provide a deeplink to the actual linked article, so one would still land on the DZone page… Since DZone does not provide an API currently, I started working on my own Rails application hosted on Heroku. Spidering the RSS, calling the page and extracting the link to the article is fragile, but it works (currently).

No voting

One of my goals was to let the iPhone user vote for the article while reading it. The lack of an API forced me to do some more fragile login and posting stuff to the DZone page, but it works too (currently)!

You can read more about the API I created on the actual page.

iPhone app

The first version of the “dzone mobile” app has passed the iTunes store review process and is available through the app store. A version with some minor bugfixes is currently beeing reviewed. Have a look at updates and documentation here or here.

voting

You have got to provide your DZone login credentials if you want to use the voting feature. Go to the iPhone Settings > DZone and add your username and password. I want you to know that there is NO SSL, so your credentials will be submitted UNSECURE!

more Features

If you are interested in pushing this further, you can add bug reports or feature requests on GitHub.

DZone iPhone sugar!

Redis is “an advanced key-value store” and has some features that make it a perfect match for a cache! I use caching extensively on my site and keep on trying out new ways to do it to circumvent Heroku’s readonly filesystem.

Like Memcache, Redis provides the ability to set a time to live (ttl) on a key. This comes in handy, if you have data that expires in a short period of time, like 3rd party data from Twitter etc.

Caching with Redis

Accessing Redis is very simple, since it is a text based protocol. The command reference is straight forward and there is a simple Ruby wrapper available:

require "redis"
redis = Redis.new
redis.set "foo", "bar"
# => "OK"
redis.get "foo"
# => "bar"

The redis-store gem already provides a Rails 3 compatible Cache Store implementation, but I needed some more configuration points, especially the ttl.

That’s why I wrote my own Rails 3 Redis Cache, also a great way to get used to the way of working with Redis and the Redistogo addon.

Using Rails Redis Cache

There is some configuration needed for Rails to pick up the new cache store. If you want to use different or no caching for test, development and production, you should put the config in your environment files:

# config/environemnts/production.rb
config.action_controller.perform_caching = true
config.cache_store = ActiveSupport::Cache::RailsRedisCache.new(:url => ENV['REDISTOGO_URL'])

If there is a Redis server available in all environments, you can put it in your environment file:

# config/environment.rb
ActionController::Base.cache_store = ActiveSupport::Cache::RailsRedisCache.new(:url => ENV['REDISTOGO_URL'])

The caching parts are mostly in my controllers:

@tweets = cache("tweets", :expires_in => 30.seconds){ Twitter::Search.new(...) }

The store is using the basic Rails cache store implementation which is broken in the Rails 3.0.0.beta1 version that runs on Heroku, so I added a monkey-patch for that using edge Rails.

Redis on localhost

Installing and running Redis on Mac OS X is really simple:

brew install redis
redis-server

There is also a commandline client available for direct access:

redis-cli
redis> set "foo" "bar"
OK
redis> get "foo"
"bar"

It’s key value stores, stupid!

One thing that I discovered recently is the support of blocks, that has been introduced with OSX 10.6 and iOS 4.0.

the environment matters

Consuming 3rd party data from the web is kind of a pain, especially compared to how easy it is in Ruby. So I was pleased to find Seriously, a framework for async calls and JSON/XML parsing. The Seriously examples made use of blocks:

NSString *url = @"http://api.twitter.com/1/users/show.json?screen_name=probablycorey";
 
[Seriously get:url handler:^(id body, NSHTTPURLResponse *response, NSError *error) {
    if (error) {
        NSLog(@"Error: %@", error);
    }
    else {
        NSLog(@"Look, JSON is parsed into a dictionary!");
        NSLog(@"%@", [body objectForKey:@"profile_background_image_url"]);
    }
}];

Executing this example in my app code raised an error, that I could not easily understand:

"__NSConcreteGlobalBlock", referenced from: ___block_holder_tmp_1.1207 in DZoneController.o
ld: symbol(s) not found
collect2: ld returned 1 exit status

The problem was, that XCode set my execution environment to OSX 10.5 which does not have support for blocks. To fix this, one has to update the MACOSX_DEPLOYMENT_TARGET build variable.

Right Clicking on the XCode project in the “Groups & Files” view will bring up a context menu with “Get Info” (or pressing CMD+I while project is selected). The info pane has a “General” tab that lets you select the “Base SDK for All Configurations”, which I set that to iOS 4.0.
An other option is to search for “MACOSX_DEPLOYMENT_TARGET” in the “Build” tab and changing that value accordingly. Make sure “Show” is set to “All Settings”.

At least some Objective-C sugar!

On Whyday, I created a live demo of the examples, that is running on Heroku.

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

I am constantly looking around for different storage mechanisms on Heroku that can be used for caching 3rd party data. A recent update of their platform offered an MongoDB addon to access the MongoHQ service that drew my attention, so I started to evaluate this noSQL document database…

MongoDB on OS X

It’s always a good starting point to have a local installation of a technology, here is how you get it running on your Mac with Homebrew:

brew install mongodb
# create a place for MongoDB to store the data
mkdir -p /data/db
# run server with default config (adapt to the right version)
mongod run --config /usr/local/Cellar/mongodb/1.4.4-x86_64/mongod.conf

Using MongoHQ requires a user-authentication, so it’s nice to have the same credentials on your local MongoDB instance:

# start the client
mongo
> use test
> db.addUser("test", "test")

evaluating different APIs

A very basic approach, that basically wraps the MongoDB API into Ruby code is the Mongo Ruby Driver, but there are two higher level APIs close to ActiveRecord called Mongoid and MongoMapper.

Mongo Ruby Driver

It’s pretty easy to connect to your MongoDB with the right connection string:

conn = Mongo::Connection.from_uri("mongodb://user:pass@host:port/db")
db = conn.db("db")

The Mongo Ruby Driver is very simple and close to the MongoDB API:

coll = db.collection('test')
coll.insert('a' => 1)
coll.find().each { |row| p row }

MongoMapper

MongoMapper can also be accessed with a connection string:

Mongo::Connection.from_uri(MONGO_URL)

Instead of using ActiveRecord::Base MongoMapper provides the MongoMapper::Document module to handle the object document mapping. Since the structure of a document in MongoDB is open and not static like in a SQL database, you have to define the structure in code, so MongoMapper knows how to map the document to your Ruby objects:

class Person
  include MongoMapper::Document
 
  key :name, String
  key :age, Integer
  key :born_at, Time
  key :active, Boolean
  key :fav_colors, Array
 
  connection Mongo::Connection.from_uri(MONGO_URL)
  set_database_name 'basement'
end
 
person = Person.create({
  :name => 'Nunemaker',
  :age => 27,
  :born_at => Time.mktime(1981, 11, 25, 2, 30),
  :active => true,
  :fav_colors => %w(red green blue)
})
 
person.save
 
Person.all.each do |p|
  ...
end

Mongoid

Configuring Mongoid is somewhat different but easy:

Mongoid.database = Mongo::Connection.new(host, port).db(db)
Mongoid.database.authenticate(user, pass)

The DSL for defining Mongoid Documents is similar to MongoMapper and works mostly the same way. Querying the database is also similar to the API provided by ActiveRecord:

class Tweeter 
  include Mongoid::Document 
  field :user 
  embeds_many :tweets 
end 
 
class Tweet 
  include Mongoid::Document 
  field :status, :type => String 
 
  embedded_in :tweeter, :inverse_of => :tweets 
end
 
tweet = Tweet.new(:status => "This is a tweet!") 
tweet.tweeter = Tweeter.new(:user => 'ted') 
tweet.save
 
Tweeter.all.each do |tweeter| 
  ...
end

You can get the complete code and some more links from the GitHub project created for testing.

MongoDB is a great way to store document focused data and it’s simple to use with these great libraries!

I always felt that using ruby-aaws was way too complicated! This is how you call Amazon for the title of a book:

require "amazon"
require "amazon/aws"
require "amazon/aws/search"
il = Amazon::AWS::ItemLookup.new('ASIN', { 'ItemId'=>asin })
rg = Amazon::AWS::ResponseGroup.new('Medium')
req = Amazon::AWS::Search::Request.new
resp = req.search(il, rg)
puts resp.item_lookup_response.items[0].item.item_attributes.title.to_s

I also had to monkeypatch some stuff to get it working with Heroku the first time:

• allow .amazonrc to be on a different location that can be used on Heroku
• remove restriction to Ruby 1.8.7 and patch related Stuff

If you look into the source and documentation of ruby-aaws you will see that it is no fun to patch anything in there… I think I would not have done it without the help of Ian Macdonald.

Another thing was, that I could not use the builtin caching facility of ruby-aaws, cause it simply does not work on Heroku’s readonly file-system.

simplicity with ASIN

Given these restrictions, I decided to build a minimum featureset gem tailored for my requirements:

• provide access to the Amazon-E-Commerce-API via REST
• simple configuration points
• minimum amount of code to write for a request
• maximum flexibility

If you have a look into the Amazon documentation you see that it is quite easy to call the API via REST. Just append some query parameters to your desired endpoint (f.e. webservices.amazon.com) and as a result you get the desired information from Amazon. The tricky thing is, that since recently you have to sign your request with your AWS credentials. I did not find any specs on how to do that on the documentation, but Cloud Carpenters had a nice example using Python that I adapted for Ruby.
There is also the nice Amazon API signing service that frees you from self signing your requests. The reason I did not use it, is that it supports the amazon.com endpoint only (I need amazon.de).

requests with ASIN

Using ASIN is simple. You just have to provide your credentials to the configuration method, the rest is covered with sensible defaults that you can override if you wish:

require 'asin'
include ASIN
 
# use the configure method to setup your api credentials
configure :secret => 'your-secret', :key => 'your-key'
 
# you can override the api endpoint if you wish
configure :secret => 'your-secret', :key => 'your-key', :host => 'webservices.amazon.de'

After this setup you can call the REST api via the lookup method:

# lookup an item with the amazon standard identification number (asin)
item = lookup '1430218150'
 
# have a look at the title of the item
item.title
=> Learn Objective-C on the Mac (Learn Series)
 
# provide additional configuration options like the response group
lookup(asin, :ResponseGroup => :Medium)

Title is currently the only attribute that is directly supported from the Item class, but this is no restriction. ASIN uses Hashie::Mash for the internal data representation of the Amazon REST XML response. The Item class stores the response in a raw attribute that can be accessed for read:

# access the internal data representation (Hashie::Mash)
item.raw.ItemAttributes.ListPrice.FormattedPrice
=> $39.99

You can tailor the Item class to your needs by opening up the class and provide the methods you like or doing something entirely different with the raw attribute.

OR, just fork me on GitHub!

Maximum flexibility with some syntactic sugar!

current problems

Since switching between runtimes became as easy rvm use x more care has to be taken to support a wide range of interpreters and versions. This is especially true for shared code like gems.

Some engines like JRuby have limitations that prevent the usage of some Ruby features. In most cases it’s possible to work around these limitations and provide a different solution that works, but might be somewhat less performant.

checking runtimes

Ruby is great at introspection, but especially 1.8 misses some key information like RUBY_ENGINE to determine the current interpreter at runtime and one has to extract it from the RUBY_DESCRIPTION constant.

WhichRuby aims at simplifying this tedious task and providing a simple API:

# irb@jruby
jruby-1.4.0 > require 'which_ruby'
 => true 
jruby-1.4.0 > include WhichRuby
 => Object 
jruby-1.4.0 > jruby?
 => true

Executing different code fragments becomes as easy as defining a scope:

ruby_scope(:jruby) do
  # custom jruby code here
end

This comes in very handy for stuff like accessing Java code natively via JRuby instead of using RJB.

I don’t like Rubbae – I love it!

But does running an app on the JRE make it a JRuby application by default? Do you really want to be stuck on JRuby?

I really like the idea of running code with the most appropriate runtime available, that is why I use RVM all the time. JRuby is still very slow on startup and tools like autotest/autospec take minutes for just a handfull of tests…

So I would like to host Rails applications on a Tomcat, but on the other hand I want the tests to be executed with MRI! This should not be a problem as long as you don’t want to share a common codebase within Ruby and Java.

Integration

Is there a best practice for combining Java and Ruby?

Since every project is different, I think that you’ve got to evaluate the possible solutions to pick the one that fits best.

The next sections cover some approaches on integration of Java and Ruby code. Make sure to have RVM installed if you want to execute the provided example code. I assume that a JRE is provided with every OS nowadays…

Java in Ruby

There are two common solutions for embeding Java into a Ruby application. The first and obvious one is via JRuby, which can only be run with the JRuby runtime:

require 'java'
 
puts "access java.util.UUID via JRuby"
puts java.util.UUID.randomUUID().toString()

rvm use jruby 
=> Using jruby 1.5.0.RC1
 
jruby lib/jruby.rb 
=> access java.util.UUID via JRuby
=> a16fda6a-c57d-43b9-8376-801e48fe56b3

The same thing is possible using the Ruby Java Bridge from MRI:

require 'rjb'
 
puts "access java.util.UUID via RJB"
puts Rjb::import('java.util.UUID').randomUUID().toString()

rvm use 1.8.7
=> Using ruby 1.8.7 p249
 
ruby lib/rjb.rb 
=> access java.util.UUID via RJB
=> 1db8298c-5486-4933-be00-cdb180388e38

But it is also possible to do it the other way around!

Ruby in Java

Evaluating Ruby code in Java is dead simple with help of the JRuby library. You just need to set up a scripting container that executes your scripts:

  @Test
  public void execute_jruby_scriptlet() {
    new ScriptingContainer().runScriptlet("puts 'hello jruby world'");
  }

A more advanced example is to wire a Ruby class as a Spring bean. You need to provide some configuration and a Java interface that can be used as the basis for the bean:

<!-- applicationContext.xml -->
<lang:jruby id="identifier" script-interfaces="de.nofail.Identifier" script-source="classpath:/ruby/identifier.rb">
    <lang:property name="uuid" value="#{ T(java.util.UUID).randomUUID().toString() }" />
</lang:jruby>

# identifier.rb
class Identifier
  def setUuid(uuid)
    @uuid = uuid
  end
  def getUuid()
    @uuid
  end
  def to_s()
    "Identifier[#{@uuid}]"
  end
end
 
# don't forget to return an instance as a bean
Identifier.new

// Identifier.java
public interface Identifier {
  String getUuid();
}

// SpringJRubyBeanTest.java
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "/applicationContext.xml")
public class SpringJRubyBeanTest {
 
  @Resource(name = "identifier")
  Identifier identifier;
 
  @Test
  public void generateUuid_success() {
    System.out.println("uuid: " + identifier);
  }
}

The code is currently not running with JRuby 1.5.0.RC1 so you need the latest stable release for testing.

checking Ruby enginges

It is even possible to mix and match all those approches! You just need to keep track of the Ruby engine that is evaluating your code. I created a little helper called which_ruby (available on rubygems) as a sidekick for this article, but more on that in the next week.

Some Ruby sugar in your cup of Java!

But even the simplest thing can be complicated if you use Java…

There are different logging frameworks like log4j, commons logging or logback even though Java includes it’s own java.util.logging API. To make it even worse, the Java community came up with a simple logging facade so one can use the logging framework of choice but implement against the facade – WTF?!

a standard that sucks

I would guess that 99% of Java code is written against log4j. Nobody really want’s to switch a logging framework during implementation and most developers I know see log4j as a technical standard.

I won’t recommend using log4j to anyone. The log4j documentation is crap! There is no usefull literature either (I never thought that one would have to buy a book for logging…). The framework misses essential things like pattern matching filters (you will have to use log4j companions) and it is difficult to configure, especially on a tomcat.

Log4j is a bitch when it comes to deployment. One has to be careful where to put the log4j jar(s) and xml or plain text configuration files. If you do it wrong you end up with broken logging behavior; webapps log to the wrong log file, spit out stuff to the system out or stop logging at all.

this is how we do it

Our Java infrastructure is service oriented. We have a bunch of webservices hosted on serveral distributed tomcats and all wars depend on log4j for logging. We want to reload the logging configuration files at runtime (why is jboss able to do it and tomcat is not?!) and manipulate it via JMX.

additional log4j configuration

To achieve this, we have to put some additional configuration into every webapp. Log4j comes with a watchdog that looks for changes in the configuration files. The functionality can be enabled by using the configureAndWatch() method. There is a precanned Spring solution for this, but it has configuration overhead and environmental restrictions. So the best place to implement it ourselves is in a custom context listener:

<!-- web.xml -->
   [...]
	<!-- listener for configuring the log4j watchdog -->
	<listener>
		<listener-class>de.nofail.TomcatLoggingListener</listener-class>
	</listener>
   [...]

   [...]
	public void contextInitialized(ServletContextEvent sce) {
		ServletContext servletContext = sce.getServletContext();
		try {
			String log4jFile = String.format("%s-log4j.xml", servletContext.getContextPath());
			String configFilename = new File(getClass().getResource(log4jFile).toURI()).getAbsolutePath();
			DOMConfigurator.configureAndWatch(configFilename, 1000);
		} catch (URISyntaxException e) {
			throw new IllegalStateException("Error resolving log4j configuration file for context=" + servletContext, e);
		}
	}
   [...]

This listener will use a config file named WEBAPP-log4j.xml lying in the root directory. The goal is, that every webapp has it’s own logging context. Every war should include a log4j.jar so that logging won’t be affected by other apps, the classloader hierarchie will ensure this. The different xml configuration files can than be placed in a shared tomcat directory for easy access of an operations team (which is probably yourself).

Using different configuration files has the advantage that you don’t have to mess around with appenders based on packages. That’s how one can configure different log levels for the same packages in each application, very usefull if you release a new application!

Java Management Extension

There are different ways to integrate JMX functionality into a webapp. The simplest approach is to use another servlet listener for propagating an mbean:

<!-- web.xml -->
   [...]
	<!-- listener for configuring JMX -->
	<listener>
		<listener-class>de.nofail.JMXListener</listener-class>
	</listener>
   [...]

   [...]
	public void contextInitialized(final ServletContextEvent sce) {
		try {
			TomcatLogging mbean = new TomcatLogging();
			ObjectName clutter = new ObjectName("de.nofail:type=TomcatLogging");
			ManagementFactory.getPlatformMBeanServer().registerMBean(mbean, clutter);
		} catch (Exception e) {
			throw new IllegalStateException("Could not create JMX context: " + e.getMessage(), e);
		}
	}
   [...]

If you are using Spring it’s easy to add JMX support via annotations.

Now you can access your running webapp via jconsole:

more information?

You can have a look at a working example based on Maven on github.

Drink a cup of Java™©®, but don’t forget the sugar!

installing Maven on OS X

The Maven documentation in general and the installation instructions in particular SUCK. They lack essential information as most Java documentation does. So here is a step by step guide for OS X:

# go to the place you want to install Maven to
cd ~/Library
# download latest Maven version
curl -O http://apache.autinity.de/maven/binaries/apache-maven-2.2.1-bin.zip
# unzip the archive
unzip apache-maven-2.2.1-bin.zip
# add a symlink for convenience
ln -s apache-maven-2.2.1 maven
# add executables to the PATH
echo export PATH="~/Library/maven/bin":\$PATH >> ~/.profile
 
# open a new bash and check Maven is running
mvn --version
=> Apache Maven 2.2.1 (r801777; 2009-08-06 21:16:01+0200)

creating the webapp

If Maven is running on the system, you can use the archetype to create a blank webapp:

# go to the workspace
cd ~/Documents/workspace/
# let Maven create a webapp
mvn archetype:generate \ 
   -DgroupId=de.nofail \
   -DartifactId=tomcat-logging \
   -Dversion=1.0.0-SNAPSHOT \
   -DarchetypeArtifactId=maven-archetype-webapp

This takes several minutes, as it requires a thousand some broken dependencies for whatever is necessary to create some files and folders! But after that, you have a fresh, apache conform webapp at hand:

# go to the webapp
cd tomcat-logging/
# let Maven create a distributable war
mvn clean package

This is very nice for a Java application! Zero configuration and you get a running webapp that you can start after another two thousand downloads instantly from the command line:

mvn jetty:run &
open http://localhost:8080/tomcat-logging/

all by myself

There is just one big problem with this so far: it won’t work bejond that! Maven lacks sensible defaults everywhere! Examples? Here you go:

Java compiler

Maven uses Java 1.4 as the default compliance level for the Java compiler. So if you start adding some Annotations or Generics to your code, which are Java 1.5 features, your build will fail until configuring the compiler plugin properly:

	[...]
	<build>
		<plugins>
			[...]
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>2.0.2</version>
				<configuration>
					<source>1.6</source>
					<target>1.6</target>
				</configuration>
			</plugin>
			[...]
		</plugins>
	</build>
	[...]

This should be a top level configuration!

Jetty plugin

Making changes to the code won’t change anything in the webapp run by the Jetty plugin. You need to configure the plugin in order to pick up changes. Since the plugin can not do any hot code replacement, it has to restart the context after every change. A no-go for most webapps:

	[...]
	<build>
		<plugins>
			[...]
			<plugin>
				<groupId>org.mortbay.jetty</groupId>
				<artifactId>maven-jetty-plugin</artifactId>
				<version>6.1.10</version>
				<configuration>
					<scanIntervalSeconds>10</scanIntervalSeconds>
				</configuration>
			</plugin>
			[...]
		</plugins>
	</build>
	[...]

Why is this soooo much XML?

Eclipse integration

Maven has support for integrating a project into Eclipse via the Maven-Eclipse-Plugin:

# configure your workspace (do not use ~ to point to your home!)
mvn eclipse:configure-workspace -Declipse.workspace=../
# create Eclipse files
mvn eclipse:eclipse

These tasks add a M2_REPO classpath variable to your Eclipse environment that points to your local Maven repository and creates a .project and .classpath file from the existing pom. Just import the project with Import > General > Existing Projects into Workspace and your done.

better with Eclipse plugins

Since there are mature Eclipse plugins for Maven and Jetty, you should consider installing these from their update sites:

• m2eclipse
• run jetty run

It’s never easy doing stuff from scratch, but Maven should help flatten the rocky path to Java projects. Instead it piles up another Mount Everest of complexity to climb for a Java developer…

additional information

Check out my github profile for a working example project that was created using these steps.

Maven – development for morons made easy!