Sometimes it’s helpful to do some performance benchmarks on your EJBs. There are a few different ways to do this, but I’ve found that Apache’s JMeter is an excellent tool for benchmarking. Unfortunately, JMeter doesn’t come with a general-purpose sampler for testing arbitrary EJBs. Luckily, it isn’t very difficult to create one.

For this article, I’m using the JBoss application server to host my EJBs. The process for using other containers should be quite similar.

1.) Create a factory to lookup your EJBs.

The first thing that you’ll probably want to do is create a simple singleton factory class to create instances of your EJB client for your test. I use something like the following:

public class MyServiceFactory {
  private static final Log log = LogFactory.getLog(MyServiceFactory.class);
  private static MyService service;
  private static MyServiceFactory me;
 
  private MyServiceFactory() { }
 
  static {
    MyServiceFactory.me = new MyServiceFactory();
  }
 
  public static MyServiceFactory getInstance() {
    return MyServiceFactory.me;
  }
 
  public MyService getService() {
    if (MyService.service == null) {
      // Get the remote interface of the music search service
      try {
        log.info("Loading the service...");
 
        // JNDI the old-fashioned way:
        Context ctx = new InitialContext();
        service = (MyService)ctx.lookup("MyAction/remote");
        if (service == null) {
          log.error("Didn't get the service!");
        }
      } catch (NamingException e) {
        log.error("Error looking up the remote service", e);
        return null;
      }
    }
    return service;
  }
}

2.) Write the test

Next, we’ll need to write the test itself. To do this, we’ll extend the AbstractJavaSamplerClient class in JMeter’s org.apache.jmeter.protocol.java.sampler package. This abstract class has a runTest method that we will override, and this method implements the actual test. We will also override the getDefaultParameters method to provide some reasonable defaults values which will be displayed in JMeter’s GUI application.

package us.mikedesjardins.demo.jmeter;
 
import org.apache.jmeter.config.Arguments;
import org.apache.jmeter.protocol.java.sampler.AbstractJavaSamplerClient;
import org.apache.jmeter.protocol.java.sampler.JavaSamplerContext;
import org.apache.jmeter.samplers.SampleResult;
 
public class DigitalContentServiceEJBTestSampler extends AbstractJavaSamplerClient {
  public SampleResult runTest(JavaSamplerContext context) {
    SampleResult results = new SampleResult();
    MyService service = MyServiceFactory.getInstance().getService();
 
    results.sampleStart();
    Long param1 = context.getLongParameter("PARAM_1");
    String param2 = context.getStringParameter("PARAM_2");
 
    MyResult result = service.myMethod(param1, param2);
    if (result != null) {
       results.setSuccessful(true);
       results.setResponseCodeOK();
       results.setResponseMessage("'myResult:" + myResult);
    } else {
       results.setSuccessful(false);
    }
    results.sampleEnd();
    return results;
  }
 
  @Override
  public Arguments getDefaultParameters() {
    Arguments args = new Arguments();
    args.addArgument("PARAM_1", "4815162342");
    args.addArgument("PARAM_2", "Iculus");
    return args;
  }
}

3.) Setup JMeter

JMeter’s extra libs directory is ${JMETER_INSTALL_LIB}/lib/ext. Into that directory you will need to copy any jars that your EJB client will need. In you’re using JBoss, you will want to copy the jbossall-client.jar into that directory as well (for the JNDI client and other remoting goodies) – presumably other application servers have similar client jar files available.

When you fire up JMeter, your new sampler should appear in the Samplers menu. Enjoy!

Photo Credit: Bill Jacobus

At my current job, I’m actually pretty lucky. Almost all of us work remotely, so we’re pretty accustomed to how to behave in the ubiquitous con-call. At a previous engagement, I wasn’t so lucky – I’ll omit their names to protect the guilty.

So here’s an arbitrary list from me, a random guy on the internet of questionable credentials, of what you should and shouldn’t do on a conference call. Some of these probably seem really obvious, but I’m listing even the obvious ones because some people still break them:

1.) Use the Mute Button, especially on a speakerphone. The most important reason for using Mute is to prevent echo-y feedback, particularly on speaker phones. If you aren’t talking, please put your speaker phone on mute for the sake of everyone else listening. Note that following this rule will invariably lead to the embarrassing situation where you start talking and don’t realize that you’ve left your phone on mute. Don’t worry, we’ve all done it and we’ll all forgive you!
2.) Introduce yourself when you enter the conference. Some conference systems will force you to state your name when you log in, and then the robo-operator will announce you when you join. I actually find this to be quite jarring, especially when robo-operator interrupts what everyone is saying. Better systems will play a quiet tone when people enter or leave the call. Some, like one that a client had at my previous job, will do nothing at all. This would allow people to lurk on the line unbeknownst to the participants, which is terribly rude. Likewise, if you enter a conference room while a conference call is already underway, announce yourself at the next free moment. Ideally, the moderator of the conference will also take a moment to introduce everybody at the beginning of the call if there is a chance that everyone doesn’t know each other. This is a great idea.
3.) Close the Door. It’s best to go to a closed room to join a conference call to eliminate background noise. If you can go to such a place, do it. Don’t join a conference call from, e.g., a street cafe or airport gate. In doing so you risk a passing ambulance, street parade, or TSA threats to destroy unattended luggage interrupting the call.
4.) Don’t use a mobile phone if you can help it. Occasionally you can get away with using a mobile for a con-call in a pinch. But if it’s a super-important meeting where you are trying to make an impression or do something complicated, nothing will be more frustrating than a garbled, broken up, or dropped call. Try to use a land-line if you can.
5.) Don’t eat on the phone. I guess this is just a personal pet peeve of mine. I can’t even listen to NPR if the announcer’s voice is all moist and saliva-sounding. This is more important if you’re wearing a headset.
6.) Have an agenda that everyone receives beforehand. This goes for all meetings, but it’s just as critical for a conference call. This helps you set expectations and stay on-topic during the call.
7.) Get some screen-sharing software. Better yet, get some screen sharing software and test it out before the meeting. With it, you can use something as simple as Notepad or TextMate as a virtual whiteboard. For some reason, we never did this at my previous jobs. We’ve done it at my current job and it works great.
8.) Pick a good time for all participants. This is particularly important if you’re working in different time zones. Generally you can depend on developers being available between 10am and 4pm in their respective time zones – you can argue that programmers need to grow up and work regular business hours like everyone else. But until the voodoo of deadline creation becomes a perfected science, software people will need to occasionally work late into the night or early in the morning to meet schedules. Or (like anyone else) we may have daycare responsibilities and have to leave a little early. So we stay flexible. This means that if you’re working on, e.g., both coasts of the United States, your best bet is between 1pm and 3pm, eastern time. If you’re working in the U.S. and the far east, you’re usually stuck with getting the U.S. participants to work early, and the others late in their workday. Similarly between Europe and the U.S., the U.S. participants will probably need to be available late in the day, and the Europeans earlier.

What do you think? Have I missed any conference call ground rules?

Photo Credit: Stephen Cummings

I’ve been enamored with the “Convention over Configuration” web frameworks lately (e.g., Grails, Django), and wondered how hard it’d be to reproduce some of their magic ORM functionality using Hibernate Tools. I’ve concluded that I’ve still got a long ways to go, but that I might have some worthwhile tips to share in the meantime.

My progress has been impeded a bit because the documentation for Hibernate Tools is pretty weak. Hibernate Tools was really generated with Eclipse users in mind. A large portion of the documentation is devoted to explaining how to use the IDE. I’m not using Eclipse, and I intend to use the tools at the command-line, and command-line use really isn’t targeted.

0.) Get the tools and dependencies.
I’m still in the dark ages – I use ant instead of maven for builds, and need to track down jar dependencies the old fashioned way. In addition to the usual Hibernate jars, you’ll also need hibernate-tools, freemarker, and jtidy.

1.) Setup an Ant task
This is pretty straightforward, and it is explained fairly well in the documentation. First, define yourself a Hibernate Tools task. Mine looks like this:

<taskdef name="hibernatetool" classname="org.hibernate.tool.ant.HibernateToolTask">
  <classpath>
    <fileset refid="hibernate.libs" />
    <fileset refid="hibernatetools.libs" />
    <fileset refid="app.libs" />
    <fileset refid="compile.libs" />
    <pathelement path="${build}" />
    <pathelement path="${basedir}" /> 
  </classpath>
</taskdef>

Next, create a task that uses our new definition. We’re going to be creating the mapping files and POJOs in this example. It will look something like this:

<target name="gen_hibernate" depends="compile"> 
  <delete dir="${genhbm}" />
  <mkdir dir="${genhbm}" />
  <hibernatetool>
    <jdbcconfiguration 
        configurationfile="${src}/hibernate-connection.cfg.xml"
        revengfile="hibernate.reveng.xml"
        packagename="us.mikedesjardins.data"
        detectmanytomany="true"
        detectoptimisticlock="true" />
    <hbm2hbmxml destdir="${genhbm}" />  
    <hbm2java destdir="${genhbm}">
      <property key="jdk5" value="true" />
      <property key="ejb3" value="false" />
    </hbm2java>
  </hibernatetool>
</target>

You’ll note that I’ve created a hibernate configuration file above which only contains connection information. This is because I ran into problems when I tried to use a hibernate configuration with cache configuration elements in it. You’ll also note a reference to a file called hibernate.reveng.xml. This file controls various aspects of the reverse engineering process. Mine is very simple – I’m working with MS SQL Server, and I don’t want it to include any of the system tables which begin with the prefix sys:

<hibernate-reverse-engineering>
  <!-- Eliminate system tables  -->
  <table-filter name="sys.*" exclude="true">
</hibernate-reverse-engineering>

That should be all that you need to do to get started. When you run this ant target, your domain object POJOs and Mappings should end up in the ${genhbm} directory.

2.) First Problem – Table Names
Let’s say you’re in a company that prefixes most of it’s tables with something silly, like “tb_”. In that case, Hibernate tools will happily create all kinds of POJOs for you named TbAccount, TbAddress, etc. This is probably not what you want. Fortunately, Hibernate tools let you provide your own “Reverse Engineering Strategy” class to deal with situations just like this.

First, update your build target in Ant to include a reference to your strategy class as an attribute of the jdbcconfiguration element:

<target name="gen_hibernate" depends="compile"> 
  <delete dir="${genhbm}" />
  <mkdir dir="${genhbm}" />
  <hibernatetool>
    <jdbcconfiguration 
        configurationfile="${src}/hibernate-connection.cfg.xml"
        revengfile="hibernate.reveng.xml"
        packagename="us.mikedesjardins.data"
        detectmanytomany="true"
        detectoptimisticlock="true" 
        reversestrategy="us.mikedesjardins.hibernate.CustomReverseEngineeringStrategy"/>
    <hbm2hbmxml destdir="${genhbm}" />  
    <hbm2java destdir="${genhbm}">
      <property key="jdk5" value="true" />
      <property key="ejb3" value="false" />
    </hbm2java>
  </hibernatetool>
</target>

Next, we’ll need to create the strategy class. The documentation recommends that you extend the DelegatingReverseEngineeringStrategy class to do this, like this:

package us.mikedesjardins.hibernate;
 
import org.hibernate.cfg.reveng.DelegatingReverseEngineeringStrategy;
import org.hibernate.cfg.reveng.ReverseEngineeringStrategy;
 
public class CustomReverseEngineeringStrategy extends DelegatingReverseEngineeringStrategy {
  public CustomReverseEngineeringStrategy(ReverseEngineeringStrategy delegate { 
    super(delegate);
  }
}

Unfortunately, I was unable to find any JavaDoc documentation for the Hibernate Tools classes, so I had to do a bit of trial-and-error. It turns out there is a method called tableToClassName that can be overridden. This class accepts a TableIdentifier as its input parameter, and returns the class name in a String. Thus, to remove the tb_ from the class, we could do something like this:

public String tableToClassName(TableIdentifier tableIdentifier) {
  String packageName = "us.mikedesjardins.data";
  String className = super.tableToClassName(tableIdentifier);
  if (className.startsWith("Tb")) {
    className = className.substring(2);
  }
  return className;
}

Compile your CustomReverseEngineeringStrategy class, make sure it’s on the hibernatetools task definition’s classpath, and re-run the task. Voila! The Tb’s are gone!

There’s a similar method for column names named columnToPropertyName that handles naming your persisted class’s member variables. In my current project, the primary key columns are named the same as the table name, with “_id” appended to the end. However, in the object model, we like to just name the primary key property “id” to simplify the creation of generic DAOs. I use the columnToPropertyName method for this.

2.) Next Problem – The Generated POJOs need tweaking.
Perhaps the code that Hibernate generates is not to your liking. Maybe you work with standards-compliance-nazis who want a copyright header at the top of each class file. Or maybe all of your persisted objects implement the same interface for use with generic DAOs.

Under the covers, Hibernate uses freemarker to generate POJOs and mapping files. The templates that it uses can be edited to your liking, but doing it is not very straightforward.

First, unzip the hibernate tools jar into a temporary directory. Once unzipped, you’ll find a directory named pojo. This directory contains all of the templates used for POJO generation. Copy that directory into your build area and name it something like hib_templates.

The hbm2java task is actually just an alias for another hibernate tools target called hbmtemplate. With hbmtemplate, you can configure the location of the source templates. So we’ll remove the hbm2java task from the gen_hibernate target, and replace it with an equivalent hbmtemplate task:

<target name="gen_hibernate" depends="compile"> 
  <delete dir="${genhbm}" />
  <mkdir dir="${genhbm}" />
  <hibernatetool>
    <jdbcconfiguration 
        configurationfile="${src}/hibernate-connection.cfg.xml"
        revengfile="hibernate.reveng.xml"
        packagename="us.mikedesjardins.data"
        detectmanytomany="true"
        detectoptimisticlock="true" 
        reversestrategy="us.mikedesjardins.hibernate.CustomReverseEngineeringStrategy"/>
     <hbm2hbmxml destdir="${genhbm}" />  
     <hbmtemplate templateprefix="pojo/"
              destdir="${genhbm}"
              template="hib_templates/Pojo.ftl"
              filepattern="{package-name}/{class-name}.java">
       <property key="jdk5" value="true">
       <property key="ejb3" value="false">
    </hbmtemplate>
  </hibernatetool>
</target>

Now that we’ve told hibernate tools where our template lives, we can edit it to our liking. For example, if we want to add a copyright notice to the top of each generated POJO, we could do so thusly:

//
// Copyright 2008 Big Amalgamated Mega Global Software Corp.  All Rights Reserved.
//
${pojo.getPackageDeclaration()}
// Generated ${date} by Hibernate Tools ${version}
 
<#assign classbody>
<#include "PojoTypeDeclaration.ftl"/>; {
.
.
.
(etc)

Now that we’ve done this, we can create more templates that, e.g., generate empty DAO classes, automatically create derived classes, etc.

Hope that helps!

Photo Credit: geishaboy500

In this example, I provide a live, online interactive search of an online cheese database, and you can download the example (more on that at the end of the post).

Step One – The Test Data
I spent the most time on this project was creating test data for the example program. I headed over to Freebase to see what was available for data sets. Among lots of other things, they have a free database of cheese. First, I downloaded the data in TSV format, dumped it into a raw table, and massaged it into a relational, normalized schema. I ended up with this when I was done:
So, a CHEESE can have only one ORIGIN (a country or region where the cheese is made), is made from one-to-many types of MILK, and may have zero-to-many TEXTURES associated with it.

Step Two – Build the Domain Model
The domain model for this system is very simple. Each Cheese class has an Origin, and a set of Milk and Textures:

@Entity @Table(name="MILK")
public class Milk {
  @Id @Column(name="milk_id")
  private Integer id;
 
  @Basic @Column(name="name")
  private String name;
 
  @Version @Column(name="version")
  private Integer version;
 
// Accessors omitted
}

@Entity @Table(name="ORIGIN")
public class Origin {
  @Id @Column(name="origin_id")
  private Integer id;
 
  @Basic @Column(name="name")
  private String name;
 
  @Version @Column(name="version")
  private Integer version;
 
// Accessors omitted
}

@Entity @Table(name="TEXTURE")
public class Texture {
  @Id @Column(name="texture_id")
  private Integer id;
 
  @Basic @Column(name="description")
  private String description;
 
  @Version @Column(name="version")
  private Integer version;
 
// Accessors omitted
}

@Entity @Table(name="CHEESE")
public class Cheese {
  @Id @GeneratedValue(strategy=GenerationType.IDENTITY)
  @Column(name="cheese_id",nullable=false,unique=true)
  private Integer id;
 
  @Basic @Column(name="name")
  private String name;
 
  @ManyToOne(cascade={CascadeType.ALL})
  @JoinColumn(name="origin_id",nullable=false)
  private Origin origin;
 
  @ManyToMany(cascade={CascadeType.PERSIST,CascadeType.MERGE})
  @JoinTable(name="CHEESE_MILK_MAP",
             joinColumns=@JoinColumn(name="cheese_id"),
             inverseJoinColumns=@JoinColumn(name="milk_id"))
  private Set<Milk> milks = new HashSet<Milk>();
 
  @ManyToMany(cascade={CascadeType.PERSIST,CascadeType.MERGE})
  @JoinTable(name="CHEESE_TEXTURE_MAP",
             joinColumns=@JoinColumn(name="cheese_id"),
             inverseJoinColumns=@JoinColumn(name="texture_id"))
  private Set<Texture> textures = new HashSet<Texture>();
 
  @Version @Column(name="version")
  private Integer version;
 
// Accessors omitted
}

Step Three – Add Search Annotations and Configure Lucene
Behind the scenes, Hibernate Search uses the Apache Lucene search engine to do its indexing. In short, it maintains a mapping of object IDs to search terms in an external file, and updates the file when objects are added, updated, or deleted. To start using Hibernate Search, you’ll need to configure the location of these index files, as well as a search directory provider (we’ll just use the default). This is done in your Hibernate properties file, or (if you use JPA, like me), in persistence.xml:

<property name="hibernate.search.default.directory_provider" value="org.hibernate.search.store.FSDirectoryProvider" />
<property name="hibernate.search.default.indexBase" value="/var/lucene/cheese-indexes" />

Next, you need to indicate to Lucene which classes need to be indexed. You also need to indicate which data fields 1.) contain the document ID, and 2.) contain relevant search text. In our example, we only need to index the Cheese objects. We want to allow users to search on cheese name, milk name, origin, and texture.

First, we indicate that we want to index the Cheese objects by applying the @Indexed annotation to the class, and we elect to use the Id field to identify the Cheese objects to Lucene by applying a @DocumentId annotation to it. Next, we indicate that the cheese name contains searchable text by adding the @Field(index=Index.TOKENIZED, store=Store.NO) annotation to it. The annotation parameters are informing Hibernate Search to use Lucene’s default tokenizer to summarize the text, and not to store a copy of the document content.

We also want to allow users to search on Origin, Milk Name, and Texture. This text is not contained within the Cheese object, instead they’re in related object. So we need to add the @IndexEmbedded annotation to the member variables in the Cheese class that refer to the objects which contain the searchable text, and we also need to add the @Field(index=Index.TOKENIZED, store=Store.NO) annotation to the Milk, Origin, and Texture classes to indicate which fields are searchable.

When you’re done, the modified domain classes will look like this:

@Entity @Table(name="MILK")
public class Milk {
  @Id @Column(name="milk_id")
  private Integer id;
 
  @Field(index=Index.TOKENIZED)
  @Basic @Column(name="name")
  private String name;
 
  @Version @Column(name="version")
  private Integer version;
 
// Accessors omitted
}

@Entity @Table(name="ORIGIN")
public class Origin {
  @Id @Column(name="origin_id")
  private Integer id;
 
  @Field(index=Index.TOKENIZED)
  @Basic @Column(name="name")
  private String name;
 
  @Version @Column(name="version")
  private Integer version;
 
// Accessors omitted
}

@Entity @Table(name="TEXTURE")
public class Texture {
  @Id @Column(name="texture_id")
  private Integer id;
 
  @Field(index=Index.TOKENIZED)
  @Basic @Column(name="description")
  private String description;
 
  @Version @Column(name="version")
  private Integer version;
 
// Accessors omitted
}

@Indexed
@Entity @Table(name="CHEESE")
public class Cheese {
  @DocumentId
  @Id @GeneratedValue(strategy=GenerationType.IDENTITY)
  @Column(name="cheese_id",nullable=false,unique=true)
  private Integer id;
 
  @Basic @Column(name="name")
  @Field(index=Index.TOKENIZED, store=Store.NO)
  private String name;
 
  @IndexedEmbedded
  @ManyToOne(cascade={CascadeType.ALL})
  @JoinColumn(name="origin_id",nullable=false)
  private Origin origin;
 
  @IndexedEmbedded
  @ManyToMany(cascade={CascadeType.PERSIST,CascadeType.MERGE})
  @JoinTable(name="CHEESE_MILK_MAP",
             joinColumns=@JoinColumn(name="cheese_id"),
             inverseJoinColumns=@JoinColumn(name="milk_id"))
  private Set<Milk> milks = new HashSet<Milk>();
 
  @IndexedEmbedded
  @ManyToMany(cascade={CascadeType.PERSIST,CascadeType.MERGE})
  @JoinTable(name="CHEESE_TEXTURE_MAP",
             joinColumns=@JoinColumn(name="cheese_id"),
             inverseJoinColumns=@JoinColumn(name="texture_id"))
  private Set<Texture> textures = new HashSet<Texture>();
 
  @Version @Column(name="version")
  private Integer version;
 
// Accessors omitted
}

Step Four – The Servlets
In this example, I didn’t want to rely on any web frameworks or even on JSPs, so I wrote a good old-fashioned servlet to exercise the search function. No sane person would ever do it this way. There are actually two servlets in the example – one for application initialization and one for the page itself.

The initialization servlet does the work of indexing all of the database data the first time through. For our small data set, this takes less than a minute. For larger data sets, it wouldn’t make sense to re-index everything every time you start the application. The initialization code iterates over all of the Cheese objects ant tells the FullTextEntityManger to index it:

public void init() {
  Dao<Cheese> dao = new CheeseDao();
  EntityManager em = dao.getEntityManager();
  FullTextEntityManager fullTextEntityManager = Search.createFullTextEntityManager(em);
 
  List<Cheese> cheeses = em.createQuery("select c from Cheese as c").getResultList();
  for (Cheese cheese : cheeses) {
    fullTextEntityManager.index(cheese);
  }
}

The main page servlet has some code in the doPost method to perform the search based on the contents of the text form field. That code looks like this (I’ve shortened it up a bit here by removing some error checking and HTML output):

public void doPost(HttpServletRequest request,
                   HttpServletResponse response) throws ServletException, IOException {
  response.setContentType("text/html");
  PrintWriter out = response.getWriter();
  emitHeader(out);
 
  String searchTerm = request.getParameter("searchterm");
  EntityManager em = dao.getEntityManager();
 
  FullTextEntityManager fullTextEntityManager =
    org.hibernate.search.jpa.Search.createFullTextEntityManager(em);
  MultiFieldQueryParser parser =
    new MultiFieldQueryParser( new String[]{"name",
                                            "origin.name",
                                            "milks.name",
                                            "textures.description"},
                               new StandardAnalyzer());
 
  try {
    org.apache.lucene.search.Query query = parser.parse(searchTerm);
    javax.persistence.Query hibQuery =
      fullTextEntityManager.createFullTextQuery(query,Cheese.class);
    List<Cheese> result = hibQuery.getResultList();
    emitTable(out,result);
  } catch (ParseException e) {
    log.error("Got a parse exception", e);
    throw new ServletException(e.getMessage());
  }
  emitFooter(out);
  out.close();
}

That’s all there is to it! As you can see, setting up Hibernate Search is very simple. Most of the effort for this project was spent creating the data and making the servlets work.

Enjoy the Finished Product
To see this less-than-world-changing application in action, visit it here. You can also download the whole eclipse project and try it out for yourself. It comes with SQL dumps suitable for MySQL and PostgreSQL, and it has been tested with both environments under Tomcat 5.5.

Photo Credit: Chris Buecheler

We also have a table that contains the sum of all of the previous days’ sales, broken down by PRODUCT and LOCATION:

This is all well and good, but we’ve been asked to create an Executive Dashboard for the President of the pizza chain, and she would like to see daily sales by product. She is not interested in a breakdown by location.

We could tally it up client side…
What if we just loaded the entire table into the client, and iterated over the per-product results, and present that? Unfortunately, ORM libraries are pretty stupid in situations like these, and will generate all kinds of expensive reads to the database when you try to solve the problem this way. If you want to learn more about lazy loading, and why you shouldn’t iterate over a collection, check out my earlier post here.

We could just create a view in the Database…
We could just create a view, and aggregate the data there. Then we can easily create a Hibernate mapping to that view. The query for the view is simple:

CREATE VIEW sales_by_product_view AS
SELECT product_id, sum(total_sales) AS total_sales
  FROM YESTERDAY_SALES
 GROUP BY product_id

However, we are working with a tyrannical DBA. She is not keen on proliferating views throughout our otherwise pristine schema every time the President has decided that the company needs a new widget for the executive dashboard application.

…or we could fake it with a custom loader
Instead, let’s create a Hibernate mapping that generates the same results as the view. First, let’s create a simple POJO to contain the results:

package us.mikedesjardins;
public class SalesByProduct {
  private Integer id;
  private Integer productId;
  private BigDecimal sales;
// accessors omitted
}

The corresponding mapping file would look like this. I re-used the product_id for the ID in this example. Note the loader element:

<hibernate-mapping package="us.mikedesjardins">
  <class name="SalesByProduct"
          dynamic-insert="false"
          dynamic-update="false"
          mutable="false">
    <id name="id" type="int" unsaved-value="null">
      <column name="__id" sql-type="int identity" not-null="true" unique="true" />    
    </id>
    <property name="productId" type="int">
      <column name="__product_id" not-null="false" />
    </property>
    <property name="sales" type="java.math.BigDecimal">
      <column name="__total_sales" not-null="false" />
    </property>
    <loader query-ref="salesByProductQuery" />
  </class>
  <sql-query name="salesByProductQuery">
    <return class="SalesByProduct" />
    <![CDATA[
    select product_id as __id
         , product_id as __product_id
         , sum(total_sales) as __total_sales
      from YESTERDAY_SALES
     where product_id = :product_id
    group by product_id
   ]]>
  </sql-query>
</hibernate-mapping>

Note that you need to put a positional argument in the query, or Hibernate will get nasty about parsing it. Hope that helps!

ORM is not a way to avoid SQL
The first thing that stood out for me was this quote:

“The language SQL is the most widely supported, implemented, and used way to connect to databases. But since most of us have long lists of complaints about the language, we end up writing abstraction layers that make it easier for us to avoid coding SQL directly.”

To his credit, the author wasn’t actually addressing ORM in this paragraph. However, anyone writing business logic which interacts with a database, who is unable to write some basic SQL, is like a bull in a china shop; nothing good will come of it regardless of the tools and abstraction layers employed.

The Simple Example
The next example in the post shows how one would write a row to a database in only four lines of PHP code – it looks something like this (I removed the comments):

$row = getPostStartingWith("inp_");
$table_id = myGetPostVarFunction('table_id');
if (!SQLX_Insert($table_id,$row)) {
 myFrameworkErrorReporting();
}

I don’t know PHP, but I think the code is reading every field in a posted form that starts with inp_, generates an insert statement straight from the ID’s on the form fields, and writes an insert statement with the results.

Perhaps it’s unfair to criticize this code because “it’s just a simple example,” but if this code is being held up as an example of how short and simple non-ORM code can be, one does have to wonder

• When the database schema changes, does the HTML need to be updated so that the form fields match the database schema?
• Where are the transactions? What if I need to insert into several tables and roll back the transaction if one fails?
• Does the handy SQLX_insert method prevent SQL injection attacks?

He goes on to say that this task is made even easier by using a data dictionary to generate the SQL. After reading the “Using a Data Dictionary” article, one has to wonder whether or not the author realizes that it is a very crude form of ORM.

What about Business Logic?
Kenneth Downs tries to head-off any arguments about business logic before they come up, knowing that ORM evangelists will argue that the domain objects can encapsulate essential business logic for the application. His response?

“The SQLX_Insert() routine can call out to functions (fast) or objects (much slower) that massage data before and after the insert operation. I will be demonstrating some of these techniques in future essays, but of course the best permforming and safest method is to use triggers.”

For me, this sounds alarm bells. Triggers slow down transactions. Triggers are in your database, which is often your system’s biggest bottleneck. Triggers silently do things behind your back without telling you. Triggers change databases from vast, efficient places to store relational data, into a lumbering behemoth interpreting procedural code inside big iron.

Conversely, business logic that can be easily distributed across many smaller web servers scales horizontally. The domain layer is a fantastic place to embed simple data massaging – sadly, I often see a pile of persistent entities with getters and setters that don’t do anything.

Counter Example: The Disaster Scenario
Lastly, Ken (can I call him that? What is the ettiquite for this sort of thing, anyway?) shows an example of a piece of code that is likely to cause hundreds of unneeded reads to the database in an untuned ORM-based system. I don’t dispute this; in fact, I posted about an almost identical nightmare scenario myself a while ago.

For this, I go back to my “bull in a china shop” analogy. Programmers can write horrible code in any language, with any tool. Layers of abstraction are a double-edged sword, because you need to understand what they are doing for you. But it’s not the tool’s fault; it’s the person misusing it.

Computer Science’s Vietnam
In 2004, Ted Neward famously called ORM Computer Science’s Vietnam. Encouraged by early successes, we got sucked into the quagmire. There are plenty of reasons to be frustrated with ORM, but I’m not sure I agree with Ken’s. I try to hit the 80/20 rule with ORM, and use it where it makes sense. When I get into a convoluted transaction or need to do a large batch of operations, I’m not afraid to dive into SQL and do the work in a stored procedure. I think it’s a good mix. How about you?

Photo Credit: Ryan Dickey

Hibernate, Hibernate
O/R Mapping sure is great
Gavin King, and H-Q-L
Make my life a living hell
Look out! Here comes Hibernate!

Mapping Files in Hibernate
Wish my team would annotate
Are its queries optimized?
Who knows – it’s always a surprise
Hey there, there goes Hibernate!

Don’t fetch data now
Lazy load, ‘cuz you might guess
I don’t need it now
Hibernate, you do know best!

Hibernate, Hibernate
Friendly neighborhood Hibernate
Grab the jars, and climb aboard
OO models are your reward
To it…
Relational DBs are old-school
When you need a complex tool
You need the Hibernate!

At my previous job, the company culture steadfastly clung to the waterfall model as the one true way to develop software. The model was imposed as a series of documents with cryptic, archaic acronyms for names. I actually had to draw a flowchart for my team to help them keep track of when each document was required in the life cycle of an enhancement request.

No code was changed in our code-base without a minimum of literally five separate documents, each usually spanning tens of pages. Project managers at the company enforced the production of these documents in a near-religious deference to “the process.” Each document was reviewed, often via conference call, to receive it’s “stamp of approval” (basically a C.Y.A. cross-check) among the affected teams (usually development, production support, professional services, client management, security, perhaps others).

It often felt as though I worked at a documentation company that happened to create software as a by-product.

It was in this atmosphere that I first started reading about so-called Agile methodologies. Iterative prototyping, unit testing, and tight user/developer communications, their practitioners argued, were a more effective way to deliver software that met customer expectations. Because specifications change, and users don’t know what they want, you’re already behind schedule by the time you get done with all of that front-end junk.

It all sounded so wonderful – too good to be true. If only my company were more like that.

Now I’m at a new job. There’s very little process here – it goes something like this: A nominal business analyst creates a document with a punch-list of specifications, and the developers go off and implement it. That’s it.

You’d think I was in paradise! I would be freed of the shackles of Microsoft Word, and I’d be able to churn out code as efficiently as possible.

What Really Happened
I soon discovered myself going in circles. I’d spend a lot of time in front of the whiteboard drawing ERDs for the database, and then I wouldn’t know where to go next. Start Object-Relational mapping? Hmm… seems to soon for that. The business model? And what is the business model… what does it need to do? And will the business model’s persistent data be adequately served by the data model on this white board?

Maybe I’ll just dive in and start implementing… Agile-style. I guess that means I should start with the UI; how do I do the UI? That’s what the user wants, right? The spec says I need to do such-and-such… I know! I’ll crate a UI, and wire it up to the model’s interface, and mock-out the actual implementation of the model! So there’s really no ugly business model code to worry about.

So what should the model’s API’s be? What parameters do I need to pass around to make this thing re-usable? Will I end up needing to refactor the whole thing to support some relationship I haven’t considered yet? Oh well. Don’t worry about that for now.

And, by the way, the UI is just an admistrative, ancillary part of this project. It’s actually a batch process that runs nightly which is configured via the UI. The UI isn’t even technically necessary. Am I putting the proverbial cart before the horse? Hmmph – probably I shouldn’t start with the UI, then.

Hey – look at this whiteboard… an ERD… let’s work on that for a while!

What Works for Me
What was actually wrong with my old job was the sheer volume of documentation, and the ratio of useful information to the total number of pages. That documentation was almost never for me – it was for other people (although I still wonder how valuable it really was to other people).

Personally, I need something to ground the project. I need a place to organize my thoughts. For me, a “specification” isn’t a giant UML class diagram that I slavishly adhere to, and keep in sync with the code at all times. It’s a place where I enumerate the affected components, discover how they interact, and itemize the work that needs to be done. It’s where I validate that the thing I’m about to build is going to come somewhat close to meeting the user’s expectations.

Sometimes, I share the document with other people. Sometimes I don’t. But I’ve learned that personally, for me, I need a place to focus, and collect the pieces that need to interact, before I start writing.

For some reason, this was an amazing revelation to me. My experience at my last job had led me to believe that I was firmly in the anti-documentation camp. It turns out that, in my case, that wasn’t true at all. I need some documentation. And I don’t think it’s true for everybody, either. I’m sure there are people who are better at diving right in, and still others that want even more documentation than I do.

What works for you?
Photo Credit: Fredrik Lundh

I should note that all of these opinions are my own – I don’t speak on behalf of BCGI, Amp’d Mobile, or anybody else.

My Role
Amp’d Mobile contracted with my former employer, Boston Communications Group (usually known by its acronym, BCGI). Among other things, BCGI sold a Postpaid Billing platform called Voyager. Up until Amp’d Mobile, Voyager’s primary market was small, regional wireless carriers with fewer than 100,000 subscribers. Before Amp’d, the Voyager product didn’t contribute much to BCGI’s bottom line and served more as a product portfolio completer than as a real potential for revenue. BCGI’s main focus had instead been on Prepaid Wireless and Payment Services.

My role was primarily to design and create a web service API to Voyager, so that other components in Amp’d’s back office could interact with the billing system. This not only included billing for voice and content, but also provisioning prepaid and postpaid services on Verizon’s network, accepting payments, and providing a customer care UI for Amp’d’s call center. Additionally, I did some testing to gauge how well the system would scale once Amp’d added the half-million-or-so subscribers that they were projecting they’d have in their first year.

What Went Well
I really don’t intend for this post to be an airing of dirty laundry. Despite the implosion of both companies, there were a few things that went very well.

• BCGI was a fairly stodgy company for its size, with a heritage in larger telecom and wireless companies like Verizon and EDS. Having said that, they gave a lot of latitude to the developers involved with this project. The pace of the development necessitated a more agile approach than BCGI was accustomed to, and the upper management at BCGI did a good job of trying to accommodate the furious speed at which things needed to be done. A lot of the normal paperwork and bureaucracy was pushed aside to get things done more quickly, to everyone’s benefit.
• Some of the development work for the project was offshored, with mixed success. The projects that I’d consider successes related to components that did real-time provisioning of services with the carrier’s network elements. These projects were small, self-contained, with clear objectives that did require a lot of business domain knowledge.
• With a few exceptions, the API scaled quite well. We quickly ramped up to support hundreds of thousands of transactions per day. These came handsets, web sites, payment platforms, etc.
• Integration between our API and Amp’d’s web components went very well. Developers from geographically dispersed areas used Instant Messaging quite extensively to communicate, and it was a far more productive means of communication than the old “our developer talks to our project manager who talks to their project manager who talks to their developer” scheme that seems so pervasive in larger companies.

What Didn’t Go Well
There wouldn’t be much to write about if there weren’t a few negatives in the postmortem, right? So here they are; first, the technical Challenges:

• Scaling the batch billing processes were more difficult than I anticipated. When I did my initial testing, I used an existing carrier’s data, and multiplied their user data gradually to project how quickly we’d be able to rate call records with larger carriers. I didn’t count on the fact that my source carrier’s subscribers made far fewer calls per subscriber than Amp’d’s subscribers eventually made. Amp’d’s market demographic was much younger than the demographic for the source data that I used, and younger subscribers make more calls. In retrospect, this should have been obvious.
• Another scaling difficulty was caused by the manner by which we received call detail records. Mediation is the process by which you obtain raw call records from a network device, and turn those records into a billable records in your billing system. For a traditional carrier, this process takes place daily (at an absolute minimum) or more often as necessary. In Amp’d’s case, we received call records once per month. This meant that we needed to process and rate over 50 million call records in a matter of hours, which is no small feat. It’s especially difficult when you’re using a billing system that was designed to mediate only hundreds of thousands of records daily, and bill an order of magnitude fewer records once per month. We managed to scrape by, but there were some pretty severe growing pains.
• We didn’t adequately anticipate the level of fraud that we encountered. We were required to make changes to head off fraud problems rather hurriedly, and that led to slapdash implementations that were prone to errors.
• The customer care UI was buggy. I previously did an entire post just about that topic.

Of course, there were business-related challenges, too.

• Most of the executive staff in both companies (Amp’d and BCGI) had a lot of experience with prepaid environments and mobile content, but very little experience in postpaid environments. This was particularly true when Amp’d Mobile was first getting started. By the time Amp’d brought on more seasoned management with post-paid experience, it was already too late. It’s important to note that the postpaid business was about three-quarters of Amp’d’s subscriber base.
• Because many of the key players came from a prepaid background, the enhancements that were requested for the platform often involved marketing content or prepaid services, instead off addressing fundamental business processes like billing and collections. BCGI, itself of prepaid pedigree, was happy to oblige. Thus, the limited development resources were allocated to content, marketing, and prepaid tasks instead of revenue assurance, payment, and other postpaid tasks. Sadly, Voyager had built-in collections modules that were never used by Amp’d because it was never a priority for them. If this had been made a priority in the very beginning, Amp’d might still be in business today.
• People still buy handsets with the intention to talk on them, not to purchase media content. When Amp’d launched, their voice plans were not competitive, and the rate of adoption was low. I think the belief was that the content was a compelling enough reason to sell the phone. However, having a good plan for good old send-to-end voice calls is still critical to attract new subscribers. Once they adjusted their rate plans for this, net add rates improved significantly.

What I Learned
It’s easy to armchair-quarterback the Amp’d experience. I obviously have the benefit of hindsight. Here are some of the things that I took away from the experience:

• As I wrote in an earlier post, business domain knowledge is key. If you’re entering a new business space, make sure you have an expert on your side who knows what the pitfalls will be, from the very beginning.
• Building a national MVNO, particularly one that offers post-paid service, is a lot harder than it sounds. I think that a lot of people mistakenly believe that the only difficult part of building a nationwide wireless carrier is having the network. But building the operational staff to support billing, credit, collections, and customer care is a huge undertaking that takes years to get right at traditional carriers. These critical business processes aren’t cheap, either, even if you manage to outsource them. I’m not sure if an MVNO can be competitive given the cost of using the host network, plus the cost of the back-office processes.
• Always plan for fraud. The bigger you get, the bigger target you become for fraud. Look at every process as a thief would – payment, distribution, service delivery, etc. Everywhere in your system where there is something of value is a target. Plan for it in advance.
• Scalability tests might be less useful than you think they are. It’s hard to predict how things will scale, and which APIs or processes will take the hardest beating. It’s probably safe to just assume that your processes will need to adapt quickly to cope with increased volume, and to be prepared for it by designing your processes to scale horizontally wherever possible.
• I had a blast. This project was one of the most rewarding experiences I’ve ever had as a developer, and it’ll be a long time before I can top it. I worked with some amazing people at Amp’d, BCGI, and a lot of Amp’d’s other vendors. The brainstorming sessions in Amp’d’s amphitheater with the whiteboard is the stuff that developer/architect types love. I still pine for the good old days when I felt like I was a part of something revolutionary in the wireless space.

“Cook was directly responsible for scaling Twitter, and he very much failed in his job.”

I’ll set aside the question of whether or not this claim is even true. And I won’t even consider the legal ramifications of levying such claims. Perhaps Arrington knows a lot more about rapidly scaling realtime communications systems, and the inner-workings and politics of Twitter, Inc., than most of us do.

This amateurish outburst made me ponder the rock-star status to which we now elevate some programmers and system architects. There are a lot of geeks to whom we bestow a (perhaps unhealthy) share of idolatry, many of whom don’t even need their full names to be recognized: DHH, Guido, Linus, PG, Scoble, Spez, Steve (and his evil twin, FSJ), and, yes, even Arrington. I could probably name dozens more. Many of us pay a lot of money to be in the same room with these people, and hear them speak.

Was Blaine Cook at this level of stardom? Probably not. But he did give talks and apparently kept a blog about the challenges of scaling a project so quickly. He was Chief Architect of arguably the hottest social service on the internet. Perhaps that’s enough to become a target.

Arrington’s job is to attract eyeballs. Eyeballs sell ads and (presumably) promote speaking engagements. At its essence, TechCrunch is not that much different than a traditional magazine. From where I sit, TechCrunch gleefully taunted a guy who left his job, forceably or otherwise. What company does that put TechCrunch in when compared to traditional media? Who follows the real rock stars around, revelling in their success and revelling even more when they crash hard?

Michael Arrington needs to decide what TechCrunch is. Is it The Wall Street Journal? Or is it The Star? The tabloids at the supermarket checkout get lots of eyeballs by celebrating the latest misery of Britney or Lindsey or Brad & Angelina. If that’s what TechCrunch is selling, then I ain’t buying.

Photo Credit: Eric Mutrie