Elephant provides a generic API for generating rankings. Since rankings will be generated within different modules and using different Dao instances, the API provides a basic entity skeleton which is extended on the required JPA context.

Main goals

• Simple inheritance from RankingEntity, with no code added.
• Multiple entities in a single JPA context.
• Unique process among modules.
• Discovering entity process classes via annotations.
• Bulk and per entity processing.
• Multiple indicators defined at entity level.
• Indicators kept in the JPA model.
• Final ranking based on a per entity editable formula.

Understanding the complexities of a multi-module approach

Using different JPA context or Dao instances with highly populated databases forces to have ranking tables in the same context where are supposed to be used. The fact that indicators are kept after calculate the final ranking value, adds, if not enough, more complexity.

Keeping indicators is not a random decision. Once calculated, they can be used for other purposes. For example, statistics, entity honoring symbols and so on.

In order to achieve the expected results with the minimum effort, the Ranking API provides base classes and interfaces to concentrate module and entity specifics.

How does it work?

The Ranking API has the starting point using Rankings.process() static method. This is a bulk processing and starts deleting the ranking table. When executing for a single entity of a specific module, uses instead Rankings.processFor(entity).

The API takes, one by one, all the module specific indicators and generate their values. After that, generates a final entry with the calculated entity ranking. The formula is written as plain text and uses indicator's name as variables. Formulas are usually expressed as a sum of weighted indicators.

(indicator1 * weight) + (indicator2 * weight) + ...

Finally, the API has some convenience methods for adding join and ordering statements to database queries.

Dossier ranking example

Dossier ranking takes information from different modules and uses the extended syntax for indicators. The image shows class inheritance and data providing. The final result is kept in dossier module's JPA.

DossierIndicator excerpt

Indicators self-provided or from external modules.

@ElephantIndicator
public class DossierIndicator extends AbstractIndicator {

  public DossierIndicator() {
    root = "dossier";
    indicators = Arrays.asList(
            "participation", "fullParticipation", "issues", 
            "generic:stars", "generic:comments",
            "attach:attachments", "forum:topics");
  }
  
  @Override
  protected Dao createDao() {
    return new DossierPU();
  }

 ...

}

Sorting entities by ranking

Ranking results can be used to sort entities. The Ranking API provides non intrusive methods for JPA queries, allowing the natural entity sort order in case there is no ranking generated.

The image shows the elements at play. RankingEntity represents the generated set of tuples containing the ranking indicators and the final formula value. The ranking value is sorted in descendant order as to show higher values first.