Elephant provides a generic API for generating matchings. Since matchings 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.

Matching is closely related to Ranking . It might be regarded as a set of rankings for collections of entities. Usually, those collections are sets of contacts.

Main goals

• Simple inheritance from MatchingEntity, 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 matching 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 matching 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.

Matching produces values for each basis entity n times the size of the related entity set.

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 Matching API provides base classes and interfaces to concentrate module and entity specifics.

How does it work?

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

The API takes, one by one, all the module specific indicators and generate their values against the whole set of related entities. After that, generates a final entry with the calculated entity matching for each related entity. 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 with the related entity and ordering statements to database queries.

Matching and the entities

Matching is a both sides value. Once stressed the relation between n-A and n-B, the results can be used to show the matching from a single A to n-B, same as from a single B to n-A.

Sorting entities by matching

Matching results can be used to sort entities for their matching value to a related entity. The Matching API provides non intrusive methods for JPA queries, allowing the natural entity sort order in case there is no related entity or matching generated.

The image shows the elements at play when the related entity is an authenticated user. MatchingEntity represents the generated set of tuples containing the matching indicators and the final formula value. The matching value is sorted in descendant order as to show higher values first. In case of no matching, the fallback goes to the ranking and, finally, to entity sort order.